.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SDFAPI 1"
.TH SDFAPI 1 "2023-08-02" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
sdfapi \- API Extraction Utility
.SH "PURPOSE"
.IX Header "PURPOSE"
\&\fIsdfapi\fR extracts \fIApplication Programming Interface\fR information
from (\fIPerl\fR) source code.
.SH "USAGE"
.IX Header "USAGE"
.Vb 6
\& 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)
.Ve
.PP
The options are:
.PP
.Vb 9
\& Option       Description
\& \-h           display help on options
\& \-o           output file extension
\& \-l           log file extension
\& \-O           output to input file\*(Aqs (or explicit) directory
\& \-f           output format tag
\& \-p           only symbols matching pattern
\& \-s           only symbols of these types
\& \-j           add SDF\-style hypertext jumps from each symbol
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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.
.PP
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 \fIout\fR is assumed.
.PP
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 \fIlog\fR is assumed.
.PP
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.
.PP
The format of the output can be controlled using the \-f option.
Supported formats are \fIstd\fR and \fIconcise\fR. The default is \fIstd\fR.
\&\fIstd\fR format is:
.PP
.Vb 1
\& require "abc.pl";
.Ve
.PP
\&\f(CW$myvar\fR = ...
.PP
\&\f(CW$result\fR =
&myfunc($myparams);
.PP
\&\fIconcise\fR format has fewer blank lines and uses 1 line per symbol.
.PP
A comma-separated list of symbol types to output can be specified
using the \-s option. Supported symbol types are:
.IP "\(bu" 4
\&\fIsub\fR \- subroutines
.IP "\(bu" 4
\&\fIvar\fR \- variables
.PP
The default is to extract all symbols.
.PP
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.
.PP
The \-j option can be used to request SDF-style hypertext jumps be
added for each symbol. The jump target is \fIlib_sym\fR where:
.IP "\(bu" 4
\&\fIlib\fR is the library name
.IP "\(bu" 4
\&\fIsym\fR is the symbol name.
.SH "LIMITATIONS AND FUTURE DIRECTIONS"
.IX Header "LIMITATIONS AND FUTURE DIRECTIONS"
The only language currently supported is \fIPerl\fR.
.PP
It would be useful to extract messages from the scripts too. This
would require a new utility called \fIsdfmsg\fR say, which searched
through the source (including libraries) for \fIAppMsg\fR and \fIAppExit\fR
calls.
.PP
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.