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.
202 =head2 Standard Shell Functions
206 Quote a string which will be consumed as a goal expression. This is
207 typically used from within goal functions which return expressions
208 (ie. ones which do I<not> have an explicit C<returning> declaration).
209 You must not use this shell function with functions that are marked as
210 C<returning string> or C<returning strings>.
214 Echo a string in green. Useful for success/OK messages.
218 Echo a string in red. Useful for error messages.
226 Richard W.M. Jones <rjones@redhat.com>
230 Copyright (C) 2020 Richard W.M. Jones
232 Copyright (C) 2020 Red Hat Inc.
234 This program is free software; you can redistribute it and/or modify
235 it under the terms of the GNU General Public License as published by
236 the Free Software Foundation; either version 2 of the License, or
237 (at your option) any later version.
239 This program is distributed in the hope that it will be useful,
240 but WITHOUT ANY WARRANTY; without even the implied warranty of
241 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
242 GNU General Public License for more details.
244 You should have received a copy of the GNU General Public License along
245 with this program; if not, write to the Free Software Foundation, Inc.,
246 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.