5 Goalfile - introduction, tutorial, and reference for writing goal files
15 =head2 Standard Variables
19 The location of a temporary directory which is created by goals when
20 it starts and is deleted when it exits (either on success or failure).
21 You can use this to store any temporary files that you want
22 automatically cleaned up.
24 =head2 Standard Functions
26 =head3 basename (path)
30 basename ("dir/file.ext") ⇒ "file.ext"
32 Returns the filename part of the path.
38 dirname ("dir/file.ext") ⇒ "dir"
40 Returns the directory part of the path.
46 error ("this should not happen")
48 This prints the error message and causes goals to exit.
50 =head3 extension (filename)
54 extension ("dir/file.ext") ⇒ "ext"
56 Returns the filename extension.
58 =head3 filter (pattern, list)
62 filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]
64 Filter a list returning only the elements that match the extended
65 regular expression C<pattern>.
67 =head3 filter-out (pattern, list)
71 filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]
73 Filter a list returning only the elements that I<do not> match the
74 extended regular expression C<pattern>.
80 head (["a", "b", "c"]) ⇒ "a"
82 Returns the head (first) element of the list.
84 =head3 join (list1, list2)
88 join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
90 Concatenate C<list1> and C<list2>. It's not usually necessary to use
91 this function since goals automatically flattens lists within lists
92 into simple lists in many cases.
98 last (["a", "b", "c"]) ⇒ "c"
100 Returns the last element of a list.
106 nth (1, ["a", "b", "c"]) ⇒ "b"
108 Returns the n’th element of a list (counting from 0).
110 =head3 read (filename)
114 read ("filename") => "this is the content of filename"
116 Read the contents of C<filename> and return it as a single string.
117 If there is a trailing C<\n> in the file it is truncated.
119 =head3 readlines (filename)
123 readlines ("filename") => ["line1", "line2", "line3"]
125 Read the lines in C<filename> returning a list of strings.
127 =head3 realpath (filename)
131 realpath ("./tests") ⇒ "/home/user/tests"
133 Run the L<realpath(1)> command to return the resolved absolute path of
134 the C<filename> parameter.
140 sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
142 This takes a list of strings and sorts it, removing duplicates.
144 =head3 split (string)
148 split ("-g -O2") ⇒ ["-g", "-O2"]
150 Split a string using shell rules into a list of strings. This is
151 commonly used for splitting C<CFLAGS> provided by autoconf into a list
154 let CFLAGS = split ("@CFLAGS@")
155 goal compile (name) =
156 "%name.o" : "%name.c" { %CC %CFLAGS -c %< -o %@ }
158 =head3 subst (from, to, text)
162 subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
163 subst ("a.*c", "b", "aaacac") ⇒ "bb"
165 This function works something like make’s C<subst> function, except
166 that C<from> is a regular expression, specifically a L<sed(1)>
167 extended regular expression.
173 tail (["a", "b", "c"]) ⇒ ["b", "c"]
175 Returns the tail (all except first) elements of the list.
177 =head3 wildcard (pattern)
181 wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
183 The single parameter is a wildcard which is expanded into a list of
184 files using ordinary globbing rules.
186 =head3 wrap (wrapper, list)
190 wrap ("is-file", ["bar.c", "foo.c"]) ⇒ [is-file("bar.c"), is-file("foo.c")]
192 Each element in C<list> is wrapped into a call to C<wrapper(element)>.
193 There are two common uses for this: either to add explicit predicates
194 (such as C<is-file>) to a plain list of strings as in the example above;
195 or to turn a list of strings into a list of goal or function calls.
203 Richard W.M. Jones <rjones@redhat.com>
207 Copyright (C) 2020 Richard W.M. Jones
209 Copyright (C) 2020 Red Hat Inc.
211 This program is free software; you can redistribute it and/or modify
212 it under the terms of the GNU General Public License as published by
213 the Free Software Foundation; either version 2 of the License, or
214 (at your option) any later version.
216 This program is distributed in the hope that it will be useful,
217 but WITHOUT ANY WARRANTY; without even the implied warranty of
218 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
219 GNU General Public License for more details.
221 You should have received a copy of the GNU General Public License along
222 with this program; if not, write to the Free Software Foundation, Inc.,
223 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.