com.martiansoftware.snip
Class RunSnip

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          com.martiansoftware.snip.RunSnip

All Implemented Interfaces:

MacroProcessor

public class RunSnip

extends org.apache.tools.ant.Task

implements MacroProcessor

An Ant task designed to help with the single-sourcing of program documentation. This task reptracts snippets of text from files, placing them into properties in the Ant project. These properties can then be used by any other Ant task, and are particularly useful when referenced by <filter>s within the <copy> task.

The <snip> task takes one or more nested <fileset>s that indicate the files to process. Any text between lines containing "@@runSnip:myProperty@@" and "@@endSnip@@" will be stored in a property called snip.myProperty.

Example Usage:

 
 <taskdef
     name="runsnip"
     classname="com.martiansoftware.snip.RunSnip" 
     classpath="snip-0.1.jar"/>
 		
 <snip>
     <fileset dir="src" includes="**/*.txt" />
 </snip>
 

Multiple snippets may be defined within a single file. Snippets may not be nested.

Author:

Marty Lamb

Field Summary

static java.lang.String

FORMAT_DOCBOOK Format constant indicating that output should be written in docbook format.

Fields inherited from class org.apache.tools.ant.Task

description, location, target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

project

Constructor Summary

RunSnip()

Method Summary

void	addFileSet(org.apache.tools.ant.types.FileSet fs) Adds a FileSet to this Task
void	execute() Reads all snippets from the previously specified FileSets, storing their contents in project properties.
java.lang.String	formatDocbook(java.lang.String command, java.lang.String output) Formats the program output in docbook format.
java.lang.String	formatResult(java.lang.String command, java.lang.String output) Formats the program output
java.lang.String	processMacro(java.lang.String macro) Processes the specified macro, returning the formatted result.
void	setFormat(java.lang.String format) Sets the output format
void	setPrompt(java.lang.String prompt) Sets the prompt to include in output

Methods inherited from class org.apache.tools.ant.Task

getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorFlush, handleErrorOutput, handleFlush, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, setProject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORMAT_DOCBOOK

public static final java.lang.String FORMAT_DOCBOOK

Format constant indicating that output should be written in docbook format.

See Also:

Constant Field Values

Constructor Detail

RunSnip

public RunSnip()

Method Detail

addFileSet

public void addFileSet(org.apache.tools.ant.types.FileSet fs)

Adds a FileSet to this Task

Parameters:

fs - the FileSet to add

setPrompt

public void setPrompt(java.lang.String prompt)

Sets the prompt to include in output

Parameters:

prompt - the prompt to include in output

formatDocbook

public java.lang.String formatDocbook(java.lang.String command,
                                      java.lang.String output)

Formats the program output in docbook format.

Parameters:

command - the command executed

output - the command's output

Returns:

the program output in docbook format (minus the enclosing <screen> tags)

formatResult

public java.lang.String formatResult(java.lang.String command,
                                     java.lang.String output)

Formats the program output

Parameters:

command - the command executed

output - the command's output

Returns:

the formatted output

setFormat

public void setFormat(java.lang.String format)

Sets the output format

Parameters:

format - the output format (currently only "docbook" is supported)

processMacro

public java.lang.String processMacro(java.lang.String macro)

Processes the specified macro, returning the formatted result.

Specified by:

processMacro in interface MacroProcessor

Parameters:

macro - the macro to run

Returns:

the formatted output of the specified macro

execute

public void execute()
             throws org.apache.tools.ant.BuildException

Reads all snippets from the previously specified FileSets, storing their contents in project properties.

Throws:

org.apache.tools.ant.BuildException - if any I/O errors occur while reading files.