Add truncate template function

This commit adds a truncate template function for safely truncating text without
breaking words. The truncate function is HTML aware, so if the input text is a
template.HTML it will be truncated without leaving broken or unclosed HTML tags.

    {{ "this is a very long text" | truncate 10 " ..." }}
    {{ "With [Markdown](/markdown) inside." | markdownify | truncate 10 }}

Author: biilmann

docs/content/templates/functions.md

@@ -662,6 +662,15 @@ e.g.
 * `{{slicestr "BatMan" 3}}` → "Man"
 * `{{slicestr "BatMan" 0 3}}` → "Bat"
 
+### truncate
+
+Truncate a text to a max length without cutting words or HTML tags in half. Since go templates are HTML aware, truncate will handle normal strings vs HTML strings intelligently.
+
+e.q.
+
+* `{{ "this is a text" | truncate 10 " ..." }}` → this is a ...
+* `{{ "With [Markdown](#markdown) inside." | markdownify | truncate 10 }}` → With <a href='#markdown'>Markdown …</a>
+
 ### split
 
 Split a string into substrings separated by a delimiter.

tpl/template_funcs.go

@@ -38,6 +38,7 @@ import (
 	"strings"
 	"sync"
 	"time"
+	"unicode"
 	"unicode/utf8"
 
 	"github.com/bep/inflect"
@@ -55,7 +56,14 @@ import (
 )
 
 var (
-	funcMap template.FuncMap
+	funcMap      template.FuncMap
+	tagRE        = regexp.MustCompile(`(?s)<(/)?([^ ]+?)(?:(\s*/)| .*?)?>`)
+	htmlRE       = regexp.MustCompile(`(?s)<.*?>|((?:\w[-\w]*|&.*?;)+)`)
+	htmlSinglets = map[string]bool{
+		"br": true, "col": true, "link": true,
+		"base": true, "img": true, "param": true,
+		"area": true, "hr": true, "input": true,
+	}
 )
 
 // eq returns the boolean truth of arg1 == arg2.
@@ -239,6 +247,130 @@ func slicestr(a interface{}, startEnd ...interface{}) (string, error) {
 
 }
 
+func truncate(a interface{}, options ...interface{}) (template.HTML, error) {
+	length, err := cast.ToIntE(a)
+	if err != nil {
+		return "", err
+	}
+	var textParam interface{}
+	var ellipsis template.HTML
+
+	switch len(options) {
+	case 0:
+		return "", errors.New("truncate requires a length and a string")
+	case 1:
+		textParam = options[0]
+		ellipsis = " …"
+	case 2:
+		textParam = options[1]
+		var ok bool
+		if ellipsis, ok = options[0].(template.HTML); !ok {
+			s, e := cast.ToStringE(options[0])
+			if e != nil {
+				return "", errors.New("ellipsis must be a string")
+			}
+			ellipsis = template.HTML(html.EscapeString(s))
+		}
+	default:
+		return "", errors.New("too many arguments passed to truncate")
+	}
+	if err != nil {
+		return "", errors.New("text to truncate must be a string")
+	}
+	text, err := cast.ToStringE(textParam)
+	if err != nil {
+		return "", errors.New("text must be a string")
+	}
+
+	if html, ok := textParam.(template.HTML); ok {
+		return truncateHTML(length, ellipsis, html)
+	}
+
+	if len(text) <= length {
+		return template.HTML(html.EscapeString(text)), nil
+	}
+
+	var lastWordIndex int
+	var lastNonSpace int
+	for i, r := range text {
+		if unicode.IsSpace(r) {
+			lastWordIndex = lastNonSpace
+		} else {
+			lastNonSpace = i
+		}
+		if i >= length {
+			return template.HTML(html.EscapeString(text[0:lastWordIndex+1])) + ellipsis, nil
+		}
+	}
+
+	return template.HTML(html.EscapeString(text)), nil
+}
+
+func truncateHTML(length int, ellipsis, text template.HTML) (template.HTML, error) {
+	if len(text) <= length {
+		return text, nil
+	}
+
+	var pos, endTextPos, currentLen int
+	openTags := []string{}
+
+	for currentLen < length {
+		slice := string(text[pos:])
+		m := htmlRE.FindStringSubmatchIndex(slice)
+		if len(m) == 0 {
+			// Checked through whole string
+			break
+		}
+
+		pos += m[1]
+		if len(m) == 4 && m[3]-m[2] > 0 {
+			// It's an actual non-HTML word or char
+			currentLen += (m[3] - m[2]) + 1 // 1 space between each word
+			if currentLen >= length {
+				endTextPos = pos
+			}
+			continue
+		}
+
+		tag := tagRE.FindStringSubmatch(slice[m[0]:m[1]])
+		if len(tag) == 0 || currentLen >= length {
+			// Don't worry about non tags or tags after our truncate point
+			continue
+		}
+		closingTag := tag[1]
+		tagname := strings.ToLower(tag[2])
+		selfClosing := tag[3]
+
+		_, singlet := htmlSinglets[tagname]
+		if !singlet && selfClosing == "" {
+			if closingTag == "" {
+				// Add it to the start of the open tags list
+				openTags = append([]string{tagname}, openTags...)
+			} else {
+				for i, tag := range openTags {
+					if tag == tagname {
+						// SGML: An end tag closes, back to the matching start tag,
+						// all unclosed intervening start tags with omitted end tags
+						openTags = openTags[i+1:]
+						break
+					}
+				}
+			}
+		}
+	}
+
+	if currentLen < length {
+		return text, nil
+	}
+
+	out := text[0:endTextPos]
+	out += ellipsis
+	for _, tag := range openTags {
+		out += ("</" + template.HTML(tag) + ">")
+	}
+	return out, nil
+}
+
 // hasPrefix tests whether the input s begins with prefix.
 func hasPrefix(s, prefix interface{}) (bool, error) {
 	ss, err := cast.ToStringE(s)
@@ -2188,6 +2320,7 @@ func initFuncMap() {
 		"title":        title,
 		"time":         asTime,
 		"trim":         trim,
+		"truncate":     truncate,
 		"upper":        upper,
 		"urlize":       helpers.CurrentPathSpec().URLize,
 		"where":        where,

tpl/template_funcs_test.go

@@ -157,6 +157,8 @@ substr: {{substr "BatMan" 3 3}}
 title: {{title "Bat man"}}
 time: {{ (time "2015-01-21").Year }}
 trim: {{ trim "++Batman--" "+-" }}
+truncate: {{ "this is a very long text" | truncate 10 " ..." }}
+truncate: {{ "With [Markdown](/markdown) inside." | markdownify | truncate 10 }}
 upper: {{upper "BatMan"}}
 urlize: {{ "Bat Man" | urlize }}
 `
@@ -228,6 +230,8 @@ substr: Man
 title: Bat Man
 time: 2015
 trim: Batman
+truncate: this is a ...
+truncate: With <a href="/markdown">Markdown …</a>
 upper: BATMAN
 urlize: bat-man
 `
@@ -815,6 +819,57 @@ func TestSlicestr(t *testing.T) {
 	}
 }
 
+func TestTruncate(t *testing.T) {
+	var err error
+	cases := []struct {
+		v1    interface{}
+		v2    interface{}
+		v3    interface{}
+		want  interface{}
+		isErr bool
+	}{
+		{10, "I am a test sentence", nil, template.HTML("I am a …"), false},
+		{10, "", "I am a test sentence", template.HTML("I am a"), false},
+		{10, "", "a b c d e f g h i j k", template.HTML("a b c d e"), false},
+		{12, "", "<b>Should be escaped</b>", template.HTML("&lt;b&gt;Should be"), false},
+		{10, template.HTML(" <a href='#'>Read more</a>"), "I am a test sentence", template.HTML("I am a <a href='#'>Read more</a>"), false},
+		{10, template.HTML("I have a <a href='/markdown'>Markdown</a> link inside."), nil, template.HTML("I have a <a href='/markdown'>Markdown …</a>"), false},
+		{10, nil, nil, template.HTML(""), true},
+		{nil, nil, nil, template.HTML(""), true},
+	}
+	for i, c := range cases {
+		var result template.HTML
+		if c.v2 == nil {
+			result, err = truncate(c.v1)
+		} else if c.v3 == nil {
+			result, err = truncate(c.v1, c.v2)
+		} else {
+			result, err = truncate(c.v1, c.v2, c.v3)
+		}
+
+		if c.isErr {
+			if err == nil {
+				t.Errorf("[%d] Slice didn't return an expected error", i)
+			}
+		} else {
+			if err != nil {
+				t.Errorf("[%d] failed: %s", i, err)
+				continue
+			}
+			if !reflect.DeepEqual(result, c.want) {
+				t.Errorf("[%d] got '%s' but expected '%s'", i, result, c.want)
+			}
+		}
+	}
+
+	// Too many arguments
+	_, err = truncate(10, " ...", "I am a test sentence", "wrong")
+	if err == nil {
+		t.Errorf("Should have errored")
+	}
+
+}
+
 func TestHasPrefix(t *testing.T) {
 	cases := []struct {
 		s      interface{}