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