stdlib: Implement split() function.

[goals.git] / docs / Goalfile.pod

diff --git a/docs/Goalfile.pod b/docs/Goalfile.pod
index 9917fd0..abe9f50 100644 (file)
--- a/docs/Goalfile.pod
+++ b/docs/Goalfile.pod
@@ -30,6 +30,14 @@ For example:
 
 Returns the directory part of the path.
 
 
 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:
 =head3 extension (filename)
 
 For example:


@@ -38,6 +46,32 @@ 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:
+
+ head (["a", "b", "c"]) ⇒ "a"
+
+Returns the head (first) element of the list.
+

 =head3 join (list1, list2)
 
 For example:
 =head3 join (list1, list2)
 
 For example:


@@ -48,6 +82,48 @@ 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:
+
+ 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:
 =head3 sort (list)
 
 For example:


@@ -56,6 +132,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:


@@ -67,6 +157,14 @@ 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.
 
 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:
 =head3 wildcard (pattern)
 
 For example: