.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" 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 "FLEXML 1" .TH FLEXML 1 "2016-06-01" "perl v5.24.1" "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" flexml \- generate validating XML processor and applications from DTD .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBflexml\fR [\fB\-ASHDvdnLXV\fR] [\fB\-s\fR\fIskel\fR] [\fB\-p\fR\fIpubid\fR] [\fB\-i\fR\fIinit_header\fR] [\fB\-u\fR\fIuri\fR] [\fB\-r\fR\fIrootags\fR] [\fB\-a\fR\fIactions\fR] \&\fIname\fR[\fI.dtd\fR] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIFlexml\fR reads \fIname\fR\fI.dtd\fR which must be a \s-1DTD \s0(Document Type Definition) describing the format of \s-1XML \s0(Extensible Markup Language) documents, and produces a \*(L"validating\*(R" \s-1XML \s0\fIprocessor\fR with an interface to support \s-1XML \s0\fIapplication\fRs. Proper applications can be generated optionally from special \*(L"action files\*(R", either for linking or textual combination with the processor. .PP The generated processor will only validate documents that conform strictly to the \s-1DTD, \s0\fIwithout extending it\fR, more precisely we in practice restrict \s-1XML\s0 rule [28] to .PP .Vb 1 \& [28r] doctypedecl ::= \*(Aq\*(Aq .Ve .PP where the \f(CW\*(C`ExternalId\*(C'\fR denotes the used \s-1DTD. \s0(One might say, in fact, that \fIflexml\fR implements \*(L"non-extensible\*(R" markup. :) .PP The generated processor is a \fIflex\fR(1) scanner, by default named \&\fIname\fR\fI.l\fR with a corresponding C header file \fIname\fR\fI.h\fR for separate compilation of generated applications. Optionally \fIflexml\fR takes an \fIactions\fR file with per-element actions and produces a C file with element functions for an \s-1XML\s0 application with entry points called from the \s-1XML\s0 processor (it can also fold the \s-1XML\s0 application into the \s-1XML\s0 processor to make stand-alone \s-1XML\s0 applications but this prevents sharing of the processor between applications). .PP In \*(L"\s-1OPTIONS\*(R"\s0 we list the possible options, in \*(L"\s-1ACTION FILE FORMAT\*(R"\s0 we explain how to write applications, in \*(L"\s-1COMPILATION\*(R"\s0 we explain how to compile produced processors and applications into executables, and in \*(L"\s-1BUGS\*(R"\s0 we list the current limitations of the system before giving standard references. .SH "OPTIONS" .IX Header "OPTIONS" \&\fIFlexml\fR takes the following options. .IP "\fB\-\-stand\-alone\fR, \fB\-A\fR" 4 .IX Item "--stand-alone, -A" Generate a \fIstand-alone\fR scanner application. If combined with \&\fB\-a\fR\fIactions\fR then the application will be named as \fIactions\fR with the extension replaced by \fI.l\fR, otherwise it will be in \fIname\fR\fI.l\fR. Conflicts with \fB\-S\fR, \fB\-H\fR, and \fB\-D\fR. .IP "\fB\-\-actions\fR \fIactions\fR, \fB\-a\fR \fIactions\fR" 4 .IX Item "--actions actions, -a actions" Uses the \fIactions\fR file to produce an \s-1XML\s0 application in the file with the same name as \fIactions\fR after replacing the extension with \&\fI.c\fR. If combined with \fB\-A\fR then instead the stand-alone application will include the action functions. .IP "\fB\-\-dummy\fR \fB[\fR\fIapp_name\fR\fB]\fR, \fB\-D\fR \fB[\fR\fIapp_name\fR\fB]\fR" 4 .IX Item "--dummy [app_name], -D [app_name]" Generate a dummy application with just empty functions to be called by the \&\s-1XML\s0 processor. If \fIapp_name\fR is not specified on the command line, it defaults to \fIname\fR\fI\-dummy.c\fR. If combined with \fB\-a\fR \fIactions\fR then the application will insert the specified actions and be named as \fIactions\fR with the extension replaced by \fI.c\fR. Conflicts with \fB\-A\fR; implied by \&\fB\-a\fR unless either of \fB\-SHD\fR is specified. .IP "\fB\-\-debug\fR, \fB\-d\fR" 4 .IX Item "--debug, -d" Turns on debug mode in the flex scanner and also prints out the details of the \s-1DTD\s0 analysis performed by \fIflexml\fR. .IP "\fB\-\-header\fR \fB[\fR\fIheader_name\fR\fB]\fR, \fB\-H\fR \fB[\fR\fIheader_name\fR\fB]\fR" 4 .IX Item "--header [header_name], -H [header_name]" Generate the header file. If the \fIheader_name\fR is not specified on the command line, defaults to \fIname\fR\fI.h\fR. Conflicts with \fB\-A\fR; on by default if none of \fB\-SHD\fR specified. .IP "\fB\-\-lineno\fR, \fB\-L\fR" 4 .IX Item "--lineno, -L" Makes the \s-1XML\s0 processor (as produced by \fIflex\fR(1)) count the lines in the input and keep it available to \s-1XML\s0 application actions in the integer \f(CW\*(C`yylineno\*(C'\fR. (This is off by default as the performance overhead is significant.) .IP "\fB\-\-quiet\fR, \fB\-q\fR" 4 .IX Item "--quiet, -q" Prevents the \s-1XML\s0 processor (as produced by \fIflex\fR(1)) from reporting the error it runs into on stderr. Instead, users will have to pool for error messages with the \fIparse_err_msg()\fR function. By default, error messages are written on stderr. .IP "\fB\-\-dry\-run\fR, \fB\-n\fR" 4 .IX Item "--dry-run, -n" \&\*(L"Dry-run\*(R": do not produce any of the output files. .IP "\fB\-\-pubid\fR \fIpubid\fR, \fB\-p\fR \fIpubid\fR" 4 .IX Item "--pubid pubid, -p pubid" Sets the document type to be \f(CW\*(C`PUBLIC\*(C'\fR with the identifier \fIpubid\fR instead of \f(CW\*(C`SYSTEM\*(C'\fR, the default. .IP "\fB\-\-init_header\fR \fIinit_header\fR, \fB\-i\fR \fIinit_header\fR" 4 .IX Item "--init_header init_header, -i init_header" Puts a line containing \f(CW\*(C`#include "init_header"\*(C'\fR in the \f(CW\*(C`%{...%}\*(C'\fR section at the top of the generated .l file. This may be useful for making various flex \f(CW\*(C`#define\*(C'\fRs, for example \f(CW\*(C`YY_INPUT\*(C'\fR or \f(CW\*(C`YY_DECL\*(C'\fR. .IP "\fB\-\-sysid\fR=\fIsysid\fR" 4 .IX Item "--sysid=sysid" Overrides the \f(CW\*(C`SYSTEM\*(C'\fR id of the accepted \s-1DTD.\s0 Sometimes useful when your dtd is placed in a subdirectory. .IP "\fB\-\-root\-tags\fR \fIroottags\fR, \fB\-r\fR \fIroottags\fR" 4 .IX Item "--root-tags roottags, -r roottags" Restricts the \s-1XML\s0 processor to validate only documents with one of the root elements listed in the comma-separated \fIroottags\fR. .IP "\fB\-\-scanner\fR \fB[\fR\fIscanner_name\fR\fB]\fR, \fB\-S\fR \fB[\fR\fIscanner_name\fR\fB]\fR" 4 .IX Item "--scanner [scanner_name], -S [scanner_name]" Generate the scanner. If \fIscanner_name\fR is not given on command line, it defaults to \fIname\fR\fI.l\fR. Conflicts with \fB\-A\fR; on by default if none of \&\fB\-SHD\fR specified. .IP "\fB\-\-skel\fR \fIskel\fR, \fB\-s\fR \fIskel\fR" 4 .IX Item "--skel skel, -s skel" Use the skeleton scanner \fIskel\fR instead of the default. .IP "\fB\-\-act\-bin\fR \fIflexml-act\fR, \fB\-T\fR \fIflexml-act\fR" 4 .IX Item "--act-bin flexml-act, -T flexml-act" This is an internal option mainly used to test versions of flexml not installed yet. .IP "\fB\-\-stack\-increment\fR \fIstack_increment\fR, \fB\-b\fR \fIstack_increment\fR" 4 .IX Item "--stack-increment stack_increment, -b stack_increment" Sets the \s-1FLEXML_BUFFERSTACKSIZE\s0 to stack_increment (100000 by default). This controls how much the data stack grows in each \fIrealloc()\fR. .IP "\fB\-\-tag\-prefix\fR \fI\s-1STRING\s0\fR, \fB\-O\fR \fI\s-1STRING\s0\fR" 4 .IX Item "--tag-prefix STRING, -O STRING" Use \s-1STRING\s0 to differentiate multiple versions of flexml in the same C code, just like the \-P flex argument. .IP "\fB\-\-uri\fR \fIuri\fR, \fB\-u\fR \fIuri\fR" 4 .IX Item "--uri uri, -u uri" Sets the \s-1URI\s0 of the \s-1DTD,\s0 used in the \f(CW\*(C`DOCTYPE\*(C'\fR header, to the specified \fIuri\fR (the default is the \s-1DTD\s0 name). .IP "\fB\-\-verbose\fR, \fB\-v\fR" 4 .IX Item "--verbose, -v" Be verbose: echo each \s-1DTD\s0 declaration (after parameter expansion). .IP "\fB\-\-version\fR, \fB\-V\fR" 4 .IX Item "--version, -V" Print the version of \fIflexml\fR and exit. .SH "ACTION FILE FORMAT" .IX Header "ACTION FILE FORMAT" Action files, passed to the \fB\-a\fR option, are \s-1XML\s0 documents conforming to the \s-1DTD \s0\fIflexml\-act.dtd\fR which is the following: .PP .Vb 6 \& \& \& \& \& \& .Ve .PP The elements should be used as follows: .ie n .IP """top""" 4 .el .IP "\f(CWtop\fR" 4 .IX Item "top" Use for top-level C code such as global declarations, utility functions, etc. .ie n .IP """start""" 4 .el .IP "\f(CWstart\fR" 4 .IX Item "start" Attaches the code as an action to the element with the name of the required "\f(CW\*(C`tag\*(C'\fR\*(L" attribute. The \*(R"\f(CW\*(C`%C\-code;\*(C'\fR" component should be C code suitable for inclusion in a C block (i.e., within \f(CW\*(C`{\*(C'\fR...\f(CW\*(C`}\*(C'\fR so it may contain local variables); furthermore the following extensions are available: .Sp \&\f(CW\*(C`{\*(C'\fR\fIattribute\fR\f(CW\*(C`}\*(C'\fR: Can be used to access the value of the \&\fIattribute\fR as set with \fIattribute\fR\f(CW\*(C`=\*(C'\fR\fIvalue\fR in the start tag. In C, \f(CW\*(C`{\*(C'\fR\fIattribute\fR\f(CW\*(C`}\*(C'\fR will be interpreted depending on the declaration of the attribute. If the attribute is declared as an enumerated type like .Sp .Vb 1 \& .Ve .Sp then the C attribute value is of an enumerated type with the elements written \f(CW\*(C`{\*(C'\fR\fIattribute\fR\f(CW\*(C`=\*(C'\fR\fIalt1\fR\f(CW\*(C`}\*(C'\fR, \&\f(CW\*(C`{\*(C'\fR\fIattribute\fR\f(CW\*(C`=\*(C'\fR\fIalt2\fR\f(CW\*(C`}\*(C'\fR, etc.; furthermore an \fIunset\fR attribute has the \*(L"value\*(R" \f(CW\*(C`{!\*(C'\fR\fIattribute\fR\f(CW\*(C`}\*(C'\fR. If the attribute is not an enumeration then \f(CW\*(C`{\*(C'\fR\fIattribute\fR\f(CW\*(C`}\*(C'\fR is a null-terminated C string (of type \f(CW\*(C`char*\*(C'\fR) and \f(CW\*(C`{!\*(C'\fR\fIattribute\fR\f(CW\*(C`}\*(C'\fR is \f(CW\*(C`NULL\*(C'\fR. .ie n .IP """end""" 4 .el .IP "\f(CWend\fR" 4 .IX Item "end" Similarly attaches the code as an action to the end tag with the name of the required "\f(CW\*(C`tag\*(C'\fR\*(L" attribute; also here the \*(R"\f(CW\*(C`%C\-code;\*(C'\fR\*(L" component should be C code suitable for inclusion in a C block. In case the element has \*(R"Mixed" contents, i.e, was declared to permit \&\f(CW\*(C`#PCDATA\*(C'\fR, then the following variable is available: .Sp \&\f(CW\*(C`{#PCDATA}\*(C'\fR: Contains the text (\f(CW\*(C`#PCDATA\*(C'\fR) of the element as a null-terminated C string (of type \f(CW\*(C`char*\*(C'\fR). In case the Mixed contents element actually mixed text and child elements then \f(CW\*(C`pcdata\*(C'\fR contains the plain concatenation of the text fragments as one string. .ie n .IP """main""" 4 .el .IP "\f(CWmain\fR" 4 .IX Item "main" Finally, an optional "\f(CW\*(C`main\*(C'\fR" element can contain the C \f(CW\*(C`main\*(C'\fR function of the \s-1XML\s0 application. Normally the \f(CW\*(C`main\*(C'\fR function should include (at least) one call of the \s-1XML\s0 processor: .Sp \&\f(CW\*(C`yylex()\*(C'\fR: Invokes the \s-1XML\s0 processor produced by \fIflex\fR(1) on the \s-1XML\s0 document found on the standard input (actually the \f(CW\*(C`yyin\*(C'\fR file handle: see the manual for \fIflex\fR(1) for information on how to change this as well as the name \f(CW\*(C`yylex\*(C'\fR). .Sp If no \f(CW\*(C`main\*(C'\fR action is provided then the following is used: .Sp .Vb 1 \& int main() { exit(yylex()); } .Ve .PP It is advisable to use \s-1XML\s0 <\f(CW\*(C`![CDATA[\*(C'\fR ... \f(CW\*(C`]]\*(C'\fR> sections for the C code to make sure that all characters are properly passed to the output file. .PP Finally note that \fIFlexml\fR handles empty elements <\fItag\fR\f(CW\*(C`/\*(C'\fR> as equivalent to <\fItag\fR><\f(CW\*(C`/\*(C'\fR\fItag\fR>. .SH "COMPILATION" .IX Header "COMPILATION" The following \fImake\fR(1) file fragment shows how one can compile \&\fIflexml\fR\-generated programs: .PP .Vb 2 \& # Programs. \& FLEXML = flexml \-v \& \& # Generate linkable XML processor with header for application. \& %.l %.h: %.dtd \& $(FLEXML) $< \& \& # Generate C source from flex scanner. \& %.c: %.l \& $(FLEX) \-Bs \-o"$@" "$<" \& \& # Generate XML application C source to link with processor. \& # Note: The dependency must be of the form "appl.c: appl.act proc.dtd". \& %.c: %.act \& $(FLEXML) \-D \-a $^ \& \& # Direct generation of stand\-alone XML processor+application. \& # Note: The dependency must be of the form "appl.l: appl.act proc.dtd". \& %.l: %.act \& $(FLEXML) \-A \-a $^ .Ve .SH "BUGS" .IX Header "BUGS" The present version of \fIflexml\fR is to be considered in \*(L"early beta\*(R" state thus bugs should be expected (and the author would like to hear about them). Here are some known restrictions that we hope to overcome in the future: .IP "\(bu" 4 The character set is merely \s-1ASCII \s0(actually \fIflex\fR(1) handles 8 bit characters but only the \s-1ASCII\s0 character set is common with the \s-1XML\s0 default \s-1UTF\-8\s0 encoding). .IP "\(bu" 4 \&\f(CW\*(C`ID\*(C'\fR type attributes are not validated for uniqueness; \f(CW\*(C`IDREF\*(C'\fR and \&\f(CW\*(C`IDREFS\*(C'\fR attributes are not validated for existence. .IP "\(bu" 4 The \f(CW\*(C`ENTITY\*(C'\fR and \f(CW\*(C`ENTITIES\*(C'\fR attribute types are not supported. .IP "\(bu" 4 \&\f(CW\*(C`NOTATION\*(C'\fR declarations are not supported. .IP "\(bu" 4 The various \f(CW\*(C`xml:\*(C'\fR\-attributes are treated like any other attributes; in particular \f(CW\*(C`xml:spaces\*(C'\fR should be supported. .IP "\(bu" 4 The \s-1DTD\s0 parser is presently a perl hack so it may parse some DTDs badly; in particular the expansion of parameter entities may not conform fully to the \s-1XML\s0 specification. .IP "\(bu" 4 A child should be able to \*(L"return\*(R" a value for the parent (also called a \fIsynthesised attribute\fR). Similarly an element in Mixed contents should be able to inject text into the \f(CW\*(C`pcdata\*(C'\fR of the parent. .SH "FILES" .IX Header "FILES" .IP "\fI/usr/share/flexml/skel\fR" 4 .IX Item "/usr/share/flexml/skel" The skeleton scanner with the generic parts of \s-1XML\s0 scanning. .IP "\fI/usr/share/doc/flexml/flexml/\fR" 4 .IX Item "/usr/share/doc/flexml/flexml/" License, further documentation, and examples. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIflex\fR(1), Extensible Markup Language (\s-1XML\s0) 1.0 (W3C Recommendation REC\-xml\-1998\-0210). .SH "AUTHOR" .IX Header "AUTHOR" \&\fIFlexml\fR was written by Kristoffer Rose, <\f(CW\*(C`krisrose@debian.org\*(C'\fR>. .SH "COPYRIGHT" .IX Header "COPYRIGHT" The program is Copyright (c) 1999 Kristoffer Rose (all rights reserved) and distributed under the \s-1GNU\s0 General Public License (\s-1GPL,\s0 also known as \*(L"copyleft\*(R", which clarifies that the author provides absolutely no warranty for \fIflexml\fR and ensures that \fIflexml\fR is and will remain available for all uses, even comercial). .SH "ACKNOWLEDGEMENT" .IX Header "ACKNOWLEDGEMENT" I am grateful to NTSys (France) for supporting the development of \&\fIflexml\fR. Finally extend my severe thanks to Jef Poskanzer, Vern Paxson, and the rest of the \fIflex\fR maintainers and \s-1GNU\s0 developers for a great tool.