1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
/**
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 );
|
