Update SCons to latest checkpoint release, 1.2.0.d20090113....

third_party/scons/scons-local/SCons/Subst.py

 """SCons.Subst
 
 SCons string substitution.
 
 """
 
 #
-# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 The SCons Foundation
+# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the
 # "Software"), to deal in the Software without restriction, including
 # without limitation the rights to use, copy, modify, merge, publish,
 # distribute, sublicense, and/or sell copies of the Software, and to
 # permit persons to whom the Software is furnished to do so, subject to
 # the following conditions:
 #
 # The above copyright notice and this permission notice shall be included
 # in all copies or substantial portions of the Software.
 #
 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
-__revision__ = "src/engine/SCons/Subst.py 3842 2008/12/20 22:59:52 scons"
+__revision__ = "src/engine/SCons/Subst.py 3897 2009/01/13 06:45:54 scons"
 
 import re
 import string
 import types
 import UserList
 import UserString
 
 import SCons.Errors
 
 from SCons.Util import is_String, is_Sequence
@@ skipping 205 matching lines @@
         nl = self.nl._create_nodelist()
         if nl:
             return str(nl[0])
         return ''
     def __repr__(self):
         nl = self.nl._create_nodelist()
         if nl:
             return repr(nl[0])
         return ''
 
+class NullNodeList(SCons.Util.NullSeq):
+  def __call__(self, *args, **kwargs): return ''
+  def __str__(self): return ''
+  # TODO(1.5):  unneeded after new-style classes introduce iterators
+  def __getitem__(self, i):
+      raise IndexError
+
+NullNodesList = NullNodeList()
+
 def subst_dict(target, source):
     """Create a dictionary for substitution of special
     construction variables.
 
     This translates the following special arguments:
 
     target - the target (object or array of objects),
              used to generate the TARGET and TARGETS
              construction variables
 
     source - the source (object or array of objects),
              used to generate the SOURCES and SOURCE
              construction variables
     """
     dict = {}
 
     if target:
         def get_tgt_subst_proxy(thing):
             try:
                 subst_proxy = thing.get_subst_proxy()
             except AttributeError:
                 subst_proxy = thing # probably a string, just return it
             return subst_proxy
         tnl = NLWrapper(target, get_tgt_subst_proxy)
         dict['TARGETS'] = Targets_or_Sources(tnl)
         dict['TARGET'] = Target_or_Source(tnl)
+
+        # This is a total cheat, but hopefully this dictionary goes
+        # away soon anyway.  We just let these expand to $TARGETS
+        # because that's "good enough" for the use of ToolSurrogates
+        # (see test/ToolSurrogate.py) to generate documentation.
+        dict['CHANGED_TARGETS'] = '$TARGETS'
+        dict['UNCHANGED_TARGETS'] = '$TARGETS'
     else:
-        dict['TARGETS'] = None
-        dict['TARGET'] = None
+        dict['TARGETS'] = NullNodesList
+        dict['TARGET'] = NullNodesList
 
     if source:
         def get_src_subst_proxy(node):
             try:
                 rfile = node.rfile
             except AttributeError:
                 pass
             else:
                 node = rfile()
             try:
                 return node.get_subst_proxy()
             except AttributeError:
                 return node     # probably a String, just return it
         snl = NLWrapper(source, get_src_subst_proxy)
         dict['SOURCES'] = Targets_or_Sources(snl)
         dict['SOURCE'] = Target_or_Source(snl)
+
+        # This is a total cheat, but hopefully this dictionary goes
+        # away soon anyway.  We just let these expand to $TARGETS
+        # because that's "good enough" for the use of ToolSurrogates
+        # (see test/ToolSurrogate.py) to generate documentation.
+        dict['CHANGED_SOURCES'] = '$SOURCES'
+        dict['UNCHANGED_SOURCES'] = '$SOURCES'
     else:
-        dict['SOURCES'] = None
-        dict['SOURCE'] = None
+        dict['SOURCES'] = NullNodesList
+        dict['SOURCE'] = NullNodesList
 
     return dict
 
 # Constants for the "mode" parameter to scons_subst_list() and
 # scons_subst().  SUBST_RAW gives the raw command line.  SUBST_CMD
 # gives a command line suitable for passing to a shell.  SUBST_SIG
 # gives a command line appropriate for calculating the signature
 # of a command line...if this changes, we should rebuild.
 SUBST_CMD = 0
 SUBST_RAW = 1
@@ skipping 65 matching lines @@
     if type(strSubst) == types.StringType and string.find(strSubst, '$') < 0:
         return strSubst
 
     class StringSubber:
         """A class to construct the results of a scons_subst() call.
 
         This binds a specific construction environment, mode, target and
         source with two methods (substitute() and expand()) that handle
         the expansion.
         """
-        def __init__(self, env, mode, target, source, conv, gvars):
+        def __init__(self, env, mode, conv, gvars):
             self.env = env
             self.mode = mode
-            self.target = target
-            self.source = source
             self.conv = conv
             self.gvars = gvars
 
         def expand(self, s, lvars):
             """Expand a single "token" as necessary, returning an
             appropriate string containing the expansion.
 
             This handles expanding different types of things (strings,
             lists, callables) appropriately.  It calls the wrapper
             substitute() method to re-expand things as necessary, so that
@@ skipping 16 matching lines @@
                     if key[0] == '{' or string.find(key, '.') >= 0:
                         if key[0] == '{':
                             key = key[1:-1]
                         try:
                             s = eval(key, self.gvars, lvars)
                         except KeyboardInterrupt:
                             raise
                         except Exception, e:
                             if e.__class__ in AllowableExceptions:
                                 return ''
-                            raise_exception(e, self.target, s)
+                            raise_exception(e, lvars['TARGETS'], s)
                     else:
                         if lvars.has_key(key):
                             s = lvars[key]
                         elif self.gvars.has_key(key):
                             s = self.gvars[key]
                         elif not NameError in AllowableExceptions:
-                            raise_exception(NameError(key), self.target, s)
+                            raise_exception(NameError(key), lvars['TARGETS'], s)
                         else:
                             return ''
     
                     # Before re-expanding the result, handle
                     # recursive expansion by copying the local
                     # variable dictionary and overwriting a null
                     # string for the value of the variable name
                     # we just expanded.
                     #
                     # This could potentially be optimized by only
                     # copying lvars when s contains more expansions,
                     # but lvars is usually supposed to be pretty
                     # small, and deeply nested variable expansions
                     # are probably more the exception than the norm,
                     # so it should be tolerable for now.
                     lv = lvars.copy()
                     var = string.split(key, '.')[0]
                     lv[var] = ''
                     return self.substitute(s, lv)
             elif is_Sequence(s):
                 def func(l, conv=self.conv, substitute=self.substitute, lvars=lvars):
                     return conv(substitute(l, lvars))
                 return map(func, s)
             elif callable(s):
                 try:
-                    s = s(target=self.target,
-                         source=self.source,
+                    s = s(target=lvars['TARGETS'],
+                         source=lvars['SOURCES'],
                          env=self.env,
                          for_signature=(self.mode != SUBST_CMD))
                 except TypeError:
                     # This probably indicates that it's a callable
                     # object that doesn't match our calling arguments
                     # (like an Action).
                     if self.mode == SUBST_RAW:
                         return s
                     s = self.conv(s)
                 return self.substitute(s, lvars)
@@ skipping 37 matching lines @@
 
     # Doing this every time is a bit of a waste, since the Executor
     # has typically already populated the OverrideEnvironment with
     # $TARGET/$SOURCE variables.  We're keeping this (for now), though,
     # because it supports existing behavior that allows us to call
     # an Action directly with an arbitrary target+source pair, which
     # we use in Tool/tex.py to handle calling $BIBTEX when necessary.
     # If we dropped that behavior (or found another way to cover it),
     # we could get rid of this call completely and just rely on the
     # Executor setting the variables.
-    d = subst_dict(target, source)
-    if d:
-        lvars = lvars.copy()
-        lvars.update(d)
+    if not lvars.has_key('TARGET'):
+        d = subst_dict(target, source)
+        if d:
+            lvars = lvars.copy()
+            lvars.update(d)
 
     # We're (most likely) going to eval() things.  If Python doesn't
     # find a __builtins__ value in the global dictionary used for eval(),
     # it copies the current global values for you.  Avoid this by
     # setting it explicitly and then deleting, so we don't pollute the
     # construction environment Dictionary(ies) that are typically used
     # for expansion.
     gvars['__builtins__'] = __builtins__
 
-    ss = StringSubber(env, mode, target, source, conv, gvars)
+    ss = StringSubber(env, mode, conv, gvars)
     result = ss.substitute(strSubst, lvars)
 
     try:
         del gvars['__builtins__']
     except KeyError:
         pass
 
     if is_String(result):
         # Remove $(-$) pairs and any stuff in between,
         # if that's appropriate.
@@ skipping 36 matching lines @@
 
         In addition, however, this class is used to track the state of
         the result(s) we're gathering so we can do the appropriate thing
         whenever we have to append another word to the result--start a new
         line, start a new word, append to the current word, etc.  We do
         this by setting the "append" attribute to the right method so
         that our wrapper methods only need ever call ListSubber.append(),
         and the rest of the object takes care of doing the right thing
         internally.
         """
-        def __init__(self, env, mode, target, source, conv, gvars):
+        def __init__(self, env, mode, conv, gvars):
             UserList.UserList.__init__(self, [])
             self.env = env
             self.mode = mode
-            self.target = target
-            self.source = source
             self.conv = conv
             self.gvars = gvars
 
             if self.mode == SUBST_RAW:
                 self.add_strip = lambda x, s=self: s.append(x)
             else:
                 self.add_strip = lambda x, s=self: None
             self.in_strip = None
             self.next_line()
 
@@ skipping 28 matching lines @@
                     if key[0] == '{' or string.find(key, '.') >= 0:
                         if key[0] == '{':
                             key = key[1:-1]
                         try:
                             s = eval(key, self.gvars, lvars)
                         except KeyboardInterrupt:
                             raise
                         except Exception, e:
                             if e.__class__ in AllowableExceptions:
                                 return
-                            raise_exception(e, self.target, s)
+                            raise_exception(e, lvars['TARGETS'], s)
                     else:
                         if lvars.has_key(key):
                             s = lvars[key]
                         elif self.gvars.has_key(key):
                             s = self.gvars[key]
                         elif not NameError in AllowableExceptions:
-                            raise_exception(NameError(), self.target, s)
+                            raise_exception(NameError(), lvars['TARGETS'], s)
                         else:
                             return
 
                     # Before re-expanding the result, handle
                     # recursive expansion by copying the local
                     # variable dictionary and overwriting a null
                     # string for the value of the variable name
                     # we just expanded.
                     lv = lvars.copy()
                     var = string.split(key, '.')[0]
                     lv[var] = ''
                     self.substitute(s, lv, 0)
                     self.this_word()
             elif is_Sequence(s):
                 for a in s:
                     self.substitute(a, lvars, 1)
                     self.next_word()
             elif callable(s):
                 try:
-                    s = s(target=self.target,
-                         source=self.source,
+                    s = s(target=lvars['TARGETS'],
+                         source=lvars['SOURCES'],
                          env=self.env,
                          for_signature=(self.mode != SUBST_CMD))
                 except TypeError:
                     # This probably indicates that it's a callable
                     # object that doesn't match our calling arguments
                     # (like an Action).
                     if self.mode == SUBST_RAW:
                         self.append(s)
                         return
                     s = self.conv(s)
@@ skipping 122 matching lines @@
 
     # Doing this every time is a bit of a waste, since the Executor
     # has typically already populated the OverrideEnvironment with
     # $TARGET/$SOURCE variables.  We're keeping this (for now), though,
     # because it supports existing behavior that allows us to call
     # an Action directly with an arbitrary target+source pair, which
     # we use in Tool/tex.py to handle calling $BIBTEX when necessary.
     # If we dropped that behavior (or found another way to cover it),
     # we could get rid of this call completely and just rely on the
     # Executor setting the variables.
-    d = subst_dict(target, source)
-    if d:
-        lvars = lvars.copy()
-        lvars.update(d)
+    if not lvars.has_key('TARGET'):
+        d = subst_dict(target, source)
+        if d:
+            lvars = lvars.copy()
+            lvars.update(d)
 
     # We're (most likely) going to eval() things.  If Python doesn't
     # find a __builtins__ value in the global dictionary used for eval(),
     # it copies the current global values for you.  Avoid this by
     # setting it explicitly and then deleting, so we don't pollute the
     # construction environment Dictionary(ies) that are typically used
     # for expansion.
     gvars['__builtins__'] = __builtins__
 
-    ls = ListSubber(env, mode, target, source, conv, gvars)
+    ls = ListSubber(env, mode, conv, gvars)
     ls.substitute(strSubst, lvars, 0)
 
     try:
         del gvars['__builtins__']
     except KeyError:
         pass
 
     return ls.data
 
 def scons_subst_once(strSubst, env, key):
@@ skipping 34 matching lines @@
                         result.append(arg)
                 else:
                     result.append(_dollar_exps.sub(sub_match, arg))
             else:
                 result.append(arg)
         return result
     elif is_String(strSubst):
         return _dollar_exps.sub(sub_match, strSubst)
     else:
         return strSubst