Implement `apply`.

- apply seq fn args…

diff --git a/docs/content/templates/functions.md b/docs/content/templates/functions.md
index b0fa0d9ed73b42964c02a5de69103b994280e901..2e9cbd3c1171345b78949eb35f5c135bc246b56f 100644 (file)
--- a/docs/content/templates/functions.md
+++ b/docs/content/templates/functions.md
@@ -258,11 +258,75 @@ Removes any trailing newline characters. Useful in a pipeline to remove newlines
 e.g., `{{chomp "<p>Blockhead</p>\n"` → `"<p>Blockhead</p>"`
 
 ### highlight
-Take a string of code and a language, uses Pygments to return the syntax
-highlighted code in HTML. Used in the [highlight
-shortcode](/extras/highlighting).
+Take a string of code and a language, uses Pygments to return the syntax highlighted code in HTML. Used in the [highlight shortcode](/extras/highlighting).
 
 ### ref, relref
 Looks up a content page by relative path or logical name to return the permalink (`ref`) or relative permalink (`relref`). Requires a Node or Page object (usually satisfied with `.`). Used in the [`ref` and `relref` shortcodes]({{% ref "extras/crossreferences.md" %}}).
 
 e.g. {{ ref . "about.md" }}
+
+## Advanced
+
+### apply
+
+Given a map, array, or slice, returns a new slice with a function applied over it. Expects at least three parameters, depending on the function being applied. The first parameter is the sequence to operate on; the second is the name of the function as a string, which must be in the Hugo function map (generally, it is these functions documented here). After that, the parameters to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against. An example is in order:
+
+    +++
+    names: [ "Derek Perkins", "Joe Bergevin", "Tanner Linsley" ]
+    +++
+
+    {{ apply .Params.names "urlize" "." }} → [ "derek-perkins", "joe-bergevin", "tanner-linsley" ]
+
+This is roughly equivalent to:
+
+    {{ range .Params.names }}{{ . | urlize }}{{ end }}
+
+However, it isn’t possible to provide the output of a range to the `delimit` function, so you need to `apply` it. A more complete example should explain this. Let's say you have two partials for displaying tag links in a post,  "post/tag/list.html" and "post/tag/link.html", as shown below.
+
+    <!-- post/tag/list.html -->
+    {{ with .Params.tags }}
+    <div class="tags-list">
+      Tags:
+      {{ $len := len . }}
+      {{ if eq $len 1 }}
+        {{ partial "post/tag/link" (index . 0) }}
+      {{ else }}
+        {{ $last := sub $len 1 }}
+        {{ range first $last . }}
+          {{ partial "post/tag/link" . }},
+        {{ end }}
+        {{ partial "post/tag/link" (index . $last) }}
+      {{ end }}
+    </div>
+    {{ end }}
+
+
+    <!-- post/tag/link.html -->
+    <a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
+
+This works, but the complexity of "post/tag/list.html" is fairly high; the Hugo template needs to perform special behaviour for the case where there’s only one tag, and it has to treat the last tag as special. Additionally, the tag list will be rendered something like "Tags: tag1 , tag2 , tag3" because of the way that the HTML is generated and it is interpreted by a browser.
+
+This is Hugo. We have a better way. If this were your "post/tag/list.html" instead, all of those problems are fixed automatically (this first version separates all of the operations for ease of reading; the combined version will be shown after the explanation).
+
+    <!-- post/tag/list.html -->
+    {{ with.Params.tags }}
+    <div class="tags-list">
+      Tags:
+      {{ $sort := sort . }}
+      {{ $links := apply $sort "partial" "post/tag/link" "." }}
+      {{ $clean := apply $links "chomp" "." }}
+      {{ delimit $clean ", " }}
+    </div>
+    {{ end }}
+
+In this version, we are now sorting the tags, converting them to links with "post/tag/link.html", cleaning off stray newlines, and joining them together in a delimited list for presentation. That can also be written as:
+
+    <!-- post/tag/list.html -->
+    {{ with.Params.tags }}
+    <div class="tags-list">
+      Tags:
+      {{ delimit (apply (apply (sort .) "partial" "post/tag/link" ".") "chomp" ".") ", " }}
+    </div>
+    {{ end }}
+
+`apply` does not work when receiving the sequence as an argument through a pipeline.

diff --git a/tpl/template.go b/tpl/template.go
index ef0096ceff36cc9dbeb09dbdf31ab7e4f5f07945..a116c21367308d2d794d504cf4a5d4ef968bfb50 100644 (file)
--- a/tpl/template.go
+++ b/tpl/template.go
@@ -422,6 +422,68 @@ func Where(seq, key, match interface{}) (r interface{}, err error) {
        }
 }
 
+func Apply(seq interface{}, fname string, args ...interface{}) (interface{}, error) {
+       if seq == nil {
+               return make([]interface{}, 0), nil
+       }
+
+       if fname == "apply" {
+               return nil, errors.New("can't apply myself (no turtles allowed)")
+       }
+
+       seqv := reflect.ValueOf(seq)
+       seqv, isNil := indirect(seqv)
+       if isNil {
+               return nil, errors.New("can't iterate over a nil value")
+       }
+
+       fn, found := funcMap[fname]
+       if !found {
+               return nil, errors.New("can't find function " + fname)
+       }
+
+       fnv := reflect.ValueOf(fn)
+
+       switch seqv.Kind() {
+       case reflect.Array, reflect.Slice:
+               r := make([]interface{}, seqv.Len())
+               for i := 0; i < seqv.Len(); i++ {
+                       vv := seqv.Index(i)
+
+                       vvv, err := applyFnToThis(fnv, vv, args...)
+
+                       if err != nil {
+                               return nil, err
+                       }
+
+                       r[i] = vvv.Interface()
+               }
+
+               return r, nil
+       default:
+               return nil, errors.New("can't apply over " + reflect.ValueOf(seq).Type().String())
+       }
+}
+
+func applyFnToThis(fn, this reflect.Value, args ...interface{}) (reflect.Value, error) {
+       n := make([]reflect.Value, len(args))
+       for i, arg := range args {
+               if arg == "." {
+                       n[i] = this
+               } else {
+                       n[i] = reflect.ValueOf(arg)
+               }
+       }
+
+       res := fn.Call(n)
+
+       if len(res) == 1 || res[1].IsNil() {
+               return res[0], nil
+       } else {
+               return reflect.ValueOf(nil), res[1].Interface().(error)
+       }
+}
+
 func Delimit(seq, delimiter interface{}, last ...interface{}) (template.HTML, error) {
        d, err := cast.ToStringE(delimiter)
        if err != nil {
@@ -1033,6 +1095,7 @@ func init() {
                "partial":     Partial,
                "ref":         Ref,
                "relref":      RelRef,
+               "apply":       Apply,
                "chomp":       Chomp,
        }