NAME
    Goalfile - introduction, tutorial, and reference for writing goal files

SUMMARY
INTRODUCTION
TUTORIAL
REFERENCE
  Standard Variables
   %stdlib
    The path to the standard library directory. This path is also searched
    by default for "include" directives.

   %tmpdir
    The location of a temporary directory which is created by goals when it
    starts and is deleted when it exits (either on success or failure). You
    can use this to store any temporary files that you want automatically
    cleaned up.

  Standard Functions
   basename (path)
    For example:

     basename ("dir/file.ext") ⇒ "file.ext"

    Returns the filename part of the path.

   dirname (path)
    For example:

     dirname ("dir/file.ext") ⇒ "dir"

    Returns the directory part of the path.

   error (msg)
    For example:

     error ("this should not happen")

    This prints the error message and causes goals to exit.

   extension (filename)
    For example:

     extension ("dir/file.ext") ⇒ "ext"

    Returns the filename extension.

   filter (pattern, list)
    For example:

     filter ("a+", ["a", "b", "ca"]) ⇒ ["a", "ca"]

    Filter a list returning only the elements that match the extended
    regular expression "pattern".

   filter-out (pattern, list)
    For example:

     filter-out ("a+", ["a", "b", "ca"]) ⇒ ["b"]

    Filter a list returning only the elements that *do not* match the
    extended regular expression "pattern".

   head (list)
    For example:

     head (["a", "b", "c"]) ⇒ "a"

    Returns the head (first) element of the list.

   join (list1, list2)
    For example:

     join (["a", "b"], ["c", "d"]) ⇒ ["a", "b", "c", "d"]

    Concatenate "list1" and "list2". It's not usually necessary to use this
    function since goals automatically flattens lists within lists into
    simple lists in many cases.

   last (list)
    For example:

     last (["a", "b", "c"]) ⇒ "c"

    Returns the last element of a list.

   nth (n, list)
    For example:

     nth (1, ["a", "b", "c"]) ⇒ "b"

    Returns the n’th element of a list (counting from 0).

   read (filename)
    For example:

     read ("filename") => "this is the content of filename"

    Read the contents of "filename" and return it as a single string. If
    there is a trailing "\n" in the file it is truncated.

   readlines (filename)
    For example:

     readlines ("filename") => ["line1", "line2", "line3"]

    Read the lines in "filename" returning a list of strings.

   realpath (filename)
    For example:

     realpath ("./tests") ⇒ "/home/user/tests"

    Run the realpath(1) command to return the resolved absolute path of the
    "filename" parameter.

   sort (list)
    For example:

     sort (["c", "b", "b", "a"]) ⇒ ["a", "b", "c"]

    This takes a list of strings and sorts it, removing duplicates.

   split (string)
    For example:

     split ("-g -O2") ⇒ ["-g", "-O2"]

    Split a string using shell rules into a list of strings. This is
    commonly used for splitting "CFLAGS" provided by autoconf into a list
    for use by goals:

     let CFLAGS = split ("@CFLAGS@")
     goal compile (name) =
     "%name.o" : "%name.c" { %CC %CFLAGS -c %< -o %@ }

   subst (from, to, text)
    For example:

     subst ("aa", "AA", "aabbccaa") ⇒ "AAbbccAA"
     subst ("a.*c", "b", "aaacac") ⇒ "bb"

    This function works something like make’s "subst" function, except that
    "from" is a regular expression, specifically a sed(1) extended regular
    expression.

   tail (list)
    For example:

     tail (["a", "b", "c"]) ⇒ ["b", "c"]

    Returns the tail (all except first) elements of the list.

   wildcard (pattern)
    For example:

     wildcard ("*.c") ⇒ ["bar.c", "foo.c"]

    The single parameter is a wildcard which is expanded into a list of
    files using ordinary globbing rules.

   wrap (wrapper, list)
    For example:

     wrap ("is-file", ["bar.c", "foo.c"]) ⇒ [is-file("bar.c"), is-file("foo.c")]

    Each element in "list" is wrapped into a call to "wrapper(element)".
    There are two common uses for this: either to add explicit predicates
    (such as "is-file") to a plain list of strings as in the example above;
    or to turn a list of strings into a list of goal or function calls.

  Standard Shell Functions
   quoted_string
    Quote a string which will be consumed as a goal expression. This is
    typically used from within goal functions which return expressions (ie.
    ones which do *not* have an explicit "returning" declaration). You must
    not use this shell function with functions that are marked as "returning
    string" or "returning strings".

   print_green
    Echo a string in green. Useful for success/OK messages.

   print_red
    Echo a string in red. Useful for error messages.

SEE ALSO
    goals(1).

AUTHORS
    Richard W.M. Jones <rjones@redhat.com>

COPYRIGHT
    Copyright (C) 2020 Richard W.M. Jones

    Copyright (C) 2020 Red Hat Inc.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.