aboutsummaryrefslogtreecommitdiff
path: root/libbuild2/functions-path.cxx
diff options
context:
space:
mode:
Diffstat (limited to 'libbuild2/functions-path.cxx')
-rw-r--r--libbuild2/functions-path.cxx198
1 files changed, 127 insertions, 71 deletions
diff --git a/libbuild2/functions-path.cxx b/libbuild2/functions-path.cxx
index 020c8f4..4b114f5 100644
--- a/libbuild2/functions-path.cxx
+++ b/libbuild2/functions-path.cxx
@@ -198,8 +198,15 @@ namespace build2
{
function_family f (m, "path", &path_thunk);
- // string
+ // $string(<paths>)
//
+ // Return the traditional string representation of a path (or a list of
+ // string representations for a list of paths). In particular, for
+ // directory paths, the traditional representation does not include the
+ // trailing directory separator (except for the POSIX root directory). See
+ // `$representation()` below for the precise string representation.
+ //
+
// Note that we must handle NULL values (relied upon by the parser
// to provide conversion semantics consistent with untyped values).
//
@@ -224,7 +231,12 @@ namespace build2
return r;
};
- // posix_string
+ // $posix_string(<paths>)
+ // $path.posix_string(<untyped>)
+ //
+ // Return the traditional string representation of a path (or a list of
+ // string representations for a list of paths) using the POSIX directory
+ // separators (forward slashes).
//
f["posix_string"] += [](path p) {return posix_string (move (p));};
f["posix_string"] += [](dir_path p) {return posix_string (move (p));};
@@ -259,7 +271,13 @@ namespace build2
return ns;
};
- // representation
+ // $representation(<paths>)
+ //
+ // Return the precise string representation of a path (or a list of string
+ // representations for a list of paths). In particular, for directory
+ // paths, the precise representation includes the trailing directory
+ // separator. See `$string()` above for the traditional string
+ // representation.
//
f["representation"] += [](path p) {return move (p).representation ();};
@@ -279,7 +297,12 @@ namespace build2
return r;
};
- // posix_representation
+ // $posix_representation(<paths>)
+ // $path.posix_representation(<untyped>)
+ //
+ // Return the precise string representation of a path (or a list of string
+ // representations for a list of paths) using the POSIX directory
+ // separators (forward slashes).
//
f["posix_representation"] += [](path p)
{
@@ -321,8 +344,14 @@ namespace build2
return ns;
};
- // canonicalize
+ // $canonicalize(<paths>)
+ // $path.canonicalize(<untyped>)
+ //
+ // Canonicalize the path (or list of paths) by converting all the
+ // directory separators to the canonical form for the host platform. Note
+ // that multiple directory separators are not collapsed.
//
+
// @@ TODO: add ability to specify alternative separator.
//
f["canonicalize"] += [](path p) {p.canonicalize (); return p;};
@@ -358,7 +387,13 @@ namespace build2
return ns;
};
- // normalize
+ // $normalize(<paths>)
+ // $path.normalize(<untyped>)
+ //
+ // Normalize the path (or list of paths) by collapsing the `.` and `..`
+ // components if possible, collapsing multiple directory separators, and
+ // converting all the directory separators to the canonical form for the
+ // host platform.
//
f["normalize"] += [](path p) {p.normalize (); return p;};
f["normalize"] += [](dir_path p) {p.normalize (); return p;};
@@ -393,7 +428,16 @@ namespace build2
return ns;
};
- // actualize
+ // $actualize(<paths>)
+ // $path.actualize(<untyped>)
+ //
+ // Actualize the path (or list of paths) by first normalizing it and then
+ // for host platforms with case-insensitive filesystems obtaining the
+ // actual spelling of the path.
+ //
+ // Note that only an absolute path can be actualized. If a path component
+ // does not exist, then its (and all subsequent) spelling is
+ // unchanged. This is a potentially expensive operation.
//
// Note that this function is not pure.
//
@@ -434,11 +478,12 @@ namespace build2
return ns;
};
- // $directory(<path>)
// $directory(<paths>)
+ // $path.directory(<untyped>)
//
- // Return the directory part of the path or empty path if there is no
- // directory. Directory of a root directory is an empty path.
+ // Return the directory part of a path (or a list of directory parts for a
+ // list of paths) or an empty path if there is no directory. A directory of
+ // a root directory is an empty path.
//
f["directory"] += &path::directory;
@@ -472,11 +517,12 @@ namespace build2
return ns;
};
- // $root_directory(<path>)
// $root_directory(<paths>)
+ // $path.root_directory(<untyped>)
//
- // Return the root directory of the path or empty path if the directory is
- // not absolute.
+ // Return the root directory of a path (or a list of root directories for
+ // a list of paths) or an empty path if the specified path is not
+ // absolute.
//
f["root_directory"] += &path::root_directory;
@@ -510,17 +556,22 @@ namespace build2
return ns;
};
- // $leaf(<path>)
- //
- f["leaf"] += &path::leaf;
-
- // $leaf(<path>, <dir-path>)
+ // $leaf(<paths>)
+ // $path.leaf(<untyped>)
// $leaf(<paths>, <dir-path>)
+ // $path.leaf(<untyped>, <dir-path>)
//
- // Return the path without the specified directory part. Return empty path
- // if the paths are the same. Issue diagnostics and fail if the directory
- // is not a prefix of the path. Note: expects both paths to be normalized.
+ // First form (one argument): return the last component of a path (or a
+ // list of last components for a list of paths).
//
+ // Second form (two arguments): return a path without the specified
+ // directory part (or a list of paths without the directory part for a
+ // list of paths). Return an empty path if the paths are the same. Issue
+ // diagnostics and fail if the directory is not a prefix of the
+ // path. Note: expects both paths to be normalized.
+ //
+ f["leaf"] += &path::leaf;
+
f["leaf"] += [](path p, dir_path d)
{
return leaf (p, move (d));
@@ -556,13 +607,13 @@ namespace build2
return ns;
};
- // $relative(<path>, <dir-path>)
// $relative(<paths>, <dir-path>)
+ // $path.relative(<untyped>, <dir-path>)
//
- // Return a path relative to the specified directory that is equivalent to
- // the specified path. Issue diagnostics and fail if a relative path
- // cannot be derived (for example, paths are on different drives on
- // Windows).
+ // Return the path relative to the specified directory that is equivalent
+ // to the specified path (or a list of relative paths for a list of
+ // specified paths). Issue diagnostics and fail if a relative path cannot
+ // be derived (for example, paths are on different drives on Windows).
//
f["relative"] += [](path p, dir_path d)
{
@@ -599,7 +650,11 @@ namespace build2
return ns;
};
- // base
+ // $base(<paths>)
+ // $path.base(<untyped>)
+ //
+ // Return the base part (without the extension) of a path (or a list of
+ // base parts for a list of paths).
//
f["base"] += &path::base;
@@ -633,7 +688,11 @@ namespace build2
return ns;
};
- // extension
+ // $extension(<path>)
+ // $path.extension(<untyped>)
+ //
+ // Return the extension part (without the dot) of a path or empty string
+ // if there is no extension.
//
f["extension"] += &extension;
@@ -643,32 +702,29 @@ namespace build2
};
// $size(<paths>)
- // $size(<dir_paths>)
+ // $size(<path>)
+ //
+ // First form: return the number of elements in the paths sequence.
+ //
+ // Second form: return the number of characters (bytes) in the path. Note
+ // that for `dir_path` the result does not include the trailing directory
+ // separator (except for the POSIX root directory).
//
- // Return the number of elements in the sequence.
//
f["size"] += [] (paths v) {return v.size ();};
f["size"] += [] (dir_paths v) {return v.size ();};
- // $size(<path>)
- // $size(<dir_path>)
- //
- // Return the number of characters (bytes) in the path. Note that for
- // dir_path the result does not include the trailing directory separator
- // (except for the POSIX root directory).
- //
f["size"] += [] (path v) {return v.size ();};
f["size"] += [] (dir_path v) {return v.size ();};
- // $sort(<paths> [, <flags>])
- // $sort(<dir_paths> [, <flags>])
+ // $sort(<paths>[, <flags>])
//
- // Sort paths in ascending order. Note that on hosts with a case-
- // insensitive filesystem the order is case-insensitive.
+ // Sort paths in ascending order. Note that on host platforms with a
+ // case-insensitive filesystem the order is case-insensitive.
//
// The following flags are supported:
//
- // dedup - in addition to sorting also remove duplicates
+ // dedup - in addition to sorting also remove duplicates
//
f["sort"] += [](paths v, optional<names> fs)
{
@@ -691,11 +747,10 @@ namespace build2
};
// $find(<paths>, <path>)
- // $find(<dir_paths>, <dir_path>)
//
- // Return true if the path sequence contains the specified path. Note that
- // on hosts with a case-insensitive filesystem the comparison is
- // case-insensitive.
+ // Return true if the paths sequence contains the specified path. Note
+ // that on host platforms with a case-insensitive filesystem the
+ // comparison is case-insensitive.
//
f["find"] += [](paths vs, value v)
{
@@ -710,12 +765,11 @@ namespace build2
};
// $find_index(<paths>, <path>)
- // $find_index(<dir_paths>, <dir_path>)
//
- // Return the index of the first element in the path sequence that is
- // equal to the specified path or $size(<paths>) if none is found. Note
- // that on hosts with a case-insensitive filesystem the comparison is
- // case-insensitive.
+ // Return the index of the first element in the paths sequence that is
+ // equal to the specified path or `$size(paths)` if none is found. Note
+ // that on host platforms with a case-insensitive filesystem the
+ // comparison is case-insensitive.
//
f["find_index"] += [](paths vs, value v)
{
@@ -729,34 +783,36 @@ namespace build2
return i != vs.end () ? i - vs.begin () : vs.size ();
};
- // $path.match(<val>, <pat> [, <start>])
+ // $path.match(<entry>, <pattern>[, <start-dir>])
//
- // Match a filesystem entry name against a name pattern (both are strings),
- // or a filesystem entry path against a path pattern. For the latter case
- // the start directory may also be required (see below). The semantics of
- // the pattern and name/entry arguments is determined according to the
+ // Match a filesystem entry name against a name pattern (both are
+ // strings), or a filesystem entry path against a path pattern. For the
+ // latter case the start directory may also be required (see below). The
+ // pattern is a shell-like wildcard pattern. The semantics of the
+ // <pattern> and <entry> arguments is determined according to the
// following rules:
//
- // - The arguments must be of the string or path types, or be untyped.
+ // 1. The arguments must be of the string or path types, or be untyped.
//
- // - If one of the arguments is typed, then the other one must be of the
- // same type or be untyped. In the later case, an untyped argument is
- // converted to the type of the other argument.
+ // 2. If one of the arguments is typed, then the other one must be of the
+ // same type or be untyped. In the later case, an untyped argument is
+ // converted to the type of the other argument.
//
- // - If both arguments are untyped and the start directory is specified,
- // then the arguments are converted to the path type.
+ // 3. If both arguments are untyped and the start directory is specified,
+ // then the arguments are converted to the path type.
//
- // - If both arguments are untyped and the start directory is not
- // specified, then, if one of the arguments is syntactically a path (the
- // value contains a directory separator), convert them to the path type,
- // otherwise to the string type (match as names).
+ // 4. If both arguments are untyped and the start directory is not
+ // specified, then, if one of the arguments is syntactically a path (the
+ // value contains a directory separator), then they are converted to the
+ // path type, otherwise -- to the string type (match as names).
//
- // If pattern and entry paths are both either absolute or relative and
- // non-empty, and the first pattern component is not a self-matching
- // wildcard (doesn't contain ***), then the start directory is not
- // required, and is ignored if specified. Otherwise, the start directory
- // must be specified and be an absolute path.
+ // If pattern and entry paths are both either absolute or relative and not
+ // empty, and the first pattern component is not a self-matching wildcard
+ // (doesn't contain `***`), then the start directory is not required, and
+ // is ignored if specified. Otherwise, the start directory must be
+ // specified and be an absolute path.
//
+
// Name matching.
//
f[".match"] += [](string name, string pattern)