ref: f5a3fb149fff3a44c2b3be8a0c46d02594d755c8
parent: fbf8bcacc464e9bfbc816fa6d097e6371662ce02
author: Anthony Fok <[email protected]>
date: Fri Dec 26 03:07:03 EST 2014
Wrap comments helpers package to fit 80-column width Add an initial space after `//` where appropriate. Minor copyediting.
--- a/helpers/content.go
+++ b/helpers/content.go
@@ -11,8 +11,10 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-//Package helpers implements general utility functions that work with and on content. The helper functions defined here
-//lay down the foundation of how Hugo works with files, filepaths and does string operations on content.
+// Package helpers implements general utility functions that work with
+// and on content. The helper functions defined here lay down the
+// foundation of how Hugo works with files and filepaths, and perform
+// string operations on content.
package helpers
import (
@@ -34,7 +36,7 @@
// Custom divider <!--more--> let's user define where summarization ends.
var SummaryDivider = []byte("<!--more-->")-//StripHTML accepts a string, strips out all HTML tags and returns it.
+// StripHTML accepts a string, strips out all HTML tags and returns it.
func StripHTML(s string) string {output := ""
@@ -72,7 +74,7 @@
return bytes.Replace(in, []byte("<nav>\n</nav>\n\n"), []byte(``), -1)}
-//BytesToHTML converts bytes to type template.HTML.
+// BytesToHTML converts bytes to type template.HTML.
func BytesToHTML(b []byte) template.HTML {return template.HTML(string(b))
}
@@ -127,7 +129,7 @@
GetMarkdownExtensions())
}
-//ExtractTOC extracts Table of Contents from content.
+// ExtractTOC extracts Table of Contents from content.
func ExtractTOC(content []byte) (newcontent []byte, toc []byte) {origContent := make([]byte, len(content))
copy(origContent, content)
@@ -197,7 +199,7 @@
return len(strings.Fields(s))
}
-//WordCount takes content and returns a map of words and count of each word.
+// WordCount takes content and returns a map of words and count of each word.
func WordCount(s string) map[string]int {m := make(map[string]int)
for _, f := range strings.Fields(s) {@@ -207,12 +209,13 @@
return m
}
-//RemoveSummaryDivider removes summary-divider <!--more--> from content.
+// RemoveSummaryDivider removes summary-divider <!--more--> from content.
func RemoveSummaryDivider(content []byte) []byte { return bytes.Replace(content, SummaryDivider, []byte(""), -1)}
-//TruncateWords takes content and na int and shortens down the number of words in the content down to the number of int.
+// TruncateWords takes content and an int and shortens down the number
+// of words in the content down to the number of int.
func TruncateWords(s string, max int) string {words := strings.Fields(s)
if max > len(words) {@@ -222,7 +225,8 @@
return strings.Join(words[:max], " ")
}
-//TruncateWordsToWholeSentence takes content and an int and returns entire sentences from content, delimited by the int.
+// TruncateWordsToWholeSentence takes content and an int
+// and returns entire sentences from content, delimited by the int.
func TruncateWordsToWholeSentence(s string, max int) string {words := strings.Fields(s)
if max > len(words) {@@ -241,6 +245,8 @@
return strings.Join(words[:max], " ")
}
+// GetRstContent calls the Python script rst2html as an external helper
+// to convert reStructuredText content to HTML.
func GetRstContent(content []byte) string { cleanContent := bytes.Replace(content, SummaryDivider, []byte(""), 1)--- a/helpers/general.go
+++ b/helpers/general.go
@@ -24,7 +24,7 @@
"strings"
)
-//Filepath separator defined by os.Separator.
+// Filepath separator defined by os.Separator.
const FilePathSeparator = string(filepath.Separator)
func FindAvailablePort() (*net.TCPAddr, error) {@@ -40,7 +40,8 @@
return nil, err
}
-// InStringArray checks if a string is an element of a slice of strings and returns a boolean value.
+// InStringArray checks if a string is an element of a slice of strings
+// and returns a boolean value.
func InStringArray(arr []string, el string) bool { for _, v := range arr { if v == el {@@ -64,7 +65,8 @@
return "unknown"
}
-//ReaderToBytes takes an io.Reader argument, reads from it and returns bytes.
+// ReaderToBytes takes an io.Reader argument, reads from it
+// and returns bytes.
func ReaderToBytes(lines io.Reader) []byte {b := new(bytes.Buffer)
b.ReadFrom(lines)
@@ -71,7 +73,7 @@
return b.Bytes()
}
-//ReaderToString is the same as ReaderToBytes, but returns a string.
+// ReaderToString is the same as ReaderToBytes, but returns a string.
func ReaderToString(lines io.Reader) string {b := new(bytes.Buffer)
b.ReadFrom(lines)
@@ -78,17 +80,17 @@
return b.String()
}
-//StringToReader does the opposite of ReaderToString.
+// StringToReader does the opposite of ReaderToString.
func StringToReader(in string) io.Reader {return strings.NewReader(in)
}
-//BytesToReader does the opposite of ReaderToBytes.
+// BytesToReader does the opposite of ReaderToBytes.
func BytesToReader(in []byte) io.Reader {return bytes.NewReader(in)
}
-// sliceToLower goes through the source slice and lowers all values.
+// SliceToLower goes through the source slice and lowers all values.
func SliceToLower(s []string) []string { if s == nil {return nil
@@ -102,7 +104,7 @@
return l
}
-//Md5String takes a string and returns a MD5 Hash of it.
+// Md5String takes a string and returns its MD5 hash.
func Md5String(f string) string {h := md5.New()
h.Write([]byte(f))
--- a/helpers/path.go
+++ b/helpers/path.go
@@ -28,15 +28,16 @@
var sanitizeRegexp = regexp.MustCompile("[^a-zA-Z0-9./_-]")-// Take a string with any characters and replace it so the string could be used in a path.
-// MakePath creates a Unicode sanitized string, with the spaces replaced, whilst
-// preserving the original casing of the string.
+// MakePath takes a string with any characters and replace it
+// so the string could be used in a path.
+// It does so by creating a Unicode-sanitized string, with the spaces replaced,
+// whilst preserving the original casing of the string.
// E.g. Social Media -> Social-Media
func MakePath(s string) string {return UnicodeSanitize(strings.Replace(strings.TrimSpace(s), " ", "-", -1))
}
-// MakePathToLower creates a Unicode santized string, with the spaces replaced,
+// MakePathToLower creates a Unicode-sanitized string, with the spaces replaced,
// and transformed to lower case.
// E.g. Social Media -> social-media
func MakePathToLower(s string) string {@@ -65,7 +66,8 @@
return string(target)
}
-//ReplaceExtension takes a path and an extension, strips the old extension and returns the path with the new extension.
+// ReplaceExtension takes a path and an extension, strips the old extension
+// and returns the path with the new extension.
func ReplaceExtension(path string, newExt string) string {f, _ := FileAndExt(path)
return f + "." + newExt
@@ -83,7 +85,7 @@
return false, err
}
-//IsDir check if a given path is a directory.
+// IsDir checks if a given path is a directory.
func IsDir(path string, fs afero.Fs) (bool, error) {fi, err := fs.Stat(path)
if err != nil {@@ -92,7 +94,7 @@
return fi.IsDir(), nil
}
-//IsEmpty checks if a given path is empty.
+// IsEmpty checks if a given path is empty.
func IsEmpty(path string, fs afero.Fs) (bool, error) { if b, _ := Exists(path, fs); !b { return false, fmt.Errorf("%q path does not exist", path)@@ -154,7 +156,8 @@
return inPath, errors.New("Can't extract relative path, unknown prefix")}
-//Filename takes a path, strips out the extension and returns the name of the file.
+// Filename takes a path, strips out the extension,
+// and returns the name of the file.
func Filename(in string) (name string) {name, _ = FileAndExt(in)
return
@@ -162,14 +165,18 @@
// FileAndExt returns the filename and any extension of a file path as
// two separate strings.
-// If path, in, contains a directory name ending in a slash then
-// both name and ext will be empty strings.
+//
+// If the path, in, contains a directory name ending in a slash,
+// then both name and ext will be empty strings.
+//
// If the path, in, is either the current directory, the parent
-// directory or the root directory, or an empty string, then both
-// name and ext will be empty strings.
-// If the path, in, represents the path of a file without an extension
+// directory or the root directory, or an empty string,
+// then both name and ext will be empty strings.
+//
+// If the path, in, represents the path of a file without an extension,
// then name will be the name of the file and ext will be an empty string.
-// If the path, in, represents a filename with an extension then
+//
+// If the path, in, represents a filename with an extension,
// then name will be the filename minus any extension - including the dot
// and ext will contain the extension - minus the dot.
func FileAndExt(in string) (name string, ext string) {@@ -201,7 +208,7 @@
}
-//GetRelativePath returns the relative path of a given path.
+// GetRelativePath returns the relative path of a given path.
func GetRelativePath(path, base string) (final string, err error) { if filepath.IsAbs(path) && base == "" { return "", errors.New("source: missing base directory")@@ -216,8 +223,9 @@
return name, nil
}
-// Given a source path, determine the section
-// A section is the part between the root slash and the second slash or before the first slash
+// Given a source path, determine the section.
+// A section is the part between the root slash and the second slash
+// or before the first slash.
func GuessSection(in string) string {parts := strings.Split(in, FilePathSeparator)
// This will include an empty entry before and after paths with leading and trailing slashes
@@ -258,10 +266,10 @@
}
}
-// Same as PrettifyUrlPath() but for paths.
-// /section/name.html becomes /section/name/index.html
-// /section/name/ becomes /section/name/index.html
-// /section/name/index.html becomes /section/name/index.html
+// Same as PrettifyUrlPath() but for file paths.
+// /section/name.html becomes /section/name/index.html
+// /section/name/ becomes /section/name/index.html
+// /section/name/index.html becomes /section/name/index.html
func PrettifyPath(in string) string { if filepath.Ext(in) == "" {// /section/name/ -> /section/name/index.html
@@ -281,7 +289,8 @@
}
}
-//FindCWD returns the current working directory from where the Hugo executable is run.
+// FindCWD returns the current working directory from where the Hugo
+// executable is run.
func FindCWD() (string, error) {serverFile, err := filepath.Abs(os.Args[0])
@@ -305,7 +314,7 @@
return path, nil
}
-//Same as WriteToDisk but checks to see if file/directory already exists.
+// Same as WriteToDisk but checks to see if file/directory already exists.
func SafeWriteToDisk(inpath string, r io.Reader, fs afero.Fs) (err error) {dir, _ := filepath.Split(inpath)
ospath := filepath.FromSlash(dir)
--- a/helpers/pygments.go
+++ b/helpers/pygments.go
@@ -25,7 +25,8 @@
const pygmentsBin = "pygmentize"
-//HasPygments checks to see if Pygments is installed and available on the system.
+// HasPygments checks to see if Pygments is installed and available
+// on the system.
func HasPygments() bool { if _, err := exec.LookPath(pygmentsBin); err != nil {return false
@@ -33,7 +34,7 @@
return true
}
-//Highlight takes some code and returns highlighted code.
+// Highlight takes some code and returns highlighted code.
func Highlight(code string, lexer string) string { if !HasPygments() {--- a/helpers/url.go
+++ b/helpers/url.go
@@ -21,7 +21,7 @@
"strings"
)
-//SanitizeUrl sanitizes the input URL string.
+// SanitizeUrl sanitizes the input URL string.
func SanitizeUrl(in string) string {url, err := purell.NormalizeURLString(in, purell.FlagsSafe|purell.FlagRemoveTrailingSlash|purell.FlagRemoveDotSegments|purell.FlagRemoveDuplicateSlashes|purell.FlagRemoveUnnecessaryHostDots|purell.FlagRemoveEmptyPortSeparator)
if err != nil {@@ -111,10 +111,11 @@
return x
}
-//PrettifyUrlPath takes a URL path to a content and converts it to enable pretty URLS.
-// /section/name.html becomes /section/name/index.html
-// /section/name/ becomes /section/name/index.html
-// /section/name/index.html becomes /section/name/index.html
+// PrettifyUrlPath takes a URL path to a content and converts it
+// to enable pretty URLs.
+// /section/name.html becomes /section/name/index.html
+// /section/name/ becomes /section/name/index.html
+// /section/name/index.html becomes /section/name/index.html
func PrettifyUrlPath(in string) string { if path.Ext(in) == "" {// /section/name/ -> /section/name/index.html
@@ -134,10 +135,10 @@
}
}
-//Uglify does the opposite of PrettifyPath().
-// /section/name/index.html becomes /section/name.html
-// /section/name/ becomes /section/name.html
-// /section/name.html becomes /section/name.html
+// Uglify does the opposite of PrettifyUrlPath().
+// /section/name/index.html becomes /section/name.html
+// /section/name/ becomes /section/name.html
+// /section/name.html becomes /section/name.html
func Uglify(in string) string { if path.Ext(in) == "" { if len(in) < 2 {@@ -162,7 +163,7 @@
}
}
-// Same as FileAndExt, but for Urls
+// Same as FileAndExt, but for URLs.
func ResourceAndExt(in string) (name string, ext string) {ext = path.Ext(in)
base := path.Base(in)