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 %tmpdir
  18
  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.
  23
  24 =head2 Standard Functions
  25
  26 =head3 basename (path)
  27
  28 For example:
  29
  30  basename ("dir/file.ext") ⇒ "file.ext"
  31
  32 Returns the filename part of the path.
  33
  34 =head3 dirname (path)
  35
  36 For example:
  37
  38  dirname ("dir/file.ext") ⇒ "dir"
  39
  40 Returns the directory part of the path.
  41
  42 =head3 error (msg)
  43
  44 For example:
  45
  46  error ("this should not happen")
  47
  48 This prints the error message and causes goals to exit.
  49
  50 =head3 extension (filename)
  51
  52 For example:
  53
  54  extension ("dir/file.ext") ⇒ "ext"
  55
  56 Returns the filename extension.
  57
  58 =head3 filter (pattern, list)
  59
  60 For example:
  61
  62  filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]
  63
  64 Filter a list returning only the elements that match the extended
  65 regular expression C<pattern>.
  66
  67 =head3 filter-out (pattern, list)
  68
  69 For example:
  70
  71  filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]
  72
  73 Filter a list returning only the elements that I<do not> match the
  74 extended regular expression C<pattern>.
  75
  76 =head3 head (list)
  77
  78 For example:
  79
  80  head (["a", "b", "c"]) ⇒ "a"
  81
  82 Returns the head (first) element of the list.
  83
  84 =head3 join (list1, list2)
  85
  86 For example:
  87
  88  join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
  89
  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.
  93
  94 =head3 last (list)
  95
  96 For example:
  97
  98  last (["a", "b", "c"]) ⇒ "c"
  99
 100 Returns the last element of a list.
 101
 102 =head3 nth (n, list)
 103
 104 For example:
 105
 106  nth (1, ["a", "b", "c"]) ⇒ "b"
 107
 108 Returns the n’th element of a list (counting from 0).
 109
 110 =head3 read (filename)
 111
 112 For example:
 113
 114  read ("filename") => "this is the content of filename"
 115
 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.
 118
 119 =head3 readlines (filename)
 120
 121 For example:
 122
 123  readlines ("filename") => ["line1", "line2", "line3"]
 124
 125 Read the lines in C<filename> returning a list of strings.
 126
 127 =head3 realpath (filename)
 128
 129 For example:
 130
 131  realpath ("./tests") ⇒ "/home/user/tests"
 132
 133 Run the L<realpath(1)> command to return the resolved absolute path of
 134 the C<filename> parameter.
 135
 136 =head3 sort (list)
 137
 138 For example:
 139
 140  sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
 141
 142 This takes a list of strings and sorts it, removing duplicates.
 143
 144 =head3 split (string)
 145
 146 For example:
 147
 148  split ("-g -O2") ⇒ ["-g", "-O2"]
 149
 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
 152 for use by goals:
 153
 154  let CFLAGS = split ("@CFLAGS@")
 155  goal compile (name) =
 156  "%name.o" : "%name.c" { %CC %CFLAGS -c %< -o %@ }
 157
 158 =head3 subst (from, to, text)
 159
 160 For example:
 161
 162  subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
 163  subst ("a.*c", "b", "aaacac") ⇒ "bb"
 164
 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.
 168
 169 =head3 tail (list)
 170
 171 For example:
 172
 173  tail (["a", "b", "c"]) ⇒ ["b", "c"]
 174
 175 Returns the tail (all except first) elements of the list.
 176
 177 =head3 wildcard (pattern)
 178
 179 For example:
 180
 181  wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
 182
 183 The single parameter is a wildcard which is expanded into a list of
 184 files using ordinary globbing rules.
 185
 186 =head3 wrap (wrapper, list)
 187
 188 For example:
 189
 190  wrap ("is-file", ["bar.c", "foo.c"]) ⇒ [is-file("bar.c"), is-file("foo.c")]
 191
 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.
 196
 197 =head1 SEE ALSO
 198
 199 L<goals(1)>.
 200
 201 =head1 AUTHORS
 202
 203 Richard W.M. Jones <rjones@redhat.com>
 204
 205 =head1 COPYRIGHT
 206
 207 Copyright (C) 2020 Richard W.M. Jones
 208
 209 Copyright (C) 2020 Red Hat Inc.
 210
 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.
 215
 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.
 220
 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.