=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
git.annexia.org / goals.git / blobdiff