docs: Document functions sort, wildcard and wrap.

[goals.git] / docs / Goalfile.pod

diff --git a/docs/Goalfile.pod b/docs/Goalfile.pod
index da4b142..9731cb1 100644 (file)
--- a/docs/Goalfile.pod
+++ b/docs/Goalfile.pod
@@ -12,6 +12,47 @@ Goalfile - introduction, tutorial, and reference for writing goal files
 
 =head1 REFERENCE
 
+=head2 Standard Functions
+
+=head3 sort (list)
+
+For example:
+
+ sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
+
+This takes a list of strings and sorts it, removing duplicates.
+
+=head3 subst (from, to, text)
+
+For example:
+
+ subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
+ subst ("a.*c", "b", "aaacac") ⇒ "bb"
+
+This function works something like make’s C<subst> function, except
+that C<from> is a regular expression, specifically a L<sed(1)>
+extended regular expression.
+
+=head3 wildcard (pattern)
+
+For example:
+
+ wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
+
+The single parameter is a wildcard which is expanded into a list of
+files using ordinary globbing rules.
+
+=head3 wrap (wrapper, list)
+
+For example:
+
+ wrap ("*file", ["bar.c", "foo.c"]) ⇒ [*file("bar.c"), *file("foo.c")]
+
+Each element in C<list> is wrapped into a call to C<wrapper(element)>.
+There are two common uses for this: either to add explicit tactics
+(such as C<*file>) to a plain list of strings as in the example above;
+or to turn a list of strings into a list of goal or function calls.
+
 =head1 SEE ALSO
 
 L<goals(1)>.