5 Goalfile - introduction, tutorial, and reference for writing goal files
15 =head2 Standard Variables
19 The path to the standard library directory. This path is also
20 searched by default for C<include> directives.
24 The location of a temporary directory which is created by goals when
25 it starts and is deleted when it exits (either on success or failure).
26 You can use this to store any temporary files that you want
27 automatically cleaned up.
29 =head2 Standard Functions
31 =head3 basename (path)
35 basename ("dir/file.ext") ⇒ "file.ext"
37 Returns the filename part of the path.
43 dirname ("dir/file.ext") ⇒ "dir"
45 Returns the directory part of the path.
51 error ("this should not happen")
53 This prints the error message and causes goals to exit.
55 =head3 extension (filename)
59 extension ("dir/file.ext") ⇒ "ext"
61 Returns the filename extension.
63 =head3 filter (pattern, list)
67 filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]
69 Filter a list returning only the elements that match the extended
70 regular expression C<pattern>.
72 =head3 filter-out (pattern, list)
76 filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]
78 Filter a list returning only the elements that I<do not> match the
79 extended regular expression C<pattern>.
85 head (["a", "b", "c"]) ⇒ "a"
87 Returns the head (first) element of the list.
89 =head3 join (list1, list2)
93 join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
95 Concatenate C<list1> and C<list2>. It's not usually necessary to use
96 this function since goals automatically flattens lists within lists
97 into simple lists in many cases.
103 last (["a", "b", "c"]) ⇒ "c"
105 Returns the last element of a list.
111 nth (1, ["a", "b", "c"]) ⇒ "b"
113 Returns the n’th element of a list (counting from 0).
115 =head3 read (filename)
119 read ("filename") => "this is the content of filename"
121 Read the contents of C<filename> and return it as a single string.
122 If there is a trailing C<\n> in the file it is truncated.
124 =head3 readlines (filename)
128 readlines ("filename") => ["line1", "line2", "line3"]
130 Read the lines in C<filename> returning a list of strings.
132 =head3 realpath (filename)
136 realpath ("./tests") ⇒ "/home/user/tests"
138 Run the L<realpath(1)> command to return the resolved absolute path of
139 the C<filename> parameter.
145 sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
147 This takes a list of strings and sorts it, removing duplicates.
149 =head3 split (string)
153 split ("-g -O2") ⇒ ["-g", "-O2"]
155 Split a string using shell rules into a list of strings. This is
156 commonly used for splitting C<CFLAGS> provided by autoconf into a list
159 let CFLAGS = split ("@CFLAGS@")
160 goal compile (name) =
161 "%name.o" : "%name.c" { %CC %CFLAGS -c %< -o %@ }
163 =head3 subst (from, to, text)
167 subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
168 subst ("a.*c", "b", "aaacac") ⇒ "bb"
170 This function works something like make’s C<subst> function, except
171 that C<from> is a regular expression, specifically a L<sed(1)>
172 extended regular expression.
178 tail (["a", "b", "c"]) ⇒ ["b", "c"]
180 Returns the tail (all except first) elements of the list.
182 =head3 wildcard (pattern)
186 wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
188 The single parameter is a wildcard which is expanded into a list of
189 files using ordinary globbing rules.
191 =head3 wrap (wrapper, list)
195 wrap ("is-file", ["bar.c", "foo.c"]) ⇒ [is-file("bar.c"), is-file("foo.c")]
197 Each element in C<list> is wrapped into a call to C<wrapper(element)>.
198 There are two common uses for this: either to add explicit predicates
199 (such as C<is-file>) to a plain list of strings as in the example above;
200 or to turn a list of strings into a list of goal or function calls.
208 Richard W.M. Jones <rjones@redhat.com>
212 Copyright (C) 2020 Richard W.M. Jones
214 Copyright (C) 2020 Red Hat Inc.
216 This program is free software; you can redistribute it and/or modify
217 it under the terms of the GNU General Public License as published by
218 the Free Software Foundation; either version 2 of the License, or
219 (at your option) any later version.
221 This program is distributed in the hope that it will be useful,
222 but WITHOUT ANY WARRANTY; without even the implied warranty of
223 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
224 GNU General Public License for more details.
226 You should have received a copy of the GNU General Public License along
227 with this program; if not, write to the Free Software Foundation, Inc.,
228 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.