[Buildbot-commits] buildbot/docs buildbot.texinfo,1.148,1.149

[Brian Warner]

Update of /cvsroot/buildbot/buildbot/docs
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv22264/docs

Modified Files:
	buildbot.texinfo 
Log Message:
[project @ #124:conflict-resolution]

Original author: dustin at v.igoro.us
Date: 2008-05-15 22:41:32+00:00

Index: buildbot.texinfo
===================================================================
RCS file: /cvsroot/buildbot/buildbot/docs/buildbot.texinfo,v
retrieving revision 1.148
retrieving revision 1.149
diff -u -d -r1.148 -r1.149
--- buildbot.texinfo	26 May 2008 23:52:23 -0000	1.148
+++ buildbot.texinfo	26 May 2008 23:52:31 -0000	1.149
@@ -4927,6 +4927,7 @@
 * Compile::                     
 * Test::                        
 * TreeSize::                    
+* SetProperty::                    
 * Build Properties::            
 @end menu
 
@@ -4983,7 +4984,7 @@
 This is meant to handle unit tests. The default command is @code{make
 test}, and the @code{warnOnFailure} flag is set.
 
- at node TreeSize, Build Properties, Test, Simple ShellCommand Subclasses
+ at node TreeSize
 @subsubsection TreeSize
 
 @bsindex buildbot.steps.shell.TreeSize
@@ -4996,7 +4997,47 @@
 @node SetProperty
 @subsubsection SetProperty
 
- at node Build Properties,  , TreeSize, Simple ShellCommand Subclasses
+ at bsindex buildbot.steps.shell.SetProperty
+
+This buildstep is similar to ShellCommand, except that it captures the
+output of the command into a property.  It is usually used like this:
+
+ at example
+f.addStep(SetProperty(command="uname -a", property="uname"))
+ at end example
+
+This runs @code{uname -a} and captures its stdout, stripped of leading
+and trailing whitespace, in the property "uname".  To avoid stripping,
+add @code{strip=False}.  The @code{property} argument can be specified
+as a @code{WithProperties} object.
+
+The more advanced usage allows you to specify a function to extract
+properties from the command output.  Here you can use regular
+expressions, string interpolation, or whatever you would like.
+The function is called with three arguments: the exit status of the
+command, its standard output as a string, and its standard error as
+a string.  It should return a dictionary containing all new properties.
+
+ at example
+def glob2list(rc, stdout, stderr):
+    jpgs = [ l.strip() for l in stdout.split('\n') ]
+    return @{ 'jpgs' : jpgs @}
+f.addStep(SetProperty(command="ls -1 *.jpg", extract_fn=glob2list))
+ at end example
+
+Note that any ordering relationship of the contents of stdout and
+stderr is lost.  For example, given
+
+ at example
+f.addStep(SetProperty(
+    command="echo output1; echo error >&2; echo output2", 
+    extract_fn=my_extract))
+ at end example
+
+Then @code{my_extract} will see @code{stdout="output1\noutput2\n"}
+and @code{stderr="error\n"}.
+
+ at node Build Properties
 @subsubsection Build Properties
 
 @cindex build properties