5 Goalfile - introduction, tutorial, and reference for writing goal files
15 =head2 Standard Functions
17 =head3 basename (path)
21 basename ("dir/file.ext") ⇒ "file.ext"
23 Returns the filename part of the path.
29 dirname ("dir/file.ext") ⇒ "dir"
31 Returns the directory part of the path.
37 error ("this should not happen")
39 This prints the error message and causes goals to exit.
41 =head3 extension (filename)
45 extension ("dir/file.ext") ⇒ "ext"
47 Returns the filename extension.
49 =head3 filter (pattern, list)
53 filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]
55 Filter a list returning only the elements that match the extended
56 regular expression C<pattern>.
58 =head3 filter-out (pattern, list)
62 filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]
64 Filter a list returning only the elements that I<do not> match the
65 extended regular expression C<pattern>.
71 head (["a", "b", "c"]) ⇒ "a"
73 Returns the head (first) element of the list.
75 =head3 join (list1, list2)
79 join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
81 Concatenate C<list1> and C<list2>. It's not usually necessary to use
82 this function since goals automatically flattens lists within lists
83 into simple lists in many cases.
89 last (["a", "b", "c"]) ⇒ "c"
91 Returns the last element of a list.
97 nth (1, ["a", "b", "c"]) ⇒ "b"
99 Returns the n’th element of a list (counting from 0).
101 =head3 read (filename)
105 read ("filename") => "this is the content of filename"
107 Read the contents of C<filename> and return it as a single string.
108 If there is a trailing C<\n> in the file it is truncated.
110 =head3 readlines (filename)
114 readlines ("filename") => ["line1", "line2", "line3"]
116 Read the lines in C<filename> returning a list of strings.
118 =head3 realpath (filename)
122 realpath ("./tests") ⇒ "/home/user/tests"
124 Run the L<realpath(1)> command to return the resolved absolute path of
125 the C<filename> parameter.
131 sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
133 This takes a list of strings and sorts it, removing duplicates.
135 =head3 split (string)
139 split ("-g -O2") ⇒ ["-g", "-O2"]
141 Split a string using shell rules into a list of strings. This is
142 commonly used for splitting C<CFLAGS> provided by autoconf into a list
145 let CFLAGS = split ("@CFLAGS@")
146 goal compile (name) =
147 "%name.o" : "%name.c" { %CC %CFLAGS -c %< -o %@ }
149 =head3 subst (from, to, text)
153 subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
154 subst ("a.*c", "b", "aaacac") ⇒ "bb"
156 This function works something like make’s C<subst> function, except
157 that C<from> is a regular expression, specifically a L<sed(1)>
158 extended regular expression.
164 tail (["a", "b", "c"]) ⇒ ["b", "c"]
166 Returns the tail (all except first) elements of the list.
168 =head3 wildcard (pattern)
172 wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
174 The single parameter is a wildcard which is expanded into a list of
175 files using ordinary globbing rules.
177 =head3 wrap (wrapper, list)
181 wrap ("*file", ["bar.c", "foo.c"]) ⇒ [*file("bar.c"), *file("foo.c")]
183 Each element in C<list> is wrapped into a call to C<wrapper(element)>.
184 There are two common uses for this: either to add explicit tactics
185 (such as C<*file>) to a plain list of strings as in the example above;
186 or to turn a list of strings into a list of goal or function calls.
194 Richard W.M. Jones <rjones@redhat.com>
198 Copyright (C) 2020 Richard W.M. Jones
200 Copyright (C) 2020 Red Hat Inc.
202 This program is free software; you can redistribute it and/or modify
203 it under the terms of the GNU General Public License as published by
204 the Free Software Foundation; either version 2 of the License, or
205 (at your option) any later version.
207 This program is distributed in the hope that it will be useful,
208 but WITHOUT ANY WARRANTY; without even the implied warranty of
209 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
210 GNU General Public License for more details.
212 You should have received a copy of the GNU General Public License along
213 with this program; if not, write to the Free Software Foundation, Inc.,
214 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.