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
|
<!doctype html public "-//W30//DTD W3 HTML 2.0//EN">
<HTML>
<!-- This file was generated using SDF 2.001 by
Ian Clatworthy (ianc@mincom.com). SDF is freely
available from http://www.mincom.com/mtr/sdf. -->
<HEAD>
<TITLE>SDF 2.001: SDF Reference: sdfapi - API Extraction Utility</TITLE>
</HEAD>
<BODY BGCOLOR="ffffff">
<DIV CLASS="header">
<P><IMG SRC="../sdflogo.gif" ALIGN="Right"></P>
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="re_sdf.html">Contents</A> | <A HREF="in_prog.html">Parent Topic</A> | <A HREF="sdf.html">Previous Topic</A> | <A HREF="sdfbatch.html">Next Topic</A> <BR><A HREF="../index.html">Home</A> | <A HREF="../catalog.html">Catalog</A></P>
</DIV>
<BR CLEAR="Right">
</DIV>
<DIV CLASS="main">
<H1><A NAME="sdfapi">11.3. sdfapi - API Extraction Utility</A></H1>
<HR>
<H2><A NAME="Purpose">Purpose</A></H2>
<P><A HREF="../ref/sdfapi.html">sdfapi</A> extracts <EM>Application Programming Interface</EM> information from (<A HREF="http://www.perl.com/perl/index.html">Perl</A>) source code.</P>
<HR>
<H2><A NAME="Usage">Usage</A></H2>
<PRE>
usage : sdfapi [-h[help]] [-o[out_ext]]
[-l[log_ext]] [-O[out_dir]] [-f fmt_tag]
[-p[pattern]] [-s sym_type,..] [-j]
file ...
purpose: extract the API from a (perl) library
version: 2.000 (SDF 2.001)
</PRE>
<P>The options are:</P>
<TABLE CLASS="columns" BORDER>
<TR CLASS="heading">
<TD>
<STRONG>Option</STRONG>
</TD>
<TD>
<STRONG>Description</STRONG>
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_h">-h</A>
</TD>
<TD>
display help on options
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_o">-o</A>
</TD>
<TD>
output file extension
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_l">-l</A>
</TD>
<TD>
log file extension
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_O">-O</A>
</TD>
<TD>
output to input file's (or explicit) directory
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_f">-f</A>
</TD>
<TD>
output format tag
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_p">-p</A>
</TD>
<TD>
only symbols matching pattern
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_s">-s</A>
</TD>
<TD>
only symbols of these types
</TD>
</TR>
<TR>
<TD>
<A HREF="#sdfapi_j">-j</A>
</TD>
<TD>
add SDF-style hypertext jumps from each symbol
</TD>
</TR>
</TABLE>
<HR>
<H2><A NAME="Description">Description</A></H2>
<P><A NAME="sdfapi_h">The -h option provides help. If it is specified without a parameter, a brief description of each option is displayed. To display the attributes for an option, specify the option letter as a parameter.</A></P>
<P><A NAME="sdfapi_o">By default, generated output goes to standard output. To direct output to a file per input file, use the -o option to specify an extension for output files. If the -o option is specified without a parameter, an extension of <EM>out</EM> is assumed.</A></P>
<P><A NAME="sdfapi_l">Likewise, error messages go to standard error by default. Use the -l option to create a log file per input file. If the -l option is specified without a parameter, an extension of <EM>log</EM> is assumed.</A></P>
<P><A NAME="sdfapi_O">By default, generated output and log files are created in the current directory. Use the -O option to specify an explicit output directory. If the -O option is specified without a parameter, the input file's directory is used.</A></P>
<P><A NAME="sdfapi_f">The format of the output can be controlled using the -f option. Supported formats are <EM>std</EM> and <EM>concise</EM>. The default is <EM>std</EM>. <EM>std</EM> format is:</A></P>
<PRE>
require "abc.pl";
$myvar = ...
$result =
&myfunc($myparams);
</PRE>
<P><EM>concise</EM> format has fewer blank lines and uses 1 line per symbol.</P>
<P><A NAME="sdfapi_s">A comma-separated list of symbol types to output can be specified using the -s option. Supported symbol types are:</A></P>
<UL>
<LI><EM>sub</EM> - subroutines
<LI><EM>var</EM> - variables</UL>
<P>The default is to extract all symbols.</P>
<P><A NAME="sdfapi_p">The -p option is used to extract only a subset of the symbols. If not supplied, the pattern is symbols beginning with a letter. If supplied without an option, the pattern defaults to all symbols. If perl libraries use the coding convention that symbols beginning with underscore are private, then -p_ can be used to extract the private symbols.</A></P>
<P><A NAME="sdfapi_j">The -j option can be used to request SDF-style hypertext jumps be added for each symbol. The jump target is <EM>lib_sym</EM> where:</A></P>
<UL>
<LI><EM>lib</EM> is the library name
<LI><EM>sym</EM> is the symbol name.</UL>
<HR>
<H2><A NAME="Limitations and future directions">Limitations and future directions</A></H2>
<P>The only language currently supported is <A HREF="http://www.perl.com/perl/index.html">Perl</A>.</P>
<P>It would be useful to extract messages from the scripts too. This would require a new utility called <EM>sdfmsg</EM> say, which searched through the source (including libraries) for <STRONG>AppMsg</STRONG> and <STRONG>AppExit</STRONG> calls.</P>
<P>Internally, it may be better to implement formats via routines. This would give better control over output. e.g. it would be up to the routine to decide if it wanted to output the 'require' header.</P>
</DIV>
<DIV CLASS="footer">
<DIV CLASS="navigate">
<P ALIGN="Center"><A HREF="re_sdf.html">Contents</A> | <A HREF="in_prog.html">Parent Topic</A> | <A HREF="sdf.html">Previous Topic</A> | <A HREF="sdfbatch.html">Next Topic</A> <BR><A HREF="../index.html">Home</A> | <A HREF="../catalog.html">Catalog</A></P>
</DIV>
</DIV>
</BODY>
</HTML>
|
