1"""SCons.Variables.PathVariable
2
3This file defines an option type for SCons implementing path settings.
4
5To be used whenever a a user-specified path override should be allowed.
6
7Arguments to PathVariable are:
8  option-name  = name of this option on the command line (e.g. "prefix")
9  option-help  = help string for option
10  option-dflt  = default value for this option
11  validator    = [optional] validator for option value.  Predefined
12                 validators are:
13
14                     PathAccept -- accepts any path setting; no validation
15                     PathIsDir  -- path must be an existing directory
16                     PathIsDirCreate -- path must be a dir; will create
17                     PathIsFile -- path must be a file
18                     PathExists -- path must exist (any type) [default]
19
20                 The validator is a function that is called and which
21                 should return True or False to indicate if the path
22                 is valid.  The arguments to the validator function
23                 are: (key, val, env).  The key is the name of the
24                 option, the val is the path specified for the option,
25                 and the env is the env to which the Otions have been
26                 added.
27
28Usage example:
29
30  Examples:
31      prefix=/usr/local
32
33  opts = Variables()
34
35  opts = Variables()
36  opts.Add(PathVariable('qtdir',
37                      'where the root of Qt is installed',
38                      qtdir, PathIsDir))
39  opts.Add(PathVariable('qt_includes',
40                      'where the Qt includes are installed',
41                      '$qtdir/includes', PathIsDirCreate))
42  opts.Add(PathVariable('qt_libraries',
43                      'where the Qt library is installed',
44                      '$qtdir/lib'))
45
46"""
47
48#
49# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 The SCons Foundation
50#
51# Permission is hereby granted, free of charge, to any person obtaining
52# a copy of this software and associated documentation files (the
53# "Software"), to deal in the Software without restriction, including
54# without limitation the rights to use, copy, modify, merge, publish,
55# distribute, sublicense, and/or sell copies of the Software, and to
56# permit persons to whom the Software is furnished to do so, subject to
57# the following conditions:
58#
59# The above copyright notice and this permission notice shall be included
60# in all copies or substantial portions of the Software.
61#
62# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
63# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
64# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
65# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
66# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
67# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
68# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
69#
70
71__revision__ = "src/engine/SCons/Variables/PathVariable.py issue-2856:2676:d23b7a2f45e8 2012/08/05 15:38:28 garyo"
72
73__all__ = ['PathVariable',]
74
75import os
76import os.path
77
78import SCons.Errors
79
80class _PathVariableClass(object):
81
82    def PathAccept(self, key, val, env):
83        """Accepts any path, no checking done."""
84        pass
85
86    def PathIsDir(self, key, val, env):
87        """Validator to check if Path is a directory."""
88        if not os.path.isdir(val):
89            if os.path.isfile(val):
90                m = 'Directory path for option %s is a file: %s'
91            else:
92                m = 'Directory path for option %s does not exist: %s'
93            raise SCons.Errors.UserError(m % (key, val))
94
95    def PathIsDirCreate(self, key, val, env):
96        """Validator to check if Path is a directory,
97           creating it if it does not exist."""
98        if os.path.isfile(val):
99            m = 'Path for option %s is a file, not a directory: %s'
100            raise SCons.Errors.UserError(m % (key, val))
101        if not os.path.isdir(val):
102            os.makedirs(val)
103
104    def PathIsFile(self, key, val, env):
105        """validator to check if Path is a file"""
106        if not os.path.isfile(val):
107            if os.path.isdir(val):
108                m = 'File path for option %s is a directory: %s'
109            else:
110                m = 'File path for option %s does not exist: %s'
111            raise SCons.Errors.UserError(m % (key, val))
112
113    def PathExists(self, key, val, env):
114        """validator to check if Path exists"""
115        if not os.path.exists(val):
116            m = 'Path for option %s does not exist: %s'
117            raise SCons.Errors.UserError(m % (key, val))
118
119    def __call__(self, key, help, default, validator=None):
120        # NB: searchfunc is currenty undocumented and unsupported
121        """
122        The input parameters describe a 'path list' option, thus they
123        are returned with the correct converter and validator appended. The
124        result is usable for input to opts.Add() .
125
126        The 'default' option specifies the default path to use if the
127        user does not specify an override with this option.
128
129        validator is a validator, see this file for examples
130        """
131        if validator is None:
132            validator = self.PathExists
133
134        if SCons.Util.is_List(key) or SCons.Util.is_Tuple(key):
135            return (key, '%s ( /path/to/%s )' % (help, key[0]), default,
136                    validator, None)
137        else:
138            return (key, '%s ( /path/to/%s )' % (help, key), default,
139                    validator, None)
140
141PathVariable = _PathVariableClass()
142
143# Local Variables:
144# tab-width:4
145# indent-tabs-mode:nil
146# End:
147# vim: set expandtab tabstop=4 shiftwidth=4:
148