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 extension (filename)
  34
  35 For example:
  36
  37  extension ("dir/file.ext") ⇒ "ext"
  38
  39 Returns the filename extension.
  40
  41 =head3 join (list1, list2)
  42
  43 For example:
  44
  45  join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]
  46
  47 Concatenate C<list1> and C<list2>.  It's not usually necessary to use
  48 this function since goals automatically flattens lists within lists
  49 into simple lists in many cases.
  50
  51 =head3 sort (list)
  52
  53 For example:
  54
  55  sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]
  56
  57 This takes a list of strings and sorts it, removing duplicates.
  58
  59 =head3 subst (from, to, text)
  60
  61 For example:
  62
  63  subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
  64  subst ("a.*c", "b", "aaacac") ⇒ "bb"
  65
  66 This function works something like make’s C<subst> function, except
  67 that C<from> is a regular expression, specifically a L<sed(1)>
  68 extended regular expression.
  69
  70 =head3 wildcard (pattern)
  71
  72 For example:
  73
  74  wildcard ("*.c") ⇒ ["bar.c", "foo.c"]
  75
  76 The single parameter is a wildcard which is expanded into a list of
  77 files using ordinary globbing rules.
  78
  79 =head3 wrap (wrapper, list)
  80
  81 For example:
  82
  83  wrap ("*file", ["bar.c", "foo.c"]) ⇒ [*file("bar.c"), *file("foo.c")]
  84
  85 Each element in C<list> is wrapped into a call to C<wrapper(element)>.
  86 There are two common uses for this: either to add explicit tactics
  87 (such as C<*file>) to a plain list of strings as in the example above;
  88 or to turn a list of strings into a list of goal or function calls.
  89
  90 =head1 SEE ALSO
  91
  92 L<goals(1)>.
  93
  94 =head1 AUTHORS
  95
  96 Richard W.M. Jones <rjones@redhat.com>
  97
  98 =head1 COPYRIGHT
  99
 100 Copyright (C) 2020 Richard W.M. Jones
 101
 102 Copyright (C) 2020 Red Hat Inc.
 103
 104 This program is free software; you can redistribute it and/or modify
 105 it under the terms of the GNU General Public License as published by
 106 the Free Software Foundation; either version 2 of the License, or
 107 (at your option) any later version.
 108
 109 This program is distributed in the hope that it will be useful,
 110 but WITHOUT ANY WARRANTY; without even the implied warranty of
 111 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 112 GNU General Public License for more details.
 113
 114 You should have received a copy of the GNU General Public License along
 115 with this program; if not, write to the Free Software Foundation, Inc.,
 116 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.