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 Functions
  16
  17 =head3 basename (path)
  18
  19 For example:
  20
  21  basename ("dir/file.ext") ⇒ "file.ext"
  22
  23 Returns the filename part of the path.
  24
  25 =head3 dirname (path)
  26
  27 For example:
  28
  29  dirname ("dir/file.ext") ⇒ "dir"
  30
  31 Returns the directory part of the path.
  32
  33 =head3 error (msg)
  34
  35 For example:
  36
  37  error ("this should not happen")
  38
  39 This prints the error message and causes goals to exit.
  40
  41 =head3 extension (filename)
  42
  43 For example:
  44
  45  extension ("dir/file.ext") ⇒ "ext"
  46
  47 Returns the filename extension.
  48
  49 =head3 filter (pattern, list)
  50
  51 For example:
  52
  53  filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]
  54
  55 Filter a list returning only the elements that match the extended
  56 regular expression C<pattern>.
  57
  58 =head3 filter-out (pattern, list)
  59
  60 For example:
  61
  62  filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]
  63
  64 Filter a list returning only the elements that I<do not> match the
  65 extended regular expression C<pattern>.
  66
  67 =head3 head (list)
  68
  69 For example:
  70
  71  head (["a", "b", "c"]) ⇒ "a"
  72
  73 Returns the head (first) element of the list.
  74
  75 =head3 join (list1, list2)
  76
  77 For example:
  78
  79  join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
  80
  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.
  84
  85 =head3 read (filename)
  86
  87 For example:
  88
  89  read ("filename") => "this is the content of filename"
  90
  91 Read the contents of C<filename> and return it as a single string.
  92 If there is a trailing C<\n> in the file it is truncated.
  93
  94 =head3 readlines (filename)
  95
  96 For example:
  97
  98  readlines ("filename") => ["line1", "line2", "line3"]
  99
 100 Read the lines in C<filename> returning a list of strings.
 101
 102 =head3 realpath (filename)
 103
 104 For example:
 105
 106  realpath ("./tests") ⇒ "/home/user/tests"
 107
 108 Run the L<realpath(1)> command to return the resolved absolute path of
 109 the C<filename> parameter.
 110
 111 =head3 sort (list)
 112
 113 For example:
 114
 115  sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
 116
 117 This takes a list of strings and sorts it, removing duplicates.
 118
 119 =head3 subst (from, to, text)
 120
 121 For example:
 122
 123  subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
 124  subst ("a.*c", "b", "aaacac") ⇒ "bb"
 125
 126 This function works something like make’s C<subst> function, except
 127 that C<from> is a regular expression, specifically a L<sed(1)>
 128 extended regular expression.
 129
 130 =head3 tail (list)
 131
 132 For example:
 133
 134  tail (["a", "b", "c"]) ⇒ ["b", "c"]
 135
 136 Returns the tail (all except first) elements of the list.
 137
 138 =head3 wildcard (pattern)
 139
 140 For example:
 141
 142  wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
 143
 144 The single parameter is a wildcard which is expanded into a list of
 145 files using ordinary globbing rules.
 146
 147 =head3 wrap (wrapper, list)
 148
 149 For example:
 150
 151  wrap ("*file", ["bar.c", "foo.c"]) ⇒ [*file("bar.c"), *file("foo.c")]
 152
 153 Each element in C<list> is wrapped into a call to C<wrapper(element)>.
 154 There are two common uses for this: either to add explicit tactics
 155 (such as C<*file>) to a plain list of strings as in the example above;
 156 or to turn a list of strings into a list of goal or function calls.
 157
 158 =head1 SEE ALSO
 159
 160 L<goals(1)>.
 161
 162 =head1 AUTHORS
 163
 164 Richard W.M. Jones <rjones@redhat.com>
 165
 166 =head1 COPYRIGHT
 167
 168 Copyright (C) 2020 Richard W.M. Jones
 169
 170 Copyright (C) 2020 Red Hat Inc.
 171
 172 This program is free software; you can redistribute it and/or modify
 173 it under the terms of the GNU General Public License as published by
 174 the Free Software Foundation; either version 2 of the License, or
 175 (at your option) any later version.
 176
 177 This program is distributed in the hope that it will be useful,
 178 but WITHOUT ANY WARRANTY; without even the implied warranty of
 179 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 180 GNU General Public License for more details.
 181
 182 You should have received a copy of the GNU General Public License along
 183 with this program; if not, write to the Free Software Foundation, Inc.,
 184 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.