FLEXML(1)

📦
version 1.9.6 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 FLEXML(1) 💖

okay bestie, sit down, hydrate, because today we're learning FLEXML(1) — the little tool that reads a DTD and hands you back a whole validating XML processor, no cap. perl people made it, it lives in the User Contributed Perl Documentation section, and it's about to be your new obsession. 🫶

✨ NAME ✨

flexml — generate validating XML processor and applications from DTD 💅

🎀 SYNOPSIS 🎀

flexml [-ASHDvdnLXV] [-sskel] [-ppubid] [-iinit_header] [-uuri]
[-rrootags] [-aactions] name[.dtd]

🦋 DESCRIPTION 🦋

so here's the vibe: Flexml reads name.dtd, which has to be a DTD (Document Type Definition) describing the format of XML (Extensible Markup Language) documents, and it produces a "validating" XML processor with an interface to support XML applications. and if you want, it can generate proper applications out of special "action files" — either for linking, or textually combined with the processor. iconic behavior. ✨

the generated processor is picky on purpose: it will only validate documents that conform strictly to the DTD, without extending it. more precisely, in practice we restrict XML rule [28] down to

[28r] doctypedecl ::= '<!DOCTYPE' S Name S ExternalID S? '>'

where the ExternalId denotes the used DTD. (one might say, in fact, that flexml implements "non-extensible" markup. :) — yes that's the author's own little joke, we love a self-aware king 👑)

the generated processor is a flex(1) scanner, by default named name.l, with a corresponding C header file name.h so you can compile generated applications separately. optionally, flexml takes an actions file with per-element actions and produces a C file with element functions for an XML application, with entry points called from the XML processor. (it can also fold the XML application into the XML processor to make stand-alone XML applications — but heads up bestie, that prevents sharing of the processor between applications. 🙈)

and because the author is organized: in "OPTIONS" we list the possible options, in "ACTION FILE FORMAT" we explain how to write applications, in "COMPILATION" we explain how to compile produced processors and applications into executables, and in "BUGS" we list the current limitations of the system before giving standard references. a full itinerary, we love a tour. 🧚

🌸 OPTIONS 🌸

Flexml takes the following options. every single one, bestie, let's go:

  • --stand-alone, -A — generate a stand-alone scanner application. if you combine it with -aactions then the application will be named as actions with the extension replaced by .l; otherwise it'll be in name.l. Conflicts with -S, -H, and -D. pick a struggle, not all of them 💀
  • --actions actions, -a actions — uses the actions file to produce an XML application in the file with the same name as actions, after replacing the extension with .c. if you combine it with -A then instead the stand-alone application will include the action functions.
  • --dummy [app_name], -D [app_name] — generate a dummy application with just empty functions, the ones that get called by the XML processor. if app_name isn't specified on the command line, it defaults to name-dummy.c. if you combine it with -a actions then the application will insert the specified actions and be named as actions with the extension replaced by .c. Conflicts with -A; and it's implied by -a unless either of -SHD is specified.
  • --debug, -d — turns on debug mode in the flex scanner, and also prints out the details of the DTD analysis performed by flexml. detective mode 🔍
  • --header [header_name], -H [header_name] — generate the header file. if header_name isn't specified on the command line, it defaults to name.h. Conflicts with -A; on by default if none of -SHD is specified.
  • --lineno, -L — makes the XML processor (as produced by flex(1)) count the lines in the input and keep it available to XML application actions in the integer yylineno. (this one is off by default, because the performance overhead is significant. respect the cost, bestie 😭)
  • --quiet, -q — prevents the XML processor (as produced by flex(1)) from reporting the error it runs into on stderr. instead, you'll have to pool for error messages yourself with the parse_err_msg() function. by default, error messages are written on stderr, so this one is very much a choose-your-own-adventure.
  • --dry-run, -n — "dry-run": do not produce any of the output files. all vibes, zero artifacts. 💅
  • --pubid pubid, -p pubid — sets the document type to be "PUBLIC" with the identifier pubid instead of "SYSTEM", which is the default.
  • --init_header init_header, -i init_header — puts a line containing #include "init_header" in the %{...%} section at the top of the generated .l file. this may be useful for making various flex #defines, for example YY_INPUT or YY_DECL.
  • --sysid=sysid — overrides the "SYSTEM" id of the accepted DTD. sometimes useful when your dtd is placed in a subdirectory. (yes, this one is written with the = and everything, we don't argue with the syntax 💖)
  • --root-tags roottags, -r roottags — restricts the XML processor to validate only documents with one of the root elements listed in the comma-separated roottags.
  • --scanner [scanner_name], -S [scanner_name] — generate the scanner. if scanner_name is not given on the command line, it defaults to name.l. Conflicts with -A; on by default if none of -SHD is specified.
  • --skel skel, -s skel — use the skeleton scanner skel instead of the default.
  • --act-bin flexml-act, -T flexml-act — this is an internal option, mainly used to test versions of flexml that aren't installed yet. insider business 🕵️
  • --stack-increment stack_increment, -b stack_increment — sets the FLEXML_BUFFERSTACKSIZE to stack_increment (which is 100000 by default). this controls how much the data stack grows in each realloc().
  • --tag-prefix STRING, -O STRING — use STRING to differentiate multiple versions of flexml in the same C code, just like the -P flex argument.
  • --uri uri, -u uri — sets the URI of the DTD, used in the "DOCTYPE" header, to the specified uri (the default is the DTD name).
  • --verbose, -v — be verbose: echo each DTD declaration (after parameter expansion).
  • --version, -V — print the version of flexml and exit. the shortest conversation in the whole page 🎀

🧚 ACTION FILE FORMAT 🧚

Action files, which you pass to the -a option, are XML documents conforming to the DTD flexml-act.dtd, which is exactly this, and yes we're keeping it verbatim because precision is the moment:

<!ELEMENT actions ((top|start|end)*,main?)>
<!ENTITY % C-code "(#PCDATA)">
<!ELEMENT top   %C-code;>
<!ELEMENT start %C-code;>  <!ATTLIST start tag NMTOKEN #REQUIRED>
<!ELEMENT end   %C-code;>  <!ATTLIST end   tag NMTOKEN #REQUIRED>
<!ELEMENT main  %C-code;>

The elements should be used as follows:

top

Use for top-level C code such as global declarations, utility functions, etc. your little global-zone bestie. 🌍

start

Attaches the code as an action to the element with the name of the required tag attribute. the %C-code; component should be C code suitable for inclusion in a C block (i.e., within {...} so it may contain local variables); furthermore the following extensions are available:

  • {attribute} — can be used to access the value of the attribute as set with attribute="value" in the start tag. in C, {attribute} will be interpreted depending on the declaration of the attribute. if the attribute is declared as an enumerated type like
<!ATTLIST attrib (alt1 | alt2 |...) ...>

then the C attribute value is of an enumerated type, with the elements written {attribute=alt1}, {attribute=alt2}, etc.; furthermore an unset attribute has the value {!attribute}. if the attribute is not an enumeration then {attribute} is a null-terminated C string (of type char*) and {!attribute} is NULL.

end

Similarly attaches the code as an action to the end tag with the name of the required tag attribute; also here the %C-code; component should be C code suitable for inclusion in a C block. in case the element has "Mixed" contents — i.e., was declared to permit #PCDATA — then the following variable is available:

  • {#PCDATA} — contains the text (#PCDATA) of the element as a null-terminated C string (of type char*). in case the Mixed contents element actually mixed text and child elements, then pcdata contains the plain concatenation of the text fragments as one string. glue it together, bestie 🫶

main

Finally, an optional main element can contain the C main function of the XML application. normally the main function should include (at least) one call of the XML processor:

  • yylex() — invokes the XML processor produced by flex(1) on the XML document found on the standard input (actually the yyin file handle: see the manual for flex(1) for information on how to change this as well as the name yylex).

If no main action is provided, then the following is used:

int main() { exit(yylex()); }

It is advisable to use XML <![CDATA[ ... ]]> sections for the C code, to make sure that all characters are properly passed to the output file. do it for the plot ✨

Finally, note that Flexml handles empty elements <tag/> as equivalent to <tag></tag>.

🌈 COMPILATION 🌈

The following make(1) file fragment shows how one can compile flexml-generated programs:

# 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 $^

💀 BUGS 💀

The present version of flexml is to be considered in "early beta" 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:

  • The character set is merely ASCII (actually flex(1) handles 8 bit characters, but only the ASCII character set is common with the XML default UTF-8 encoding).
  • ID type attributes are not validated for uniqueness; IDREF and IDREFS attributes are not validated for existence.
  • The ENTITY and ENTITIES attribute types are not supported.
  • NOTATION declarations are not supported.
  • The various xml:-attributes are treated like any other attributes; in particular xml:spaces should be supported.
  • The DTD 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 XML specification.
  • A child should be able to "return" a value for the parent (also called a synthesised attribute). Similarly, an element in Mixed contents should be able to inject text into the pcdata of the parent.

🍓 FILES 🍓

  • /usr/share/flexml/skel — the skeleton scanner with the generic parts of XML scanning.
  • /usr/share/doc/flexml/flexml/ — License, further documentation, and examples.

okay bestie that's the whole first half — the rest of the page is still coming, so don't wander off 💜

💫 SEE ALSO ✨

  • flex(1) — the og tool this whole thing is built on top of, go say hi 💖
  • Extensible Markup Language (XML) 1.0 (W3C Recommendation REC-xml-1998-0210) — the actual spec spec, no cap, if you wanna know what XML really means 🦋

👑 AUTHOR 🌸

Flexml was written by Kristoffer Rose, <"krisrose@debian.org">. yes that's the whole credit, one icon carrying the entire vibe, we stan 🙌

okay so legally speaking bestie, listen up, this is the paperwork part and it's giving very serious:

The program is Copyright (c) 1999 Kristoffer Rose (all rights reserved) and distributed under the GNU General Public License (GPL, also known as "copyleft", which clarifies that the author provides absolutely no warranty for flexml and ensures that flexml is and will remain available for all uses, even comercial).

no warranty means NO WARRANTY fr fr 😭 don't come for the author if it breaks, that's the deal, that's the copyleft vibe 💅

🫶 ACKNOWLEDGEMENT 🌈

ngl this part is so sweet 🥹

I am grateful to NTSys (France) for supporting the development of flexml. Finally extend my severe thanks to Jef Poskanzer, Vern Paxson, and the rest of the flex maintainers and GNU developers for a great tool.

like the way they said "severe thanks"?? that's commitment to gratitude, we love to see it 💖✨

okay bestie that's the whole page 🎀 this one is perl v5.40.1, dated 2025-07-26, and it's FLEXML(1) — go compile something iconic with it, you got this, periodt 🦋💜

📦 where this page comes from