# path

Performs various path manipulations. Paths are always in a 'normalized' representation. In it, a path may be either:

- `'.'`, or

- `['/'] [ ( '..' '/' )* (token '/')* token ]`

In plain english, a path can be rooted, `'..'` elements are allowed only at the beginning, and it never ends in slash, except for the path consisting of slash only.

1. `rule make ( native )`

   Converts the native path into normalized form.

2. `rule native ( path )`

   Builds the native representation of the path.

3. `rule is-rooted ( path )`

   Tests if a path is rooted.

4. `rule has-parent ( path )`

   Tests if a path has a parent.

5. `rule basename ( path )`

   Returns the path without any directory components.

6. `rule parent ( path )`

   Returns the parent directory of the path. If no parent exists, an error is issued.

7. `rule reverse ( path )`

   Returns `path2` such that `[ join path path2 ] = "."`. The path may not contain `".."` element or be rooted.

8. `rule join ( elements + )`

   Concatenates the passed path elements. Generates an error if any element other than the first one is rooted. Skips any empty or undefined path elements.

9. `rule root ( path root )`

   If `path` is relative, it is rooted at `root`. Otherwise, it is unchanged.

10. `rule pwd ( )`

    Returns the current working directory.

11. `rule glob ( dirs * : patterns + : exclude-patterns * )`

    Returns the list of files matching the given pattern in the specified directory. Both directories and patterns are supplied as portable paths. Each pattern should be a non-absolute path, and can't contain "." or ".." elements. Each slash separated element of a pattern can contain the following special characters:

    - '?' matches any character

    - '*' matches an arbitrary number of characters

    A file $(d)/e1/e2/e3 (where 'd' is in $(dirs)) matches the pattern p1/p2/p3 if and only if e1 matches p1, e2 matches p2 and so on.

    For example:

        [ glob . : *.cpp ]
        [ glob . : */build/Jamfile ]

12. `rule glob-tree ( roots * : patterns + : exclude-patterns * )`

    Recursive version of glob. Builds the glob of files while also searching in the subdirectories of the given roots. An optional set of exclusion patterns will filter out the matching entries from the result. The exclusions also apply to the subdirectory scanning, such that directories that match the exclusion patterns will not be searched.

13. `rule exists ( file )`

    Returns true if the specified file exists.

14. `rule all-parents ( path : upper_limit ? : cwd ? )`

    Find out the absolute name of path and return the list of all the parents, starting with the immediate one. Parents are returned as relative names. If `upper_limit` is specified, directories above it will be pruned.

15. `rule glob-in-parents ( dir : patterns + : upper-limit ? )`

    Search for `patterns` in parent directories of `dir`, up to and including `upper_limit`, if it is specified, or till the filesystem root otherwise.

16. `rule relative ( child parent : no-error ? )`

    Assuming `child` is a subdirectory of `parent`, return the relative path from `parent` to `child`.

17. `rule relative-to ( path1 path2 )`

    Returns the minimal path to path2 that is relative path1.

18. `rule programs-path ( )`

    Returns the list of paths which are used by the operating system for looking up programs.

19. `rule makedirs ( path )`

    Creates a directory and all parent directories that do not already exist.