Imported Upstream version 1.2.0.d20100306upstream/1.2.0.d20100306

5 files changed, 227 insertions, 77 deletions

diff --git a/bin/SConsDoc.py b/bin/SConsDoc.py
index d3a043b..cd78195 100644
--- a/bin/SConsDoc.py
+++ b/bin/SConsDoc.py
@@ -5,8 +5,8 @@
 
 __doc__ = """
 This module parses home-brew XML files that document various things
-in SCons.  Right now, it handles Builders, construction variables,
-and Tools, but we expect it to get extended in the future.
+in SCons.  Right now, it handles Builders, functions, construction
+variables, and Tools, but we expect it to get extended in the future.
 
 In general, you can use any DocBook tag in the input, and this module
 just adds processing various home-brew tags to try to make life a
@@ -14,14 +14,14 @@ little easier.
 
 Builder example:
 
-    <builder name="VARIABLE">
+    <builder name="BUILDER">
     <summary>
-    This is the summary description of an SCons Tool.
+    This is the summary description of an SCons Builder.
     It will get placed in the man page,
     and in the appropriate User's Guide appendix.
     The name of any builder may be interpolated
     anywhere in the document by specifying the
-    &b-VARIABLE;
+    &b-BUILDER;
     element.  It need not be on a line by itself.
 
     Unlike normal XML, blank lines are significant in these
@@ -35,6 +35,32 @@ Builder example:
     </summary>
     </builder>
 
+Function example:
+
+    <scons_function name="FUNCTION">
+    <arguments>
+    (arg1, arg2, key=value)
+    </arguments>
+    <summary>
+    This is the summary description of an SCons function.
+    It will get placed in the man page,
+    and in the appropriate User's Guide appendix.
+    The name of any builder may be interpolated
+    anywhere in the document by specifying the
+    &f-FUNCTION;
+    element.  It need not be on a line by itself.
+
+    Unlike normal XML, blank lines are significant in these
+    descriptions and serve to separate paragraphs.
+    They'll get replaced in DocBook output with appropriate tags
+    to indicate a new paragraph.
+
+    <example>
+    print "this is example code, it will be offset and indented"
+    </example>
+    </summary>
+    </scons_function>
+
 Construction variable example:
 
     <cvar name="VARIABLE">
@@ -60,14 +86,14 @@ Construction variable example:
 
 Tool example:
 
-    <tool name="VARIABLE">
+    <tool name="TOOL">
     <summary>
     This is the summary description of an SCons Tool.
     It will get placed in the man page,
     and in the appropriate User's Guide appendix.
     The name of any tool may be interpolated
     anywhere in the document by specifying the
-    &t-VARIABLE;
+    &t-TOOL;
     element.  It need not be on a line by itself.
 
     Unlike normal XML, blank lines are significant in these
@@ -82,12 +108,13 @@ Tool example:
     </tool>
 """
 
-import os.path
 import imp
+import os.path
+import re
 import sys
 import xml.sax.handler
 
-class Item:
+class Item(object):
     def __init__(self, name):
         self.name = name
         self.sort_name = name.lower()
@@ -106,6 +133,12 @@ class Item:
 class Builder(Item):
     pass
 
+class Function(Item):
+    def __init__(self, name, global_signature, env_signature):
+        super(Function, self).__init__(name)
+        self.global_signature = global_signature
+        self.env_signature = env_signature
+
 class Tool(Item):
     def __init__(self, name):
         Item.__init__(self, name)
@@ -126,6 +159,22 @@ class Chunk:
     def append(self, data):
         self.body.append(data)
 
+class Arguments:
+    def __init__(self, body=None):
+        if not body:
+            body = []
+        self.body = body
+    def __str__(self):
+        s = ''.join(self.body).strip()
+        result = []
+        for m in re.findall('([a-zA-Z/_]+|[^a-zA-Z/_]+)', s):
+            if ' ' in m:
+                m = '"%s"' % m
+            result.append(m)
+        return ' '.join(result)
+    def append(self, data):
+        self.body.append(data)
+
 class Summary:
     def __init__(self):
         self.body = []
@@ -181,6 +230,7 @@ class SConsDocHandler(xml.sax.handler.ContentHandler,
         self.collect = []
         self.current_object = []
         self.builders = {}
+        self.functions = {}
         self.tools = {}
         self.cvars = {}
 
@@ -244,6 +294,19 @@ class SConsDocHandler(xml.sax.handler.ContentHandler,
     def end_builder(self):
         self.end_xxx()
 
+    def start_scons_function(self, attrs):
+        name = attrs.get('name')
+        try:
+            function = self.functions[name]
+        except KeyError:
+            function = Function(name,
+                                attrs.get('global', "1"),
+                                attrs.get('env', "1"))
+            self.functions[name] = function
+        self.begin_xxx(function)
+    def end_scons_function(self):
+        self.end_xxx()
+
     def start_tool(self, attrs):
         name = attrs.get('name')
         try:
@@ -266,6 +329,14 @@ class SConsDocHandler(xml.sax.handler.ContentHandler,
     def end_cvar(self):
         self.end_xxx()
 
+    def start_arguments(self, attrs):
+        arguments = Arguments()
+        self.current_object.arguments = arguments
+        self.begin_xxx(arguments)
+        self.begin_collecting(arguments)
+    def end_arguments(self):
+        self.end_xxx()
+
     def start_summary(self, attrs):
         summary = Summary()
         self.current_object.summary = summary
diff --git a/bin/import-test.py b/bin/import-test.py
index e7d4db4..e0731d0 100644
--- a/bin/import-test.py
+++ b/bin/import-test.py
@@ -25,7 +25,7 @@
 # """ triple-quotes will need to have their contents edited by hand.
 #
 
-__revision__ = "bin/import-test.py 4629 2010/01/17 22:23:21 scons"
+__revision__ = "bin/import-test.py 4691 2010/03/06 16:22:36 bdbaddog"
 
 import os.path
 import sys
diff --git a/bin/linecount.py b/bin/linecount.py
index aa0a8aa..c087963 100644
--- a/bin/linecount.py
+++ b/bin/linecount.py
@@ -23,7 +23,7 @@
 # interesting one for most purposes.
 #
 
-__revision__ = "bin/linecount.py 4629 2010/01/17 22:23:21 scons"
+__revision__ = "bin/linecount.py 4691 2010/03/06 16:22:36 bdbaddog"
 
 import os.path
 import string
diff --git a/bin/restore.sh b/bin/restore.sh
index 0eec02f..98ad1ed 100644
--- a/bin/restore.sh
+++ b/bin/restore.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env sh
 #
-# Simple hack script to restore __revision__, __COPYRIGHT_, 1.2.0.d20100117
+# Simple hack script to restore __revision__, __COPYRIGHT_, 1.2.0.d20100306
 # and other similar variables to what gets checked in to source.  This
 # comes in handy when people send in diffs based on the released source.
 #
@@ -24,7 +24,7 @@ for i in `find $DIRS -name '*.py'`; do
     ed $i <<EOF
 g/Copyright (c) 2001.*SCons Foundation/s//Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation/p
 w
-/^__revision__ = /s/= .*/= "bin/restore.sh 4629 2010/01/17 22:23:21 scons"/p
+/^__revision__ = /s/= .*/= "bin/restore.sh 4691 2010/03/06 16:22:36 bdbaddog"/p
 w
 q
 EOF
@@ -35,7 +35,7 @@ for i in `find $DIRS -name 'scons.bat'`; do
     ed $i <<EOF
 g/Copyright (c) 2001.*SCons Foundation/s//Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation/p
 w
-/^@REM src\/script\/scons.bat/s/@REM .* knight/@REM bin/restore.sh 4629 2010/01/17 22:23:21 scons/p
+/^@REM src\/script\/scons.bat/s/@REM .* knight/@REM bin/restore.sh 4691 2010/03/06 16:22:36 bdbaddog/p
 w
 q
 EOF
@@ -44,15 +44,15 @@ done
 for i in `find $DIRS -name '__init__.py' -o -name 'scons.py' -o -name 'sconsign.py'`; do
     header $i
     ed $i <<EOF
-/^__version__ = /s/= .*/= "1.2.0.d20100117"/p
+/^__version__ = /s/= .*/= "1.2.0.d20100306"/p
 w
-/^__build__ = /s/= .*/= "r4629"/p
+/^__build__ = /s/= .*/= "r4691"/p
 w
-/^__buildsys__ = /s/= .*/= "scons-dev"/p
+/^__buildsys__ = /s/= .*/= "mvdog"/p
 w
-/^__date__ = /s/= .*/= "2010/01/17 22:23:21"/p
+/^__date__ = /s/= .*/= "2010/03/06 16:22:36"/p
 w
-/^__developer__ = /s/= .*/= "scons"/p
+/^__developer__ = /s/= .*/= "bdbaddog"/p
 w
 q
 EOF
@@ -61,7 +61,7 @@ done
 for i in `find $DIRS -name 'setup.py'`; do
     header $i
     ed $i <<EOF
-/^ *version = /s/= .*/= "1.2.0.d20100117",/p
+/^ *version = /s/= .*/= "1.2.0.d20100306",/p
 w
 q
 EOF
@@ -72,9 +72,9 @@ for i in `find $DIRS -name '*.txt'`; do
     ed $i <<EOF
 g/Copyright (c) 2001.*SCons Foundation/s//Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation/p
 w
-/# [^ ]* 0.96.[CD][0-9]* [0-9\/]* [0-9:]* knight$/s/.*/# bin/restore.sh 4629 2010/01/17 22:23:21 scons/p
+/# [^ ]* 0.96.[CD][0-9]* [0-9\/]* [0-9:]* knight$/s/.*/# bin/restore.sh 4691 2010/03/06 16:22:36 bdbaddog/p
 w
-/Version [0-9][0-9]*\.[0-9][0-9]*/s//Version 1.2.0.d20100117/p
+/Version [0-9][0-9]*\.[0-9][0-9]*/s//Version 1.2.0.d20100306/p
 w
 q
 EOF
diff --git a/bin/scons-proc.py b/bin/scons-proc.py
index cc3b085..41ff09a 100644
--- a/bin/scons-proc.py
+++ b/bin/scons-proc.py
@@ -2,8 +2,8 @@
 #
 # Process a list of Python and/or XML files containing SCons documentation.
 #
-# This script creates formatted lists of the Builders, Tools or
-# construction variables documented in the specified XML files.
+# This script creates formatted lists of the Builders, functions, Tools
+# or construction variables documented in the specified XML files.
 #
 # Dependening on the options, the lists are output in either
 # DocBook-formatted generated XML files containing the summary text
@@ -24,9 +24,11 @@ base_sys_path = [os.getcwd() + '/build/test-tar-gz/lib/scons'] + sys.path
 
 helpstr = """\
 Usage: scons-proc.py [--man|--xml]
-                     [-b file(s)] [-t file(s)] [-v file(s)] [infile ...]
+                     [-b file(s)] [-f file(s)] [-t file(s)] [-v file(s)]
+                     [infile ...]
 Options:
   -b file(s)        dump builder information to the specified file(s)
+  -f file(s)        dump function information to the specified file(s)
   -t file(s)        dump tool information to the specified file(s)
   -v file(s)        dump variable information to the specified file(s)
   --man             print info in man page format, each -[btv] argument
@@ -36,11 +38,12 @@ Options:
 """
 
 opts, args = getopt.getopt(sys.argv[1:],
-                           "b:ht:v:",
+                           "b:f:ht:v:",
                            ['builders=', 'help',
                             'man', 'xml', 'tools=', 'variables='])
 
 buildersfiles = None
+functionsfiles = None
 output_type = '--xml'
 toolsfiles = None
 variablesfiles = None
@@ -48,6 +51,8 @@ variablesfiles = None
 for o, a in opts:
     if o in ['-b', '--builders']:
         buildersfiles = a
+    elif o in ['-f', '--functions']:
+        functionsfiles = a
     elif o in ['-h', '--help']:
         sys.stdout.write(helpstr)
         sys.exit(0)
@@ -122,9 +127,7 @@ Link_Entities_Header = """\
 
 class SCons_XML:
     def __init__(self, entries, **kw):
-        values = entries.values()
-        values.sort()
-        self.values = values
+        self.values = entries
         for k, v in kw.items():
             setattr(self, k, v)
     def fopen(self, name):
@@ -143,10 +146,10 @@ class SCons_XML_to_XML(SCons_XML):
         f = self.fopen(filename)
         for v in self.values:
             f.write('\n<varlistentry id="%s%s">\n' %
-                        (self.prefix, self.idfunc(v.name)))
-            for term in self.termfunc(v.name):
+                        (v.prefix, v.idfunc()))
+            for term in v.termfunc():
                 f.write('<term><%s>%s</%s></term>\n' %
-                        (self.tag, term, self.tag))
+                        (v.tag, term, v.tag))
             f.write('<listitem>\n')
             for chunk in v.summary.body:
                 f.write(str(chunk))
@@ -163,44 +166,40 @@ class SCons_XML_to_XML(SCons_XML):
             f.write('</listitem>\n')
             f.write('</varlistentry>\n')
     def write_mod(self, filename):
+        description = self.values[0].description
         if not filename:
             return
         f = self.fopen(filename)
         f.write(Warning)
         f.write('\n')
-        f.write(Regular_Entities_Header % self.description)
+        f.write(Regular_Entities_Header % description)
         f.write('\n')
         for v in self.values:
             f.write('<!ENTITY %s%s "<%s>%s</%s>">\n' %
-                        (self.prefix, self.idfunc(v.name),
-                         self.tag, self.entityfunc(v.name), self.tag))
+                        (v.prefix, v.idfunc(),
+                         v.tag, v.entityfunc(), v.tag))
         f.write('\n')
         f.write(Warning)
         f.write('\n')
-        f.write(Link_Entities_Header % self.description)
+        f.write(Link_Entities_Header % description)
         f.write('\n')
         for v in self.values:
             f.write('<!ENTITY %slink-%s \'<link linkend="%s%s"><%s>%s</%s></link>\'>\n' %
-                        (self.prefix, self.idfunc(v.name),
-                         self.prefix, self.idfunc(v.name),
-                         self.tag, self.entityfunc(v.name), self.tag))
+                        (v.prefix, v.idfunc(),
+                         v.prefix, v.idfunc(),
+                         v.tag, v.entityfunc(), v.tag))
         f.write('\n')
         f.write(Warning)
 
 class SCons_XML_to_man(SCons_XML):
-    def mansep(self):
-        return ['\n']
-    def initial_chunks(self, name):
-        return [name]
     def write(self, filename):
         if not filename:
             return
         f = self.fopen(filename)
         chunks = []
         for v in self.values:
-            chunks.extend(self.mansep())
-            for n in self.initial_chunks(v.name):
-                chunks.append('.IP %s\n' % n)
+            chunks.extend(v.mansep())
+            chunks.extend(v.initial_chunks())
             chunks.extend(map(str, v.summary.body))
 
         body = ''.join(chunks)
@@ -210,28 +209,128 @@ class SCons_XML_to_man(SCons_XML):
         body = string.replace(body, '<para>\n', '')
         body = string.replace(body, '<para>', '\n')
         body = string.replace(body, '</para>\n', '')
-        body = re.sub('\.EE\n\n+(?!\.IP)', '.EE\n.IP\n', body)
+
+        body = string.replace(body, '<variablelist>\n', '.RS 10\n')
+        body = re.compile(r'<varlistentry>\n<term>([^<]*)</term>\n<listitem>\n').sub(r'.HP 6\n.B \1\n', body)
+        body = string.replace(body, '</listitem>\n', '')
+        body = string.replace(body, '</varlistentry>\n', '')
+        body = string.replace(body, '</variablelist>\n', '.RE\n')
+
+        body = re.sub(r'\.EE\n\n+(?!\.IP)', '.EE\n.IP\n', body)
+        body = string.replace(body, '\n.IP\n\'\\"', '\n\n\'\\"')
         body = re.sub('&(scons|SConstruct|SConscript|jar);', r'\\fB\1\\fP', body)
         body = string.replace(body, '&Dir;', r'\fBDir\fP')
         body = string.replace(body, '&target;', r'\fItarget\fP')
         body = string.replace(body, '&source;', r'\fIsource\fP')
         body = re.sub('&b(-link)?-([^;]*);', r'\\fB\2\\fP()', body)
         body = re.sub('&cv(-link)?-([^;]*);', r'$\2', body)
-        body = re.sub(r'<(command|envar|filename|literal|option)>([^<]*)</\1>',
+        body = re.sub('&f(-link)?-([^;]*);', r'\\fB\2\\fP()', body)
+        body = re.sub(r'<(command|envar|filename|function|literal|option)>([^<]*)</\1>',
                       r'\\fB\2\\fP', body)
         body = re.sub(r'<(classname|emphasis|varname)>([^<]*)</\1>',
                       r'\\fI\2\\fP', body)
+        body = re.compile(r'^\\f([BI])([^\\]* [^\\]*)\\fP\s*$', re.M).sub(r'.\1 "\2"', body)
         body = re.compile(r'^\\f([BI])(.*)\\fP\s*$', re.M).sub(r'.\1 \2', body)
-        body = re.compile(r'^\\f([BI])(.*)\\fP(\S+)', re.M).sub(r'.\1R \2 \3', body)
+        body = re.compile(r'^\\f([BI])(.*)\\fP(\S+)$', re.M).sub(r'.\1R \2 \3', body)
+        body = re.compile(r'^(\S+)\\f([BI])(.*)\\fP$', re.M).sub(r'.R\2 \1 \3', body)
         body = string.replace(body, '&lt;', '<')
         body = string.replace(body, '&gt;', '>')
         body = re.sub(r'\\([^f])', r'\\\\\1', body)
         body = re.compile("^'\\\\\\\\", re.M).sub("'\\\\", body)
+        body = re.compile(r'^\.([BI]R?) --', re.M).sub(r'.\1 \-\-', body)
         body = re.compile(r'^\.([BI]R?) -', re.M).sub(r'.\1 \-', body)
-        body = re.compile(r'^\.([BI]R?) (\S+)\\\\(\S+)', re.M).sub(r'.\1 "\2\\\\\\\\\2"', body)
+        body = re.compile(r'^\.([BI]R?) (\S+)\\\\(\S+)$', re.M).sub(r'.\1 "\2\\\\\\\\\2"', body)
         body = re.compile(r'\\f([BI])-', re.M).sub(r'\\f\1\-', body)
         f.write(body)
 
+class Proxy:
+    def __init__(self, subject):
+        """Wrap an object as a Proxy object"""
+        self.__subject = subject
+
+    def __getattr__(self, name):
+        """Retrieve an attribute from the wrapped object.  If the named
+           attribute doesn't exist, AttributeError is raised"""
+        return getattr(self.__subject, name)
+
+    def get(self):
+        """Retrieve the entire wrapped object"""
+        return self.__subject
+
+    def __cmp__(self, other):
+        if issubclass(other.__class__, self.__subject.__class__):
+            return cmp(self.__subject, other)
+        return cmp(self.__dict__, other.__dict__)
+
+class Builder(Proxy):
+    description = 'builder'
+    prefix = 'b-'
+    tag = 'function'
+    def idfunc(self):
+        return self.name
+    def termfunc(self):
+        return ['%s()' % self.name, 'env.%s()' % self.name]
+    def entityfunc(self):
+        return self.name
+    def mansep(self):
+        return ['\n', "'\\" + '"'*69 + '\n']
+    def initial_chunks(self):
+        return [ '.IP %s\n' % t for t in self.termfunc() ]
+
+class Function(Proxy):
+    description = 'function'
+    prefix = 'f-'
+    tag = 'function'
+    def idfunc(self):
+        return self.name
+    def termfunc(self):
+        return ['%s()' % self.name, 'env.%s()' % self.name]
+    def entityfunc(self):
+        return self.name
+    def mansep(self):
+        return ['\n', "'\\" + '"'*69 + '\n']
+    def initial_chunks(self):
+        try:
+            x = self.arguments
+        except AttributeError:
+            x = '()'
+        result = []
+        if self.global_signature != "0":
+            result.append('.TP\n.RI %s%s\n' % (self.name, x))
+        if self.env_signature != "0":
+            result.append('.TP\n.IR env .%s%s\n' % (self.name, x))
+        return result
+
+class Tool(Proxy):
+    description = 'tool'
+    prefix = 't-'
+    tag = 'literal'
+    def idfunc(self):
+        return string.replace(self.name, '+', 'X')
+    def termfunc(self):
+        return [self.name]
+    def entityfunc(self):
+        return self.name
+    def mansep(self):
+        return ['\n']
+    def initial_chunks(self):
+        return ['.IP %s\n' % self.name]
+
+class Variable(Proxy):
+    description = 'construction variable'
+    prefix = 'cv-'
+    tag = 'envar'
+    def idfunc(self):
+        return self.name
+    def termfunc(self):
+        return [self.name]
+    def entityfunc(self):
+        return '$' + self.name
+    def mansep(self):
+        return ['\n']
+    def initial_chunks(self):
+        return ['.IP %s\n' % self.name]
+
 if output_type == '--man':
     processor_class = SCons_XML_to_man
 elif output_type == '--xml':
@@ -241,39 +340,19 @@ else:
     sys.exit(1)
 
 if buildersfiles:
-    g = processor_class(h.builders,
-            description = 'builder',
-            prefix = 'b-',
-            tag = 'function',
-            idfunc = lambda x: x,
-            termfunc = lambda x: [x+'()', 'env.'+x+'()'],
-            entityfunc = lambda x: x)
-
-    g.mansep = lambda: ['\n', "'\\" + '"'*69 + '\n']
-    g.initial_chunks = lambda n: [n+'()', 'env.'+n+'()']
-
+    g = processor_class([ Builder(b) for b in sorted(h.builders.values()) ])
     g.write(buildersfiles)
 
-if toolsfiles:
-    g = processor_class(h.tools,
-            description = 'tool',
-            prefix = 't-',
-            tag = 'literal',
-            idfunc = lambda x: string.replace(x, '+', 'X'),
-            termfunc = lambda x: [x],
-            entityfunc = lambda x: x)
+if functionsfiles:
+    g = processor_class([ Function(b) for b in sorted(h.functions.values()) ])
+    g.write(functionsfiles)
 
+if toolsfiles:
+    g = processor_class([ Tool(t) for t in sorted(h.tools.values()) ])
     g.write(toolsfiles)
 
 if variablesfiles:
-    g = processor_class(h.cvars,
-            description = 'construction variable',
-            prefix = 'cv-',
-            tag = 'envar',
-            idfunc = lambda x: x,
-            termfunc = lambda x: [x],
-            entityfunc = lambda x: '$'+x)
-
+    g = processor_class([ Variable(v) for v in sorted(h.cvars.values()) ])
     g.write(variablesfiles)
 
 # Local Variables: