Viewing file:  bshdoc (4.45 KB) -rwxr-xr-x
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
#!/usr/bin/env /usr/bin/bsh
/**
This is BeanShell documentation for the bshdoc script.
bshdoc.bsh in conjunction with bshdoc.xsl supports javadoc style
documentation of BeanShell scripts and files.
<p/>
bshdoc reads a javadoc style comment and method signatures from one or
more files and generates XML output representing their contents.
An XSL stylesheet bshcommands.xsl (supplied with the user manual source)
can be used to render this to an indexed HTML page describing the commands.
<p/>
Method signatures may be supplied expliticly via javadoc style @method
tags in the comment. For example you might do this to provide a more
verbose description for loosely typed arguments. The bshcommands.xsl
stylesheet supplied with the user manual source will use the tag
signatures in lieu of autogenerated ones when they are present. So you
can use this tag to determine exactly which methods from a file are
listed if you wish.
<p/>
Output goes to standard out. Comments may include normal HTML tags.
Javadoc style @tags are only recognized at the start of a line and
terminate the comment.
<p/>
Note: bshdoc generates full method and comment information for the file
but bshdoc.xsl uses only file comments and method signatures to create
the command index.
<p/>
The bshdoc command requires Java 1.4 for regular expressions.
<p/>
@method void bshdoc( String filename, String text )
@method void bshdoc( String [] filenames )
*/
import bsh.*;
import java.util.regex.*;
// The ASTs are not currently public. We'll probably move them to another
// package soon to do that.
setAccessibility(true);
// Trivial support for formatting the XML
tabs=0;
tab() { super.tabs++; }
untab() { super.tabs--; }
print( arg ) {
for(int i=0; i<tabs; i++)
this.interpreter.print(" ");
this.interpreter.println(String.valueOf(arg));
}
// Regexps used to parse the comment body.
//
// only on start of line
String tag = "\\n\\s*@(\\w+)";
// zero width lookahead to next tag or end of comment
String tagOrEndComment =
"(?="+tag+"|\\*/)";
Pattern commentTextPattern = Pattern.compile(
"(?s)/\\*\\*(.*?)"+tagOrEndComment );
Pattern tagsPattern = Pattern.compile(
"(?s)"+tag+"\\s*(.*?)"+tagOrEndComment );
/**
Print a comment section, with optional javadoc style tags
*/
printComment( String text )
{
print("<Comment>");
Matcher matcher = commentTextPattern.matcher( text );
if ( matcher.find() )
print("<Text><![CDATA["+ matcher.group(1) +"\n]]></Text>");
print("<Tags>");
Matcher matcher = tagsPattern.matcher( text );
while ( matcher.find() ) {
this.tagname=matcher.group(1);
this.tagvalue=matcher.group(2);
print("<"+tagname+">"+ tagvalue +"</"+tagname+">");
}
print("</Tags>");
print("</Comment>");
}
/**
bshdoc file comment.
*/
bshdoc( filename )
{
print("<File>");
tab();
if ( filename.endsWith(".bsh") )
this.name=filename.substring(0,filename.length()-4);
if ( (i=name.lastIndexOf("/")) != -1 )
this.name=name.substring(i+1);
print("<Name>"+name+"</Name>");
this.parser = new Parser( new FileReader(filename) );
parser.setRetainComments(true);
this.lastNode = null;
this.firstComment = null;
while( !parser.Line() )
{
this.node = parser.popNode();
if ( node instanceof BSHFormalComment
&& firstComment == null )
firstComment = node;
if ( node instanceof BSHMethodDeclaration )
{
this.sig=node.getText();
int i=sig.indexOf('{');
if ( i > -1 )
sig=sig.substring(0,i);
print("<Method>");
tab();
print("<Name>"+node.name+"</Name>");
print("<Sig>"+sig+"</Sig>");
if ( lastNode instanceof BSHFormalComment ) {
printComment( lastNode.text );
if ( firstComment == lastNode )
firstComment = null;
}
untab();
print("</Method>");
}
lastNode = node;
}
if ( firstComment != null ) {
tab();
printComment(firstComment.text);
untab();
}
untab();
print("</File>");
}
/**
bshdoc list comment.
*/
bshdoc( String [] filenames )
{
print("<?xml version="1.0\" encoding=\"UTF-8\"?>");
print("<?xml-stylesheet type=\"text/xsl\" href=\"bshcommands.xsl\"?>");
print("<!-- This file was auto-generated by the bshdoc.bsh script -->");
print("<BshDoc>");
tab();
for( int i=0; i<filenames.length; i++)
try {
bshdoc( filenames[i] );
} catch ( e ) {
throw new RuntimeException(
"bshdoc: Error parsing file: "+filenames[i]+": "+e );
}
untab();
print("</BshDoc>");
}
list=bsh.args;
if ( list.length == 0 ) {
print("usage: bshdoc file [ file ] [ ... ]");
return;
}
bshdoc( list );
|