stdlib: Implement join() function.

[goals.git] / docs / Goalfile.pod

diff --git a/docs/Goalfile.pod b/docs/Goalfile.pod
index 18142fe..9917fd0 100644 (file)
--- a/docs/Goalfile.pod
+++ b/docs/Goalfile.pod
@@ -2,20 +2,94 @@
 
 =head1 NAME
 
-Goalfile - introduction and tutorial to writing goal files
+Goalfile - introduction, tutorial, and reference for writing goal files
 
 =head1 SUMMARY
 
+=head1 INTRODUCTION
 
-=head1 DESCRIPTION
+=head1 TUTORIAL
 
+=head1 REFERENCE
 
+=head2 Standard Functions
 
+=head3 basename (path)
 
+For example:
+
+ basename ("dir/file.ext") ⇒ "file.ext"
+
+Returns the filename part of the path.
+
+=head3 dirname (path)
+
+For example:
+
+ dirname ("dir/file.ext") ⇒ "dir"
+
+Returns the directory part of the path.
+
+=head3 extension (filename)
+
+For example:
+
+ extension ("dir/file.ext") ⇒ "ext"
+
+Returns the filename extension.
+
+=head3 join (list1, list2)
+
+For example:
+
+ join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
+
+Concatenate C<list1> and C<list2>.  It's not usually necessary to use
+this function since goals automatically flattens lists within lists
+into simple lists in many cases.
+
+=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)>, L<goals-reference(5)>.
+L<goals(1)>.
 
 =head1 AUTHORS