Support rpmautospec / %autochangelog

[goals.git] / docs / Goalfile.pod

diff --git a/docs/Goalfile.pod b/docs/Goalfile.pod
index 85d19ba..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
 
 
 =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)
 =head2 Standard Functions
 
 =head3 basename (path)


@@ -46,6 +60,24 @@ For example:
 
 Returns the filename extension.
 
 
 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:
 =head3 head (list)
 
 For example:


@@ -64,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.
 
 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:
 =head3 read (filename)
 
 For example:


@@ -98,6 +146,20 @@ For example:
 
 This takes a list of strings and sorts it, removing duplicates.
 
 
 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:
 =head3 subst (from, to, text)
 
 For example:


@@ -130,13 +192,31 @@ files using ordinary globbing rules.
 
 For example:
 
 
 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)>.
 
 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.
 
 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)>.
 =head1 SEE ALSO
 
 L<goals(1)>.