stdlib/fedora.gl: Try to cache dependencies

[goals.git] / docs / Goalfile.pod

diff --git a/docs/Goalfile.pod b/docs/Goalfile.pod
index 9031780..93ca225 100644 (file)
--- a/docs/Goalfile.pod
+++ b/docs/Goalfile.pod
@@ -12,6 +12,20 @@ Goalfile - introduction, tutorial, and reference for writing goal files
 
 =head1 REFERENCE
 
+=head2 Standard Variables
+
+=head3 %stdlib
+
+The path to the standard library directory.  This path is also
+searched by default for C<include> directives.
+
+=head3 %tmpdir
+
+The location of a temporary directory which is created by goals when
+it starts and is deleted when it exits (either on success or failure).
+You can use this to store any temporary files that you want
+automatically cleaned up.
+
 =head2 Standard Functions
 
 =head3 basename (path)
@@ -82,6 +96,22 @@ 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:
@@ -116,6 +146,20 @@ For example:
 
 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:
@@ -148,13 +192,31 @@ files using ordinary globbing rules.
 
 For example:
 
- wrap ("*file", ["bar.c", "foo.c"]) ⇒ [*file("bar.c"), *file("foo.c")]
+ wrap ("is-file", ["bar.c", "foo.c"]) ⇒ [is-file("bar.c"), is-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;
+There are two common uses for this: either to add explicit predicates
+(such as C<is-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.
 
+=head2 Standard Shell Functions
+
+=head3 quoted_string
+
+Quote a string which will be consumed as a goal expression.  This is
+typically used from within goal functions which return expressions
+(ie. ones which do I<not> have an explicit C<returning> declaration).
+You must not use this shell function with functions that are marked as
+C<returning string> or C<returning strings>.
+
+=head3 print_green
+
+Echo a string in green.  Useful for success/OK messages.
+
+=head3 print_red
+
+Echo a string in red.  Useful for error messages.
+
 =head1 SEE ALSO
 
 L<goals(1)>.