X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=docs%2FGoalfile.pod;h=abe9f502e61605a749c1efa26a1bd4e38e30eeaa;hb=5a456c968ee7e7bbe477ae4e756967c4aa2e3fc1;hp=18142fef3238d1cb99985a25a7f72e2fb06f9b5e;hpb=d513d8b6aa8c70191deb3e1a8392819c9181a8f9;p=goals.git

diff --git a/docs/Goalfile.pod b/docs/Goalfile.pod
index 18142fe..abe9f50 100644
--- a/docs/Goalfile.pod
+++ b/docs/Goalfile.pod
@@ -2,20 +2,192 @@
 
 =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 error (msg)
+
+For example:
+
+ error ("this should not happen")
+
+This prints the error message and causes goals to exit.
+
+=head3 extension (filename)
+
+For example:
+
+ extension ("dir/file.ext") ⇒ "ext"
+
+Returns the filename extension.
+
+=head3 filter (pattern, list)
+
+For example:
+
+ filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]
+
+Filter a list returning only the elements that match the extended
+regular expression C<pattern>.
+
+=head3 filter-out (pattern, list)
+
+For example:
+
+ filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]
+
+Filter a list returning only the elements that I<do not> match the
+extended regular expression C<pattern>.
+
+=head3 head (list)
+
+For example:
+
+ head (["a", "b", "c"]) ⇒ "a"
+
+Returns the head (first) element of the list.
+
+=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 last (list)
+
+For example:
+
+ last (["a", "b", "c"]) ⇒ "c"
+
+Returns the last element of a list.
+
+=head3 nth (n, list)
+
+For example:
+
+ nth (1, ["a", "b", "c"]) ⇒ "b"
+
+Returns the n’th element of a list (counting from 0).
+
+=head3 read (filename)
+
+For example:
+
+ read ("filename") => "this is the content of filename"
+
+Read the contents of C<filename> and return it as a single string.
+If there is a trailing C<\n> in the file it is truncated.
+
+=head3 readlines (filename)
+
+For example:
+
+ readlines ("filename") => ["line1", "line2", "line3"]
+
+Read the lines in C<filename> returning a list of strings.
+
+=head3 realpath (filename)
+
+For example:
+
+ realpath ("./tests") ⇒ "/home/user/tests"
+
+Run the L<realpath(1)> command to return the resolved absolute path of
+the C<filename> parameter.
+
+=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 split (string)
+
+For example:
+
+ split ("-g -O2") ⇒ ["-g", "-O2"]
+
+Split a string using shell rules into a list of strings.  This is
+commonly used for splitting C<CFLAGS> provided by autoconf into a list
+for use by goals:
+
+ let CFLAGS = split ("@CFLAGS@")
+ goal compile (name) =
+ "%name.o" : "%name.c" { %CC %CFLAGS -c %< -o %@ }
+
+=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 tail (list)
+
+For example:
+
+ tail (["a", "b", "c"]) ⇒ ["b", "c"]
+
+Returns the tail (all except first) elements of the list.
+
+=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