docs/Goalfile.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 Goalfile - introduction, tutorial, and reference for writing goal files
   6
   7 =head1 SUMMARY
   8
   9 =head1 INTRODUCTION
  10
  11 =head1 TUTORIAL
  12
  13 =head1 REFERENCE
  14
  15 =head2 Standard Variables
  16
  17 =head3 %stdlib
  18
  19 The path to the standard library directory.  This path is also
  20 searched by default for C<include> directives.
  21
  22 =head3 %tmpdir
  23
  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.
  28
  29 =head2 Standard Functions
  30
  31 =head3 basename (path)
  32
  33 For example:
  34
  35  basename ("dir/file.ext") ⇒ "file.ext"
  36
  37 Returns the filename part of the path.
  38
  39 =head3 dirname (path)
  40
  41 For example:
  42
  43  dirname ("dir/file.ext") ⇒ "dir"
  44
  45 Returns the directory part of the path.
  46
  47 =head3 error (msg)
  48
  49 For example:
  50
  51  error ("this should not happen")
  52
  53 This prints the error message and causes goals to exit.
  54
  55 =head3 extension (filename)
  56
  57 For example:
  58
  59  extension ("dir/file.ext") ⇒ "ext"
  60
  61 Returns the filename extension.
  62
  63 =head3 filter (pattern, list)
  64
  65 For example:
  66
  67  filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]
  68
  69 Filter a list returning only the elements that match the extended
  70 regular expression C<pattern>.
  71
  72 =head3 filter-out (pattern, list)
  73
  74 For example:
  75
  76  filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]
  77
  78 Filter a list returning only the elements that I<do not> match the
  79 extended regular expression C<pattern>.
  80
  81 =head3 head (list)
  82
  83 For example:
  84
  85  head (["a", "b", "c"]) ⇒ "a"
  86
  87 Returns the head (first) element of the list.
  88
  89 =head3 join (list1, list2)
  90
  91 For example:
  92
  93  join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
  94
  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.
  98
  99 =head3 last (list)
 100
 101 For example:
 102
 103  last (["a", "b", "c"]) ⇒ "c"
 104
 105 Returns the last element of a list.
 106
 107 =head3 nth (n, list)
 108
 109 For example:
 110
 111  nth (1, ["a", "b", "c"]) ⇒ "b"
 112
 113 Returns the n’th element of a list (counting from 0).
 114
 115 =head3 read (filename)
 116
 117 For example:
 118
 119  read ("filename") => "this is the content of filename"
 120
 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.
 123
 124 =head3 readlines (filename)
 125
 126 For example:
 127
 128  readlines ("filename") => ["line1", "line2", "line3"]
 129
 130 Read the lines in C<filename> returning a list of strings.
 131
 132 =head3 realpath (filename)
 133
 134 For example:
 135
 136  realpath ("./tests") ⇒ "/home/user/tests"
 137
 138 Run the L<realpath(1)> command to return the resolved absolute path of
 139 the C<filename> parameter.
 140
 141 =head3 sort (list)
 142
 143 For example:
 144
 145  sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
 146
 147 This takes a list of strings and sorts it, removing duplicates.
 148
 149 =head3 split (string)
 150
 151 For example:
 152
 153  split ("-g -O2") ⇒ ["-g", "-O2"]
 154
 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
 157 for use by goals:
 158
 159  let CFLAGS = split ("@CFLAGS@")
 160  goal compile (name) =
 161  "%name.o" : "%name.c" { %CC %CFLAGS -c %< -o %@ }
 162
 163 =head3 subst (from, to, text)
 164
 165 For example:
 166
 167  subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
 168  subst ("a.*c", "b", "aaacac") ⇒ "bb"
 169
 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.
 173
 174 =head3 tail (list)
 175
 176 For example:
 177
 178  tail (["a", "b", "c"]) ⇒ ["b", "c"]
 179
 180 Returns the tail (all except first) elements of the list.
 181
 182 =head3 wildcard (pattern)
 183
 184 For example:
 185
 186  wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
 187
 188 The single parameter is a wildcard which is expanded into a list of
 189 files using ordinary globbing rules.
 190
 191 =head3 wrap (wrapper, list)
 192
 193 For example:
 194
 195  wrap ("is-file", ["bar.c", "foo.c"]) ⇒ [is-file("bar.c"), is-file("foo.c")]
 196
 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.
 201
 202 =head2 Standard Shell Functions
 203
 204 =head3 quoted_string
 205
 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>.
 211
 212 =head3 print_green
 213
 214 Echo a string in green.  Useful for success/OK messages.
 215
 216 =head3 print_red
 217
 218 Echo a string in red.  Useful for error messages.
 219
 220 =head1 SEE ALSO
 221
 222 L<goals(1)>.
 223
 224 =head1 AUTHORS
 225
 226 Richard W.M. Jones <rjones@redhat.com>
 227
 228 =head1 COPYRIGHT
 229
 230 Copyright (C) 2020 Richard W.M. Jones
 231
 232 Copyright (C) 2020 Red Hat Inc.
 233
 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.
 238
 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.
 243
 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.