Running multiple parsers on an input file

Universal-ctags provides parser developers ways to run multiple parsers for an input file.

This subsection explains some examples of running multiple parsers. An example includes cases people wants to run multiple parsers on an input file, parser APIs used in the implementation.

There are two ways to combine parsers: guest/host and sub/base.

Applying a parser to specified areas of input file (guest/host)

guest/host combination considers the case that an input file has areas written in languages different from the language for the input file.

host parser parses the input file and detects the areas. guest parsers parses the areas.

guest parsers are run only when –extras=+g is given. If –fields=+E is given, all tags generated by a guest parser is marked guest in their extras: fields.

_images/area-and-parsers.svg

Examples of guest/host combinations

{CSS,JavaScript}/HTML parser combination

For a html file, you may want to run HTML parser, of course. The html file may have CSS areas and JavaScript areas. In other hand Universal-ctags has both CSS and JavaScript parsers. Don’t you think it is useful if you can apply these parsers to the areas?

In this case, HTML has responsible to detect the CSS and JavaScript areas and record the positions of the areas. The HTML parser schedules delayed invocations of CSS and JavaScript parsers on the area with promise API.

Here HTML parser is a host parser. CSS and JavaScript parsers are guest parsers.

See parsers/html.c.

C/Yacc parser combination

Similar case is found in YACC input. A yacc file has some areas written in C. Universal-ctags has both YACC and C parsers. You may want to run C parser for the areas from YACC parser.

Here YACC parser is a host parser. C parser is a guest parser. See promise API and parsers/yacc.c.

Pod/Perl parser combination

Pod (Plain Old Documentation) is a language for documentation. Not only the language can be used in stand alone file but also it can be used inside a perl script.

Universal-ctags has both parsers for Perl and Pod. The perl parser recognizes the area where Pod document is embedded and runs Pod parser as a guest parser on the area.

API for running a parser in an area

promise API can be used. A host parser using the interface has responsibility to detect areas from input stream and record them with name of guest parsers that will be applied to the areas.