src/engine/SCons/Options/PathOption.py

   1 """SCons.Options.PathOption
   2
   3 This file defines an option type for SCons implementing path settings.
   4
   5 To be used whenever a a user-specified path override should be allowed.
   6
   7 Arguments to PathOption 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
  28 Usage example:
  29
  30   Examples:
  31       prefix=/usr/local
  32
  33   opts = Options()
  34
  35   opts = Options()
  36   opts.Add(PathOption('qtdir',
  37                       'where the root of Qt is installed',
  38                       qtdir, PathIsDir))
  39   opts.Add(PathOption('qt_includes',
  40                       'where the Qt includes are installed',
  41                       '$qtdir/includes', PathIsDirCreate))
  42   opts.Add(PathOption('qt_libraries',
  43                       'where the Qt library is installed',
  44                       '$qtdir/lib'))
  45
  46 """
  47
  48 #
  49 # __COPYRIGHT__
  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__ = "__FILE__ __REVISION__ __DATE__ __DEVELOPER__"
  72
  73 import os
  74 import os.path
  75
  76 import SCons.Errors
  77
  78 class _PathOptionClass:
  79
  80     def PathAccept(self, key, val, env):
  81         """Accepts any path, no checking done."""
  82         pass
  83
  84     def PathIsDir(self, key, val, env):
  85         """Validator to check if Path is a directory."""
  86         if not os.path.isdir(val):
  87             if os.path.isfile(val):
  88                 m = 'Directory path for option %s is a file: %s'
  89             else:
  90                 m = 'Directory path for option %s does not exist: %s'
  91             raise SCons.Errors.UserError(m % (key, val))
  92
  93     def PathIsDirCreate(self, key, val, env):
  94         """Validator to check if Path is a directory,
  95            creating it if it does not exist."""
  96         if os.path.isfile(val):
  97             m = 'Path for option %s is a file, not a directory: %s'
  98             raise SCons.Errors.UserError(m % (key, val))
  99         if not os.path.isdir(val):
 100             os.makedirs(val)
 101
 102     def PathIsFile(self, key, val, env):
 103         """validator to check if Path is a file"""
 104         if not os.path.isfile(val):
 105             if os.path.isdir(val):
 106                 m = 'File path for option %s is a directory: %s'
 107             else:
 108                 m = 'File path for option %s does not exist: %s'
 109             raise SCons.Errors.UserError(m % (key, val))
 110
 111     def PathExists(self, key, val, env):
 112         """validator to check if Path exists"""
 113         if not os.path.exists(val):
 114             m = 'Path for option %s does not exist: %s'
 115             raise SCons.Errors.UserError(m % (key, val))
 116
 117     def __call__(self, key, help, default, validator=None):
 118         # NB: searchfunc is currenty undocumented and unsupported
 119         """
 120         The input parameters describe a 'path list' option, thus they
 121         are returned with the correct converter and validator appended. The
 122         result is usable for input to opts.Add() .
 123
 124         The 'default' option specifies the default path to use if the
 125         user does not specify an override with this option.
 126
 127         validator is a validator, see this file for examples
 128         """
 129         if validator is None:
 130             validator = self.PathExists
 131
 132         if SCons.Util.is_List(key) or SCons.Util.is_Tuple(key):
 133             return (key, '%s ( /path/to/%s )' % (help, key[0]), default,
 134                     validator, None)
 135         else:
 136             return (key, '%s ( /path/to/%s )' % (help, key), default,
 137                     validator, None)
 138
 139 PathOption = _PathOptionClass()