path.jam

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

# Copyright Vladimir Prus 2002-2006.
# Copyright Dave Abrahams 2003-2004.
# Copyright Rene Rivera 2003-2006.
#
# Distributed under the Boost Software License, Version 1.0.
#    (See accompanying file LICENSE_1_0.txt or copy at
#          http://www.boost.org/LICENSE_1_0.txt)

# Performs various path manipulations. Paths are always in a 'normalized'
# representation. In it, a path may be either:
#
#     - '.', or
#
#     - ['/'] [ ( '..' '/' )* (token '/')* token ]
#
# In plain english, path can be rooted, '..' elements are allowed only at the
# beginning, and it never ends in slash, except for path consisting of slash
# only.

import errors ;
import modules ;
import regex ;
import sequence ;
import set ;
import version ;


os = [ modules.peek : OS ] ;
if [ modules.peek : UNIX ]
{
    local uname = [ modules.peek : JAMUNAME ] ;
    switch $(uname)
    {
        case CYGWIN* : os = CYGWIN ;
        case *       : os = UNIX ;
    }
}


# Converts the native path into normalized form.
#
rule make ( native )
{
    return [ make-$(os) $(native) ] ;
}


# Builds native representation of the path.
#
rule native ( path )
{
    return [ native-$(os) $(path) ] ;
}


# Tests if a path is rooted.
#
rule is-rooted ( path )
{
    return [ MATCH "^(/)" : $(path) ] ;
}


# Tests if a path has a parent.
#
rule has-parent ( path )
{
    if $(path) != /
    {
        return 1 ;
    }
    else
    {
        return ;
    }
}


# Returns the path without any directory components.
#
rule basename ( path )
{
    return [ MATCH "([^/]+)$" : $(path) ] ;
}


# Returns parent directory of the path. If no parent exists, error is issued.
#
rule parent ( path )
{
    if [ has-parent $(path) ]
    {
        if $(path) = .
        {
            return .. ;
        }
        else
        {
            # Strip everything at the end of path up to and including the last
            # slash.
            local result = [ regex.match "((.*)/)?([^/]+)" : $(path) : 2 3 ] ;

            # Did we strip what we shouldn't?
            if $(result[2]) = ".."
            {
                return $(path)/.. ;
            }
            else
            {
                if ! $(result[1])
                {
                    if [ is-rooted $(path) ]
                    {
                        result = / ;
                    }
                    else
                    {
                        result = . ;
                    }
                }
                return $(result[1]) ;
            }
        }
    }
    else
    {
        errors.error "Path '$(path)' has no parent" ;
    }
}


# Returns path2 such that "[ join path path2 ] = .". The path may not contain
# ".." element or be rooted.
#
rule reverse ( path )
{
    if $(path) = .
    {
        return $(path) ;
    }
    else
    {
        local tokens = [ regex.split $(path) "/" ] ;
        local tokens2 ;
        for local i in $(tokens)
        {
            tokens2 += .. ;
        }
        return [ sequence.join $(tokens2) : "/" ] ;
    }
}


# 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.
#
rule join ( elements + )
{
    if ! $(elements[2-])
    {
        return $(elements[1]) ;
    }
    else
    {
        for local e in $(elements[2-])
        {
            if [ is-rooted $(e) ]
            {
                errors.error only the first element may be rooted ;
            }
        }
        if [ version.check-jam-version 3 1 17 ]
        {
            return [ NORMALIZE_PATH "$(elements)" ] ;
        }
        else
        {
            # Boost Jam prior to version 3.1.17 had problems with its
            # NORMALIZE_PATH rule in case you passed it a leading backslash
            # instead of a slash, in some cases when you sent it an empty
            # initial path element and possibly some others. At least some of
            # those cases were being hit and relied upon when calling this rule
            # from the path.make-NT rule.
            if ! $(elements[1]) && $(elements[2])
            {
                return [ NORMALIZE_PATH "/" "$(elements[2-])" ] ;
            }
            else
            {
                return [ NORMALIZE_PATH "$(elements)" ] ;
            }
        }
    }
}


# If 'path' is relative, it is rooted at 'root'. Otherwise, it is unchanged.
#
rule root ( path root )
{
    if [ is-rooted $(path) ]
    {
        return $(path) ;
    }
    else
    {
        return [ join $(root) $(path) ] ;
    }
}


# Returns the current working directory.
#
rule pwd ( )
{
    if ! $(.pwd)
    {
        .pwd = [ make [ PWD ] ] ;
    }
    return $(.pwd) ;
}


# 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 non-absolute path, and can't contain "." or ".." elements.
# Each slash separated element of pattern can contain the following special
# characters:
#   - '?', which match any character
#   - '*', which matches arbitrary number of characters.
# A file $(d)/e1/e2/e3 (where 'd' is in $(dirs)) matches pattern p1/p2/p3 if and
# only if e1 matches p1, e2 matches p2 and so on.
#
# For example:
#   [ glob . : *.cpp ]
#   [ glob . : */build/Jamfile ]
#
rule glob ( dirs * : patterns + : exclude-patterns * )
{
    local result ;
    local real-patterns ;
    local real-exclude-patterns ;
    for local d in $(dirs)
    {
        for local p in $(patterns)
        {
            local pattern = [ path.root $(p) $(d) ] ;
            real-patterns += [ path.native $(pattern) ] ;
        }

        for local p in $(exclude-patterns)
        {
            local pattern = [ path.root $(p) $(d) ] ;
            real-exclude-patterns += [ path.native $(pattern) ] ;
        }
    }

    local inc = [ GLOB-RECURSIVELY $(real-patterns) ] ;
    inc = [ sequence.transform NORMALIZE_PATH : $(inc) ] ;
    local exc = [ GLOB-RECURSIVELY $(real-exclude-patterns) ] ;
    exc = [ sequence.transform NORMALIZE_PATH : $(exc) ] ;

    return [ sequence.transform path.make : [ set.difference $(inc) : $(exc) ] ]
        ;
}


# 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.
#
rule glob-tree ( roots * : patterns + : exclude-patterns * )
{
    return [ sequence.transform path.make : [ .glob-tree [ sequence.transform
        path.native : $(roots) ] : $(patterns) : $(exclude-patterns) ] ] ;
}


local rule .glob-tree ( roots * : patterns * : exclude-patterns * )
{
    local excluded ;
    if $(exclude-patterns)
    {
        excluded = [ GLOB $(roots) : $(exclude-patterns) ] ;
    }
    local result = [ set.difference [ GLOB $(roots) : $(patterns) ] :
        $(excluded) ] ;
    local subdirs ;
    for local d in [ set.difference [ GLOB $(roots) : * ] : $(excluded) ]
    {
        if ! ( $(d:D=) in . .. ) && ! [ CHECK_IF_FILE $(d) ]
        {
            subdirs += $(d) ;
        }
    }
    if $(subdirs)
    {
        result += [ .glob-tree $(subdirs) : $(patterns) : $(exclude-patterns) ]
            ;
    }
    return $(result) ;
}


# Returns true is the specified file exists.
#
rule exists ( file )
{
    return [ path.glob $(file:D) : $(file:D=) ] ;
}
NATIVE_RULE path : exists ;


# Find out the absolute name of path and returns 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.
#
rule all-parents ( path : upper_limit ? : cwd ? )
{
    cwd ?= [ pwd ] ;
    local path_ele = [ regex.split [ root $(path) $(cwd) ] "/" ] ;

    if ! $(upper_limit)
    {
        upper_limit = / ;
    }
    local upper_ele = [ regex.split [ root $(upper_limit) $(cwd) ] "/" ] ;

    # Leave only elements in 'path_ele' below 'upper_ele'.
    while $(path_ele) && ( $(upper_ele[1]) = $(path_ele[1]) )
    {
        upper_ele = $(upper_ele[2-]) ;
        path_ele = $(path_ele[2-]) ;
    }

    # Have all upper elements been removed ?
    if $(upper_ele)
    {
        errors.error "$(upper_limit) is not prefix of $(path)" ;
    }
    
    # Create the relative paths to parents, number of elements in 'path_ele'.
    local result ;
    for local i in $(path_ele)
    {
        path = [ parent $(path) ] ;
        result += $(path) ;
    }
    return $(result) ;
}


# Search for 'pattern' in parent directories of 'dir', up till and including
# 'upper_limit', if it is specified, or till the filesystem root otherwise.
#
rule glob-in-parents ( dir : patterns + : upper-limit ? )
{
    local result ;
    local parent-dirs = [ all-parents $(dir) : $(upper-limit) ] ;

    while $(parent-dirs) && ! $(result)
    {
        result = [ glob $(parent-dirs[1]) : $(patterns) ] ;
        parent-dirs = $(parent-dirs[2-]) ;
    }
    return $(result) ;
}


# Assuming 'child' is a subdirectory of 'parent', return the relative path from
# 'parent' to 'child'.
#
rule relative ( child parent )
{
    if $(parent) = "."
    {
        return $(child) ;
    }
    else
    {
        local split1 = [ regex.split $(parent) / ] ;
        local split2 = [ regex.split $(child) / ] ;

        while $(split1)
        {
            if $(split1[1]) = $(split2[1])
            {
                split1 = $(split1[2-]) ;
                split2 = $(split2[2-]) ;
            }
            else
            {
                errors.error $(child) is not a subdir of $(parent) ;
            }
        }
        if $(split2)
        {
            return [ join $(split2) ] ;
        }
        else
        {
            return "." ;
        }
    }
}


# Returns the minimal path to path2 that is relative path1.
#
rule relative-to ( path1 path2 )
{
    local root_1 = [ regex.split [ reverse $(path1) ] / ] ;
    local split1 = [ regex.split $(path1) / ] ;
    local split2 = [ regex.split $(path2) / ] ;

    while $(split1) && $(root_1)
    {
        if $(split1[1]) = $(split2[1])
        {
            root_1 = $(root_1[2-]) ;
            split1 = $(split1[2-]) ;
            split2 = $(split2[2-]) ;
        }
        else
        {
            split1 = ;
        }
    }
    return [ join . $(root_1) $(split2) ] ;
}


# Returns the list of paths which are used by the operating system for looking
# up programs.
#
rule programs-path ( )
{
    local result ;
    local raw = [ modules.peek : PATH Path path ] ;
    for local p in $(raw)
    {
        if $(p)
        {
            result += [ path.make $(p) ] ;
        }
    }
    return $(result) ;
}