diff options
Diffstat (limited to 'ctags')
98 files changed, 49234 insertions, 0 deletions
diff --git a/ctags/README.md b/ctags/README.md new file mode 100644 index 0000000..fe49941 --- /dev/null +++ b/ctags/README.md @@ -0,0 +1,123 @@ +# Universal Ctags + +[](https://scan.coverity.com/projects/4355) +[](https://coveralls.io/github/universal-ctags/ctags?branch=master) +[](https://ci.appveyor.com/project/universalctags/ctags/branch/master) +[](https://docs.ctags.io) +[](https://circleci.com/gh/universal-ctags) + + +[Universal Ctags](https://ctags.io/) (abbreviated as u-ctags) is a *maintained* +implementation of `ctags`. +`ctags` generates an index (or tag) file of language objects found in source +files for programming languages. +This index makes it easy for text editors and other tools to locate the indexed +items. + +[Exuberant Ctags](http://ctags.sourceforge.net/) (e-ctags) maintained by Darren +Hiebert, the ancestor of Universal Ctags, improved traditional `ctags` with +multi-language support, the ability for the user to define new languages +searched by regular expressions (called optlib in Universal Ctags), and the +ability to generate emacs-style TAGS files. +But the activity of the project unfortunately stalled. + +Universal Ctags has the objective of continuing the development of Exuberant +Ctags. +Reza Jelveh <reza.jelveh@gmail.com> initially created a personal fork of +Exuberant Ctags on GitHub. +As interest and participation grew, it was decided to move development to a +dedicated project as Universal Ctags. +The goal of this project is to maintain a common/unified working space where +people interested in making ctags better can work together. + +Some of major features of Universal Ctags are; + +* more numbers of improved language support + * new extended C/C++ language parser, etc. +* fully extended optlib (a feature to define a new language parser from a + command line) +* interactive mode (experimental) + +## The latest build and package ## + +If you want to try the latest Universal Ctags without building it yourself... + +### Windows +Daily builds are available at the [ctags-win32](https://github.com/universal-ctags/ctags-win32) project. +Go to the [releases](https://github.com/universal-ctags/ctags-win32/releases) page to download zip packages. + +### Mac +See [Homebrew Tap for Universal Ctags](https://github.com/universal-ctags/homebrew-universal-ctags) + +### Snap +Go to [ctags-snap](https://github.com/universal-ctags/ctags-snap) and +clone the `ctags-snap` repo. Then, follow instructions to build the +snap package of Universal Ctags. Snapcraft will automatically fetch the source +code from GitHub. + +## How to build and install ## + +To build with Autotools (Autoconf, Automake, and Libtool) on GNU/Linux, OSX, or Windows 10 WSL, +``` + $ git clone https://github.com/universal-ctags/ctags.git + $ cd ctags + $ ./autogen.sh + $ ./configure --prefix=/where/you/want # defaults to /usr/local + $ make + $ make install # may require extra privileges depending on where to install +``` + +See +[`docs/autotools.rst`](https://github.com/universal-ctags/ctags/blob/master/docs/autotools.rst) +for more information. + +To build on Windows, see +[`docs/windows.rst`](https://github.com/universal-ctags/ctags/blob/master/docs/windows.rst) +for more information. + +To build on OSX, see +[`docs/osx.rst`](https://github.com/universal-ctags/ctags/blob/master/docs/osx.rst) +for more information. + +## Manual ## +The primary documents of Universal Ctags are man pages. +Users should first consult the +[ctags(1)](https://docs.ctags.io/en/latest/man/ctags.1.html), and [other man +pages](https://docs.ctags.io/en/latest/man-pages.html) if necessary. + +[Universal Ctags Hacking Guide](https://docs.ctags.io), which also includes the +man pages, is primarily for developers and provides additional information to +the man pages, including experimental features. + +See also `*/README.md` on this repository. + +## Differences from exuberant-ctags ## + +You may be interested in how Universal Ctags is different from Exuberant Ctags. +See +[ctags-incompatibilities(7)](https://docs.ctags.io/en/latest/man/ctags-incompatibilities.7.html) +and [Introduced changes](https://docs.ctags.io/en/latest/news.html) for details. + +The most significant incompatible changes: + +* Universal Ctags doesn't load `~/.ctags` and `./.ctags` at starting up time. + Instead, it loads `~/.ctags.d/*.ctags` and `./.ctags.d/*.ctags`. + +* Universal Ctags is more strict about characters that can be + used in kind letters and kind names than Exuberant-ctags. + + - The letter must be an alphabetical character (`[a-zA-EG-Z]`). + `F` is reserved for `file` kind. + + - The first character of the name must be alphabetic, and + the rest characters must be alphanumeric (`[a-zA-Z][a-zA-Z0-9]*`). + + The detailed background is explained in + [#1737](https://github.com/universal-ctags/ctags/pull/1737). + + If you want to reuse your `.ctags` written for Exuberant-ctags, + you must review kind letters and names defined with `--regex-<LANG>=...` + options. When updating the definitions, using `--kinddef-<LANG>=...` option + is appreciated. + +Pull-requests are welcome! diff --git a/ctags/ctags.exe b/ctags/ctags.exe Binary files differnew file mode 100644 index 0000000..144c542 --- /dev/null +++ b/ctags/ctags.exe diff --git a/ctags/docs/.buildinfo b/ctags/docs/.buildinfo new file mode 100644 index 0000000..c689e10 --- /dev/null +++ b/ctags/docs/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: dc0bed28d76d27b3f327399c8812a8fd +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/ctags/docs/_images/area-and-parsers.svg b/ctags/docs/_images/area-and-parsers.svg new file mode 100644 index 0000000..55688e5 --- /dev/null +++ b/ctags/docs/_images/area-and-parsers.svg @@ -0,0 +1,456 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="72.79567mm" + height="80.585587mm" + viewBox="0 0 257.93741 285.53947" + id="svg2" + version="1.1" + inkscape:version="0.92.0 r" + sodipodi:docname="area-and-parsers.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker12257" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path12259" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker11059" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path11061" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6737" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6191" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-6" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-7" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.8284271" + inkscape:cx="459.13739" + inkscape:cy="141.21166" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="2880" + inkscape:window-height="1517" + inkscape:window-x="0" + inkscape:window-y="55" + inkscape:window-maximized="1" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + scale-x="0.9375"> + <sodipodi:guide + position="415.39384,5.0795382" + orientation="1,0" + id="guide7768" + inkscape:locked="false" /> + <sodipodi:guide + position="90.877794,80.212487" + orientation="1,0" + id="guide4617" + inkscape:locked="false" /> + <sodipodi:guide + position="144.90517,269.80548" + orientation="0,1" + id="guide4619" + inkscape:locked="false" /> + <sodipodi:guide + position="256.9374,62.645304" + orientation="1,0" + id="guide4621" + inkscape:locked="false" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-121.65977,-41.187943)"> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 192.97021,76.736577 12.39295,0.0223 -0.0207,10.0459 15.43867,-18.10275 -15.42523,-17.8284 -0.01,10.00683 -12.41063,-0.0434 z" + id="path5618-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <rect + y="56.921947" + x="212.53755" + height="268.80545" + width="166.05962" + id="rect5837-3" + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,192.19745 H 370.06867" + id="path3856" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,170.04157 H 370.06867" + id="path3856-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,147.88567 H 370.06867" + id="path3856-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,92.495947 H 370.06868" + id="path3856-3-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,136.80773 H 370.06867" + id="path3856-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,81.418011 H 370.06868" + id="path3856-3-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,125.7298 H 370.06867" + id="path3856-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,70.340072 H 370.06868" + id="path3856-3-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,114.65183 H 370.06867" + id="path3856-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,103.57389 H 370.06868" + id="path3856-3-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,314.05482 H 370.06867" + id="path3856-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,236.50923 H 370.06868" + id="path3856-3-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,302.97688 H 370.06867" + id="path3856-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,214.35332 H 370.06868" + id="path3856-3-06" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,280.82101 H 370.06867" + id="path3856-26" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,258.6651 H 370.06868" + id="path3856-3-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,158.96364 H 370.06867" + id="path3856-8" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,291.89895 H 370.06867" + id="path3856-9-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,203.27539 H 370.06868" + id="path3856-3-3-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,269.74303 H 370.06867" + id="path3856-6-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,181.11951 H 370.06868" + id="path3856-3-06-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,247.58715 H 370.06867" + id="path3856-26-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 220.67844,225.43126 H 370.06868" + id="path3856-3-1-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="259.20898" + y="50.687943" + id="text4771-7"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5" + x="259.20898" + y="50.687943">input file</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 255.2964,187.32758 h -6.07639 v 10.41668 l 6.11255,-0.0362" + id="path4039" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 333.85358,218.87042 6.07638,0.0105 0.018,-10.41665 -6.1126,0.0256" + id="path4039-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:2.81249994, 8.43749982;stroke-dashoffset:0;stroke-opacity:1" + d="m 256.25126,192.13226 113.81742,-0.26131" + id="path4908" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:2.81249997, 8.4374999;stroke-dashoffset:0;stroke-opacity:1" + d="M 220.67844,202.94889 H 370.06868" + id="path4908-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:2.8125, 8.43749998;stroke-dashoffset:0;stroke-opacity:1" + d="M 220.67844,214.02683 H 335.38118" + id="path4908-2-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <g + aria-label="area" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + id="text4771-7-3" /> + <g + id="g5595" + transform="translate(-145.21796,91.603998)"> + <g + id="text4771-7-9-7" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:#ffffff;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + aria-label="area" + transform="translate(10.093756,22.609375)"> + <path + inkscape:connector-curvature="0" + id="path5522-8" + style="stroke:#ffffff;stroke-width:1px;stroke-opacity:1" + d="m 417.02206,85.088997 q 1.25,0 1.7125,0.5 0.475,0.5 0.475,1.875 v 4.25 h -0.9 l -0.025,-0.9375 h -0.025 q -0.5875,1.0625 -1.8625,1.0625 -0.8125,0 -1.3125,-0.5125 -0.5,-0.525 -0.5,-1.425 0,-1.1375 0.7625,-1.75 0.775,-0.625 2.3,-0.625 h 0.6 v -0.3125 q 0,-0.7125 -0.275,-1 -0.275,-0.2875 -0.95,-0.2875 -0.4125,0 -1.05,0.15 -0.6375,0.15 -1.075,0.35 v -0.9 q 0.4375,-0.1875 1.0625,-0.3125 0.625,-0.125 1.0625,-0.125 z m 1.225,3.1875 h -0.6 q -2.125,0 -2.125,1.5625 0,0.5625 0.2875,0.8625 0.2875,0.3 0.775,0.3 0.7375,0 1.2,-0.6 0.4625,-0.6 0.4625,-1.6875 z" /> + <path + inkscape:connector-curvature="0" + id="path5524-4" + style="stroke:#ffffff;stroke-width:1px;stroke-opacity:1" + d="m 422.40956,85.213997 v 1.25 h 0.025 q 0.775,-1.375 2.15,-1.375 0.4625,0 0.875,0.125 v 0.875 q -0.4375,-0.1375 -0.875,-0.1375 -0.9125,0 -1.525,0.7625 -0.6125,0.7625 -0.6125,2 v 3 h -0.9875 v -6.5 z" /> + <path + inkscape:connector-curvature="0" + id="path5526-5" + style="stroke:#ffffff;stroke-width:1px;stroke-opacity:1" + d="m 428.05956,88.788997 q 0.05,1.1625 0.475,1.675 0.425,0.5125 1.2375,0.5125 0.7625,0 1.6875,-0.45 v 1 q -0.925,0.3125 -1.75,0.3125 -2.6875,0 -2.6875,-3.375 0,-1.7625 0.625,-2.5625 0.625,-0.8125 1.875,-0.8125 1.1375,0 1.6875,0.775 0.5625,0.775 0.5625,2.5375 0,0.1375 -0.025,0.3875 z m 0,-0.825 h 2.725 q -0.0125,-2.0125 -1.2625,-2.0125 -0.7125,0 -1.0625,0.45 -0.35,0.45 -0.4,1.5625 z" /> + <path + inkscape:connector-curvature="0" + id="path5528-0" + style="stroke:#ffffff;stroke-width:1px;stroke-opacity:1" + d="m 435.77206,85.088997 q 1.25,0 1.7125,0.5 0.475,0.5 0.475,1.875 v 4.25 h -0.9 l -0.025,-0.9375 h -0.025 q -0.5875,1.0625 -1.8625,1.0625 -0.8125,0 -1.3125,-0.5125 -0.5,-0.525 -0.5,-1.425 0,-1.1375 0.7625,-1.75 0.775,-0.625 2.3,-0.625 h 0.6 v -0.3125 q 0,-0.7125 -0.275,-1 -0.275,-0.2875 -0.95,-0.2875 -0.4125,0 -1.05,0.15 -0.6375,0.15 -1.075,0.35 v -0.9 q 0.4375,-0.1875 1.0625,-0.3125 0.625,-0.125 1.0625,-0.125 z m 1.225,3.1875 h -0.6 q -2.125,0 -2.125,1.5625 0,0.5625 0.2875,0.8625 0.2875,0.3 0.775,0.3 0.7375,0 1.2,-0.6 0.4625,-0.6 0.4625,-1.6875 z" /> + </g> + <g + transform="translate(10.093756,22.609375)" + id="text4771-7-9" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + aria-label="area"> + <path + inkscape:connector-curvature="0" + id="path5522" + style="stroke-width:1px" + d="m 417.02206,85.088997 q 1.25,0 1.7125,0.5 0.475,0.5 0.475,1.875 v 4.25 h -0.9 l -0.025,-0.9375 h -0.025 q -0.5875,1.0625 -1.8625,1.0625 -0.8125,0 -1.3125,-0.5125 -0.5,-0.525 -0.5,-1.425 0,-1.1375 0.7625,-1.75 0.775,-0.625 2.3,-0.625 h 0.6 v -0.3125 q 0,-0.7125 -0.275,-1 -0.275,-0.2875 -0.95,-0.2875 -0.4125,0 -1.05,0.15 -0.6375,0.15 -1.075,0.35 v -0.9 q 0.4375,-0.1875 1.0625,-0.3125 0.625,-0.125 1.0625,-0.125 z m 1.225,3.1875 h -0.6 q -2.125,0 -2.125,1.5625 0,0.5625 0.2875,0.8625 0.2875,0.3 0.775,0.3 0.7375,0 1.2,-0.6 0.4625,-0.6 0.4625,-1.6875 z" /> + <path + inkscape:connector-curvature="0" + id="path5524" + style="stroke-width:1px" + d="m 422.40956,85.213997 v 1.25 h 0.025 q 0.775,-1.375 2.15,-1.375 0.4625,0 0.875,0.125 v 0.875 q -0.4375,-0.1375 -0.875,-0.1375 -0.9125,0 -1.525,0.7625 -0.6125,0.7625 -0.6125,2 v 3 h -0.9875 v -6.5 z" /> + <path + inkscape:connector-curvature="0" + id="path5526" + style="stroke-width:1px" + d="m 428.05956,88.788997 q 0.05,1.1625 0.475,1.675 0.425,0.5125 1.2375,0.5125 0.7625,0 1.6875,-0.45 v 1 q -0.925,0.3125 -1.75,0.3125 -2.6875,0 -2.6875,-3.375 0,-1.7625 0.625,-2.5625 0.625,-0.8125 1.875,-0.8125 1.1375,0 1.6875,0.775 0.5625,0.775 0.5625,2.5375 0,0.1375 -0.025,0.3875 z m 0,-0.825 h 2.725 q -0.0125,-2.0125 -1.2625,-2.0125 -0.7125,0 -1.0625,0.45 -0.35,0.45 -0.4,1.5625 z" /> + <path + inkscape:connector-curvature="0" + id="path5528" + style="stroke-width:1px" + d="m 435.77206,85.088997 q 1.25,0 1.7125,0.5 0.475,0.5 0.475,1.875 v 4.25 h -0.9 l -0.025,-0.9375 h -0.025 q -0.5875,1.0625 -1.8625,1.0625 -0.8125,0 -1.3125,-0.5125 -0.5,-0.525 -0.5,-1.425 0,-1.1375 0.7625,-1.75 0.775,-0.625 2.3,-0.625 h 0.6 v -0.3125 q 0,-0.7125 -0.275,-1 -0.275,-0.2875 -0.95,-0.2875 -0.4125,0 -1.05,0.15 -0.6375,0.15 -1.075,0.35 v -0.9 q 0.4375,-0.1875 1.0625,-0.3125 0.625,-0.125 1.0625,-0.125 z m 1.225,3.1875 h -0.6 q -2.125,0 -2.125,1.5625 0,0.5625 0.2875,0.8625 0.2875,0.3 0.775,0.3 0.7375,0 1.2,-0.6 0.4625,-0.6 0.4625,-1.6875 z" /> + </g> + </g> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 218.89686,200.25581 12.39295,0.0223 -0.0207,10.0459 15.43867,-18.10275 -15.42523,-17.8284 -0.01,10.00683 -12.41063,-0.0434 z" + id="path5618-0-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="120.78477" + y="72.011642" + id="text4771-7-36"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7" + x="120.78477" + y="72.011642">host parser</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="131.38818" + y="195.4604" + id="text4771-7-36-5"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-3" + x="131.38818" + y="195.4604">guest parser</tspan></text> + </g> +</svg> diff --git a/ctags/docs/_images/input-text-stream.svg b/ctags/docs/_images/input-text-stream.svg new file mode 100644 index 0000000..1842f6c --- /dev/null +++ b/ctags/docs/_images/input-text-stream.svg @@ -0,0 +1,498 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="167.89255mm" + height="99.839706mm" + viewBox="0 0 594.89486 353.76276" + id="svg2" + version="1.1" + inkscape:version="0.91 r13725" + sodipodi:docname="input-text-stream.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker12257" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path12259" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker11059" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + id="path11061" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6737" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6191" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-6" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-7" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="2.0000001" + inkscape:cx="234.25314" + inkscape:cy="183.38668" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="2880" + inkscape:window-height="1583" + inkscape:window-x="1200" + inkscape:window-y="0" + inkscape:window-maximized="1" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0"> + <sodipodi:guide + position="426.1203,332.25068" + orientation="1,0" + id="guide7768" /> + <sodipodi:guide + position="276.92077,57.186122" + orientation="1,0" + id="guide6795" /> + <sodipodi:guide + position="524.61361,27.425191" + orientation="0,1" + id="guide6910" /> + <sodipodi:guide + position="473.14292,279.92477" + orientation="0,1" + id="guide7227" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-67.866371,-141.45457)"> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="67.530678" + y="335.67322" + id="text9293" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan9295" + x="67.530678" + y="335.67322" + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';text-align:start;writing-mode:lr-tb;text-anchor:start">File</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#666666;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:" + d="m 92.08532,334.79905 26.03301,15.03449" + id="path7947-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5890-3" + width="115.17915" + height="143.60025" + x="120.64043" + y="350.61703" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="192.03923" + y="437.42728" + id="text4751-9" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4753-3" + x="192.03923" + y="437.42728">inputFileInfo</tspan></text> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5890-3-2" + width="74.179138" + height="26.850252" + x="284.89038" + y="466.61707" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="289.03918" + y="485.67725" + id="text4751-9-5" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4753-3-3" + x="289.03918" + y="485.67725">MIO</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="183.0112" + y="375.04214" + id="text4723-9" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725-6" + x="183.0112" + y="375.04214">.<tspan + style="fill:#ff0000" + id="tspan7233">input</tspan></tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#666666;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:" + d="m 229.87899,474.95864 54.38481,-8.6455" + id="path7947-9-5-1" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="202.2612" + y="478.54218" + id="text4723-9-3" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725-6-5" + x="202.2612" + y="478.54218">.mio</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="182.54245" + y="415.66718" + id="text4723-9-37" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725-6-9" + x="182.54245" + y="415.66718">.source</tspan></text> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5890-3-2-0" + width="227.67914" + height="37.35025" + x="188.89038" + y="361.86703" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="122.66747" + y="492.16711" + id="text4751-9-2" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4753-3-7" + x="122.66747" + y="492.16711">inputFile</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="192.0737" + y="394.16714" + id="text4751-9-7" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4753-3-6" + x="192.0737" + y="394.16714">inputFileInfo</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="379.04248" + y="376.66718" + id="text4723-9-6" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725-6-0" + x="379.04248" + y="376.66718">.name</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="343.10495" + y="390.54218" + id="text4723-9-6-5" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725-6-0-8" + x="343.10495" + y="390.54218">.lineNumber</tspan></text> + <rect + y="405.86703" + x="188.89038" + height="37.35025" + width="227.67914" + id="rect6754" + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="380.82373" + y="421.10468" + id="text4723-9-6-8" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725-6-0-7" + x="380.82373" + y="421.10468">.name</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="344.8862" + y="434.97968" + id="text4723-9-6-5-1" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725-6-0-8-3" + x="344.8862" + y="434.97968">.lineNumber</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.56267413;marker-end:" + d="m 326.78713,483.28606 43.13352,-43.84062 0,-61.51829 -43.13352,-24.90314 0,-105.20449" + id="path6819" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="260.0112" + y="229.16718" + id="text4413-4" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4415-4" + x="260.0112" + y="229.16718">readLineFrom<tspan + style="fill:#ff0000" + id="tspan7229">Input</tspan>File()</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="259.13953" + y="244.50829" + id="text4413-4-4" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4415-4-7" + x="259.13953" + y="244.50829">getcFrom<tspan + style="fill:#ff0000" + id="tspan7231">Input</tspan>File()</tspan></text> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3382-6" + width="188.39343" + height="34.850262" + x="173.88332" + y="155.94229" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="272.13773" + y="185.185" + id="text4295-0" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4297-1" + x="272.13773" + y="185.185">lang->parser()</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="174.36806" + y="150.95457" + id="text4299-7" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4301-4" + x="174.36806" + y="150.95457">native parser written in C</tspan></text> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:" + d="m 318.88942,215.03846 -0.022,-12.39295 -10.0459,0.0207 18.1028,-15.43867 17.82841,15.42523 -10.00691,0.01 0.043,12.41063 z" + id="path5618-0-6-14-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.47632315;marker-end:" + d="m 326.78713,482.57895 149.35029,-37.18376 -0.5,-204.93964" + id="path6945" + inkscape:connector-curvature="0" + sodipodi:nodetypes="ccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="412.98727" + y="230.28645" + id="text4413-4-1" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4415-4-5" + x="412.98727" + y="230.28645">readLineFrom<tspan + style="fill:#000080" + id="tspan7235">Bypass</tspan>()</tspan></text> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5890-3-2-9" + width="74.179138" + height="26.850252" + x="585.39044" + y="467.36707" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="589.53925" + y="486.42725" + id="text4751-9-5-6" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4753-3-3-7" + x="589.53925" + y="486.42725">MIO</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.72144847;marker-end:" + d="m 624.47997,476.79215 c 0,-237 0,-237 0,-237" + id="path7025" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="583.07373" + y="230.22966" + id="text4413-4-1-8" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4415-4-5-5" + x="583.07373" + y="230.22966">readLine<tspan + style="fill:#008000" + id="tspan7237">Raw</tspan>()</tspan></text> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:" + d="m 465.58226,215.68015 -0.022,-12.39295 -10.0459,0.0207 18.1028,-15.43867 17.82841,15.42523 -10.00691,0.01 0.043,12.41063 z" + id="path5618-0-6-14-4-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:" + d="m 613.58226,214.68015 -0.022,-12.39295 -10.0459,0.0207 18.1028,-15.43867 17.82841,15.42523 -10.00691,0.01 0.043,12.41063 z" + id="path5618-0-6-14-4-4-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3382-6-8" + width="188.39343" + height="34.850262" + x="174.22289" + y="286.2106" /> + <text + sodipodi:linespacing="0%" + id="text7290" + y="280.95459" + x="174.36806" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve"><tspan + y="280.95459" + x="174.36806" + id="tspan7292" + sodipodi:role="line">regex parser pattern matching</tspan></text> + </g> +</svg> diff --git a/ctags/docs/_images/output-tag-stream.svg b/ctags/docs/_images/output-tag-stream.svg new file mode 100644 index 0000000..adccd79 --- /dev/null +++ b/ctags/docs/_images/output-tag-stream.svg @@ -0,0 +1,693 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="182.72736mm" + height="151.30022mm" + viewBox="0 0 647.45913 536.10312" + id="svg2" + version="1.1" + inkscape:version="0.91 r13725" + sodipodi:docname="output-tag-stream.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker12257" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path12259" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker11059" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + id="path11061" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6737" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6191" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-6" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-7" + d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.87" + inkscape:cx="346.42618" + inkscape:cy="423.28269" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="1920" + inkscape:window-height="1016" + inkscape:window-x="0" + inkscape:window-y="27" + inkscape:window-maximized="1" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0"> + <sodipodi:guide + position="511.54715,236.14422" + orientation="1,0" + id="guide7768" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-25.506451,-21.688993)"> + <path + style="fill:#b3b3b3;fill-rule:evenodd;stroke:#e2e4e4;stroke-width:10.10000038;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="M 81.07377,300.30479 457.92005,301.719" + id="path4279-5-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="184.74545" + y="304.69986" + id="text4413" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4415" + x="184.74545" + y="304.69986">jsonWriter</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="283.88431" + y="305.40698" + id="text4763" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4765" + x="283.88431" + y="305.40698">xrefWriter</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="382.71069" + y="304.69986" + id="text4767" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4769" + x="382.71069" + y="304.69986">ctagsWriter</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="79.806602" + y="305.10468" + id="text4413-3" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4415-5" + x="79.806602" + y="305.10468">etagsWriter</tspan></text> + <path + style="fill:#b3b3b3;fill-rule:evenodd;stroke:#e2e4e4;stroke-width:10.10000038;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 197.3414,195.06721 406.58639,1.41421" + id="path4279-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:#b3b3b3;fill-rule:evenodd;stroke:#e2e4e4;stroke-width:10.10000038;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 269.83382,153.0672 274.35743,1.41421" + id="path4279" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect3382" + width="188.39343" + height="34.850262" + x="306.42352" + y="71.447166" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 396.15383,115.31842 -0.0223,12.39295 -10.0459,-0.0207 18.10275,15.43867 17.8284,-15.42523 -10.00683,-0.01 0.0434,-12.41063 z" + id="path5618-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 245.31691,159.54564 -0.0223,12.39295 -10.0459,-0.0207 18.10275,15.43867 17.8284,-15.42523 -10.00683,-0.01 0.0434,-12.41063 z" + id="path5618-0-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <rect + y="346.8757" + x="280.06638" + height="72.35025" + width="77.679146" + id="rect5837" + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cccccccc" + inkscape:connector-curvature="0" + id="path5845" + d="m 241.84566,323.14873 8.03233,9.43755 -7.65191,6.50913 23.79205,-0.0189 3.53717,-23.30833 -7.61526,6.49189 -8.02777,-9.46469 z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 389.5553,323.14873 -8.03233,9.43755 7.65191,6.50913 -23.79205,-0.0189 -3.53717,-23.30833 7.61526,6.49189 8.02777,-9.46469 z" + id="path5862" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 115.61629,312.33404 -0.0223,12.39295 -10.0459,-0.0207 18.10275,15.43867 17.8284,-15.42523 -10.00683,-0.01 0.0434,-12.41063 z" + id="path5888" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5890" + width="77.679146" + height="72.35025" + x="86.066391" + y="346.8757" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 208.58379,385.56106 12.39295,0.0223 -0.0207,10.0459 15.43867,-18.10275 -15.42523,-17.8284 -0.01,10.00683 -12.41063,-0.0434 z" + id="path5618-0-6-1-3" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + sodipodi:nodetypes="cccccccc" + inkscape:connector-curvature="0" + id="path5927" + d="m 539.31691,159.54564 -0.0223,12.39295 -10.0459,-0.0207 18.10275,15.43867 17.8284,-15.42523 -10.00683,-0.01 0.0434,-12.41063 z" + style="fill:none;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <rect + y="233.49739" + x="467.19669" + height="38.701088" + width="41.551579" + id="rect5837-1" + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5952" + width="41.551579" + height="38.701088" + x="467.19669" + y="233.49739" /> + <rect + y="233.49739" + x="467.19669" + height="38.701088" + width="41.551579" + id="rect5954" + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect5956" + width="41.551579" + height="38.701088" + x="509.19669" + y="233.49739" /> + <rect + y="233.49739" + x="551.19672" + height="38.701088" + width="41.551579" + id="rect5958" + style="opacity:1;fill:none;fill-opacity:1;stroke:#ff0000;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <g + id="g5972" + transform="translate(259.55907,-190.23523)"> + <circle + r="5.5558391" + cy="443.24023" + cx="346.9874" + id="path5962" + style="opacity:1;fill:#666666;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <circle + style="opacity:1;fill:#666666;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="circle5964" + cx="346.9874" + cy="443.24023" + r="5.5558391" /> + <circle + r="5.5558391" + cy="443.24023" + cx="346.9874" + id="circle5966" + style="opacity:1;fill:#666666;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <circle + style="opacity:1;fill:#666666;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="circle5968" + cx="362.9874" + cy="443.24023" + r="5.5558391" /> + <circle + r="5.5558391" + cy="443.24023" + cx="378.9874" + id="circle5970" + style="opacity:1;fill:#666666;fill-opacity:1;stroke:none;stroke-width:1;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + </g> + <path + sodipodi:nodetypes="cccccccc" + inkscape:connector-curvature="0" + id="path5927-4" + d="m 561.78831,210.16742 -0.0223,12.39295 -10.0459,-0.0207 18.10275,15.43867 17.8284,-15.42523 -10.00683,-0.01 0.0434,-12.41063 z" + style="fill:#ffffff;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#666666;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4, 8;stroke-dashoffset:0;stroke-opacity:1" + d="m 537.11399,286.32865 -0.0514,25.25382 118.05104,0 -0.82197,-287.893477 -401.03056,0 0,130.309677" + id="path6643" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccc" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 647.10262,99.7502 -0.0223,-12.39295 -10.0459,0.0207 18.10275,-15.43867 17.8284,15.42523 -10.00683,0.01 0.0434,12.41063 z" + id="path5618-0-6-14" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 465,103.86221 c 25,135.5 25,135.5 25,135.5" + id="path7947" + inkscape:connector-curvature="0" /> + <rect + y="484.44189" + x="204.85831" + height="72.35025" + width="77.679146" + id="rect5837-8" + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="108.89445" + y="473.50165" + id="text9293" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan9295" + x="108.89445" + y="473.50165" + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';text-align:start;writing-mode:lr-tb;text-anchor:start">TagFile</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#666666;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 159.9491,467.12748 45.53301,18.53449" + id="path7947-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#666666;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 278.53294,498.24274 78.88478,-78.3955" + id="path7947-9-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <rect + style="opacity:1;fill:none;fill-opacity:1;stroke:#666666;stroke-width:2;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="rect11783" + width="77.679146" + height="72.35025" + x="432.85831" + y="484.44189" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path11823" + d="M 278.98416,518.24883 432.44359,484.7295" + style="fill:none;fill-rule:evenodd;stroke:#666666;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#666666;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 506.74466,494.2973 465.60506,272.92337" + id="path12255" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="250.69174" + y="503.36951" + id="text4723" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4725" + x="250.69174" + y="503.36951">.mio</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="212.93439" + y="520.0766" + id="text4727" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4729" + x="212.93439" + y="520.0766">.corkQueue</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="208.12556" + y="551.69763" + id="text4731" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4733" + x="208.12556" + y="551.69763">tagFile</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="435.61075" + y="551.87939" + id="text4735" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4737" + x="435.61075" + y="551.87939">sCorkQueue</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="466.79224" + y="499.26263" + id="text4739" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4741" + x="466.79224" + y="499.26263">.queue</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="283.84296" + y="415.47815" + id="text4743" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4745" + x="283.84296" + y="415.47815">MIO</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="179.7706" + y="406.90338" + id="text4747" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4749" + x="179.7706" + y="406.90338">endEtagsFile()</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="89.215195" + y="414.43594" + id="text4751" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4753" + x="89.215195" + y="414.43594">MIO</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="157.84821" + y="156.5154" + id="text4755" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4757" + x="157.84821" + y="156.5154">if (!use_cork)</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="204.45424" + y="199.53238" + id="text4759" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4761" + x="204.45424" + y="199.53238">writeTagEntry()</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="572.71277" + y="304.77167" + id="text4771" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4773" + x="572.71277" + y="304.77167">flushing</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="561.21216" + y="157.6367" + id="text4775" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4777" + x="561.21216" + y="157.6367">if (use_cork)</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="365.88055" + y="157.40643" + id="text4779" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4781" + x="365.88055" + y="157.40643">makeTagEntry()</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="503.32812" + y="203.0789" + id="text4291" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4293" + x="503.32812" + y="203.0789">queueTagEntry()</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="404.67789" + y="100.68987" + id="text4295" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4297" + x="404.67789" + y="100.68987">lang->parser()</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="306.90823" + y="66.45945" + id="text4299" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4301" + x="306.90823" + y="66.45945">native parser written in C</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:#ffffff;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="472.24466" + y="266.97083" + id="text4283" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4285" + x="472.24466" + y="266.97083">tagEntryInfo</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="472.24466" + y="266.97083" + id="text4287" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4289" + x="472.24466" + y="266.97083">tagEntryInfo</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="59.61412" + y="431.24063" + id="text9293-3" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan9295-6" + x="59.61412" + y="431.24063" + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';text-align:start;writing-mode:lr-tb;text-anchor:start">writer-etags.c private</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="204.96909" + y="249.66718" + id="text4759-3" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4761-6" + x="204.96909" + y="249.66718">writeWriteTag()</tspan></text> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 245.29047,205.90418 -0.0223,12.39295 -10.0459,-0.0207 18.10275,15.43867 17.8284,-15.42523 -10.00683,-0.01 0.0434,-12.41063 z" + id="path5618-0-6-1-7" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 307.79047,312.83032 -0.0223,12.39295 -10.0459,-0.0207 18.10275,15.43867 17.8284,-15.42523 -10.00683,-0.01 0.0434,-12.41063 z" + id="path5618-0-6-1-7-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 2;stroke-dashoffset:0;stroke-opacity:1" + d="m 254.18784,256.29217 c 148.49999,38 148.49999,38 148.49999,38" + id="path3532" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 2;stroke-dashoffset:0;stroke-opacity:1" + d="m 252.93784,256.79217 -131.99999,36.5" + id="path3532-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 2;stroke-dashoffset:0;stroke-opacity:1" + d="m 252.68784,257.04217 -38.49999,36" + id="path3532-6-2" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1, 2;stroke-dashoffset:0;stroke-opacity:1" + d="m 253.93784,256.29217 59.00001,38" + id="path3532-6-2-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="25.256451" + y="285.27063" + id="text4759-3-1" + sodipodi:linespacing="0%"><tspan + sodipodi:role="line" + id="tspan4761-6-2" + x="25.256451" + y="285.27063">writerTable[]</tspan></text> + </g> +</svg> diff --git a/ctags/docs/_images/promise.svg b/ctags/docs/_images/promise.svg new file mode 100644 index 0000000..346dc5f --- /dev/null +++ b/ctags/docs/_images/promise.svg @@ -0,0 +1,546 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="140.86948mm" + height="49.095894mm" + viewBox="0 0 499.14381 173.96183" + id="svg2" + version="1.1" + inkscape:version="0.92.4 (unknown)" + sodipodi:docname="promise.svg"> + <defs + id="defs4"> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker5611" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Send"> + <path + transform="matrix(-0.2,0,0,-0.2,-1.2,0)" + style="fill:#434442;fill-opacity:1;fill-rule:evenodd;stroke:#434442;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path5609" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Send" + orient="auto" + refY="0" + refX="0" + id="Arrow1Send" + style="overflow:visible" + inkscape:isstock="true" + inkscape:collect="always"> + <path + id="path4640" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.2,0,0,-0.2,-1.2,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker4963" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow2Mend"> + <path + inkscape:connector-curvature="0" + transform="scale(-0.6)" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + id="path4961" /> + </marker> + <marker + inkscape:stockid="Arrow2Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path4646" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="matrix(-1.1,0,0,-1.1,-1.1,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6464" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" + inkscape:connector-curvature="0" /> + </marker> + <inkscape:path-effect + effect="bspline" + id="path-effect6395" + is_visible="true" + weight="33.333333" + steps="2" + helper_size="0" + apply_no_weight="true" + apply_with_weight="true" + only_selected="false" /> + <inkscape:path-effect + effect="spiro" + id="path-effect6343" + is_visible="true" /> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker12257" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path12259" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker11059" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path11061" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6737" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6191" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-6" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-7" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker5611-6" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Send"> + <path + inkscape:connector-curvature="0" + transform="matrix(-0.2,0,0,-0.2,-1.2,0)" + style="fill:#0000ff;fill-opacity:1;fill-rule:evenodd;stroke:#0000ff;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path5609-2" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker5611-6-6" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Send"> + <path + inkscape:connector-curvature="0" + transform="matrix(-0.2,0,0,-0.2,-1.2,0)" + style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path5609-2-0" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.2218218" + inkscape:cx="50.371414" + inkscape:cy="96.637368" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + showguides="false" + inkscape:guide-bbox="true" + inkscape:window-width="1920" + inkscape:window-height="972" + inkscape:window-x="0" + inkscape:window-y="55" + inkscape:window-maximized="1" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + scale-x="0.9375"> + <sodipodi:guide + position="617.64084,108.78106" + orientation="1,0" + id="guide7768" + inkscape:locked="false" /> + <sodipodi:guide + position="320.90835,169.99278" + orientation="1,0" + id="guide4617" + inkscape:locked="false" /> + <sodipodi:guide + position="347.15216,373.50701" + orientation="0,1" + id="guide4619" + inkscape:locked="false" /> + <sodipodi:guide + position="459.1844,166.34682" + orientation="1,0" + id="guide4621" + inkscape:locked="false" /> + <sodipodi:guide + position="155.05672,2.2516886" + orientation="0,1" + id="guide13925" + inkscape:locked="false" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(80.58721,-256.46709)"> + <g + aria-label="area" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + id="text4771-7-3" /> + <flowRoot + xml:space="preserve" + id="flowRoot4699" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0px;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + transform="matrix(0.9375,0,0,0.9375,21.027264,97.641448)"><flowRegion + id="flowRegion4701"><rect + id="rect4703" + width="157.96085" + height="59.746849" + x="330.65381" + y="240.80962" /></flowRegion><flowPara + id="flowPara4705" /></flowRoot> <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.875;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#Arrow1Send)" + d="M -80.58721,406.35501 H 354.78268" + id="path4623" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="354.147" + y="418.76654" + id="text4771-7-36-6-3"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4-6" + x="354.147" + y="418.76654">t</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="-31.141937" + y="427.67892" + id="text4771-7-36-7"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-5" + x="-31.141937" + y="427.67892">A host parser runs</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M -45.199435,414.5894 V 397.32522" + id="path5573" + inkscape:connector-curvature="0" /> + <path + inkscape:connector-curvature="0" + id="path5599" + d="M 99.17556,414.5894 V 397.32522" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#434442;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker5611)" + d="m -45.391259,406.70575 c 5.968169,10.85122 46.3966015,9.39363 75.955777,9.72851 29.559169,0.33488 64.701623,-3.91925 67.414423,-8.8023" + id="path5601" + inkscape:connector-curvature="0" + sodipodi:nodetypes="czc" /> + <path + sodipodi:type="star" + style="opacity:1;fill:#fd0000;fill-opacity:1;stroke:#c7c7c7;stroke-width:1.03733325;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="path5888" + sodipodi:sides="5" + sodipodi:cx="19.89691" + sodipodi:cy="405.89642" + sodipodi:r1="4.8120704" + sodipodi:r2="2.4060352" + sodipodi:arg1="1.5707963" + sodipodi:arg2="2.1991149" + inkscape:flatsided="false" + inkscape:rounded="0" + inkscape:randomized="0" + d="m 19.89691,410.70849 -1.414232,-2.86554 -3.162319,-0.45952 2.288275,-2.23051 -0.540188,-3.14954 2.828464,1.48701 2.828464,-1.48701 -0.540189,3.14954 2.288276,2.23051 -3.162319,0.45952 z" + inkscape:transform-center-y="0.45952153" + inkscape:transform-center-x="1.4171862e-06" /> + <path + sodipodi:type="star" + style="opacity:1;fill:#0000ff;fill-opacity:1;stroke:#c7c7c7;stroke-width:1.03733325;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="path5888-5" + sodipodi:sides="5" + sodipodi:cx="-22.920158" + sodipodi:cy="405.47275" + sodipodi:r1="4.8120704" + sodipodi:r2="2.4060352" + sodipodi:arg1="1.5707963" + sodipodi:arg2="2.1991149" + inkscape:flatsided="false" + inkscape:rounded="0" + inkscape:randomized="0" + d="m -22.920158,410.28482 -1.414232,-2.86555 -3.162319,-0.45951 2.288275,-2.23052 -0.540188,-3.14954 2.828464,1.48701 2.828464,-1.48701 -0.540189,3.14954 2.288276,2.23052 -3.162319,0.45951 z" + inkscape:transform-center-y="0.45952153" + inkscape:transform-center-x="1.4171862e-06" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#0000ff;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker5611-6)" + d="m 100.65059,406.78421 c 9.42101,10.08392 43.05978,10.04955 56.50571,10.19261 13.44593,0.14306 35.87249,1.43255 50.67021,-9.20523" + id="path5601-9" + inkscape:connector-curvature="0" + sodipodi:nodetypes="czc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 208.94058,414.04684 V 396.78266" + id="path11193" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="-319.76288" + y="235.35492" + id="text4771-7-36-6-1" + transform="rotate(-50.477323)"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4-2" + x="-319.76288" + y="235.35492">guest parser X is scheduled</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000191px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="-293.1586" + y="268.05173" + id="text4771-7-36-6-1-7" + inkscape:transform-center-x="70.62788" + inkscape:transform-center-y="26.816414" + transform="rotate(-50.477323)"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000191px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4-2-0" + x="-293.1586" + y="268.05173">guest parser Y is scheduled</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000191px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="141.21521" + y="427.84195" + id="text4771-7-36-7-9"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-5-3" + x="141.21521" + y="427.84195">X runs</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#marker5611-6-6)" + d="m 211.09459,406.2211 c 9.42101,10.08392 43.05978,10.04955 56.50571,10.19261 13.44593,0.14306 35.87249,1.43255 50.67021,-9.20523" + id="path5601-9-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="czc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 319.38458,413.48373 V 396.21954" + id="path11193-2" + inkscape:connector-curvature="0" /> + <text + id="text15065" + y="427.84195" + x="251.56892" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000191px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve"><tspan + y="427.84195" + x="251.56892" + id="tspan15063" + sodipodi:role="line" + style="stroke-width:1px">Y runs</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="-242.36191" + y="329.81918" + id="text4771-7-36-6-1-8" + transform="rotate(-50.477323)"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4-2-7" + x="-242.36191" + y="329.81918">promise for X is forced</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="-171.92081" + y="413.22397" + id="text4771-7-36-6-1-8-9" + transform="rotate(-50.477323)"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4-2-7-2" + x="-171.92081" + y="413.22397">promise for Y is forced</tspan></text> + <path + sodipodi:type="star" + style="opacity:1;fill:#ffff00;fill-opacity:1;stroke:#000000;stroke-width:1.875;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="path16493" + sodipodi:sides="3" + sodipodi:cx="-71.886269" + sodipodi:cy="404.71149" + sodipodi:r1="5.4256077" + sodipodi:r2="2.758086" + sodipodi:arg1="1.5707963" + sodipodi:arg2="2.6179939" + inkscape:flatsided="false" + inkscape:rounded="0" + inkscape:randomized="0" + d="m -71.886268,410.13709 -2.388573,-4.04656 -2.310142,-4.09185 4.698714,-0.0453 4.698714,0.0453 -2.310141,4.09185 z" + inkscape:transform-center-y="1.3337608" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="-352.85925" + y="198.87411" + id="text4771-7-36-6-1-8-0" + transform="rotate(-50.477323)"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4-2-7-23" + x="-352.85925" + y="198.87411">opens an input file</tspan></text> + <path + sodipodi:type="star" + style="opacity:1;fill:#ffff00;fill-opacity:1;stroke:#000000;stroke-width:1.875;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + id="path16493-7" + sodipodi:sides="3" + sodipodi:cx="340.00958" + sodipodi:cy="404.30811" + sodipodi:r1="5.4256077" + sodipodi:r2="2.758086" + sodipodi:arg1="1.5707963" + sodipodi:arg2="2.6179939" + inkscape:flatsided="false" + inkscape:rounded="0" + inkscape:randomized="0" + d="m 340.00958,409.73371 -2.38857,-4.04656 -2.31014,-4.09185 4.69871,-0.0453 4.69872,0.0453 -2.31014,4.09185 z" + inkscape:transform-center-y="-1.3260982" + transform="rotate(60.736224,338.40961,405.24561)" + inkscape:transform-center-x="0.034854492" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="-90.424301" + y="516.34271" + id="text4771-7-36-6-1-8-0-5" + transform="rotate(-50.477323)"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4-2-7-23-9" + x="-90.424301" + y="516.34271">closes the input file</tspan></text> + </g> +</svg> diff --git a/ctags/docs/_images/stack-and-parsers.svg b/ctags/docs/_images/stack-and-parsers.svg new file mode 100644 index 0000000..a8429dd --- /dev/null +++ b/ctags/docs/_images/stack-and-parsers.svg @@ -0,0 +1,618 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="121.29728mm" + height="67.63649mm" + viewBox="0 0 429.79351 239.65685" + id="svg2" + version="1.1" + inkscape:version="0.92.1 r" + sodipodi:docname="stack-and-parsers.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow2Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow2Mend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6482" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1" + d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" + transform="scale(-0.6)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Mend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6464" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" + inkscape:connector-curvature="0" /> + </marker> + <inkscape:path-effect + effect="bspline" + id="path-effect6395" + is_visible="true" + weight="33.333333" + steps="2" + helper_size="0" + apply_no_weight="true" + apply_with_weight="true" + only_selected="false" /> + <inkscape:path-effect + effect="spiro" + id="path-effect6343" + is_visible="true" /> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker12257" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path12259" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:isstock="true" + style="overflow:visible" + id="marker11059" + refX="0" + refY="0" + orient="auto" + inkscape:stockid="Arrow1Lend"> + <path + transform="matrix(-0.8,0,0,-0.8,-10,0)" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + id="path11061" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6737" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path6191" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-4" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-6" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="marker6735-6" + style="overflow:visible" + inkscape:isstock="true"> + <path + inkscape:connector-curvature="0" + id="path6737-7" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:#666666;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="1.2218218" + inkscape:cx="367.04879" + inkscape:cy="111.90442" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="1200" + inkscape:window-height="1536" + inkscape:window-x="0" + inkscape:window-y="47" + inkscape:window-maximized="1" + fit-margin-top="0" + fit-margin-left="0" + fit-margin-right="0" + fit-margin-bottom="0" + scale-x="0.9375"> + <sodipodi:guide + position="516.02635,15.65043" + orientation="1,0" + id="guide7768" + inkscape:locked="false" /> + <sodipodi:guide + position="219.29387,76.862154" + orientation="1,0" + id="guide4617" + inkscape:locked="false" /> + <sodipodi:guide + position="245.53768,280.37638" + orientation="0,1" + id="guide4619" + inkscape:locked="false" /> + <sodipodi:guide + position="357.56991,73.216197" + orientation="1,0" + id="guide4621" + inkscape:locked="false" /> + </sodipodi:namedview> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-21.027264,-97.641448)"> + <g + aria-label="area" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + id="text4771-7-3" /> + <g + id="g5858" + transform="translate(-145.32403,-23.446042)"> + <path + id="rect5837-3-0-2" + d="M 186.51929,165.75169 H 352.5789 V 387.73042 H 186.51929 Z" + style="opacity:1;fill:#ffffff;fill-opacity:1;stroke:#666666;stroke-width:1.81746745;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + transform="matrix(1,0,0.44448425,0.89578667,0,0)" + inkscape:connector-curvature="0" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-36-6" + d="M 317.98756,248.54658 H 467.37779" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-10-6" + d="M 309.85516,232.15704 H 459.24539" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-5-6-4" + d="M 301.72276,215.76748 H 451.11299" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-6-3-9" + d="M 281.39176,174.7936 H 430.78201" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-2-2-5" + d="M 297.65656,207.5727 H 447.04679" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-9-0-0" + d="M 277.32556,166.59883 H 426.71581" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-1-6-4" + d="M 293.59036,199.37794 H 442.98059" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-2-1-8" + d="M 273.25936,158.40406 H 422.64961" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-7-5-7" + d="M 289.52415,191.18315 H 438.91438" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-0-5-1" + d="M 285.45795,182.98837 H 434.8482" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-9-4-7" + d="M 362.71577,338.6891 H 512.106" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-3-7-2" + d="M 334.25237,281.32568 H 483.64262" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-6-6-7" + d="M 358.64957,330.49432 H 508.0398" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-06-5-2" + d="M 326.11996,264.93612 H 475.51021" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-26-6-2" + d="M 350.51717,314.10479 H 499.9074" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-1-9-6" + d="M 342.38476,297.71522 H 491.77501" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-8-3-1" + d="M 305.78897,223.96227 H 455.1792" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-9-7-7-0" + d="M 354.58337,322.29956 H 503.9736" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-3-9-4-6" + d="M 322.05376,256.74135 H 471.44401" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-6-2-5-1" + d="M 346.45096,305.90999 H 495.84119" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-06-0-2-5" + d="M 313.92136,240.35181 H 463.31161" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-26-2-5-9" + d="M 338.31856,289.52044 H 487.70879" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-1-3-4-4" + d="M 330.18616,273.13089 H 479.57641" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + </g> + <g + transform="translate(-121.31023,-50.022675)" + id="g5858-6"> + <path + inkscape:connector-curvature="0" + id="rect5837-3-0-2-8" + d="M 186.51929,165.75169 H 352.5789 V 387.73042 H 186.51929 Z" + style="opacity:1;fill:#ffffff;fill-opacity:1;stroke:#666666;stroke-width:1.81746745;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" + transform="matrix(1,0,0.44448425,0.89578667,0,0)" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-36-6-0" + d="M 317.98756,248.54658 H 467.37779" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-10-6-2" + d="M 309.85516,232.15704 H 459.24539" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-5-6-4-1" + d="M 301.72276,215.76748 H 451.11299" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-6-3-9-0" + d="M 281.39176,174.7936 H 430.78201" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-2-2-5-5" + d="M 297.65656,207.5727 H 447.04679" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-9-0-0-1" + d="M 277.32556,166.59883 H 426.71581" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-1-6-4-1" + d="M 293.59036,199.37794 H 442.98059" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-2-1-8-0" + d="M 273.25936,158.40406 H 422.64961" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-7-5-7-8" + d="M 289.52415,191.18315 H 438.91438" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-0-5-1-5" + d="M 285.45795,182.98837 H 434.8482" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-9-4-7-0" + d="M 362.71577,338.6891 H 512.106" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-3-7-2-6" + d="M 334.25237,281.32568 H 483.64262" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-6-6-7-4" + d="M 358.64957,330.49432 H 508.0398" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-06-5-2-6" + d="M 326.11996,264.93612 H 475.51021" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-26-6-2-2" + d="M 350.51717,314.10479 H 499.9074" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-1-9-6-5" + d="M 342.38476,297.71522 H 491.77501" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-8-3-1-8" + d="M 305.78897,223.96227 H 455.1792" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-9-7-7-0-6" + d="M 354.58337,322.29956 H 503.9736" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-3-9-4-6-2" + d="M 322.05376,256.74135 H 471.44401" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-6-2-5-1-8" + d="M 346.45096,305.90999 H 495.84119" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-06-0-2-5-4" + d="M 313.92136,240.35181 H 463.31161" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-26-2-5-9-7" + d="M 338.31856,289.52044 H 487.70879" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + <path + sodipodi:nodetypes="cc" + inkscape:connector-curvature="0" + id="path3856-3-1-3-4-4-2" + d="M 330.18616,273.13089 H 479.57641" + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80632514px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" /> + </g> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 100.12441,142.99257 12.39295,0.0223 -0.0207,10.0459 15.43867,-18.10275 -15.42523,-17.8284 -0.01,10.00683 -12.41063,-0.0434 z" + id="path5618-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="27.938955" + y="138.26762" + id="text4771-7-36"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7" + x="27.938955" + y="138.26762">base parser</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="90.335609" + y="169.58246" + id="text4771-7-36-5"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-3" + x="90.335609" + y="169.58246">subparser</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 280.82034,198.59405 50.5051,-0.38431" + id="path6201" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 180.41253,165.74481 50.5051,-0.38431" + id="path6201-0" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:2.8125;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" + d="m 208.87593,223.10822 50.5051,-0.38431" + id="path6201-0-5" + inkscape:connector-curvature="0" /> + <path + style="fill:#666666;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 152.60161,173.77936 12.39295,0.0223 -0.0207,10.0459 15.43867,-18.10275 -15.42523,-17.8284 -0.01,10.00683 -12.41063,-0.0434 z" + id="path5618-0-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccccccc" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.9375px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#Arrow2Mend)" + d="m 57.025791,139.62033 v 27.0137 h 31.985533" + id="path6339" + inkscape:connector-curvature="0" /> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="20.453533" + y="178.02365" + id="text4771-7-36-6"><tspan + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-4" + x="20.453533" + y="178.02365">callback</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000095px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="356.87888" + y="337.17331" + id="text4771-7-36-5-3"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-3-6" + x="356.87888" + y="337.17331">lower view</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.50000191px;line-height:0%;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="382.32077" + y="310.96411" + id="text4771-7-36-5-3-7"><tspan + style="stroke-width:1px" + sodipodi:role="line" + id="tspan4773-5-7-3-6-5" + x="382.32077" + y="310.96411">higher view</tspan></text> + <flowRoot + xml:space="preserve" + id="flowRoot4699" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12.5px;line-height:0px;font-family:'VL Gothic';-inkscape-font-specification:'VL Gothic';text-align:start;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + transform="matrix(0.9375,0,0,0.9375,21.027264,97.641448)"><flowRegion + id="flowRegion4701"><rect + id="rect4703" + width="157.96085" + height="59.746849" + x="330.65381" + y="240.80962" /></flowRegion><flowPara + id="flowPara4705"></flowPara></flowRoot> </g> +</svg> diff --git a/ctags/docs/_static/basic.css b/ctags/docs/_static/basic.css new file mode 100644 index 0000000..aa9df31 --- /dev/null +++ b/ctags/docs/_static/basic.css @@ -0,0 +1,904 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +div.section::after { + display: block; + content: ''; + clear: left; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; + word-wrap: break-word; + overflow-wrap : break-word; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox form.search { + overflow: hidden; +} + +div.sphinxsidebar #searchbox input[type="text"] { + float: left; + width: 80%; + padding: 0.25em; + box-sizing: border-box; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + float: left; + width: 20%; + border-left: none; + padding: 0.25em; + box-sizing: border-box; +} + + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li p.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; + margin-left: auto; + margin-right: auto; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- general body styles --------------------------------------------------- */ + +div.body { + min-width: 450px; + max-width: 800px; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + -moz-hyphens: auto; + -ms-hyphens: auto; + -webkit-hyphens: auto; + hyphens: auto; +} + +a.headerlink { + visibility: hidden; +} + +a.brackets:before, +span.brackets > a:before{ + content: "["; +} + +a.brackets:after, +span.brackets > a:after { + content: "]"; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, figure.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, figure.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, figure.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +img.align-default, figure.align-default, .figure.align-default { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-default { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar, +aside.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px; + background-color: #ffe; + width: 40%; + float: right; + clear: right; + overflow-x: auto; +} + +p.sidebar-title { + font-weight: bold; +} + +div.admonition, div.topic, blockquote { + clear: left; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- content of sidebars/topics/admonitions -------------------------------- */ + +div.sidebar > :last-child, +aside.sidebar > :last-child, +div.topic > :last-child, +div.admonition > :last-child { + margin-bottom: 0; +} + +div.sidebar::after, +aside.sidebar::after, +div.topic::after, +div.admonition::after, +blockquote::after { + display: block; + content: ''; + clear: both; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + margin-top: 10px; + margin-bottom: 10px; + border: 0; + border-collapse: collapse; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +table.align-default { + margin-left: auto; + margin-right: auto; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +th > :first-child, +td > :first-child { + margin-top: 0px; +} + +th > :last-child, +td > :last-child { + margin-bottom: 0px; +} + +/* -- figures --------------------------------------------------------------- */ + +div.figure, figure { + margin: 0.5em; + padding: 0.5em; +} + +div.figure p.caption, figcaption { + padding: 0.3em; +} + +div.figure p.caption span.caption-number, +figcaption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text, +figcaption span.caption-text { +} + +/* -- field list styles ----------------------------------------------------- */ + +table.field-list td, table.field-list th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.field-name { + -moz-hyphens: manual; + -ms-hyphens: manual; + -webkit-hyphens: manual; + hyphens: manual; +} + +/* -- hlist styles ---------------------------------------------------------- */ + +table.hlist { + margin: 1em 0; +} + +table.hlist td { + vertical-align: top; +} + +/* -- object description styles --------------------------------------------- */ + +.sig { + font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; +} + +.sig-name, code.descname { + background-color: transparent; + font-weight: bold; +} + +.sig-name { + font-size: 1.1em; +} + +code.descname { + font-size: 1.2em; +} + +.sig-prename, code.descclassname { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.sig-paren { + font-size: larger; +} + +.sig-param.n { + font-style: italic; +} + +/* C++ specific styling */ + +.sig-inline.c-texpr, +.sig-inline.cpp-texpr { + font-family: unset; +} + +.sig.c .k, .sig.c .kt, +.sig.cpp .k, .sig.cpp .kt { + color: #0033B3; +} + +.sig.c .m, +.sig.cpp .m { + color: #1750EB; +} + +.sig.c .s, .sig.c .sc, +.sig.cpp .s, .sig.cpp .sc { + color: #067D17; +} + + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +:not(li) > ol > li:first-child > :first-child, +:not(li) > ul > li:first-child > :first-child { + margin-top: 0px; +} + +:not(li) > ol > li:last-child > :last-child, +:not(li) > ul > li:last-child > :last-child { + margin-bottom: 0px; +} + +ol.simple ol p, +ol.simple ul p, +ul.simple ol p, +ul.simple ul p { + margin-top: 0; +} + +ol.simple > li:not(:first-child) > p, +ul.simple > li:not(:first-child) > p { + margin-top: 0; +} + +ol.simple p, +ul.simple p { + margin-bottom: 0; +} + +dl.footnote > dt, +dl.citation > dt { + float: left; + margin-right: 0.5em; +} + +dl.footnote > dd, +dl.citation > dd { + margin-bottom: 0em; +} + +dl.footnote > dd:after, +dl.citation > dd:after { + content: ""; + clear: both; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dt:after { + content: ":"; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0em; + margin-left: 0em; + margin-bottom: 0em; +} + +dl { + margin-bottom: 15px; +} + +dd > :first-child { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dl > dd:last-child, +dl > dd:last-child > :last-child { + margin-bottom: 0; +} + +dt:target, span.highlighted { + background-color: #fbe54e; +} + +rect.highlighted { + fill: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +.classifier:before { + font-style: normal; + margin: 0.5em; + content: ":"; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +pre, div[class*="highlight-"] { + clear: both; +} + +span.pre { + -moz-hyphens: none; + -ms-hyphens: none; + -webkit-hyphens: none; + hyphens: none; +} + +div[class*="highlight-"] { + margin: 1em 0; +} + +td.linenos pre { + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + display: block; +} + +table.highlighttable tbody { + display: block; +} + +table.highlighttable tr { + display: flex; +} + +table.highlighttable td { + margin: 0; + padding: 0; +} + +table.highlighttable td.linenos { + padding-right: 0.5em; +} + +table.highlighttable td.code { + flex: 1; + overflow: hidden; +} + +.highlight .hll { + display: block; +} + +div.highlight pre, +table.highlighttable pre { + margin: 0; +} + +div.code-block-caption + div { + margin-top: 0; +} + +div.code-block-caption { + margin-top: 1em; + padding: 2px 5px; + font-size: small; +} + +div.code-block-caption code { + background-color: transparent; +} + +table.highlighttable td.linenos, +span.linenos, +div.doctest > div.highlight span.gp { /* gp: Generic.Prompt */ + user-select: none; + -webkit-user-select: text; /* Safari fallback only */ + -webkit-user-select: none; /* Chrome/Safari */ + -moz-user-select: none; /* Firefox */ + -ms-user-select: none; /* IE10+ */ +} + +div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.code-block-caption span.caption-text { +} + +div.literal-block-wrapper { + margin: 1em 0; +} + +code.xref, a code { + background-color: transparent; + font-weight: bold; +} + +h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +span.eqno a.headerlink { + position: absolute; + z-index: 1; +} + +div.math:hover a.headerlink { + visibility: visible; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +}
\ No newline at end of file diff --git a/ctags/docs/_static/classic.css b/ctags/docs/_static/classic.css new file mode 100644 index 0000000..dcae946 --- /dev/null +++ b/ctags/docs/_static/classic.css @@ -0,0 +1,266 @@ +/* + * classic.css_t + * ~~~~~~~~~~~~~ + * + * Sphinx stylesheet -- classic theme. + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +html { + /* CSS hack for macOS's scrollbar (see #1125) */ + background-color: #FFFFFF; +} + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: #ffffff; + color: #000000; + padding: 0 20px 30px 20px; +} + +div.footer { + color: #ffffff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #ffffff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + line-height: 30px; + color: #ffffff; +} + +div.related a { + color: #ffffff; +} + +div.sphinxsidebar { +} + +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: #ffffff; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: #ffffff; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: #ffffff; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: #ffffff; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + + + +/* -- hyperlink styles ------------------------------------------------------ */ + +a { + color: #355f7c; + text-decoration: none; +} + +a:visited { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + + + +/* -- body styles ----------------------------------------------------------- */ + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li, div.body blockquote { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.admonition p { + margin-bottom: 5px; +} + +div.admonition pre { + margin-bottom: 5px; +} + +div.admonition ul, div.admonition ol { + margin-bottom: 5px; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: unset; + color: unset; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +code { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +th, dl.field-list > dt { + background-color: #ede; +} + +.warning code { + background: #efc2c2; +} + +.note code { + background: #d6d6d6; +} + +.viewcode-back { + font-family: sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} + +div.code-block-caption { + color: #efefef; + background-color: #1c4e63; +}
\ No newline at end of file diff --git a/ctags/docs/_static/default.css b/ctags/docs/_static/default.css new file mode 100644 index 0000000..81b9363 --- /dev/null +++ b/ctags/docs/_static/default.css @@ -0,0 +1 @@ +@import url("classic.css"); diff --git a/ctags/docs/_static/doctools.js b/ctags/docs/_static/doctools.js new file mode 100644 index 0000000..61ac9d2 --- /dev/null +++ b/ctags/docs/_static/doctools.js @@ -0,0 +1,321 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for all documentation. + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + * + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL + */ +jQuery.urldecode = function(x) { + if (!x) { + return x + } + return decodeURIComponent(x.replace(/\+/g, ' ')); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s === 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node, addItems) { + if (node.nodeType === 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && + !jQuery(node.parentNode).hasClass(className) && + !jQuery(node.parentNode).hasClass("nohighlight")) { + var span; + var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg"); + if (isInSVG) { + span = document.createElementNS("http://www.w3.org/2000/svg", "tspan"); + } else { + span = document.createElement("span"); + span.className = className; + } + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + if (isInSVG) { + var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); + var bbox = node.parentElement.getBBox(); + rect.x.baseVal.value = bbox.x; + rect.y.baseVal.value = bbox.y; + rect.width.baseVal.value = bbox.width; + rect.height.baseVal.value = bbox.height; + rect.setAttribute('class', className); + addItems.push({ + "parent": node.parentNode, + "target": rect}); + } + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this, addItems); + }); + } + } + var addItems = []; + var result = this.each(function() { + highlight(this, addItems); + }); + for (var i = 0; i < addItems.length; ++i) { + jQuery(addItems[i].parent).before(addItems[i].target); + } + return result; +}; + +/* + * backward compatibility for jQuery.browser + * This will be supported until firefox bug is fixed. + */ +if (!jQuery.browser) { + jQuery.uaMatch = function(ua) { + ua = ua.toLowerCase(); + + var match = /(chrome)[ \/]([\w.]+)/.exec(ua) || + /(webkit)[ \/]([\w.]+)/.exec(ua) || + /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) || + /(msie) ([\w.]+)/.exec(ua) || + ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) || + []; + + return { + browser: match[ 1 ] || "", + version: match[ 2 ] || "0" + }; + }; + jQuery.browser = {}; + jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true; +} + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) { + this.initOnKeyListeners(); + } + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated === 'undefined') + return string; + return (typeof translated === 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated === 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('<a class="headerlink">\u00B6</a>'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075 + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + if (!body.length) { + body = $('body'); + } + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('<p class="highlight-link"><a href="javascript:Documentation.' + + 'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) === 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this === '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + }, + + initOnKeyListeners: function() { + $(document).keydown(function(event) { + var activeElementType = document.activeElement.tagName; + // don't navigate when in search box, textarea, dropdown or button + if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT' + && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey + && !event.shiftKey) { + switch (event.keyCode) { + case 37: // left + var prevHref = $('link[rel="prev"]').prop('href'); + if (prevHref) { + window.location.href = prevHref; + return false; + } + case 39: // right + var nextHref = $('link[rel="next"]').prop('href'); + if (nextHref) { + window.location.href = nextHref; + return false; + } + } + } + }); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/ctags/docs/_static/documentation_options.js b/ctags/docs/_static/documentation_options.js new file mode 100644 index 0000000..dd5b32f --- /dev/null +++ b/ctags/docs/_static/documentation_options.js @@ -0,0 +1,12 @@ +var DOCUMENTATION_OPTIONS = { + URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), + VERSION: '0.3.0', + LANGUAGE: 'None', + COLLAPSE_INDEX: false, + BUILDER: 'html', + FILE_SUFFIX: '.html', + LINK_SUFFIX: '.html', + HAS_SOURCE: true, + SOURCELINK_SUFFIX: '.txt', + NAVIGATION_WITH_KEYS: false +};
\ No newline at end of file diff --git a/ctags/docs/_static/file.png b/ctags/docs/_static/file.png Binary files differnew file mode 100644 index 0000000..a858a41 --- /dev/null +++ b/ctags/docs/_static/file.png diff --git a/ctags/docs/_static/jquery-3.5.1.js b/ctags/docs/_static/jquery-3.5.1.js new file mode 100644 index 0000000..5093733 --- /dev/null +++ b/ctags/docs/_static/jquery-3.5.1.js @@ -0,0 +1,10872 @@ +/*! + * jQuery JavaScript Library v3.5.1 + * https://jquery.com/ + * + * Includes Sizzle.js + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://jquery.org/license + * + * Date: 2020-05-04T22:49Z + */ +( function( global, factory ) { + + "use strict"; + + if ( typeof module === "object" && typeof module.exports === "object" ) { + + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. + // e.g. var jQuery = require("jquery")(window); + // See ticket #14549 for more info. + module.exports = global.document ? + factory( global, true ) : + function( w ) { + if ( !w.document ) { + throw new Error( "jQuery requires a window with a document" ); + } + return factory( w ); + }; + } else { + factory( global ); + } + +// Pass this if window is not defined yet +} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) { + +// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1 +// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode +// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common +// enough that all such attempts are guarded in a try block. +"use strict"; + +var arr = []; + +var getProto = Object.getPrototypeOf; + +var slice = arr.slice; + +var flat = arr.flat ? function( array ) { + return arr.flat.call( array ); +} : function( array ) { + return arr.concat.apply( [], array ); +}; + + +var push = arr.push; + +var indexOf = arr.indexOf; + +var class2type = {}; + +var toString = class2type.toString; + +var hasOwn = class2type.hasOwnProperty; + +var fnToString = hasOwn.toString; + +var ObjectFunctionString = fnToString.call( Object ); + +var support = {}; + +var isFunction = function isFunction( obj ) { + + // Support: Chrome <=57, Firefox <=52 + // In some browsers, typeof returns "function" for HTML <object> elements + // (i.e., `typeof document.createElement( "object" ) === "function"`). + // We don't want to classify *any* DOM node as a function. + return typeof obj === "function" && typeof obj.nodeType !== "number"; + }; + + +var isWindow = function isWindow( obj ) { + return obj != null && obj === obj.window; + }; + + +var document = window.document; + + + + var preservedScriptAttributes = { + type: true, + src: true, + nonce: true, + noModule: true + }; + + function DOMEval( code, node, doc ) { + doc = doc || document; + + var i, val, + script = doc.createElement( "script" ); + + script.text = code; + if ( node ) { + for ( i in preservedScriptAttributes ) { + + // Support: Firefox 64+, Edge 18+ + // Some browsers don't support the "nonce" property on scripts. + // On the other hand, just using `getAttribute` is not enough as + // the `nonce` attribute is reset to an empty string whenever it + // becomes browsing-context connected. + // See https://github.com/whatwg/html/issues/2369 + // See https://html.spec.whatwg.org/#nonce-attributes + // The `node.getAttribute` check was added for the sake of + // `jQuery.globalEval` so that it can fake a nonce-containing node + // via an object. + val = node[ i ] || node.getAttribute && node.getAttribute( i ); + if ( val ) { + script.setAttribute( i, val ); + } + } + } + doc.head.appendChild( script ).parentNode.removeChild( script ); + } + + +function toType( obj ) { + if ( obj == null ) { + return obj + ""; + } + + // Support: Android <=2.3 only (functionish RegExp) + return typeof obj === "object" || typeof obj === "function" ? + class2type[ toString.call( obj ) ] || "object" : + typeof obj; +} +/* global Symbol */ +// Defining this global in .eslintrc.json would create a danger of using the global +// unguarded in another place, it seems safer to define global only for this module + + + +var + version = "3.5.1", + + // Define a local copy of jQuery + jQuery = function( selector, context ) { + + // The jQuery object is actually just the init constructor 'enhanced' + // Need init if jQuery is called (just allow error to be thrown if not included) + return new jQuery.fn.init( selector, context ); + }; + +jQuery.fn = jQuery.prototype = { + + // The current version of jQuery being used + jquery: version, + + constructor: jQuery, + + // The default length of a jQuery object is 0 + length: 0, + + toArray: function() { + return slice.call( this ); + }, + + // Get the Nth element in the matched element set OR + // Get the whole matched element set as a clean array + get: function( num ) { + + // Return all the elements in a clean array + if ( num == null ) { + return slice.call( this ); + } + + // Return just the one element from the set + return num < 0 ? this[ num + this.length ] : this[ num ]; + }, + + // Take an array of elements and push it onto the stack + // (returning the new matched element set) + pushStack: function( elems ) { + + // Build a new jQuery matched element set + var ret = jQuery.merge( this.constructor(), elems ); + + // Add the old object onto the stack (as a reference) + ret.prevObject = this; + + // Return the newly-formed element set + return ret; + }, + + // Execute a callback for every element in the matched set. + each: function( callback ) { + return jQuery.each( this, callback ); + }, + + map: function( callback ) { + return this.pushStack( jQuery.map( this, function( elem, i ) { + return callback.call( elem, i, elem ); + } ) ); + }, + + slice: function() { + return this.pushStack( slice.apply( this, arguments ) ); + }, + + first: function() { + return this.eq( 0 ); + }, + + last: function() { + return this.eq( -1 ); + }, + + even: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return ( i + 1 ) % 2; + } ) ); + }, + + odd: function() { + return this.pushStack( jQuery.grep( this, function( _elem, i ) { + return i % 2; + } ) ); + }, + + eq: function( i ) { + var len = this.length, + j = +i + ( i < 0 ? len : 0 ); + return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] ); + }, + + end: function() { + return this.prevObject || this.constructor(); + }, + + // For internal use only. + // Behaves like an Array's method, not like a jQuery method. + push: push, + sort: arr.sort, + splice: arr.splice +}; + +jQuery.extend = jQuery.fn.extend = function() { + var options, name, src, copy, copyIsArray, clone, + target = arguments[ 0 ] || {}, + i = 1, + length = arguments.length, + deep = false; + + // Handle a deep copy situation + if ( typeof target === "boolean" ) { + deep = target; + + // Skip the boolean and the target + target = arguments[ i ] || {}; + i++; + } + + // Handle case when target is a string or something (possible in deep copy) + if ( typeof target !== "object" && !isFunction( target ) ) { + target = {}; + } + + // Extend jQuery itself if only one argument is passed + if ( i === length ) { + target = this; + i--; + } + + for ( ; i < length; i++ ) { + + // Only deal with non-null/undefined values + if ( ( options = arguments[ i ] ) != null ) { + + // Extend the base object + for ( name in options ) { + copy = options[ name ]; + + // Prevent Object.prototype pollution + // Prevent never-ending loop + if ( name === "__proto__" || target === copy ) { + continue; + } + + // Recurse if we're merging plain objects or arrays + if ( deep && copy && ( jQuery.isPlainObject( copy ) || + ( copyIsArray = Array.isArray( copy ) ) ) ) { + src = target[ name ]; + + // Ensure proper type for the source value + if ( copyIsArray && !Array.isArray( src ) ) { + clone = []; + } else if ( !copyIsArray && !jQuery.isPlainObject( src ) ) { + clone = {}; + } else { + clone = src; + } + copyIsArray = false; + + // Never move original objects, clone them + target[ name ] = jQuery.extend( deep, clone, copy ); + + // Don't bring in undefined values + } else if ( copy !== undefined ) { + target[ name ] = copy; + } + } + } + } + + // Return the modified object + return target; +}; + +jQuery.extend( { + + // Unique for each copy of jQuery on the page + expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ), + + // Assume jQuery is ready without the ready module + isReady: true, + + error: function( msg ) { + throw new Error( msg ); + }, + + noop: function() {}, + + isPlainObject: function( obj ) { + var proto, Ctor; + + // Detect obvious negatives + // Use toString instead of jQuery.type to catch host objects + if ( !obj || toString.call( obj ) !== "[object Object]" ) { + return false; + } + + proto = getProto( obj ); + + // Objects with no prototype (e.g., `Object.create( null )`) are plain + if ( !proto ) { + return true; + } + + // Objects with prototype are plain iff they were constructed by a global Object function + Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor; + return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString; + }, + + isEmptyObject: function( obj ) { + var name; + + for ( name in obj ) { + return false; + } + return true; + }, + + // Evaluates a script in a provided context; falls back to the global one + // if not specified. + globalEval: function( code, options, doc ) { + DOMEval( code, { nonce: options && options.nonce }, doc ); + }, + + each: function( obj, callback ) { + var length, i = 0; + + if ( isArrayLike( obj ) ) { + length = obj.length; + for ( ; i < length; i++ ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } else { + for ( i in obj ) { + if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) { + break; + } + } + } + + return obj; + }, + + // results is for internal usage only + makeArray: function( arr, results ) { + var ret = results || []; + + if ( arr != null ) { + if ( isArrayLike( Object( arr ) ) ) { + jQuery.merge( ret, + typeof arr === "string" ? + [ arr ] : arr + ); + } else { + push.call( ret, arr ); + } + } + + return ret; + }, + + inArray: function( elem, arr, i ) { + return arr == null ? -1 : indexOf.call( arr, elem, i ); + }, + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + merge: function( first, second ) { + var len = +second.length, + j = 0, + i = first.length; + + for ( ; j < len; j++ ) { + first[ i++ ] = second[ j ]; + } + + first.length = i; + + return first; + }, + + grep: function( elems, callback, invert ) { + var callbackInverse, + matches = [], + i = 0, + length = elems.length, + callbackExpect = !invert; + + // Go through the array, only saving the items + // that pass the validator function + for ( ; i < length; i++ ) { + callbackInverse = !callback( elems[ i ], i ); + if ( callbackInverse !== callbackExpect ) { + matches.push( elems[ i ] ); + } + } + + return matches; + }, + + // arg is for internal usage only + map: function( elems, callback, arg ) { + var length, value, + i = 0, + ret = []; + + // Go through the array, translating each of the items to their new values + if ( isArrayLike( elems ) ) { + length = elems.length; + for ( ; i < length; i++ ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + + // Go through every key on the object, + } else { + for ( i in elems ) { + value = callback( elems[ i ], i, arg ); + + if ( value != null ) { + ret.push( value ); + } + } + } + + // Flatten any nested arrays + return flat( ret ); + }, + + // A global GUID counter for objects + guid: 1, + + // jQuery.support is not used in Core but other projects attach their + // properties to it so it needs to exist. + support: support +} ); + +if ( typeof Symbol === "function" ) { + jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ]; +} + +// Populate the class2type map +jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ), +function( _i, name ) { + class2type[ "[object " + name + "]" ] = name.toLowerCase(); +} ); + +function isArrayLike( obj ) { + + // Support: real iOS 8.2 only (not reproducible in simulator) + // `in` check used to prevent JIT error (gh-2145) + // hasOwn isn't used here due to false negatives + // regarding Nodelist length in IE + var length = !!obj && "length" in obj && obj.length, + type = toType( obj ); + + if ( isFunction( obj ) || isWindow( obj ) ) { + return false; + } + + return type === "array" || length === 0 || + typeof length === "number" && length > 0 && ( length - 1 ) in obj; +} +var Sizzle = +/*! + * Sizzle CSS Selector Engine v2.3.5 + * https://sizzlejs.com/ + * + * Copyright JS Foundation and other contributors + * Released under the MIT license + * https://js.foundation/ + * + * Date: 2020-03-14 + */ +( function( window ) { +var i, + support, + Expr, + getText, + isXML, + tokenize, + compile, + select, + outermostContext, + sortInput, + hasDuplicate, + + // Local document vars + setDocument, + document, + docElem, + documentIsHTML, + rbuggyQSA, + rbuggyMatches, + matches, + contains, + + // Instance-specific data + expando = "sizzle" + 1 * new Date(), + preferredDoc = window.document, + dirruns = 0, + done = 0, + classCache = createCache(), + tokenCache = createCache(), + compilerCache = createCache(), + nonnativeSelectorCache = createCache(), + sortOrder = function( a, b ) { + if ( a === b ) { + hasDuplicate = true; + } + return 0; + }, + + // Instance methods + hasOwn = ( {} ).hasOwnProperty, + arr = [], + pop = arr.pop, + pushNative = arr.push, + push = arr.push, + slice = arr.slice, + + // Use a stripped-down indexOf as it's faster than native + // https://jsperf.com/thor-indexof-vs-for/5 + indexOf = function( list, elem ) { + var i = 0, + len = list.length; + for ( ; i < len; i++ ) { + if ( list[ i ] === elem ) { + return i; + } + } + return -1; + }, + + booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|" + + "ismap|loop|multiple|open|readonly|required|scoped", + + // Regular expressions + + // http://www.w3.org/TR/css3-selectors/#whitespace + whitespace = "[\\x20\\t\\r\\n\\f]", + + // https://www.w3.org/TR/css-syntax-3/#ident-token-diagram + identifier = "(?:\\\\[\\da-fA-F]{1,6}" + whitespace + + "?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+", + + // Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors + attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace + + + // Operator (capture 2) + "*([*^$|!~]?=)" + whitespace + + + // "Attribute values must be CSS identifiers [capture 5] + // or strings [capture 3 or capture 4]" + "*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + + whitespace + "*\\]", + + pseudos = ":(" + identifier + ")(?:\\((" + + + // To reduce the number of selectors needing tokenize in the preFilter, prefer arguments: + // 1. quoted (capture 3; capture 4 or capture 5) + "('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" + + + // 2. simple (capture 6) + "((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" + + + // 3. anything else (capture 2) + ".*" + + ")\\)|)", + + // Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter + rwhitespace = new RegExp( whitespace + "+", "g" ), + rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + + whitespace + "+$", "g" ), + + rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ), + rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + + "*" ), + rdescend = new RegExp( whitespace + "|>" ), + + rpseudo = new RegExp( pseudos ), + ridentifier = new RegExp( "^" + identifier + "$" ), + + matchExpr = { + "ID": new RegExp( "^#(" + identifier + ")" ), + "CLASS": new RegExp( "^\\.(" + identifier + ")" ), + "TAG": new RegExp( "^(" + identifier + "|[*])" ), + "ATTR": new RegExp( "^" + attributes ), + "PSEUDO": new RegExp( "^" + pseudos ), + "CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + + whitespace + "*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + + whitespace + "*(\\d+)|))" + whitespace + "*\\)|)", "i" ), + "bool": new RegExp( "^(?:" + booleans + ")$", "i" ), + + // For use in libraries implementing .is() + // We use this for POS matching in `select` + "needsContext": new RegExp( "^" + whitespace + + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" + whitespace + + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" ) + }, + + rhtml = /HTML$/i, + rinputs = /^(?:input|select|textarea|button)$/i, + rheader = /^h\d$/i, + + rnative = /^[^{]+\{\s*\[native \w/, + + // Easily-parseable/retrievable ID or TAG or CLASS selectors + rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/, + + rsibling = /[+~]/, + + // CSS escapes + // http://www.w3.org/TR/CSS21/syndata.html#escaped-characters + runescape = new RegExp( "\\\\[\\da-fA-F]{1,6}" + whitespace + "?|\\\\([^\\r\\n\\f])", "g" ), + funescape = function( escape, nonHex ) { + var high = "0x" + escape.slice( 1 ) - 0x10000; + + return nonHex ? + + // Strip the backslash prefix from a non-hex escape sequence + nonHex : + + // Replace a hexadecimal escape sequence with the encoded Unicode code point + // Support: IE <=11+ + // For values outside the Basic Multilingual Plane (BMP), manually construct a + // surrogate pair + high < 0 ? + String.fromCharCode( high + 0x10000 ) : + String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 ); + }, + + // CSS string/identifier serialization + // https://drafts.csswg.org/cssom/#common-serializing-idioms + rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g, + fcssescape = function( ch, asCodePoint ) { + if ( asCodePoint ) { + + // U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER + if ( ch === "\0" ) { + return "\uFFFD"; + } + + // Control characters and (dependent upon position) numbers get escaped as code points + return ch.slice( 0, -1 ) + "\\" + + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " "; + } + + // Other potentially-special ASCII characters get backslash-escaped + return "\\" + ch; + }, + + // Used for iframes + // See setDocument() + // Removing the function wrapper causes a "Permission Denied" + // error in IE + unloadHandler = function() { + setDocument(); + }, + + inDisabledFieldset = addCombinator( + function( elem ) { + return elem.disabled === true && elem.nodeName.toLowerCase() === "fieldset"; + }, + { dir: "parentNode", next: "legend" } + ); + +// Optimize for push.apply( _, NodeList ) +try { + push.apply( + ( arr = slice.call( preferredDoc.childNodes ) ), + preferredDoc.childNodes + ); + + // Support: Android<4.0 + // Detect silently failing push.apply + // eslint-disable-next-line no-unused-expressions + arr[ preferredDoc.childNodes.length ].nodeType; +} catch ( e ) { + push = { apply: arr.length ? + + // Leverage slice if possible + function( target, els ) { + pushNative.apply( target, slice.call( els ) ); + } : + + // Support: IE<9 + // Otherwise append directly + function( target, els ) { + var j = target.length, + i = 0; + + // Can't trust NodeList.length + while ( ( target[ j++ ] = els[ i++ ] ) ) {} + target.length = j - 1; + } + }; +} + +function Sizzle( selector, context, results, seed ) { + var m, i, elem, nid, match, groups, newSelector, + newContext = context && context.ownerDocument, + + // nodeType defaults to 9, since context defaults to document + nodeType = context ? context.nodeType : 9; + + results = results || []; + + // Return early from calls with invalid selector or context + if ( typeof selector !== "string" || !selector || + nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) { + + return results; + } + + // Try to shortcut find operations (as opposed to filters) in HTML documents + if ( !seed ) { + setDocument( context ); + context = context || document; + + if ( documentIsHTML ) { + + // If the selector is sufficiently simple, try using a "get*By*" DOM method + // (excepting DocumentFragment context, where the methods don't exist) + if ( nodeType !== 11 && ( match = rquickExpr.exec( selector ) ) ) { + + // ID selector + if ( ( m = match[ 1 ] ) ) { + + // Document context + if ( nodeType === 9 ) { + if ( ( elem = context.getElementById( m ) ) ) { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( elem.id === m ) { + results.push( elem ); + return results; + } + } else { + return results; + } + + // Element context + } else { + + // Support: IE, Opera, Webkit + // TODO: identify versions + // getElementById can match elements by name instead of ID + if ( newContext && ( elem = newContext.getElementById( m ) ) && + contains( context, elem ) && + elem.id === m ) { + + results.push( elem ); + return results; + } + } + + // Type selector + } else if ( match[ 2 ] ) { + push.apply( results, context.getElementsByTagName( selector ) ); + return results; + + // Class selector + } else if ( ( m = match[ 3 ] ) && support.getElementsByClassName && + context.getElementsByClassName ) { + + push.apply( results, context.getElementsByClassName( m ) ); + return results; + } + } + + // Take advantage of querySelectorAll + if ( support.qsa && + !nonnativeSelectorCache[ selector + " " ] && + ( !rbuggyQSA || !rbuggyQSA.test( selector ) ) && + + // Support: IE 8 only + // Exclude object elements + ( nodeType !== 1 || context.nodeName.toLowerCase() !== "object" ) ) { + + newSelector = selector; + newContext = context; + + // qSA considers elements outside a scoping root when evaluating child or + // descendant combinators, which is not what we want. + // In such cases, we work around the behavior by prefixing every selector in the + // list with an ID selector referencing the scope context. + // The technique has to be used as well when a leading combinator is used + // as such selectors are not recognized by querySelectorAll. + // Thanks to Andrew Dupont for this technique. + if ( nodeType === 1 && + ( rdescend.test( selector ) || rcombinators.test( selector ) ) ) { + + // Expand context for sibling selectors + newContext = rsibling.test( selector ) && testContext( context.parentNode ) || + context; + + // We can use :scope instead of the ID hack if the browser + // supports it & if we're not changing the context. + if ( newContext !== context || !support.scope ) { + + // Capture the context ID, setting it first if necessary + if ( ( nid = context.getAttribute( "id" ) ) ) { + nid = nid.replace( rcssescape, fcssescape ); + } else { + context.setAttribute( "id", ( nid = expando ) ); + } + } + + // Prefix every selector in the list + groups = tokenize( selector ); + i = groups.length; + while ( i-- ) { + groups[ i ] = ( nid ? "#" + nid : ":scope" ) + " " + + toSelector( groups[ i ] ); + } + newSelector = groups.join( "," ); + } + + try { + push.apply( results, + newContext.querySelectorAll( newSelector ) + ); + return results; + } catch ( qsaError ) { + nonnativeSelectorCache( selector, true ); + } finally { + if ( nid === expando ) { + context.removeAttribute( "id" ); + } + } + } + } + } + + // All others + return select( selector.replace( rtrim, "$1" ), context, results, seed ); +} + +/** + * Create key-value caches of limited size + * @returns {function(string, object)} Returns the Object data after storing it on itself with + * property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength) + * deleting the oldest entry + */ +function createCache() { + var keys = []; + + function cache( key, value ) { + + // Use (key + " ") to avoid collision with native prototype properties (see Issue #157) + if ( keys.push( key + " " ) > Expr.cacheLength ) { + + // Only keep the most recent entries + delete cache[ keys.shift() ]; + } + return ( cache[ key + " " ] = value ); + } + return cache; +} + +/** + * Mark a function for special use by Sizzle + * @param {Function} fn The function to mark + */ +function markFunction( fn ) { + fn[ expando ] = true; + return fn; +} + +/** + * Support testing using an element + * @param {Function} fn Passed the created element and returns a boolean result + */ +function assert( fn ) { + var el = document.createElement( "fieldset" ); + + try { + return !!fn( el ); + } catch ( e ) { + return false; + } finally { + + // Remove from its parent by default + if ( el.parentNode ) { + el.parentNode.removeChild( el ); + } + + // release memory in IE + el = null; + } +} + +/** + * Adds the same handler for all of the specified attrs + * @param {String} attrs Pipe-separated list of attributes + * @param {Function} handler The method that will be applied + */ +function addHandle( attrs, handler ) { + var arr = attrs.split( "|" ), + i = arr.length; + + while ( i-- ) { + Expr.attrHandle[ arr[ i ] ] = handler; + } +} + +/** + * Checks document order of two siblings + * @param {Element} a + * @param {Element} b + * @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b + */ +function siblingCheck( a, b ) { + var cur = b && a, + diff = cur && a.nodeType === 1 && b.nodeType === 1 && + a.sourceIndex - b.sourceIndex; + + // Use IE sourceIndex if available on both nodes + if ( diff ) { + return diff; + } + + // Check if b follows a + if ( cur ) { + while ( ( cur = cur.nextSibling ) ) { + if ( cur === b ) { + return -1; + } + } + } + + return a ? 1 : -1; +} + +/** + * Returns a function to use in pseudos for input types + * @param {String} type + */ +function createInputPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for buttons + * @param {String} type + */ +function createButtonPseudo( type ) { + return function( elem ) { + var name = elem.nodeName.toLowerCase(); + return ( name === "input" || name === "button" ) && elem.type === type; + }; +} + +/** + * Returns a function to use in pseudos for :enabled/:disabled + * @param {Boolean} disabled true for :disabled; false for :enabled + */ +function createDisabledPseudo( disabled ) { + + // Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable + return function( elem ) { + + // Only certain elements can match :enabled or :disabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-enabled + // https://html.spec.whatwg.org/multipage/scripting.html#selector-disabled + if ( "form" in elem ) { + + // Check for inherited disabledness on relevant non-disabled elements: + // * listed form-associated elements in a disabled fieldset + // https://html.spec.whatwg.org/multipage/forms.html#category-listed + // https://html.spec.whatwg.org/multipage/forms.html#concept-fe-disabled + // * option elements in a disabled optgroup + // https://html.spec.whatwg.org/multipage/forms.html#concept-option-disabled + // All such elements have a "form" property. + if ( elem.parentNode && elem.disabled === false ) { + + // Option elements defer to a parent optgroup if present + if ( "label" in elem ) { + if ( "label" in elem.parentNode ) { + return elem.parentNode.disabled === disabled; + } else { + return elem.disabled === disabled; + } + } + + // Support: IE 6 - 11 + // Use the isDisabled shortcut property to check for disabled fieldset ancestors + return elem.isDisabled === disabled || + + // Where there is no isDisabled, check manually + /* jshint -W018 */ + elem.isDisabled !== !disabled && + inDisabledFieldset( elem ) === disabled; + } + + return elem.disabled === disabled; + + // Try to winnow out elements that can't be disabled before trusting the disabled property. + // Some victims get caught in our net (label, legend, menu, track), but it shouldn't + // even exist on them, let alone have a boolean value. + } else if ( "label" in elem ) { + return elem.disabled === disabled; + } + + // Remaining elements are neither :enabled nor :disabled + return false; + }; +} + +/** + * Returns a function to use in pseudos for positionals + * @param {Function} fn + */ +function createPositionalPseudo( fn ) { + return markFunction( function( argument ) { + argument = +argument; + return markFunction( function( seed, matches ) { + var j, + matchIndexes = fn( [], seed.length, argument ), + i = matchIndexes.length; + + // Match elements found at the specified indexes + while ( i-- ) { + if ( seed[ ( j = matchIndexes[ i ] ) ] ) { + seed[ j ] = !( matches[ j ] = seed[ j ] ); + } + } + } ); + } ); +} + +/** + * Checks a node for validity as a Sizzle context + * @param {Element|Object=} context + * @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value + */ +function testContext( context ) { + return context && typeof context.getElementsByTagName !== "undefined" && context; +} + +// Expose support vars for convenience +support = Sizzle.support = {}; + +/** + * Detects XML nodes + * @param {Element|Object} elem An element or a document + * @returns {Boolean} True iff elem is a non-HTML XML node + */ +isXML = Sizzle.isXML = function( elem ) { + var namespace = elem.namespaceURI, + docElem = ( elem.ownerDocument || elem ).documentElement; + + // Support: IE <=8 + // Assume HTML when documentElement doesn't yet exist, such as inside loading iframes + // https://bugs.jquery.com/ticket/4833 + return !rhtml.test( namespace || docElem && docElem.nodeName || "HTML" ); +}; + +/** + * Sets document-related variables once based on the current document + * @param {Element|Object} [doc] An element or document object to use to set the document + * @returns {Object} Returns the current document + */ +setDocument = Sizzle.setDocument = function( node ) { + var hasCompare, subWindow, + doc = node ? node.ownerDocument || node : preferredDoc; + + // Return early if doc is invalid or already selected + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( doc == document || doc.nodeType !== 9 || !doc.documentElement ) { + return document; + } + + // Update global variables + document = doc; + docElem = document.documentElement; + documentIsHTML = !isXML( document ); + + // Support: IE 9 - 11+, Edge 12 - 18+ + // Accessing iframe documents after unload throws "permission denied" errors (jQuery #13936) + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( preferredDoc != document && + ( subWindow = document.defaultView ) && subWindow.top !== subWindow ) { + + // Support: IE 11, Edge + if ( subWindow.addEventListener ) { + subWindow.addEventListener( "unload", unloadHandler, false ); + + // Support: IE 9 - 10 only + } else if ( subWindow.attachEvent ) { + subWindow.attachEvent( "onunload", unloadHandler ); + } + } + + // Support: IE 8 - 11+, Edge 12 - 18+, Chrome <=16 - 25 only, Firefox <=3.6 - 31 only, + // Safari 4 - 5 only, Opera <=11.6 - 12.x only + // IE/Edge & older browsers don't support the :scope pseudo-class. + // Support: Safari 6.0 only + // Safari 6.0 supports :scope but it's an alias of :root there. + support.scope = assert( function( el ) { + docElem.appendChild( el ).appendChild( document.createElement( "div" ) ); + return typeof el.querySelectorAll !== "undefined" && + !el.querySelectorAll( ":scope fieldset div" ).length; + } ); + + /* Attributes + ---------------------------------------------------------------------- */ + + // Support: IE<8 + // Verify that getAttribute really returns attributes and not properties + // (excepting IE8 booleans) + support.attributes = assert( function( el ) { + el.className = "i"; + return !el.getAttribute( "className" ); + } ); + + /* getElement(s)By* + ---------------------------------------------------------------------- */ + + // Check if getElementsByTagName("*") returns only elements + support.getElementsByTagName = assert( function( el ) { + el.appendChild( document.createComment( "" ) ); + return !el.getElementsByTagName( "*" ).length; + } ); + + // Support: IE<9 + support.getElementsByClassName = rnative.test( document.getElementsByClassName ); + + // Support: IE<10 + // Check if getElementById returns elements by name + // The broken getElementById methods don't pick up programmatically-set names, + // so use a roundabout getElementsByName test + support.getById = assert( function( el ) { + docElem.appendChild( el ).id = expando; + return !document.getElementsByName || !document.getElementsByName( expando ).length; + } ); + + // ID filter and find + if ( support.getById ) { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + return elem.getAttribute( "id" ) === attrId; + }; + }; + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var elem = context.getElementById( id ); + return elem ? [ elem ] : []; + } + }; + } else { + Expr.filter[ "ID" ] = function( id ) { + var attrId = id.replace( runescape, funescape ); + return function( elem ) { + var node = typeof elem.getAttributeNode !== "undefined" && + elem.getAttributeNode( "id" ); + return node && node.value === attrId; + }; + }; + + // Support: IE 6 - 7 only + // getElementById is not reliable as a find shortcut + Expr.find[ "ID" ] = function( id, context ) { + if ( typeof context.getElementById !== "undefined" && documentIsHTML ) { + var node, i, elems, + elem = context.getElementById( id ); + + if ( elem ) { + + // Verify the id attribute + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + + // Fall back on getElementsByName + elems = context.getElementsByName( id ); + i = 0; + while ( ( elem = elems[ i++ ] ) ) { + node = elem.getAttributeNode( "id" ); + if ( node && node.value === id ) { + return [ elem ]; + } + } + } + + return []; + } + }; + } + + // Tag + Expr.find[ "TAG" ] = support.getElementsByTagName ? + function( tag, context ) { + if ( typeof context.getElementsByTagName !== "undefined" ) { + return context.getElementsByTagName( tag ); + + // DocumentFragment nodes don't have gEBTN + } else if ( support.qsa ) { + return context.querySelectorAll( tag ); + } + } : + + function( tag, context ) { + var elem, + tmp = [], + i = 0, + + // By happy coincidence, a (broken) gEBTN appears on DocumentFragment nodes too + results = context.getElementsByTagName( tag ); + + // Filter out possible comments + if ( tag === "*" ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem.nodeType === 1 ) { + tmp.push( elem ); + } + } + + return tmp; + } + return results; + }; + + // Class + Expr.find[ "CLASS" ] = support.getElementsByClassName && function( className, context ) { + if ( typeof context.getElementsByClassName !== "undefined" && documentIsHTML ) { + return context.getElementsByClassName( className ); + } + }; + + /* QSA/matchesSelector + ---------------------------------------------------------------------- */ + + // QSA and matchesSelector support + + // matchesSelector(:active) reports false when true (IE9/Opera 11.5) + rbuggyMatches = []; + + // qSa(:focus) reports false when true (Chrome 21) + // We allow this because of a bug in IE8/9 that throws an error + // whenever `document.activeElement` is accessed on an iframe + // So, we allow :focus to pass through QSA all the time to avoid the IE error + // See https://bugs.jquery.com/ticket/13378 + rbuggyQSA = []; + + if ( ( support.qsa = rnative.test( document.querySelectorAll ) ) ) { + + // Build QSA regex + // Regex strategy adopted from Diego Perini + assert( function( el ) { + + var input; + + // Select is set to empty string on purpose + // This is to test IE's treatment of not explicitly + // setting a boolean content attribute, + // since its presence should be enough + // https://bugs.jquery.com/ticket/12359 + docElem.appendChild( el ).innerHTML = "<a id='" + expando + "'></a>" + + "<select id='" + expando + "-\r\\' msallowcapture=''>" + + "<option selected=''></option></select>"; + + // Support: IE8, Opera 11-12.16 + // Nothing should be selected when empty strings follow ^= or $= or *= + // The test attribute must be unknown in Opera but "safe" for WinRT + // https://msdn.microsoft.com/en-us/library/ie/hh465388.aspx#attribute_section + if ( el.querySelectorAll( "[msallowcapture^='']" ).length ) { + rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" ); + } + + // Support: IE8 + // Boolean attributes and "value" are not treated correctly + if ( !el.querySelectorAll( "[selected]" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" ); + } + + // Support: Chrome<29, Android<4.4, Safari<7.0+, iOS<7.0+, PhantomJS<1.9.8+ + if ( !el.querySelectorAll( "[id~=" + expando + "-]" ).length ) { + rbuggyQSA.push( "~=" ); + } + + // Support: IE 11+, Edge 15 - 18+ + // IE 11/Edge don't find elements on a `[name='']` query in some cases. + // Adding a temporary attribute to the document before the selection works + // around the issue. + // Interestingly, IE 10 & older don't seem to have the issue. + input = document.createElement( "input" ); + input.setAttribute( "name", "" ); + el.appendChild( input ); + if ( !el.querySelectorAll( "[name='']" ).length ) { + rbuggyQSA.push( "\\[" + whitespace + "*name" + whitespace + "*=" + + whitespace + "*(?:''|\"\")" ); + } + + // Webkit/Opera - :checked should return selected option elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + // IE8 throws error here and will not see later tests + if ( !el.querySelectorAll( ":checked" ).length ) { + rbuggyQSA.push( ":checked" ); + } + + // Support: Safari 8+, iOS 8+ + // https://bugs.webkit.org/show_bug.cgi?id=136851 + // In-page `selector#id sibling-combinator selector` fails + if ( !el.querySelectorAll( "a#" + expando + "+*" ).length ) { + rbuggyQSA.push( ".#.+[+~]" ); + } + + // Support: Firefox <=3.6 - 5 only + // Old Firefox doesn't throw on a badly-escaped identifier. + el.querySelectorAll( "\\\f" ); + rbuggyQSA.push( "[\\r\\n\\f]" ); + } ); + + assert( function( el ) { + el.innerHTML = "<a href='' disabled='disabled'></a>" + + "<select disabled='disabled'><option/></select>"; + + // Support: Windows 8 Native Apps + // The type and name attributes are restricted during .innerHTML assignment + var input = document.createElement( "input" ); + input.setAttribute( "type", "hidden" ); + el.appendChild( input ).setAttribute( "name", "D" ); + + // Support: IE8 + // Enforce case-sensitivity of name attribute + if ( el.querySelectorAll( "[name=d]" ).length ) { + rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" ); + } + + // FF 3.5 - :enabled/:disabled and hidden elements (hidden elements are still enabled) + // IE8 throws error here and will not see later tests + if ( el.querySelectorAll( ":enabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: IE9-11+ + // IE's :disabled selector does not pick up the children of disabled fieldsets + docElem.appendChild( el ).disabled = true; + if ( el.querySelectorAll( ":disabled" ).length !== 2 ) { + rbuggyQSA.push( ":enabled", ":disabled" ); + } + + // Support: Opera 10 - 11 only + // Opera 10-11 does not throw on post-comma invalid pseudos + el.querySelectorAll( "*,:x" ); + rbuggyQSA.push( ",.*:" ); + } ); + } + + if ( ( support.matchesSelector = rnative.test( ( matches = docElem.matches || + docElem.webkitMatchesSelector || + docElem.mozMatchesSelector || + docElem.oMatchesSelector || + docElem.msMatchesSelector ) ) ) ) { + + assert( function( el ) { + + // Check to see if it's possible to do matchesSelector + // on a disconnected node (IE 9) + support.disconnectedMatch = matches.call( el, "*" ); + + // This should fail with an exception + // Gecko does not error, returns false instead + matches.call( el, "[s!='']:x" ); + rbuggyMatches.push( "!=", pseudos ); + } ); + } + + rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join( "|" ) ); + rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join( "|" ) ); + + /* Contains + ---------------------------------------------------------------------- */ + hasCompare = rnative.test( docElem.compareDocumentPosition ); + + // Element contains another + // Purposefully self-exclusive + // As in, an element does not contain itself + contains = hasCompare || rnative.test( docElem.contains ) ? + function( a, b ) { + var adown = a.nodeType === 9 ? a.documentElement : a, + bup = b && b.parentNode; + return a === bup || !!( bup && bup.nodeType === 1 && ( + adown.contains ? + adown.contains( bup ) : + a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16 + ) ); + } : + function( a, b ) { + if ( b ) { + while ( ( b = b.parentNode ) ) { + if ( b === a ) { + return true; + } + } + } + return false; + }; + + /* Sorting + ---------------------------------------------------------------------- */ + + // Document order sorting + sortOrder = hasCompare ? + function( a, b ) { + + // Flag for duplicate removal + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + // Sort on method existence if only one input has compareDocumentPosition + var compare = !a.compareDocumentPosition - !b.compareDocumentPosition; + if ( compare ) { + return compare; + } + + // Calculate position if both inputs belong to the same document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + compare = ( a.ownerDocument || a ) == ( b.ownerDocument || b ) ? + a.compareDocumentPosition( b ) : + + // Otherwise we know they are disconnected + 1; + + // Disconnected nodes + if ( compare & 1 || + ( !support.sortDetached && b.compareDocumentPosition( a ) === compare ) ) { + + // Choose the first element that is related to our preferred document + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( a == document || a.ownerDocument == preferredDoc && + contains( preferredDoc, a ) ) { + return -1; + } + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( b == document || b.ownerDocument == preferredDoc && + contains( preferredDoc, b ) ) { + return 1; + } + + // Maintain original order + return sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + } + + return compare & 4 ? -1 : 1; + } : + function( a, b ) { + + // Exit early if the nodes are identical + if ( a === b ) { + hasDuplicate = true; + return 0; + } + + var cur, + i = 0, + aup = a.parentNode, + bup = b.parentNode, + ap = [ a ], + bp = [ b ]; + + // Parentless nodes are either documents or disconnected + if ( !aup || !bup ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + return a == document ? -1 : + b == document ? 1 : + /* eslint-enable eqeqeq */ + aup ? -1 : + bup ? 1 : + sortInput ? + ( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) : + 0; + + // If the nodes are siblings, we can do a quick check + } else if ( aup === bup ) { + return siblingCheck( a, b ); + } + + // Otherwise we need full lists of their ancestors for comparison + cur = a; + while ( ( cur = cur.parentNode ) ) { + ap.unshift( cur ); + } + cur = b; + while ( ( cur = cur.parentNode ) ) { + bp.unshift( cur ); + } + + // Walk down the tree looking for a discrepancy + while ( ap[ i ] === bp[ i ] ) { + i++; + } + + return i ? + + // Do a sibling check if the nodes have a common ancestor + siblingCheck( ap[ i ], bp[ i ] ) : + + // Otherwise nodes in our document sort first + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + /* eslint-disable eqeqeq */ + ap[ i ] == preferredDoc ? -1 : + bp[ i ] == preferredDoc ? 1 : + /* eslint-enable eqeqeq */ + 0; + }; + + return document; +}; + +Sizzle.matches = function( expr, elements ) { + return Sizzle( expr, null, null, elements ); +}; + +Sizzle.matchesSelector = function( elem, expr ) { + setDocument( elem ); + + if ( support.matchesSelector && documentIsHTML && + !nonnativeSelectorCache[ expr + " " ] && + ( !rbuggyMatches || !rbuggyMatches.test( expr ) ) && + ( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) { + + try { + var ret = matches.call( elem, expr ); + + // IE 9's matchesSelector returns false on disconnected nodes + if ( ret || support.disconnectedMatch || + + // As well, disconnected nodes are said to be in a document + // fragment in IE 9 + elem.document && elem.document.nodeType !== 11 ) { + return ret; + } + } catch ( e ) { + nonnativeSelectorCache( expr, true ); + } + } + + return Sizzle( expr, document, null, [ elem ] ).length > 0; +}; + +Sizzle.contains = function( context, elem ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( context.ownerDocument || context ) != document ) { + setDocument( context ); + } + return contains( context, elem ); +}; + +Sizzle.attr = function( elem, name ) { + + // Set document vars if needed + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( ( elem.ownerDocument || elem ) != document ) { + setDocument( elem ); + } + + var fn = Expr.attrHandle[ name.toLowerCase() ], + + // Don't get fooled by Object.prototype properties (jQuery #13807) + val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ? + fn( elem, name, !documentIsHTML ) : + undefined; + + return val !== undefined ? + val : + support.attributes || !documentIsHTML ? + elem.getAttribute( name ) : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; +}; + +Sizzle.escape = function( sel ) { + return ( sel + "" ).replace( rcssescape, fcssescape ); +}; + +Sizzle.error = function( msg ) { + throw new Error( "Syntax error, unrecognized expression: " + msg ); +}; + +/** + * Document sorting and removing duplicates + * @param {ArrayLike} results + */ +Sizzle.uniqueSort = function( results ) { + var elem, + duplicates = [], + j = 0, + i = 0; + + // Unless we *know* we can detect duplicates, assume their presence + hasDuplicate = !support.detectDuplicates; + sortInput = !support.sortStable && results.slice( 0 ); + results.sort( sortOrder ); + + if ( hasDuplicate ) { + while ( ( elem = results[ i++ ] ) ) { + if ( elem === results[ i ] ) { + j = duplicates.push( i ); + } + } + while ( j-- ) { + results.splice( duplicates[ j ], 1 ); + } + } + + // Clear input after sorting to release objects + // See https://github.com/jquery/sizzle/pull/225 + sortInput = null; + + return results; +}; + +/** + * Utility function for retrieving the text value of an array of DOM nodes + * @param {Array|Element} elem + */ +getText = Sizzle.getText = function( elem ) { + var node, + ret = "", + i = 0, + nodeType = elem.nodeType; + + if ( !nodeType ) { + + // If no nodeType, this is expected to be an array + while ( ( node = elem[ i++ ] ) ) { + + // Do not traverse comment nodes + ret += getText( node ); + } + } else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) { + + // Use textContent for elements + // innerText usage removed for consistency of new lines (jQuery #11153) + if ( typeof elem.textContent === "string" ) { + return elem.textContent; + } else { + + // Traverse its children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + ret += getText( elem ); + } + } + } else if ( nodeType === 3 || nodeType === 4 ) { + return elem.nodeValue; + } + + // Do not include comment or processing instruction nodes + + return ret; +}; + +Expr = Sizzle.selectors = { + + // Can be adjusted by the user + cacheLength: 50, + + createPseudo: markFunction, + + match: matchExpr, + + attrHandle: {}, + + find: {}, + + relative: { + ">": { dir: "parentNode", first: true }, + " ": { dir: "parentNode" }, + "+": { dir: "previousSibling", first: true }, + "~": { dir: "previousSibling" } + }, + + preFilter: { + "ATTR": function( match ) { + match[ 1 ] = match[ 1 ].replace( runescape, funescape ); + + // Move the given value to match[3] whether quoted or unquoted + match[ 3 ] = ( match[ 3 ] || match[ 4 ] || + match[ 5 ] || "" ).replace( runescape, funescape ); + + if ( match[ 2 ] === "~=" ) { + match[ 3 ] = " " + match[ 3 ] + " "; + } + + return match.slice( 0, 4 ); + }, + + "CHILD": function( match ) { + + /* matches from matchExpr["CHILD"] + 1 type (only|nth|...) + 2 what (child|of-type) + 3 argument (even|odd|\d*|\d*n([+-]\d+)?|...) + 4 xn-component of xn+y argument ([+-]?\d*n|) + 5 sign of xn-component + 6 x of xn-component + 7 sign of y-component + 8 y of y-component + */ + match[ 1 ] = match[ 1 ].toLowerCase(); + + if ( match[ 1 ].slice( 0, 3 ) === "nth" ) { + + // nth-* requires argument + if ( !match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + // numeric x and y parameters for Expr.filter.CHILD + // remember that false/true cast respectively to 0/1 + match[ 4 ] = +( match[ 4 ] ? + match[ 5 ] + ( match[ 6 ] || 1 ) : + 2 * ( match[ 3 ] === "even" || match[ 3 ] === "odd" ) ); + match[ 5 ] = +( ( match[ 7 ] + match[ 8 ] ) || match[ 3 ] === "odd" ); + + // other types prohibit arguments + } else if ( match[ 3 ] ) { + Sizzle.error( match[ 0 ] ); + } + + return match; + }, + + "PSEUDO": function( match ) { + var excess, + unquoted = !match[ 6 ] && match[ 2 ]; + + if ( matchExpr[ "CHILD" ].test( match[ 0 ] ) ) { + return null; + } + + // Accept quoted arguments as-is + if ( match[ 3 ] ) { + match[ 2 ] = match[ 4 ] || match[ 5 ] || ""; + + // Strip excess characters from unquoted arguments + } else if ( unquoted && rpseudo.test( unquoted ) && + + // Get excess from tokenize (recursively) + ( excess = tokenize( unquoted, true ) ) && + + // advance to the next closing parenthesis + ( excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length ) ) { + + // excess is a negative index + match[ 0 ] = match[ 0 ].slice( 0, excess ); + match[ 2 ] = unquoted.slice( 0, excess ); + } + + // Return only captures needed by the pseudo filter method (type and argument) + return match.slice( 0, 3 ); + } + }, + + filter: { + + "TAG": function( nodeNameSelector ) { + var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase(); + return nodeNameSelector === "*" ? + function() { + return true; + } : + function( elem ) { + return elem.nodeName && elem.nodeName.toLowerCase() === nodeName; + }; + }, + + "CLASS": function( className ) { + var pattern = classCache[ className + " " ]; + + return pattern || + ( pattern = new RegExp( "(^|" + whitespace + + ")" + className + "(" + whitespace + "|$)" ) ) && classCache( + className, function( elem ) { + return pattern.test( + typeof elem.className === "string" && elem.className || + typeof elem.getAttribute !== "undefined" && + elem.getAttribute( "class" ) || + "" + ); + } ); + }, + + "ATTR": function( name, operator, check ) { + return function( elem ) { + var result = Sizzle.attr( elem, name ); + + if ( result == null ) { + return operator === "!="; + } + if ( !operator ) { + return true; + } + + result += ""; + + /* eslint-disable max-len */ + + return operator === "=" ? result === check : + operator === "!=" ? result !== check : + operator === "^=" ? check && result.indexOf( check ) === 0 : + operator === "*=" ? check && result.indexOf( check ) > -1 : + operator === "$=" ? check && result.slice( -check.length ) === check : + operator === "~=" ? ( " " + result.replace( rwhitespace, " " ) + " " ).indexOf( check ) > -1 : + operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" : + false; + /* eslint-enable max-len */ + + }; + }, + + "CHILD": function( type, what, _argument, first, last ) { + var simple = type.slice( 0, 3 ) !== "nth", + forward = type.slice( -4 ) !== "last", + ofType = what === "of-type"; + + return first === 1 && last === 0 ? + + // Shortcut for :nth-*(n) + function( elem ) { + return !!elem.parentNode; + } : + + function( elem, _context, xml ) { + var cache, uniqueCache, outerCache, node, nodeIndex, start, + dir = simple !== forward ? "nextSibling" : "previousSibling", + parent = elem.parentNode, + name = ofType && elem.nodeName.toLowerCase(), + useCache = !xml && !ofType, + diff = false; + + if ( parent ) { + + // :(first|last|only)-(child|of-type) + if ( simple ) { + while ( dir ) { + node = elem; + while ( ( node = node[ dir ] ) ) { + if ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) { + + return false; + } + } + + // Reverse direction for :only-* (if we haven't yet done so) + start = dir = type === "only" && !start && "nextSibling"; + } + return true; + } + + start = [ forward ? parent.firstChild : parent.lastChild ]; + + // non-xml :nth-child(...) stores cache data on `parent` + if ( forward && useCache ) { + + // Seek `elem` from a previously-cached index + + // ...in a gzip-friendly way + node = parent; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex && cache[ 2 ]; + node = nodeIndex && parent.childNodes[ nodeIndex ]; + + while ( ( node = ++nodeIndex && node && node[ dir ] || + + // Fallback to seeking `elem` from the start + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + // When found, cache indexes on `parent` and break + if ( node.nodeType === 1 && ++diff && node === elem ) { + uniqueCache[ type ] = [ dirruns, nodeIndex, diff ]; + break; + } + } + + } else { + + // Use previously-cached element index if available + if ( useCache ) { + + // ...in a gzip-friendly way + node = elem; + outerCache = node[ expando ] || ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + cache = uniqueCache[ type ] || []; + nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ]; + diff = nodeIndex; + } + + // xml :nth-child(...) + // or :nth-last-child(...) or :nth(-last)?-of-type(...) + if ( diff === false ) { + + // Use the same loop as above to seek `elem` from the start + while ( ( node = ++nodeIndex && node && node[ dir ] || + ( diff = nodeIndex = 0 ) || start.pop() ) ) { + + if ( ( ofType ? + node.nodeName.toLowerCase() === name : + node.nodeType === 1 ) && + ++diff ) { + + // Cache the index of each encountered element + if ( useCache ) { + outerCache = node[ expando ] || + ( node[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ node.uniqueID ] || + ( outerCache[ node.uniqueID ] = {} ); + + uniqueCache[ type ] = [ dirruns, diff ]; + } + + if ( node === elem ) { + break; + } + } + } + } + } + + // Incorporate the offset, then check against cycle size + diff -= last; + return diff === first || ( diff % first === 0 && diff / first >= 0 ); + } + }; + }, + + "PSEUDO": function( pseudo, argument ) { + + // pseudo-class names are case-insensitive + // http://www.w3.org/TR/selectors/#pseudo-classes + // Prioritize by case sensitivity in case custom pseudos are added with uppercase letters + // Remember that setFilters inherits from pseudos + var args, + fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] || + Sizzle.error( "unsupported pseudo: " + pseudo ); + + // The user may use createPseudo to indicate that + // arguments are needed to create the filter function + // just as Sizzle does + if ( fn[ expando ] ) { + return fn( argument ); + } + + // But maintain support for old signatures + if ( fn.length > 1 ) { + args = [ pseudo, pseudo, "", argument ]; + return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ? + markFunction( function( seed, matches ) { + var idx, + matched = fn( seed, argument ), + i = matched.length; + while ( i-- ) { + idx = indexOf( seed, matched[ i ] ); + seed[ idx ] = !( matches[ idx ] = matched[ i ] ); + } + } ) : + function( elem ) { + return fn( elem, 0, args ); + }; + } + + return fn; + } + }, + + pseudos: { + + // Potentially complex pseudos + "not": markFunction( function( selector ) { + + // Trim the selector passed to compile + // to avoid treating leading and trailing + // spaces as combinators + var input = [], + results = [], + matcher = compile( selector.replace( rtrim, "$1" ) ); + + return matcher[ expando ] ? + markFunction( function( seed, matches, _context, xml ) { + var elem, + unmatched = matcher( seed, null, xml, [] ), + i = seed.length; + + // Match elements unmatched by `matcher` + while ( i-- ) { + if ( ( elem = unmatched[ i ] ) ) { + seed[ i ] = !( matches[ i ] = elem ); + } + } + } ) : + function( elem, _context, xml ) { + input[ 0 ] = elem; + matcher( input, null, xml, results ); + + // Don't keep the element (issue #299) + input[ 0 ] = null; + return !results.pop(); + }; + } ), + + "has": markFunction( function( selector ) { + return function( elem ) { + return Sizzle( selector, elem ).length > 0; + }; + } ), + + "contains": markFunction( function( text ) { + text = text.replace( runescape, funescape ); + return function( elem ) { + return ( elem.textContent || getText( elem ) ).indexOf( text ) > -1; + }; + } ), + + // "Whether an element is represented by a :lang() selector + // is based solely on the element's language value + // being equal to the identifier C, + // or beginning with the identifier C immediately followed by "-". + // The matching of C against the element's language value is performed case-insensitively. + // The identifier C does not have to be a valid language name." + // http://www.w3.org/TR/selectors/#lang-pseudo + "lang": markFunction( function( lang ) { + + // lang value must be a valid identifier + if ( !ridentifier.test( lang || "" ) ) { + Sizzle.error( "unsupported lang: " + lang ); + } + lang = lang.replace( runescape, funescape ).toLowerCase(); + return function( elem ) { + var elemLang; + do { + if ( ( elemLang = documentIsHTML ? + elem.lang : + elem.getAttribute( "xml:lang" ) || elem.getAttribute( "lang" ) ) ) { + + elemLang = elemLang.toLowerCase(); + return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0; + } + } while ( ( elem = elem.parentNode ) && elem.nodeType === 1 ); + return false; + }; + } ), + + // Miscellaneous + "target": function( elem ) { + var hash = window.location && window.location.hash; + return hash && hash.slice( 1 ) === elem.id; + }, + + "root": function( elem ) { + return elem === docElem; + }, + + "focus": function( elem ) { + return elem === document.activeElement && + ( !document.hasFocus || document.hasFocus() ) && + !!( elem.type || elem.href || ~elem.tabIndex ); + }, + + // Boolean properties + "enabled": createDisabledPseudo( false ), + "disabled": createDisabledPseudo( true ), + + "checked": function( elem ) { + + // In CSS3, :checked should return both checked and selected elements + // http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked + var nodeName = elem.nodeName.toLowerCase(); + return ( nodeName === "input" && !!elem.checked ) || + ( nodeName === "option" && !!elem.selected ); + }, + + "selected": function( elem ) { + + // Accessing this property makes selected-by-default + // options in Safari work properly + if ( elem.parentNode ) { + // eslint-disable-next-line no-unused-expressions + elem.parentNode.selectedIndex; + } + + return elem.selected === true; + }, + + // Contents + "empty": function( elem ) { + + // http://www.w3.org/TR/selectors/#empty-pseudo + // :empty is negated by element (1) or content nodes (text: 3; cdata: 4; entity ref: 5), + // but not by others (comment: 8; processing instruction: 7; etc.) + // nodeType < 6 works because attributes (2) do not appear as children + for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) { + if ( elem.nodeType < 6 ) { + return false; + } + } + return true; + }, + + "parent": function( elem ) { + return !Expr.pseudos[ "empty" ]( elem ); + }, + + // Element/input types + "header": function( elem ) { + return rheader.test( elem.nodeName ); + }, + + "input": function( elem ) { + return rinputs.test( elem.nodeName ); + }, + + "button": function( elem ) { + var name = elem.nodeName.toLowerCase(); + return name === "input" && elem.type === "button" || name === "button"; + }, + + "text": function( elem ) { + var attr; + return elem.nodeName.toLowerCase() === "input" && + elem.type === "text" && + + // Support: IE<8 + // New HTML5 attribute values (e.g., "search") appear with elem.type === "text" + ( ( attr = elem.getAttribute( "type" ) ) == null || + attr.toLowerCase() === "text" ); + }, + + // Position-in-collection + "first": createPositionalPseudo( function() { + return [ 0 ]; + } ), + + "last": createPositionalPseudo( function( _matchIndexes, length ) { + return [ length - 1 ]; + } ), + + "eq": createPositionalPseudo( function( _matchIndexes, length, argument ) { + return [ argument < 0 ? argument + length : argument ]; + } ), + + "even": createPositionalPseudo( function( matchIndexes, length ) { + var i = 0; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "odd": createPositionalPseudo( function( matchIndexes, length ) { + var i = 1; + for ( ; i < length; i += 2 ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "lt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? + argument + length : + argument > length ? + length : + argument; + for ( ; --i >= 0; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ), + + "gt": createPositionalPseudo( function( matchIndexes, length, argument ) { + var i = argument < 0 ? argument + length : argument; + for ( ; ++i < length; ) { + matchIndexes.push( i ); + } + return matchIndexes; + } ) + } +}; + +Expr.pseudos[ "nth" ] = Expr.pseudos[ "eq" ]; + +// Add button/input type pseudos +for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) { + Expr.pseudos[ i ] = createInputPseudo( i ); +} +for ( i in { submit: true, reset: true } ) { + Expr.pseudos[ i ] = createButtonPseudo( i ); +} + +// Easy API for creating new setFilters +function setFilters() {} +setFilters.prototype = Expr.filters = Expr.pseudos; +Expr.setFilters = new setFilters(); + +tokenize = Sizzle.tokenize = function( selector, parseOnly ) { + var matched, match, tokens, type, + soFar, groups, preFilters, + cached = tokenCache[ selector + " " ]; + + if ( cached ) { + return parseOnly ? 0 : cached.slice( 0 ); + } + + soFar = selector; + groups = []; + preFilters = Expr.preFilter; + + while ( soFar ) { + + // Comma and first run + if ( !matched || ( match = rcomma.exec( soFar ) ) ) { + if ( match ) { + + // Don't consume trailing commas as valid + soFar = soFar.slice( match[ 0 ].length ) || soFar; + } + groups.push( ( tokens = [] ) ); + } + + matched = false; + + // Combinators + if ( ( match = rcombinators.exec( soFar ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + + // Cast descendant combinators to space + type: match[ 0 ].replace( rtrim, " " ) + } ); + soFar = soFar.slice( matched.length ); + } + + // Filters + for ( type in Expr.filter ) { + if ( ( match = matchExpr[ type ].exec( soFar ) ) && ( !preFilters[ type ] || + ( match = preFilters[ type ]( match ) ) ) ) { + matched = match.shift(); + tokens.push( { + value: matched, + type: type, + matches: match + } ); + soFar = soFar.slice( matched.length ); + } + } + + if ( !matched ) { + break; + } + } + + // Return the length of the invalid excess + // if we're just parsing + // Otherwise, throw an error or return tokens + return parseOnly ? + soFar.length : + soFar ? + Sizzle.error( selector ) : + + // Cache the tokens + tokenCache( selector, groups ).slice( 0 ); +}; + +function toSelector( tokens ) { + var i = 0, + len = tokens.length, + selector = ""; + for ( ; i < len; i++ ) { + selector += tokens[ i ].value; + } + return selector; +} + +function addCombinator( matcher, combinator, base ) { + var dir = combinator.dir, + skip = combinator.next, + key = skip || dir, + checkNonElements = base && key === "parentNode", + doneName = done++; + + return combinator.first ? + + // Check against closest ancestor/preceding element + function( elem, context, xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + return matcher( elem, context, xml ); + } + } + return false; + } : + + // Check against all ancestor/preceding elements + function( elem, context, xml ) { + var oldCache, uniqueCache, outerCache, + newCache = [ dirruns, doneName ]; + + // We can't set arbitrary data on XML nodes, so they don't benefit from combinator caching + if ( xml ) { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + if ( matcher( elem, context, xml ) ) { + return true; + } + } + } + } else { + while ( ( elem = elem[ dir ] ) ) { + if ( elem.nodeType === 1 || checkNonElements ) { + outerCache = elem[ expando ] || ( elem[ expando ] = {} ); + + // Support: IE <9 only + // Defend against cloned attroperties (jQuery gh-1709) + uniqueCache = outerCache[ elem.uniqueID ] || + ( outerCache[ elem.uniqueID ] = {} ); + + if ( skip && skip === elem.nodeName.toLowerCase() ) { + elem = elem[ dir ] || elem; + } else if ( ( oldCache = uniqueCache[ key ] ) && + oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) { + + // Assign to newCache so results back-propagate to previous elements + return ( newCache[ 2 ] = oldCache[ 2 ] ); + } else { + + // Reuse newcache so results back-propagate to previous elements + uniqueCache[ key ] = newCache; + + // A match means we're done; a fail means we have to keep checking + if ( ( newCache[ 2 ] = matcher( elem, context, xml ) ) ) { + return true; + } + } + } + } + } + return false; + }; +} + +function elementMatcher( matchers ) { + return matchers.length > 1 ? + function( elem, context, xml ) { + var i = matchers.length; + while ( i-- ) { + if ( !matchers[ i ]( elem, context, xml ) ) { + return false; + } + } + return true; + } : + matchers[ 0 ]; +} + +function multipleContexts( selector, contexts, results ) { + var i = 0, + len = contexts.length; + for ( ; i < len; i++ ) { + Sizzle( selector, contexts[ i ], results ); + } + return results; +} + +function condense( unmatched, map, filter, context, xml ) { + var elem, + newUnmatched = [], + i = 0, + len = unmatched.length, + mapped = map != null; + + for ( ; i < len; i++ ) { + if ( ( elem = unmatched[ i ] ) ) { + if ( !filter || filter( elem, context, xml ) ) { + newUnmatched.push( elem ); + if ( mapped ) { + map.push( i ); + } + } + } + } + + return newUnmatched; +} + +function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) { + if ( postFilter && !postFilter[ expando ] ) { + postFilter = setMatcher( postFilter ); + } + if ( postFinder && !postFinder[ expando ] ) { + postFinder = setMatcher( postFinder, postSelector ); + } + return markFunction( function( seed, results, context, xml ) { + var temp, i, elem, + preMap = [], + postMap = [], + preexisting = results.length, + + // Get initial elements from seed or context + elems = seed || multipleContexts( + selector || "*", + context.nodeType ? [ context ] : context, + [] + ), + + // Prefilter to get matcher input, preserving a map for seed-results synchronization + matcherIn = preFilter && ( seed || !selector ) ? + condense( elems, preMap, preFilter, context, xml ) : + elems, + + matcherOut = matcher ? + + // If we have a postFinder, or filtered seed, or non-seed postFilter or preexisting results, + postFinder || ( seed ? preFilter : preexisting || postFilter ) ? + + // ...intermediate processing is necessary + [] : + + // ...otherwise use results directly + results : + matcherIn; + + // Find primary matches + if ( matcher ) { + matcher( matcherIn, matcherOut, context, xml ); + } + + // Apply postFilter + if ( postFilter ) { + temp = condense( matcherOut, postMap ); + postFilter( temp, [], context, xml ); + + // Un-match failing elements by moving them back to matcherIn + i = temp.length; + while ( i-- ) { + if ( ( elem = temp[ i ] ) ) { + matcherOut[ postMap[ i ] ] = !( matcherIn[ postMap[ i ] ] = elem ); + } + } + } + + if ( seed ) { + if ( postFinder || preFilter ) { + if ( postFinder ) { + + // Get the final matcherOut by condensing this intermediate into postFinder contexts + temp = []; + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) ) { + + // Restore matcherIn since elem is not yet a final match + temp.push( ( matcherIn[ i ] = elem ) ); + } + } + postFinder( null, ( matcherOut = [] ), temp, xml ); + } + + // Move matched elements from seed to results to keep them synchronized + i = matcherOut.length; + while ( i-- ) { + if ( ( elem = matcherOut[ i ] ) && + ( temp = postFinder ? indexOf( seed, elem ) : preMap[ i ] ) > -1 ) { + + seed[ temp ] = !( results[ temp ] = elem ); + } + } + } + + // Add elements to results, through postFinder if defined + } else { + matcherOut = condense( + matcherOut === results ? + matcherOut.splice( preexisting, matcherOut.length ) : + matcherOut + ); + if ( postFinder ) { + postFinder( null, results, matcherOut, xml ); + } else { + push.apply( results, matcherOut ); + } + } + } ); +} + +function matcherFromTokens( tokens ) { + var checkContext, matcher, j, + len = tokens.length, + leadingRelative = Expr.relative[ tokens[ 0 ].type ], + implicitRelative = leadingRelative || Expr.relative[ " " ], + i = leadingRelative ? 1 : 0, + + // The foundational matcher ensures that elements are reachable from top-level context(s) + matchContext = addCombinator( function( elem ) { + return elem === checkContext; + }, implicitRelative, true ), + matchAnyContext = addCombinator( function( elem ) { + return indexOf( checkContext, elem ) > -1; + }, implicitRelative, true ), + matchers = [ function( elem, context, xml ) { + var ret = ( !leadingRelative && ( xml || context !== outermostContext ) ) || ( + ( checkContext = context ).nodeType ? + matchContext( elem, context, xml ) : + matchAnyContext( elem, context, xml ) ); + + // Avoid hanging onto element (issue #299) + checkContext = null; + return ret; + } ]; + + for ( ; i < len; i++ ) { + if ( ( matcher = Expr.relative[ tokens[ i ].type ] ) ) { + matchers = [ addCombinator( elementMatcher( matchers ), matcher ) ]; + } else { + matcher = Expr.filter[ tokens[ i ].type ].apply( null, tokens[ i ].matches ); + + // Return special upon seeing a positional matcher + if ( matcher[ expando ] ) { + + // Find the next relative operator (if any) for proper handling + j = ++i; + for ( ; j < len; j++ ) { + if ( Expr.relative[ tokens[ j ].type ] ) { + break; + } + } + return setMatcher( + i > 1 && elementMatcher( matchers ), + i > 1 && toSelector( + + // If the preceding token was a descendant combinator, insert an implicit any-element `*` + tokens + .slice( 0, i - 1 ) + .concat( { value: tokens[ i - 2 ].type === " " ? "*" : "" } ) + ).replace( rtrim, "$1" ), + matcher, + i < j && matcherFromTokens( tokens.slice( i, j ) ), + j < len && matcherFromTokens( ( tokens = tokens.slice( j ) ) ), + j < len && toSelector( tokens ) + ); + } + matchers.push( matcher ); + } + } + + return elementMatcher( matchers ); +} + +function matcherFromGroupMatchers( elementMatchers, setMatchers ) { + var bySet = setMatchers.length > 0, + byElement = elementMatchers.length > 0, + superMatcher = function( seed, context, xml, results, outermost ) { + var elem, j, matcher, + matchedCount = 0, + i = "0", + unmatched = seed && [], + setMatched = [], + contextBackup = outermostContext, + + // We must always have either seed elements or outermost context + elems = seed || byElement && Expr.find[ "TAG" ]( "*", outermost ), + + // Use integer dirruns iff this is the outermost matcher + dirrunsUnique = ( dirruns += contextBackup == null ? 1 : Math.random() || 0.1 ), + len = elems.length; + + if ( outermost ) { + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + outermostContext = context == document || context || outermost; + } + + // Add elements passing elementMatchers directly to results + // Support: IE<9, Safari + // Tolerate NodeList properties (IE: "length"; Safari: <number>) matching elements by id + for ( ; i !== len && ( elem = elems[ i ] ) != null; i++ ) { + if ( byElement && elem ) { + j = 0; + + // Support: IE 11+, Edge 17 - 18+ + // IE/Edge sometimes throw a "Permission denied" error when strict-comparing + // two documents; shallow comparisons work. + // eslint-disable-next-line eqeqeq + if ( !context && elem.ownerDocument != document ) { + setDocument( elem ); + xml = !documentIsHTML; + } + while ( ( matcher = elementMatchers[ j++ ] ) ) { + if ( matcher( elem, context || document, xml ) ) { + results.push( elem ); + break; + } + } + if ( outermost ) { + dirruns = dirrunsUnique; + } + } + + // Track unmatched elements for set filters + if ( bySet ) { + + // They will have gone through all possible matchers + if ( ( elem = !matcher && elem ) ) { + matchedCount--; + } + + // Lengthen the array for every element, matched or not + if ( seed ) { + unmatched.push( elem ); + } + } + } + + // `i` is now the count of elements visited above, and adding it to `matchedCount` + // makes the latter nonnegative. + matchedCount += i; + + // Apply set filters to unmatched elements + // NOTE: This can be skipped if there are no unmatched elements (i.e., `matchedCount` + // equals `i`), unless we didn't visit _any_ elements in the above loop because we have + // no element matchers and no seed. + // Incrementing an initially-string "0" `i` allows `i` to remain a string only in that + // case, which will result in a "00" `matchedCount` that differs from `i` but is also + // numerically zero. + if ( bySet && i !== matchedCount ) { + j = 0; + while ( ( matcher = setMatchers[ j++ ] ) ) { + matcher( unmatched, setMatched, context, xml ); + } + + if ( seed ) { + + // Reintegrate element matches to eliminate the need for sorting + if ( matchedCount > 0 ) { + while ( i-- ) { + if ( !( unmatched[ i ] || setMatched[ i ] ) ) { + setMatched[ i ] = pop.call( results ); + } + } + } + + // Discard index placeholder values to get only actual matches + setMatched = condense( setMatched ); + } + + // Add matches to results + push.apply( results, setMatched ); + + // Seedless set matches succeeding multiple successful matchers stipulate sorting + if ( outermost && !seed && setMatched.length > 0 && + ( matchedCount + setMatchers.length ) > 1 ) { + + Sizzle.uniqueSort( results ); + } + } + + // Override manipulation of globals by nested matchers + if ( outermost ) { + dirruns = dirrunsUnique; + outermostContext = contextBackup; + } + + return unmatched; + }; + + return bySet ? + markFunction( superMatcher ) : + superMatcher; +} + +compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) { + var i, + setMatchers = [], + elementMatchers = [], + cached = compilerCache[ selector + " " ]; + + if ( !cached ) { + + // Generate a function of recursive functions that can be used to check each element + if ( !match ) { + match = tokenize( selector ); + } + i = match.length; + while ( i-- ) { + cached = matcherFromTokens( match[ i ] ); + if ( cached[ expando ] ) { + setMatchers.push( cached ); + } else { + elementMatchers.push( cached ); + } + } + + // Cache the compiled function + cached = compilerCache( + selector, + matcherFromGroupMatchers( elementMatchers, setMatchers ) + ); + + // Save selector and tokenization + cached.selector = selector; + } + return cached; +}; + +/** + * A low-level selection function that works with Sizzle's compiled + * selector functions + * @param {String|Function} selector A selector or a pre-compiled + * selector function built with Sizzle.compile + * @param {Element} context + * @param {Array} [results] + * @param {Array} [seed] A set of elements to match against + */ +select = Sizzle.select = function( selector, context, results, seed ) { + var i, tokens, token, type, find, + compiled = typeof selector === "function" && selector, + match = !seed && tokenize( ( selector = compiled.selector || selector ) ); + + results = results || []; + + // Try to minimize operations if there is only one selector in the list and no seed + // (the latter of which guarantees us context) + if ( match.length === 1 ) { + + // Reduce context if the leading compound selector is an ID + tokens = match[ 0 ] = match[ 0 ].slice( 0 ); + if ( tokens.length > 2 && ( token = tokens[ 0 ] ).type === "ID" && + context.nodeType === 9 && documentIsHTML && Expr.relative[ tokens[ 1 ].type ] ) { + + context = ( Expr.find[ "ID" ]( token.matches[ 0 ] + .replace( runescape, funescape ), context ) || [] )[ 0 ]; + if ( !context ) { + return results; + + // Precompiled matchers will still verify ancestry, so step up a level + } else if ( compiled ) { + context = context.parentNode; + } + + selector = selector.slice( tokens.shift().value.length ); + } + + // Fetch a seed set for right-to-left matching + i = matchExpr[ "needsContext" ].test( selector ) ? 0 : tokens.length; + while ( i-- ) { + token = tokens[ i ]; + + // Abort if we hit a combinator + if ( Expr.relative[ ( type = token.type ) ] ) { + break; + } + if ( ( find = Expr.find[ type ] ) ) { + + // Search, expanding context for leading sibling combinators + if ( ( seed = find( + token.matches[ 0 ].replace( runescape, funescape ), + rsibling.test( tokens[ 0 ].type ) && testContext( context.parentNode ) || + context + ) ) ) { + + // If seed is empty or no tokens remain, we can return early + tokens.splice( i, 1 ); + selector = seed.length && toSelector( tokens ); + if ( !selector ) { + push.apply( results, seed ); + return results; + } + + break; + } + } + } + } + + // Compile and execute a filtering function if one is not provided + // Provide `match` to avoid retokenization if we modified the selector above + ( compiled || compile( selector, match ) )( + seed, + context, + !documentIsHTML, + results, + !context || rsibling.test( selector ) && testContext( context.parentNode ) || context + ); + return results; +}; + +// One-time assignments + +// Sort stability +support.sortStable = expando.split( "" ).sort( sortOrder ).join( "" ) === expando; + +// Support: Chrome 14-35+ +// Always assume duplicates if they aren't passed to the comparison function +support.detectDuplicates = !!hasDuplicate; + +// Initialize against the default document +setDocument(); + +// Support: Webkit<537.32 - Safari 6.0.3/Chrome 25 (fixed in Chrome 27) +// Detached nodes confoundingly follow *each other* +support.sortDetached = assert( function( el ) { + + // Should return 1, but returns 4 (following) + return el.compareDocumentPosition( document.createElement( "fieldset" ) ) & 1; +} ); + +// Support: IE<8 +// Prevent attribute/property "interpolation" +// https://msdn.microsoft.com/en-us/library/ms536429%28VS.85%29.aspx +if ( !assert( function( el ) { + el.innerHTML = "<a href='#'></a>"; + return el.firstChild.getAttribute( "href" ) === "#"; +} ) ) { + addHandle( "type|href|height|width", function( elem, name, isXML ) { + if ( !isXML ) { + return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 ); + } + } ); +} + +// Support: IE<9 +// Use defaultValue in place of getAttribute("value") +if ( !support.attributes || !assert( function( el ) { + el.innerHTML = "<input/>"; + el.firstChild.setAttribute( "value", "" ); + return el.firstChild.getAttribute( "value" ) === ""; +} ) ) { + addHandle( "value", function( elem, _name, isXML ) { + if ( !isXML && elem.nodeName.toLowerCase() === "input" ) { + return elem.defaultValue; + } + } ); +} + +// Support: IE<9 +// Use getAttributeNode to fetch booleans when getAttribute lies +if ( !assert( function( el ) { + return el.getAttribute( "disabled" ) == null; +} ) ) { + addHandle( booleans, function( elem, name, isXML ) { + var val; + if ( !isXML ) { + return elem[ name ] === true ? name.toLowerCase() : + ( val = elem.getAttributeNode( name ) ) && val.specified ? + val.value : + null; + } + } ); +} + +return Sizzle; + +} )( window ); + + + +jQuery.find = Sizzle; +jQuery.expr = Sizzle.selectors; + +// Deprecated +jQuery.expr[ ":" ] = jQuery.expr.pseudos; +jQuery.uniqueSort = jQuery.unique = Sizzle.uniqueSort; +jQuery.text = Sizzle.getText; +jQuery.isXMLDoc = Sizzle.isXML; +jQuery.contains = Sizzle.contains; +jQuery.escapeSelector = Sizzle.escape; + + + + +var dir = function( elem, dir, until ) { + var matched = [], + truncate = until !== undefined; + + while ( ( elem = elem[ dir ] ) && elem.nodeType !== 9 ) { + if ( elem.nodeType === 1 ) { + if ( truncate && jQuery( elem ).is( until ) ) { + break; + } + matched.push( elem ); + } + } + return matched; +}; + + +var siblings = function( n, elem ) { + var matched = []; + + for ( ; n; n = n.nextSibling ) { + if ( n.nodeType === 1 && n !== elem ) { + matched.push( n ); + } + } + + return matched; +}; + + +var rneedsContext = jQuery.expr.match.needsContext; + + + +function nodeName( elem, name ) { + + return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase(); + +}; +var rsingleTag = ( /^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i ); + + + +// Implement the identical functionality for filter and not +function winnow( elements, qualifier, not ) { + if ( isFunction( qualifier ) ) { + return jQuery.grep( elements, function( elem, i ) { + return !!qualifier.call( elem, i, elem ) !== not; + } ); + } + + // Single element + if ( qualifier.nodeType ) { + return jQuery.grep( elements, function( elem ) { + return ( elem === qualifier ) !== not; + } ); + } + + // Arraylike of elements (jQuery, arguments, Array) + if ( typeof qualifier !== "string" ) { + return jQuery.grep( elements, function( elem ) { + return ( indexOf.call( qualifier, elem ) > -1 ) !== not; + } ); + } + + // Filtered directly for both simple and complex selectors + return jQuery.filter( qualifier, elements, not ); +} + +jQuery.filter = function( expr, elems, not ) { + var elem = elems[ 0 ]; + + if ( not ) { + expr = ":not(" + expr + ")"; + } + + if ( elems.length === 1 && elem.nodeType === 1 ) { + return jQuery.find.matchesSelector( elem, expr ) ? [ elem ] : []; + } + + return jQuery.find.matches( expr, jQuery.grep( elems, function( elem ) { + return elem.nodeType === 1; + } ) ); +}; + +jQuery.fn.extend( { + find: function( selector ) { + var i, ret, + len = this.length, + self = this; + + if ( typeof selector !== "string" ) { + return this.pushStack( jQuery( selector ).filter( function() { + for ( i = 0; i < len; i++ ) { + if ( jQuery.contains( self[ i ], this ) ) { + return true; + } + } + } ) ); + } + + ret = this.pushStack( [] ); + + for ( i = 0; i < len; i++ ) { + jQuery.find( selector, self[ i ], ret ); + } + + return len > 1 ? jQuery.uniqueSort( ret ) : ret; + }, + filter: function( selector ) { + return this.pushStack( winnow( this, selector || [], false ) ); + }, + not: function( selector ) { + return this.pushStack( winnow( this, selector || [], true ) ); + }, + is: function( selector ) { + return !!winnow( + this, + + // If this is a positional/relative selector, check membership in the returned set + // so $("p:first").is("p:last") won't return true for a doc with two "p". + typeof selector === "string" && rneedsContext.test( selector ) ? + jQuery( selector ) : + selector || [], + false + ).length; + } +} ); + + +// Initialize a jQuery object + + +// A central reference to the root jQuery(document) +var rootjQuery, + + // A simple way to check for HTML strings + // Prioritize #id over <tag> to avoid XSS via location.hash (#9521) + // Strict HTML recognition (#11290: must start with <) + // Shortcut simple #id case for speed + rquickExpr = /^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/, + + init = jQuery.fn.init = function( selector, context, root ) { + var match, elem; + + // HANDLE: $(""), $(null), $(undefined), $(false) + if ( !selector ) { + return this; + } + + // Method init() accepts an alternate rootjQuery + // so migrate can support jQuery.sub (gh-2101) + root = root || rootjQuery; + + // Handle HTML strings + if ( typeof selector === "string" ) { + if ( selector[ 0 ] === "<" && + selector[ selector.length - 1 ] === ">" && + selector.length >= 3 ) { + + // Assume that strings that start and end with <> are HTML and skip the regex check + match = [ null, selector, null ]; + + } else { + match = rquickExpr.exec( selector ); + } + + // Match html or make sure no context is specified for #id + if ( match && ( match[ 1 ] || !context ) ) { + + // HANDLE: $(html) -> $(array) + if ( match[ 1 ] ) { + context = context instanceof jQuery ? context[ 0 ] : context; + + // Option to run scripts is true for back-compat + // Intentionally let the error be thrown if parseHTML is not present + jQuery.merge( this, jQuery.parseHTML( + match[ 1 ], + context && context.nodeType ? context.ownerDocument || context : document, + true + ) ); + + // HANDLE: $(html, props) + if ( rsingleTag.test( match[ 1 ] ) && jQuery.isPlainObject( context ) ) { + for ( match in context ) { + + // Properties of context are called as methods if possible + if ( isFunction( this[ match ] ) ) { + this[ match ]( context[ match ] ); + + // ...and otherwise set as attributes + } else { + this.attr( match, context[ match ] ); + } + } + } + + return this; + + // HANDLE: $(#id) + } else { + elem = document.getElementById( match[ 2 ] ); + + if ( elem ) { + + // Inject the element directly into the jQuery object + this[ 0 ] = elem; + this.length = 1; + } + return this; + } + + // HANDLE: $(expr, $(...)) + } else if ( !context || context.jquery ) { + return ( context || root ).find( selector ); + + // HANDLE: $(expr, context) + // (which is just equivalent to: $(context).find(expr) + } else { + return this.constructor( context ).find( selector ); + } + + // HANDLE: $(DOMElement) + } else if ( selector.nodeType ) { + this[ 0 ] = selector; + this.length = 1; + return this; + + // HANDLE: $(function) + // Shortcut for document ready + } else if ( isFunction( selector ) ) { + return root.ready !== undefined ? + root.ready( selector ) : + + // Execute immediately if ready is not present + selector( jQuery ); + } + + return jQuery.makeArray( selector, this ); + }; + +// Give the init function the jQuery prototype for later instantiation +init.prototype = jQuery.fn; + +// Initialize central reference +rootjQuery = jQuery( document ); + + +var rparentsprev = /^(?:parents|prev(?:Until|All))/, + + // Methods guaranteed to produce a unique set when starting from a unique set + guaranteedUnique = { + children: true, + contents: true, + next: true, + prev: true + }; + +jQuery.fn.extend( { + has: function( target ) { + var targets = jQuery( target, this ), + l = targets.length; + + return this.filter( function() { + var i = 0; + for ( ; i < l; i++ ) { + if ( jQuery.contains( this, targets[ i ] ) ) { + return true; + } + } + } ); + }, + + closest: function( selectors, context ) { + var cur, + i = 0, + l = this.length, + matched = [], + targets = typeof selectors !== "string" && jQuery( selectors ); + + // Positional selectors never match, since there's no _selection_ context + if ( !rneedsContext.test( selectors ) ) { + for ( ; i < l; i++ ) { + for ( cur = this[ i ]; cur && cur !== context; cur = cur.parentNode ) { + + // Always skip document fragments + if ( cur.nodeType < 11 && ( targets ? + targets.index( cur ) > -1 : + + // Don't pass non-elements to Sizzle + cur.nodeType === 1 && + jQuery.find.matchesSelector( cur, selectors ) ) ) { + + matched.push( cur ); + break; + } + } + } + } + + return this.pushStack( matched.length > 1 ? jQuery.uniqueSort( matched ) : matched ); + }, + + // Determine the position of an element within the set + index: function( elem ) { + + // No argument, return index in parent + if ( !elem ) { + return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1; + } + + // Index in selector + if ( typeof elem === "string" ) { + return indexOf.call( jQuery( elem ), this[ 0 ] ); + } + + // Locate the position of the desired element + return indexOf.call( this, + + // If it receives a jQuery object, the first element is used + elem.jquery ? elem[ 0 ] : elem + ); + }, + + add: function( selector, context ) { + return this.pushStack( + jQuery.uniqueSort( + jQuery.merge( this.get(), jQuery( selector, context ) ) + ) + ); + }, + + addBack: function( selector ) { + return this.add( selector == null ? + this.prevObject : this.prevObject.filter( selector ) + ); + } +} ); + +function sibling( cur, dir ) { + while ( ( cur = cur[ dir ] ) && cur.nodeType !== 1 ) {} + return cur; +} + +jQuery.each( { + parent: function( elem ) { + var parent = elem.parentNode; + return parent && parent.nodeType !== 11 ? parent : null; + }, + parents: function( elem ) { + return dir( elem, "parentNode" ); + }, + parentsUntil: function( elem, _i, until ) { + return dir( elem, "parentNode", until ); + }, + next: function( elem ) { + return sibling( elem, "nextSibling" ); + }, + prev: function( elem ) { + return sibling( elem, "previousSibling" ); + }, + nextAll: function( elem ) { + return dir( elem, "nextSibling" ); + }, + prevAll: function( elem ) { + return dir( elem, "previousSibling" ); + }, + nextUntil: function( elem, _i, until ) { + return dir( elem, "nextSibling", until ); + }, + prevUntil: function( elem, _i, until ) { + return dir( elem, "previousSibling", until ); + }, + siblings: function( elem ) { + return siblings( ( elem.parentNode || {} ).firstChild, elem ); + }, + children: function( elem ) { + return siblings( elem.firstChild ); + }, + contents: function( elem ) { + if ( elem.contentDocument != null && + + // Support: IE 11+ + // <object> elements with no `data` attribute has an object + // `contentDocument` with a `null` prototype. + getProto( elem.contentDocument ) ) { + + return elem.contentDocument; + } + + // Support: IE 9 - 11 only, iOS 7 only, Android Browser <=4.3 only + // Treat the template element as a regular one in browsers that + // don't support it. + if ( nodeName( elem, "template" ) ) { + elem = elem.content || elem; + } + + return jQuery.merge( [], elem.childNodes ); + } +}, function( name, fn ) { + jQuery.fn[ name ] = function( until, selector ) { + var matched = jQuery.map( this, fn, until ); + + if ( name.slice( -5 ) !== "Until" ) { + selector = until; + } + + if ( selector && typeof selector === "string" ) { + matched = jQuery.filter( selector, matched ); + } + + if ( this.length > 1 ) { + + // Remove duplicates + if ( !guaranteedUnique[ name ] ) { + jQuery.uniqueSort( matched ); + } + + // Reverse order for parents* and prev-derivatives + if ( rparentsprev.test( name ) ) { + matched.reverse(); + } + } + + return this.pushStack( matched ); + }; +} ); +var rnothtmlwhite = ( /[^\x20\t\r\n\f]+/g ); + + + +// Convert String-formatted options into Object-formatted ones +function createOptions( options ) { + var object = {}; + jQuery.each( options.match( rnothtmlwhite ) || [], function( _, flag ) { + object[ flag ] = true; + } ); + return object; +} + +/* + * Create a callback list using the following parameters: + * + * options: an optional list of space-separated options that will change how + * the callback list behaves or a more traditional option object + * + * By default a callback list will act like an event callback list and can be + * "fired" multiple times. + * + * Possible options: + * + * once: will ensure the callback list can only be fired once (like a Deferred) + * + * memory: will keep track of previous values and will call any callback added + * after the list has been fired right away with the latest "memorized" + * values (like a Deferred) + * + * unique: will ensure a callback can only be added once (no duplicate in the list) + * + * stopOnFalse: interrupt callings when a callback returns false + * + */ +jQuery.Callbacks = function( options ) { + + // Convert options from String-formatted to Object-formatted if needed + // (we check in cache first) + options = typeof options === "string" ? + createOptions( options ) : + jQuery.extend( {}, options ); + + var // Flag to know if list is currently firing + firing, + + // Last fire value for non-forgettable lists + memory, + + // Flag to know if list was already fired + fired, + + // Flag to prevent firing + locked, + + // Actual callback list + list = [], + + // Queue of execution data for repeatable lists + queue = [], + + // Index of currently firing callback (modified by add/remove as needed) + firingIndex = -1, + + // Fire callbacks + fire = function() { + + // Enforce single-firing + locked = locked || options.once; + + // Execute callbacks for all pending executions, + // respecting firingIndex overrides and runtime changes + fired = firing = true; + for ( ; queue.length; firingIndex = -1 ) { + memory = queue.shift(); + while ( ++firingIndex < list.length ) { + + // Run callback and check for early termination + if ( list[ firingIndex ].apply( memory[ 0 ], memory[ 1 ] ) === false && + options.stopOnFalse ) { + + // Jump to end and forget the data so .add doesn't re-fire + firingIndex = list.length; + memory = false; + } + } + } + + // Forget the data if we're done with it + if ( !options.memory ) { + memory = false; + } + + firing = false; + + // Clean up if we're done firing for good + if ( locked ) { + + // Keep an empty list if we have data for future add calls + if ( memory ) { + list = []; + + // Otherwise, this object is spent + } else { + list = ""; + } + } + }, + + // Actual Callbacks object + self = { + + // Add a callback or a collection of callbacks to the list + add: function() { + if ( list ) { + + // If we have memory from a past run, we should fire after adding + if ( memory && !firing ) { + firingIndex = list.length - 1; + queue.push( memory ); + } + + ( function add( args ) { + jQuery.each( args, function( _, arg ) { + if ( isFunction( arg ) ) { + if ( !options.unique || !self.has( arg ) ) { + list.push( arg ); + } + } else if ( arg && arg.length && toType( arg ) !== "string" ) { + + // Inspect recursively + add( arg ); + } + } ); + } )( arguments ); + + if ( memory && !firing ) { + fire(); + } + } + return this; + }, + + // Remove a callback from the list + remove: function() { + jQuery.each( arguments, function( _, arg ) { + var index; + while ( ( index = jQuery.inArray( arg, list, index ) ) > -1 ) { + list.splice( index, 1 ); + + // Handle firing indexes + if ( index <= firingIndex ) { + firingIndex--; + } + } + } ); + return this; + }, + + // Check if a given callback is in the list. + // If no argument is given, return whether or not list has callbacks attached. + has: function( fn ) { + return fn ? + jQuery.inArray( fn, list ) > -1 : + list.length > 0; + }, + + // Remove all callbacks from the list + empty: function() { + if ( list ) { + list = []; + } + return this; + }, + + // Disable .fire and .add + // Abort any current/pending executions + // Clear all callbacks and values + disable: function() { + locked = queue = []; + list = memory = ""; + return this; + }, + disabled: function() { + return !list; + }, + + // Disable .fire + // Also disable .add unless we have memory (since it would have no effect) + // Abort any pending executions + lock: function() { + locked = queue = []; + if ( !memory && !firing ) { + list = memory = ""; + } + return this; + }, + locked: function() { + return !!locked; + }, + + // Call all callbacks with the given context and arguments + fireWith: function( context, args ) { + if ( !locked ) { + args = args || []; + args = [ context, args.slice ? args.slice() : args ]; + queue.push( args ); + if ( !firing ) { + fire(); + } + } + return this; + }, + + // Call all the callbacks with the given arguments + fire: function() { + self.fireWith( this, arguments ); + return this; + }, + + // To know if the callbacks have already been called at least once + fired: function() { + return !!fired; + } + }; + + return self; +}; + + +function Identity( v ) { + return v; +} +function Thrower( ex ) { + throw ex; +} + +function adoptValue( value, resolve, reject, noValue ) { + var method; + + try { + + // Check for promise aspect first to privilege synchronous behavior + if ( value && isFunction( ( method = value.promise ) ) ) { + method.call( value ).done( resolve ).fail( reject ); + + // Other thenables + } else if ( value && isFunction( ( method = value.then ) ) ) { + method.call( value, resolve, reject ); + + // Other non-thenables + } else { + + // Control `resolve` arguments by letting Array#slice cast boolean `noValue` to integer: + // * false: [ value ].slice( 0 ) => resolve( value ) + // * true: [ value ].slice( 1 ) => resolve() + resolve.apply( undefined, [ value ].slice( noValue ) ); + } + + // For Promises/A+, convert exceptions into rejections + // Since jQuery.when doesn't unwrap thenables, we can skip the extra checks appearing in + // Deferred#then to conditionally suppress rejection. + } catch ( value ) { + + // Support: Android 4.0 only + // Strict mode functions invoked without .call/.apply get global-object context + reject.apply( undefined, [ value ] ); + } +} + +jQuery.extend( { + + Deferred: function( func ) { + var tuples = [ + + // action, add listener, callbacks, + // ... .then handlers, argument index, [final state] + [ "notify", "progress", jQuery.Callbacks( "memory" ), + jQuery.Callbacks( "memory" ), 2 ], + [ "resolve", "done", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 0, "resolved" ], + [ "reject", "fail", jQuery.Callbacks( "once memory" ), + jQuery.Callbacks( "once memory" ), 1, "rejected" ] + ], + state = "pending", + promise = { + state: function() { + return state; + }, + always: function() { + deferred.done( arguments ).fail( arguments ); + return this; + }, + "catch": function( fn ) { + return promise.then( null, fn ); + }, + + // Keep pipe for back-compat + pipe: function( /* fnDone, fnFail, fnProgress */ ) { + var fns = arguments; + + return jQuery.Deferred( function( newDefer ) { + jQuery.each( tuples, function( _i, tuple ) { + + // Map tuples (progress, done, fail) to arguments (done, fail, progress) + var fn = isFunction( fns[ tuple[ 4 ] ] ) && fns[ tuple[ 4 ] ]; + + // deferred.progress(function() { bind to newDefer or newDefer.notify }) + // deferred.done(function() { bind to newDefer or newDefer.resolve }) + // deferred.fail(function() { bind to newDefer or newDefer.reject }) + deferred[ tuple[ 1 ] ]( function() { + var returned = fn && fn.apply( this, arguments ); + if ( returned && isFunction( returned.promise ) ) { + returned.promise() + .progress( newDefer.notify ) + .done( newDefer.resolve ) + .fail( newDefer.reject ); + } else { + newDefer[ tuple[ 0 ] + "With" ]( + this, + fn ? [ returned ] : arguments + ); + } + } ); + } ); + fns = null; + } ).promise(); + }, + then: function( onFulfilled, onRejected, onProgress ) { + var maxDepth = 0; + function resolve( depth, deferred, handler, special ) { + return function() { + var that = this, + args = arguments, + mightThrow = function() { + var returned, then; + + // Support: Promises/A+ section 2.3.3.3.3 + // https://promisesaplus.com/#point-59 + // Ignore double-resolution attempts + if ( depth < maxDepth ) { + return; + } + + returned = handler.apply( that, args ); + + // Support: Promises/A+ section 2.3.1 + // https://promisesaplus.com/#point-48 + if ( returned === deferred.promise() ) { + throw new TypeError( "Thenable self-resolution" ); + } + + // Support: Promises/A+ sections 2.3.3.1, 3.5 + // https://promisesaplus.com/#point-54 + // https://promisesaplus.com/#point-75 + // Retrieve `then` only once + then = returned && + + // Support: Promises/A+ section 2.3.4 + // https://promisesaplus.com/#point-64 + // Only check objects and functions for thenability + ( typeof returned === "object" || + typeof returned === "function" ) && + returned.then; + + // Handle a returned thenable + if ( isFunction( then ) ) { + + // Special processors (notify) just wait for resolution + if ( special ) { + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ) + ); + + // Normal processors (resolve) also hook into progress + } else { + + // ...and disregard older resolution values + maxDepth++; + + then.call( + returned, + resolve( maxDepth, deferred, Identity, special ), + resolve( maxDepth, deferred, Thrower, special ), + resolve( maxDepth, deferred, Identity, + deferred.notifyWith ) + ); + } + + // Handle all other returned values + } else { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Identity ) { + that = undefined; + args = [ returned ]; + } + + // Process the value(s) + // Default process is resolve + ( special || deferred.resolveWith )( that, args ); + } + }, + + // Only normal processors (resolve) catch and reject exceptions + process = special ? + mightThrow : + function() { + try { + mightThrow(); + } catch ( e ) { + + if ( jQuery.Deferred.exceptionHook ) { + jQuery.Deferred.exceptionHook( e, + process.stackTrace ); + } + + // Support: Promises/A+ section 2.3.3.3.4.1 + // https://promisesaplus.com/#point-61 + // Ignore post-resolution exceptions + if ( depth + 1 >= maxDepth ) { + + // Only substitute handlers pass on context + // and multiple values (non-spec behavior) + if ( handler !== Thrower ) { + that = undefined; + args = [ e ]; + } + + deferred.rejectWith( that, args ); + } + } + }; + + // Support: Promises/A+ section 2.3.3.3.1 + // https://promisesaplus.com/#point-57 + // Re-resolve promises immediately to dodge false rejection from + // subsequent errors + if ( depth ) { + process(); + } else { + + // Call an optional hook to record the stack, in case of exception + // since it's otherwise lost when execution goes async + if ( jQuery.Deferred.getStackHook ) { + process.stackTrace = jQuery.Deferred.getStackHook(); + } + window.setTimeout( process ); + } + }; + } + + return jQuery.Deferred( function( newDefer ) { + + // progress_handlers.add( ... ) + tuples[ 0 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onProgress ) ? + onProgress : + Identity, + newDefer.notifyWith + ) + ); + + // fulfilled_handlers.add( ... ) + tuples[ 1 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onFulfilled ) ? + onFulfilled : + Identity + ) + ); + + // rejected_handlers.add( ... ) + tuples[ 2 ][ 3 ].add( + resolve( + 0, + newDefer, + isFunction( onRejected ) ? + onRejected : + Thrower + ) + ); + } ).promise(); + }, + + // Get a promise for this deferred + // If obj is provided, the promise aspect is added to the object + promise: function( obj ) { + return obj != null ? jQuery.extend( obj, promise ) : promise; + } + }, + deferred = {}; + + // Add list-specific methods + jQuery.each( tuples, function( i, tuple ) { + var list = tuple[ 2 ], + stateString = tuple[ 5 ]; + + // promise.progress = list.add + // promise.done = list.add + // promise.fail = list.add + promise[ tuple[ 1 ] ] = list.add; + + // Handle state + if ( stateString ) { + list.add( + function() { + + // state = "resolved" (i.e., fulfilled) + // state = "rejected" + state = stateString; + }, + + // rejected_callbacks.disable + // fulfilled_callbacks.disable + tuples[ 3 - i ][ 2 ].disable, + + // rejected_handlers.disable + // fulfilled_handlers.disable + tuples[ 3 - i ][ 3 ].disable, + + // progress_callbacks.lock + tuples[ 0 ][ 2 ].lock, + + // progress_handlers.lock + tuples[ 0 ][ 3 ].lock + ); + } + + // progress_handlers.fire + // fulfilled_handlers.fire + // rejected_handlers.fire + list.add( tuple[ 3 ].fire ); + + // deferred.notify = function() { deferred.notifyWith(...) } + // deferred.resolve = function() { deferred.resolveWith(...) } + // deferred.reject = function() { deferred.rejectWith(...) } + deferred[ tuple[ 0 ] ] = function() { + deferred[ tuple[ 0 ] + "With" ]( this === deferred ? undefined : this, arguments ); + return this; + }; + + // deferred.notifyWith = list.fireWith + // deferred.resolveWith = list.fireWith + // deferred.rejectWith = list.fireWith + deferred[ tuple[ 0 ] + "With" ] = list.fireWith; + } ); + + // Make the deferred a promise + promise.promise( deferred ); + + // Call given func if any + if ( func ) { + func.call( deferred, deferred ); + } + + // All done! + return deferred; + }, + + // Deferred helper + when: function( singleValue ) { + var + + // count of uncompleted subordinates + remaining = arguments.length, + + // count of unprocessed arguments + i = remaining, + + // subordinate fulfillment data + resolveContexts = Array( i ), + resolveValues = slice.call( arguments ), + + // the master Deferred + master = jQuery.Deferred(), + + // subordinate callback factory + updateFunc = function( i ) { + return function( value ) { + resolveContexts[ i ] = this; + resolveValues[ i ] = arguments.length > 1 ? slice.call( arguments ) : value; + if ( !( --remaining ) ) { + master.resolveWith( resolveContexts, resolveValues ); + } + }; + }; + + // Single- and empty arguments are adopted like Promise.resolve + if ( remaining <= 1 ) { + adoptValue( singleValue, master.done( updateFunc( i ) ).resolve, master.reject, + !remaining ); + + // Use .then() to unwrap secondary thenables (cf. gh-3000) + if ( master.state() === "pending" || + isFunction( resolveValues[ i ] && resolveValues[ i ].then ) ) { + + return master.then(); + } + } + + // Multiple arguments are aggregated like Promise.all array elements + while ( i-- ) { + adoptValue( resolveValues[ i ], updateFunc( i ), master.reject ); + } + + return master.promise(); + } +} ); + + +// These usually indicate a programmer mistake during development, +// warn about them ASAP rather than swallowing them by default. +var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/; + +jQuery.Deferred.exceptionHook = function( error, stack ) { + + // Support: IE 8 - 9 only + // Console exists when dev tools are open, which can happen at any time + if ( window.console && window.console.warn && error && rerrorNames.test( error.name ) ) { + window.console.warn( "jQuery.Deferred exception: " + error.message, error.stack, stack ); + } +}; + + + + +jQuery.readyException = function( error ) { + window.setTimeout( function() { + throw error; + } ); +}; + + + + +// The deferred used on DOM ready +var readyList = jQuery.Deferred(); + +jQuery.fn.ready = function( fn ) { + + readyList + .then( fn ) + + // Wrap jQuery.readyException in a function so that the lookup + // happens at the time of error handling instead of callback + // registration. + .catch( function( error ) { + jQuery.readyException( error ); + } ); + + return this; +}; + +jQuery.extend( { + + // Is the DOM ready to be used? Set to true once it occurs. + isReady: false, + + // A counter to track how many items to wait for before + // the ready event fires. See #6781 + readyWait: 1, + + // Handle when the DOM is ready + ready: function( wait ) { + + // Abort if there are pending holds or we're already ready + if ( wait === true ? --jQuery.readyWait : jQuery.isReady ) { + return; + } + + // Remember that the DOM is ready + jQuery.isReady = true; + + // If a normal DOM Ready event fired, decrement, and wait if need be + if ( wait !== true && --jQuery.readyWait > 0 ) { + return; + } + + // If there are functions bound, to execute + readyList.resolveWith( document, [ jQuery ] ); + } +} ); + +jQuery.ready.then = readyList.then; + +// The ready event handler and self cleanup method +function completed() { + document.removeEventListener( "DOMContentLoaded", completed ); + window.removeEventListener( "load", completed ); + jQuery.ready(); +} + +// Catch cases where $(document).ready() is called +// after the browser event has already occurred. +// Support: IE <=9 - 10 only +// Older IE sometimes signals "interactive" too soon +if ( document.readyState === "complete" || + ( document.readyState !== "loading" && !document.documentElement.doScroll ) ) { + + // Handle it asynchronously to allow scripts the opportunity to delay ready + window.setTimeout( jQuery.ready ); + +} else { + + // Use the handy event callback + document.addEventListener( "DOMContentLoaded", completed ); + + // A fallback to window.onload, that will always work + window.addEventListener( "load", completed ); +} + + + + +// Multifunctional method to get and set values of a collection +// The value/s can optionally be executed if it's a function +var access = function( elems, fn, key, value, chainable, emptyGet, raw ) { + var i = 0, + len = elems.length, + bulk = key == null; + + // Sets many values + if ( toType( key ) === "object" ) { + chainable = true; + for ( i in key ) { + access( elems, fn, i, key[ i ], true, emptyGet, raw ); + } + + // Sets one value + } else if ( value !== undefined ) { + chainable = true; + + if ( !isFunction( value ) ) { + raw = true; + } + + if ( bulk ) { + + // Bulk operations run against the entire set + if ( raw ) { + fn.call( elems, value ); + fn = null; + + // ...except when executing function values + } else { + bulk = fn; + fn = function( elem, _key, value ) { + return bulk.call( jQuery( elem ), value ); + }; + } + } + + if ( fn ) { + for ( ; i < len; i++ ) { + fn( + elems[ i ], key, raw ? + value : + value.call( elems[ i ], i, fn( elems[ i ], key ) ) + ); + } + } + } + + if ( chainable ) { + return elems; + } + + // Gets + if ( bulk ) { + return fn.call( elems ); + } + + return len ? fn( elems[ 0 ], key ) : emptyGet; +}; + + +// Matches dashed string for camelizing +var rmsPrefix = /^-ms-/, + rdashAlpha = /-([a-z])/g; + +// Used by camelCase as callback to replace() +function fcamelCase( _all, letter ) { + return letter.toUpperCase(); +} + +// Convert dashed to camelCase; used by the css and data modules +// Support: IE <=9 - 11, Edge 12 - 15 +// Microsoft forgot to hump their vendor prefix (#9572) +function camelCase( string ) { + return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); +} +var acceptData = function( owner ) { + + // Accepts only: + // - Node + // - Node.ELEMENT_NODE + // - Node.DOCUMENT_NODE + // - Object + // - Any + return owner.nodeType === 1 || owner.nodeType === 9 || !( +owner.nodeType ); +}; + + + + +function Data() { + this.expando = jQuery.expando + Data.uid++; +} + +Data.uid = 1; + +Data.prototype = { + + cache: function( owner ) { + + // Check if the owner object already has a cache + var value = owner[ this.expando ]; + + // If not, create one + if ( !value ) { + value = {}; + + // We can accept data for non-element nodes in modern browsers, + // but we should not, see #8335. + // Always return an empty object. + if ( acceptData( owner ) ) { + + // If it is a node unlikely to be stringify-ed or looped over + // use plain assignment + if ( owner.nodeType ) { + owner[ this.expando ] = value; + + // Otherwise secure it in a non-enumerable property + // configurable must be true to allow the property to be + // deleted when data is removed + } else { + Object.defineProperty( owner, this.expando, { + value: value, + configurable: true + } ); + } + } + } + + return value; + }, + set: function( owner, data, value ) { + var prop, + cache = this.cache( owner ); + + // Handle: [ owner, key, value ] args + // Always use camelCase key (gh-2257) + if ( typeof data === "string" ) { + cache[ camelCase( data ) ] = value; + + // Handle: [ owner, { properties } ] args + } else { + + // Copy the properties one-by-one to the cache object + for ( prop in data ) { + cache[ camelCase( prop ) ] = data[ prop ]; + } + } + return cache; + }, + get: function( owner, key ) { + return key === undefined ? + this.cache( owner ) : + + // Always use camelCase key (gh-2257) + owner[ this.expando ] && owner[ this.expando ][ camelCase( key ) ]; + }, + access: function( owner, key, value ) { + + // In cases where either: + // + // 1. No key was specified + // 2. A string key was specified, but no value provided + // + // Take the "read" path and allow the get method to determine + // which value to return, respectively either: + // + // 1. The entire cache object + // 2. The data stored at the key + // + if ( key === undefined || + ( ( key && typeof key === "string" ) && value === undefined ) ) { + + return this.get( owner, key ); + } + + // When the key is not a string, or both a key and value + // are specified, set or extend (existing objects) with either: + // + // 1. An object of properties + // 2. A key and value + // + this.set( owner, key, value ); + + // Since the "set" path can have two possible entry points + // return the expected data based on which path was taken[*] + return value !== undefined ? value : key; + }, + remove: function( owner, key ) { + var i, + cache = owner[ this.expando ]; + + if ( cache === undefined ) { + return; + } + + if ( key !== undefined ) { + + // Support array or space separated string of keys + if ( Array.isArray( key ) ) { + + // If key is an array of keys... + // We always set camelCase keys, so remove that. + key = key.map( camelCase ); + } else { + key = camelCase( key ); + + // If a key with the spaces exists, use it. + // Otherwise, create an array by matching non-whitespace + key = key in cache ? + [ key ] : + ( key.match( rnothtmlwhite ) || [] ); + } + + i = key.length; + + while ( i-- ) { + delete cache[ key[ i ] ]; + } + } + + // Remove the expando if there's no more data + if ( key === undefined || jQuery.isEmptyObject( cache ) ) { + + // Support: Chrome <=35 - 45 + // Webkit & Blink performance suffers when deleting properties + // from DOM nodes, so set to undefined instead + // https://bugs.chromium.org/p/chromium/issues/detail?id=378607 (bug restricted) + if ( owner.nodeType ) { + owner[ this.expando ] = undefined; + } else { + delete owner[ this.expando ]; + } + } + }, + hasData: function( owner ) { + var cache = owner[ this.expando ]; + return cache !== undefined && !jQuery.isEmptyObject( cache ); + } +}; +var dataPriv = new Data(); + +var dataUser = new Data(); + + + +// Implementation Summary +// +// 1. Enforce API surface and semantic compatibility with 1.9.x branch +// 2. Improve the module's maintainability by reducing the storage +// paths to a single mechanism. +// 3. Use the same single mechanism to support "private" and "user" data. +// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) +// 5. Avoid exposing implementation details on user objects (eg. expando properties) +// 6. Provide a clear path for implementation upgrade to WeakMap in 2014 + +var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/, + rmultiDash = /[A-Z]/g; + +function getData( data ) { + if ( data === "true" ) { + return true; + } + + if ( data === "false" ) { + return false; + } + + if ( data === "null" ) { + return null; + } + + // Only convert to a number if it doesn't change the string + if ( data === +data + "" ) { + return +data; + } + + if ( rbrace.test( data ) ) { + return JSON.parse( data ); + } + + return data; +} + +function dataAttr( elem, key, data ) { + var name; + + // If nothing was found internally, try to fetch any + // data from the HTML5 data-* attribute + if ( data === undefined && elem.nodeType === 1 ) { + name = "data-" + key.replace( rmultiDash, "-$&" ).toLowerCase(); + data = elem.getAttribute( name ); + + if ( typeof data === "string" ) { + try { + data = getData( data ); + } catch ( e ) {} + + // Make sure we set the data so it isn't changed later + dataUser.set( elem, key, data ); + } else { + data = undefined; + } + } + return data; +} + +jQuery.extend( { + hasData: function( elem ) { + return dataUser.hasData( elem ) || dataPriv.hasData( elem ); + }, + + data: function( elem, name, data ) { + return dataUser.access( elem, name, data ); + }, + + removeData: function( elem, name ) { + dataUser.remove( elem, name ); + }, + + // TODO: Now that all calls to _data and _removeData have been replaced + // with direct calls to dataPriv methods, these can be deprecated. + _data: function( elem, name, data ) { + return dataPriv.access( elem, name, data ); + }, + + _removeData: function( elem, name ) { + dataPriv.remove( elem, name ); + } +} ); + +jQuery.fn.extend( { + data: function( key, value ) { + var i, name, data, + elem = this[ 0 ], + attrs = elem && elem.attributes; + + // Gets all values + if ( key === undefined ) { + if ( this.length ) { + data = dataUser.get( elem ); + + if ( elem.nodeType === 1 && !dataPriv.get( elem, "hasDataAttrs" ) ) { + i = attrs.length; + while ( i-- ) { + + // Support: IE 11 only + // The attrs elements can be null (#14894) + if ( attrs[ i ] ) { + name = attrs[ i ].name; + if ( name.indexOf( "data-" ) === 0 ) { + name = camelCase( name.slice( 5 ) ); + dataAttr( elem, name, data[ name ] ); + } + } + } + dataPriv.set( elem, "hasDataAttrs", true ); + } + } + + return data; + } + + // Sets multiple values + if ( typeof key === "object" ) { + return this.each( function() { + dataUser.set( this, key ); + } ); + } + + return access( this, function( value ) { + var data; + + // The calling jQuery object (element matches) is not empty + // (and therefore has an element appears at this[ 0 ]) and the + // `value` parameter was not undefined. An empty jQuery object + // will result in `undefined` for elem = this[ 0 ] which will + // throw an exception if an attempt to read a data cache is made. + if ( elem && value === undefined ) { + + // Attempt to get data from the cache + // The key will always be camelCased in Data + data = dataUser.get( elem, key ); + if ( data !== undefined ) { + return data; + } + + // Attempt to "discover" the data in + // HTML5 custom data-* attrs + data = dataAttr( elem, key ); + if ( data !== undefined ) { + return data; + } + + // We tried really hard, but the data doesn't exist. + return; + } + + // Set the data... + this.each( function() { + + // We always store the camelCased key + dataUser.set( this, key, value ); + } ); + }, null, value, arguments.length > 1, null, true ); + }, + + removeData: function( key ) { + return this.each( function() { + dataUser.remove( this, key ); + } ); + } +} ); + + +jQuery.extend( { + queue: function( elem, type, data ) { + var queue; + + if ( elem ) { + type = ( type || "fx" ) + "queue"; + queue = dataPriv.get( elem, type ); + + // Speed up dequeue by getting out quickly if this is just a lookup + if ( data ) { + if ( !queue || Array.isArray( data ) ) { + queue = dataPriv.access( elem, type, jQuery.makeArray( data ) ); + } else { + queue.push( data ); + } + } + return queue || []; + } + }, + + dequeue: function( elem, type ) { + type = type || "fx"; + + var queue = jQuery.queue( elem, type ), + startLength = queue.length, + fn = queue.shift(), + hooks = jQuery._queueHooks( elem, type ), + next = function() { + jQuery.dequeue( elem, type ); + }; + + // If the fx queue is dequeued, always remove the progress sentinel + if ( fn === "inprogress" ) { + fn = queue.shift(); + startLength--; + } + + if ( fn ) { + + // Add a progress sentinel to prevent the fx queue from being + // automatically dequeued + if ( type === "fx" ) { + queue.unshift( "inprogress" ); + } + + // Clear up the last queue stop function + delete hooks.stop; + fn.call( elem, next, hooks ); + } + + if ( !startLength && hooks ) { + hooks.empty.fire(); + } + }, + + // Not public - generate a queueHooks object, or return the current one + _queueHooks: function( elem, type ) { + var key = type + "queueHooks"; + return dataPriv.get( elem, key ) || dataPriv.access( elem, key, { + empty: jQuery.Callbacks( "once memory" ).add( function() { + dataPriv.remove( elem, [ type + "queue", key ] ); + } ) + } ); + } +} ); + +jQuery.fn.extend( { + queue: function( type, data ) { + var setter = 2; + + if ( typeof type !== "string" ) { + data = type; + type = "fx"; + setter--; + } + + if ( arguments.length < setter ) { + return jQuery.queue( this[ 0 ], type ); + } + + return data === undefined ? + this : + this.each( function() { + var queue = jQuery.queue( this, type, data ); + + // Ensure a hooks for this queue + jQuery._queueHooks( this, type ); + + if ( type === "fx" && queue[ 0 ] !== "inprogress" ) { + jQuery.dequeue( this, type ); + } + } ); + }, + dequeue: function( type ) { + return this.each( function() { + jQuery.dequeue( this, type ); + } ); + }, + clearQueue: function( type ) { + return this.queue( type || "fx", [] ); + }, + + // Get a promise resolved when queues of a certain type + // are emptied (fx is the type by default) + promise: function( type, obj ) { + var tmp, + count = 1, + defer = jQuery.Deferred(), + elements = this, + i = this.length, + resolve = function() { + if ( !( --count ) ) { + defer.resolveWith( elements, [ elements ] ); + } + }; + + if ( typeof type !== "string" ) { + obj = type; + type = undefined; + } + type = type || "fx"; + + while ( i-- ) { + tmp = dataPriv.get( elements[ i ], type + "queueHooks" ); + if ( tmp && tmp.empty ) { + count++; + tmp.empty.add( resolve ); + } + } + resolve(); + return defer.promise( obj ); + } +} ); +var pnum = ( /[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/ ).source; + +var rcssNum = new RegExp( "^(?:([+-])=|)(" + pnum + ")([a-z%]*)$", "i" ); + + +var cssExpand = [ "Top", "Right", "Bottom", "Left" ]; + +var documentElement = document.documentElement; + + + + var isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ); + }, + composed = { composed: true }; + + // Support: IE 9 - 11+, Edge 12 - 18+, iOS 10.0 - 10.2 only + // Check attachment across shadow DOM boundaries when possible (gh-3504) + // Support: iOS 10.0-10.2 only + // Early iOS 10 versions support `attachShadow` but not `getRootNode`, + // leading to errors. We need to check for `getRootNode`. + if ( documentElement.getRootNode ) { + isAttached = function( elem ) { + return jQuery.contains( elem.ownerDocument, elem ) || + elem.getRootNode( composed ) === elem.ownerDocument; + }; + } +var isHiddenWithinTree = function( elem, el ) { + + // isHiddenWithinTree might be called from jQuery#filter function; + // in that case, element will be second argument + elem = el || elem; + + // Inline style trumps all + return elem.style.display === "none" || + elem.style.display === "" && + + // Otherwise, check computed style + // Support: Firefox <=43 - 45 + // Disconnected elements can have computed display: none, so first confirm that elem is + // in the document. + isAttached( elem ) && + + jQuery.css( elem, "display" ) === "none"; + }; + + + +function adjustCSS( elem, prop, valueParts, tween ) { + var adjusted, scale, + maxIterations = 20, + currentValue = tween ? + function() { + return tween.cur(); + } : + function() { + return jQuery.css( elem, prop, "" ); + }, + initial = currentValue(), + unit = valueParts && valueParts[ 3 ] || ( jQuery.cssNumber[ prop ] ? "" : "px" ), + + // Starting value computation is required for potential unit mismatches + initialInUnit = elem.nodeType && + ( jQuery.cssNumber[ prop ] || unit !== "px" && +initial ) && + rcssNum.exec( jQuery.css( elem, prop ) ); + + if ( initialInUnit && initialInUnit[ 3 ] !== unit ) { + + // Support: Firefox <=54 + // Halve the iteration target value to prevent interference from CSS upper bounds (gh-2144) + initial = initial / 2; + + // Trust units reported by jQuery.css + unit = unit || initialInUnit[ 3 ]; + + // Iteratively approximate from a nonzero starting point + initialInUnit = +initial || 1; + + while ( maxIterations-- ) { + + // Evaluate and update our best guess (doubling guesses that zero out). + // Finish if the scale equals or crosses 1 (making the old*new product non-positive). + jQuery.style( elem, prop, initialInUnit + unit ); + if ( ( 1 - scale ) * ( 1 - ( scale = currentValue() / initial || 0.5 ) ) <= 0 ) { + maxIterations = 0; + } + initialInUnit = initialInUnit / scale; + + } + + initialInUnit = initialInUnit * 2; + jQuery.style( elem, prop, initialInUnit + unit ); + + // Make sure we update the tween properties later on + valueParts = valueParts || []; + } + + if ( valueParts ) { + initialInUnit = +initialInUnit || +initial || 0; + + // Apply relative offset (+=/-=) if specified + adjusted = valueParts[ 1 ] ? + initialInUnit + ( valueParts[ 1 ] + 1 ) * valueParts[ 2 ] : + +valueParts[ 2 ]; + if ( tween ) { + tween.unit = unit; + tween.start = initialInUnit; + tween.end = adjusted; + } + } + return adjusted; +} + + +var defaultDisplayMap = {}; + +function getDefaultDisplay( elem ) { + var temp, + doc = elem.ownerDocument, + nodeName = elem.nodeName, + display = defaultDisplayMap[ nodeName ]; + + if ( display ) { + return display; + } + + temp = doc.body.appendChild( doc.createElement( nodeName ) ); + display = jQuery.css( temp, "display" ); + + temp.parentNode.removeChild( temp ); + + if ( display === "none" ) { + display = "block"; + } + defaultDisplayMap[ nodeName ] = display; + + return display; +} + +function showHide( elements, show ) { + var display, elem, + values = [], + index = 0, + length = elements.length; + + // Determine new display value for elements that need to change + for ( ; index < length; index++ ) { + elem = elements[ index ]; + if ( !elem.style ) { + continue; + } + + display = elem.style.display; + if ( show ) { + + // Since we force visibility upon cascade-hidden elements, an immediate (and slow) + // check is required in this first loop unless we have a nonempty display value (either + // inline or about-to-be-restored) + if ( display === "none" ) { + values[ index ] = dataPriv.get( elem, "display" ) || null; + if ( !values[ index ] ) { + elem.style.display = ""; + } + } + if ( elem.style.display === "" && isHiddenWithinTree( elem ) ) { + values[ index ] = getDefaultDisplay( elem ); + } + } else { + if ( display !== "none" ) { + values[ index ] = "none"; + + // Remember what we're overwriting + dataPriv.set( elem, "display", display ); + } + } + } + + // Set the display of the elements in a second loop to avoid constant reflow + for ( index = 0; index < length; index++ ) { + if ( values[ index ] != null ) { + elements[ index ].style.display = values[ index ]; + } + } + + return elements; +} + +jQuery.fn.extend( { + show: function() { + return showHide( this, true ); + }, + hide: function() { + return showHide( this ); + }, + toggle: function( state ) { + if ( typeof state === "boolean" ) { + return state ? this.show() : this.hide(); + } + + return this.each( function() { + if ( isHiddenWithinTree( this ) ) { + jQuery( this ).show(); + } else { + jQuery( this ).hide(); + } + } ); + } +} ); +var rcheckableType = ( /^(?:checkbox|radio)$/i ); + +var rtagName = ( /<([a-z][^\/\0>\x20\t\r\n\f]*)/i ); + +var rscriptType = ( /^$|^module$|\/(?:java|ecma)script/i ); + + + +( function() { + var fragment = document.createDocumentFragment(), + div = fragment.appendChild( document.createElement( "div" ) ), + input = document.createElement( "input" ); + + // Support: Android 4.0 - 4.3 only + // Check state lost if the name is set (#11217) + // Support: Windows Web Apps (WWA) + // `name` and `type` must use .setAttribute for WWA (#14901) + input.setAttribute( "type", "radio" ); + input.setAttribute( "checked", "checked" ); + input.setAttribute( "name", "t" ); + + div.appendChild( input ); + + // Support: Android <=4.1 only + // Older WebKit doesn't clone checked state correctly in fragments + support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked; + + // Support: IE <=11 only + // Make sure textarea (and checkbox) defaultValue is properly cloned + div.innerHTML = "<textarea>x</textarea>"; + support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue; + + // Support: IE <=9 only + // IE <=9 replaces <option> tags with their contents when inserted outside of + // the select element. + div.innerHTML = "<option></option>"; + support.option = !!div.lastChild; +} )(); + + +// We have to close these tags to support XHTML (#13200) +var wrapMap = { + + // XHTML parsers do not magically insert elements in the + // same way that tag soup parsers do. So we cannot shorten + // this by omitting <tbody> or other required elements. + thead: [ 1, "<table>", "</table>" ], + col: [ 2, "<table><colgroup>", "</colgroup></table>" ], + tr: [ 2, "<table><tbody>", "</tbody></table>" ], + td: [ 3, "<table><tbody><tr>", "</tr></tbody></table>" ], + + _default: [ 0, "", "" ] +}; + +wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead; +wrapMap.th = wrapMap.td; + +// Support: IE <=9 only +if ( !support.option ) { + wrapMap.optgroup = wrapMap.option = [ 1, "<select multiple='multiple'>", "</select>" ]; +} + + +function getAll( context, tag ) { + + // Support: IE <=9 - 11 only + // Use typeof to avoid zero-argument method invocation on host objects (#15151) + var ret; + + if ( typeof context.getElementsByTagName !== "undefined" ) { + ret = context.getElementsByTagName( tag || "*" ); + + } else if ( typeof context.querySelectorAll !== "undefined" ) { + ret = context.querySelectorAll( tag || "*" ); + + } else { + ret = []; + } + + if ( tag === undefined || tag && nodeName( context, tag ) ) { + return jQuery.merge( [ context ], ret ); + } + + return ret; +} + + +// Mark scripts as having already been evaluated +function setGlobalEval( elems, refElements ) { + var i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + dataPriv.set( + elems[ i ], + "globalEval", + !refElements || dataPriv.get( refElements[ i ], "globalEval" ) + ); + } +} + + +var rhtml = /<|&#?\w+;/; + +function buildFragment( elems, context, scripts, selection, ignored ) { + var elem, tmp, tag, wrap, attached, j, + fragment = context.createDocumentFragment(), + nodes = [], + i = 0, + l = elems.length; + + for ( ; i < l; i++ ) { + elem = elems[ i ]; + + if ( elem || elem === 0 ) { + + // Add nodes directly + if ( toType( elem ) === "object" ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem ); + + // Convert non-html into a text node + } else if ( !rhtml.test( elem ) ) { + nodes.push( context.createTextNode( elem ) ); + + // Convert html into DOM nodes + } else { + tmp = tmp || fragment.appendChild( context.createElement( "div" ) ); + + // Deserialize a standard representation + tag = ( rtagName.exec( elem ) || [ "", "" ] )[ 1 ].toLowerCase(); + wrap = wrapMap[ tag ] || wrapMap._default; + tmp.innerHTML = wrap[ 1 ] + jQuery.htmlPrefilter( elem ) + wrap[ 2 ]; + + // Descend through wrappers to the right content + j = wrap[ 0 ]; + while ( j-- ) { + tmp = tmp.lastChild; + } + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( nodes, tmp.childNodes ); + + // Remember the top-level container + tmp = fragment.firstChild; + + // Ensure the created nodes are orphaned (#12392) + tmp.textContent = ""; + } + } + } + + // Remove wrapper from fragment + fragment.textContent = ""; + + i = 0; + while ( ( elem = nodes[ i++ ] ) ) { + + // Skip elements already in the context collection (trac-4087) + if ( selection && jQuery.inArray( elem, selection ) > -1 ) { + if ( ignored ) { + ignored.push( elem ); + } + continue; + } + + attached = isAttached( elem ); + + // Append to fragment + tmp = getAll( fragment.appendChild( elem ), "script" ); + + // Preserve script evaluation history + if ( attached ) { + setGlobalEval( tmp ); + } + + // Capture executables + if ( scripts ) { + j = 0; + while ( ( elem = tmp[ j++ ] ) ) { + if ( rscriptType.test( elem.type || "" ) ) { + scripts.push( elem ); + } + } + } + } + + return fragment; +} + + +var + rkeyEvent = /^key/, + rmouseEvent = /^(?:mouse|pointer|contextmenu|drag|drop)|click/, + rtypenamespace = /^([^.]*)(?:\.(.+)|)/; + +function returnTrue() { + return true; +} + +function returnFalse() { + return false; +} + +// Support: IE <=9 - 11+ +// focus() and blur() are asynchronous, except when they are no-op. +// So expect focus to be synchronous when the element is already active, +// and blur to be synchronous when the element is not already active. +// (focus and blur are always synchronous in other supported browsers, +// this just defines when we can count on it). +function expectSync( elem, type ) { + return ( elem === safeActiveElement() ) === ( type === "focus" ); +} + +// Support: IE <=9 only +// Accessing document.activeElement can throw unexpectedly +// https://bugs.jquery.com/ticket/13393 +function safeActiveElement() { + try { + return document.activeElement; + } catch ( err ) { } +} + +function on( elem, types, selector, data, fn, one ) { + var origFn, type; + + // Types can be a map of types/handlers + if ( typeof types === "object" ) { + + // ( types-Object, selector, data ) + if ( typeof selector !== "string" ) { + + // ( types-Object, data ) + data = data || selector; + selector = undefined; + } + for ( type in types ) { + on( elem, type, selector, data, types[ type ], one ); + } + return elem; + } + + if ( data == null && fn == null ) { + + // ( types, fn ) + fn = selector; + data = selector = undefined; + } else if ( fn == null ) { + if ( typeof selector === "string" ) { + + // ( types, selector, fn ) + fn = data; + data = undefined; + } else { + + // ( types, data, fn ) + fn = data; + data = selector; + selector = undefined; + } + } + if ( fn === false ) { + fn = returnFalse; + } else if ( !fn ) { + return elem; + } + + if ( one === 1 ) { + origFn = fn; + fn = function( event ) { + + // Can use an empty set, since event contains the info + jQuery().off( event ); + return origFn.apply( this, arguments ); + }; + + // Use same guid so caller can remove using origFn + fn.guid = origFn.guid || ( origFn.guid = jQuery.guid++ ); + } + return elem.each( function() { + jQuery.event.add( this, types, fn, data, selector ); + } ); +} + +/* + * Helper functions for managing events -- not part of the public interface. + * Props to Dean Edwards' addEvent library for many of the ideas. + */ +jQuery.event = { + + global: {}, + + add: function( elem, types, handler, data, selector ) { + + var handleObjIn, eventHandle, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.get( elem ); + + // Only attach events to objects that accept data + if ( !acceptData( elem ) ) { + return; + } + + // Caller can pass in an object of custom data in lieu of the handler + if ( handler.handler ) { + handleObjIn = handler; + handler = handleObjIn.handler; + selector = handleObjIn.selector; + } + + // Ensure that invalid selectors throw exceptions at attach time + // Evaluate against documentElement in case elem is a non-element node (e.g., document) + if ( selector ) { + jQuery.find.matchesSelector( documentElement, selector ); + } + + // Make sure that the handler has a unique ID, used to find/remove it later + if ( !handler.guid ) { + handler.guid = jQuery.guid++; + } + + // Init the element's event structure and main handler, if this is the first + if ( !( events = elemData.events ) ) { + events = elemData.events = Object.create( null ); + } + if ( !( eventHandle = elemData.handle ) ) { + eventHandle = elemData.handle = function( e ) { + + // Discard the second event of a jQuery.event.trigger() and + // when an event is called after a page has unloaded + return typeof jQuery !== "undefined" && jQuery.event.triggered !== e.type ? + jQuery.event.dispatch.apply( elem, arguments ) : undefined; + }; + } + + // Handle multiple events separated by a space + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // There *must* be a type, no attaching namespace-only handlers + if ( !type ) { + continue; + } + + // If event changes its type, use the special event handlers for the changed type + special = jQuery.event.special[ type ] || {}; + + // If selector defined, determine special event api type, otherwise given type + type = ( selector ? special.delegateType : special.bindType ) || type; + + // Update special based on newly reset type + special = jQuery.event.special[ type ] || {}; + + // handleObj is passed to all event handlers + handleObj = jQuery.extend( { + type: type, + origType: origType, + data: data, + handler: handler, + guid: handler.guid, + selector: selector, + needsContext: selector && jQuery.expr.match.needsContext.test( selector ), + namespace: namespaces.join( "." ) + }, handleObjIn ); + + // Init the event handler queue if we're the first + if ( !( handlers = events[ type ] ) ) { + handlers = events[ type ] = []; + handlers.delegateCount = 0; + + // Only use addEventListener if the special events handler returns false + if ( !special.setup || + special.setup.call( elem, data, namespaces, eventHandle ) === false ) { + + if ( elem.addEventListener ) { + elem.addEventListener( type, eventHandle ); + } + } + } + + if ( special.add ) { + special.add.call( elem, handleObj ); + + if ( !handleObj.handler.guid ) { + handleObj.handler.guid = handler.guid; + } + } + + // Add to the element's handler list, delegates in front + if ( selector ) { + handlers.splice( handlers.delegateCount++, 0, handleObj ); + } else { + handlers.push( handleObj ); + } + + // Keep track of which events have ever been used, for event optimization + jQuery.event.global[ type ] = true; + } + + }, + + // Detach an event or set of events from an element + remove: function( elem, types, handler, selector, mappedTypes ) { + + var j, origCount, tmp, + events, t, handleObj, + special, handlers, type, namespaces, origType, + elemData = dataPriv.hasData( elem ) && dataPriv.get( elem ); + + if ( !elemData || !( events = elemData.events ) ) { + return; + } + + // Once for each type.namespace in types; type may be omitted + types = ( types || "" ).match( rnothtmlwhite ) || [ "" ]; + t = types.length; + while ( t-- ) { + tmp = rtypenamespace.exec( types[ t ] ) || []; + type = origType = tmp[ 1 ]; + namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort(); + + // Unbind all events (on this namespace, if provided) for the element + if ( !type ) { + for ( type in events ) { + jQuery.event.remove( elem, type + types[ t ], handler, selector, true ); + } + continue; + } + + special = jQuery.event.special[ type ] || {}; + type = ( selector ? special.delegateType : special.bindType ) || type; + handlers = events[ type ] || []; + tmp = tmp[ 2 ] && + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ); + + // Remove matching events + origCount = j = handlers.length; + while ( j-- ) { + handleObj = handlers[ j ]; + + if ( ( mappedTypes || origType === handleObj.origType ) && + ( !handler || handler.guid === handleObj.guid ) && + ( !tmp || tmp.test( handleObj.namespace ) ) && + ( !selector || selector === handleObj.selector || + selector === "**" && handleObj.selector ) ) { + handlers.splice( j, 1 ); + + if ( handleObj.selector ) { + handlers.delegateCount--; + } + if ( special.remove ) { + special.remove.call( elem, handleObj ); + } + } + } + + // Remove generic event handler if we removed something and no more handlers exist + // (avoids potential for endless recursion during removal of special event handlers) + if ( origCount && !handlers.length ) { + if ( !special.teardown || + special.teardown.call( elem, namespaces, elemData.handle ) === false ) { + + jQuery.removeEvent( elem, type, elemData.handle ); + } + + delete events[ type ]; + } + } + + // Remove data and the expando if it's no longer used + if ( jQuery.isEmptyObject( events ) ) { + dataPriv.remove( elem, "handle events" ); + } + }, + + dispatch: function( nativeEvent ) { + + var i, j, ret, matched, handleObj, handlerQueue, + args = new Array( arguments.length ), + + // Make a writable jQuery.Event from the native event object + event = jQuery.event.fix( nativeEvent ), + + handlers = ( + dataPriv.get( this, "events" ) || Object.create( null ) + )[ event.type ] || [], + special = jQuery.event.special[ event.type ] || {}; + + // Use the fix-ed jQuery.Event rather than the (read-only) native event + args[ 0 ] = event; + + for ( i = 1; i < arguments.length; i++ ) { + args[ i ] = arguments[ i ]; + } + + event.delegateTarget = this; + + // Call the preDispatch hook for the mapped type, and let it bail if desired + if ( special.preDispatch && special.preDispatch.call( this, event ) === false ) { + return; + } + + // Determine handlers + handlerQueue = jQuery.event.handlers.call( this, event, handlers ); + + // Run delegates first; they may want to stop propagation beneath us + i = 0; + while ( ( matched = handlerQueue[ i++ ] ) && !event.isPropagationStopped() ) { + event.currentTarget = matched.elem; + + j = 0; + while ( ( handleObj = matched.handlers[ j++ ] ) && + !event.isImmediatePropagationStopped() ) { + + // If the event is namespaced, then each handler is only invoked if it is + // specially universal or its namespaces are a superset of the event's. + if ( !event.rnamespace || handleObj.namespace === false || + event.rnamespace.test( handleObj.namespace ) ) { + + event.handleObj = handleObj; + event.data = handleObj.data; + + ret = ( ( jQuery.event.special[ handleObj.origType ] || {} ).handle || + handleObj.handler ).apply( matched.elem, args ); + + if ( ret !== undefined ) { + if ( ( event.result = ret ) === false ) { + event.preventDefault(); + event.stopPropagation(); + } + } + } + } + } + + // Call the postDispatch hook for the mapped type + if ( special.postDispatch ) { + special.postDispatch.call( this, event ); + } + + return event.result; + }, + + handlers: function( event, handlers ) { + var i, handleObj, sel, matchedHandlers, matchedSelectors, + handlerQueue = [], + delegateCount = handlers.delegateCount, + cur = event.target; + + // Find delegate handlers + if ( delegateCount && + + // Support: IE <=9 + // Black-hole SVG <use> instance trees (trac-13180) + cur.nodeType && + + // Support: Firefox <=42 + // Suppress spec-violating clicks indicating a non-primary pointer button (trac-3861) + // https://www.w3.org/TR/DOM-Level-3-Events/#event-type-click + // Support: IE 11 only + // ...but not arrow key "clicks" of radio inputs, which can have `button` -1 (gh-2343) + !( event.type === "click" && event.button >= 1 ) ) { + + for ( ; cur !== this; cur = cur.parentNode || this ) { + + // Don't check non-elements (#13208) + // Don't process clicks on disabled elements (#6911, #8165, #11382, #11764) + if ( cur.nodeType === 1 && !( event.type === "click" && cur.disabled === true ) ) { + matchedHandlers = []; + matchedSelectors = {}; + for ( i = 0; i < delegateCount; i++ ) { + handleObj = handlers[ i ]; + + // Don't conflict with Object.prototype properties (#13203) + sel = handleObj.selector + " "; + + if ( matchedSelectors[ sel ] === undefined ) { + matchedSelectors[ sel ] = handleObj.needsContext ? + jQuery( sel, this ).index( cur ) > -1 : + jQuery.find( sel, this, null, [ cur ] ).length; + } + if ( matchedSelectors[ sel ] ) { + matchedHandlers.push( handleObj ); + } + } + if ( matchedHandlers.length ) { + handlerQueue.push( { elem: cur, handlers: matchedHandlers } ); + } + } + } + } + + // Add the remaining (directly-bound) handlers + cur = this; + if ( delegateCount < handlers.length ) { + handlerQueue.push( { elem: cur, handlers: handlers.slice( delegateCount ) } ); + } + + return handlerQueue; + }, + + addProp: function( name, hook ) { + Object.defineProperty( jQuery.Event.prototype, name, { + enumerable: true, + configurable: true, + + get: isFunction( hook ) ? + function() { + if ( this.originalEvent ) { + return hook( this.originalEvent ); + } + } : + function() { + if ( this.originalEvent ) { + return this.originalEvent[ name ]; + } + }, + + set: function( value ) { + Object.defineProperty( this, name, { + enumerable: true, + configurable: true, + writable: true, + value: value + } ); + } + } ); + }, + + fix: function( originalEvent ) { + return originalEvent[ jQuery.expando ] ? + originalEvent : + new jQuery.Event( originalEvent ); + }, + + special: { + load: { + + // Prevent triggered image.load events from bubbling to window.load + noBubble: true + }, + click: { + + // Utilize native event to ensure correct state for checkable inputs + setup: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Claim the first handler + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + // dataPriv.set( el, "click", ... ) + leverageNative( el, "click", returnTrue ); + } + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function( data ) { + + // For mutual compressibility with _default, replace `this` access with a local var. + // `|| data` is dead code meant only to preserve the variable through minification. + var el = this || data; + + // Force setup before triggering a click + if ( rcheckableType.test( el.type ) && + el.click && nodeName( el, "input" ) ) { + + leverageNative( el, "click" ); + } + + // Return non-false to allow normal event-path propagation + return true; + }, + + // For cross-browser consistency, suppress native .click() on links + // Also prevent it if we're currently inside a leveraged native-event stack + _default: function( event ) { + var target = event.target; + return rcheckableType.test( target.type ) && + target.click && nodeName( target, "input" ) && + dataPriv.get( target, "click" ) || + nodeName( target, "a" ); + } + }, + + beforeunload: { + postDispatch: function( event ) { + + // Support: Firefox 20+ + // Firefox doesn't alert if the returnValue field is not set. + if ( event.result !== undefined && event.originalEvent ) { + event.originalEvent.returnValue = event.result; + } + } + } + } +}; + +// Ensure the presence of an event listener that handles manually-triggered +// synthetic events by interrupting progress until reinvoked in response to +// *native* events that it fires directly, ensuring that state changes have +// already occurred before other listeners are invoked. +function leverageNative( el, type, expectSync ) { + + // Missing expectSync indicates a trigger call, which must force setup through jQuery.event.add + if ( !expectSync ) { + if ( dataPriv.get( el, type ) === undefined ) { + jQuery.event.add( el, type, returnTrue ); + } + return; + } + + // Register the controller as a special universal handler for all event namespaces + dataPriv.set( el, type, false ); + jQuery.event.add( el, type, { + namespace: false, + handler: function( event ) { + var notAsync, result, + saved = dataPriv.get( this, type ); + + if ( ( event.isTrigger & 1 ) && this[ type ] ) { + + // Interrupt processing of the outer synthetic .trigger()ed event + // Saved data should be false in such cases, but might be a leftover capture object + // from an async native handler (gh-4350) + if ( !saved.length ) { + + // Store arguments for use when handling the inner native event + // There will always be at least one argument (an event object), so this array + // will not be confused with a leftover capture object. + saved = slice.call( arguments ); + dataPriv.set( this, type, saved ); + + // Trigger the native event and capture its result + // Support: IE <=9 - 11+ + // focus() and blur() are asynchronous + notAsync = expectSync( this, type ); + this[ type ](); + result = dataPriv.get( this, type ); + if ( saved !== result || notAsync ) { + dataPriv.set( this, type, false ); + } else { + result = {}; + } + if ( saved !== result ) { + + // Cancel the outer synthetic event + event.stopImmediatePropagation(); + event.preventDefault(); + return result.value; + } + + // If this is an inner synthetic event for an event with a bubbling surrogate + // (focus or blur), assume that the surrogate already propagated from triggering the + // native event and prevent that from happening again here. + // This technically gets the ordering wrong w.r.t. to `.trigger()` (in which the + // bubbling surrogate propagates *after* the non-bubbling base), but that seems + // less bad than duplication. + } else if ( ( jQuery.event.special[ type ] || {} ).delegateType ) { + event.stopPropagation(); + } + + // If this is a native event triggered above, everything is now in order + // Fire an inner synthetic event with the original arguments + } else if ( saved.length ) { + + // ...and capture the result + dataPriv.set( this, type, { + value: jQuery.event.trigger( + + // Support: IE <=9 - 11+ + // Extend with the prototype to reset the above stopImmediatePropagation() + jQuery.extend( saved[ 0 ], jQuery.Event.prototype ), + saved.slice( 1 ), + this + ) + } ); + + // Abort handling of the native event + event.stopImmediatePropagation(); + } + } + } ); +} + +jQuery.removeEvent = function( elem, type, handle ) { + + // This "if" is needed for plain objects + if ( elem.removeEventListener ) { + elem.removeEventListener( type, handle ); + } +}; + +jQuery.Event = function( src, props ) { + + // Allow instantiation without the 'new' keyword + if ( !( this instanceof jQuery.Event ) ) { + return new jQuery.Event( src, props ); + } + + // Event object + if ( src && src.type ) { + this.originalEvent = src; + this.type = src.type; + + // Events bubbling up the document may have been marked as prevented + // by a handler lower down the tree; reflect the correct value. + this.isDefaultPrevented = src.defaultPrevented || + src.defaultPrevented === undefined && + + // Support: Android <=2.3 only + src.returnValue === false ? + returnTrue : + returnFalse; + + // Create target properties + // Support: Safari <=6 - 7 only + // Target should not be a text node (#504, #13143) + this.target = ( src.target && src.target.nodeType === 3 ) ? + src.target.parentNode : + src.target; + + this.currentTarget = src.currentTarget; + this.relatedTarget = src.relatedTarget; + + // Event type + } else { + this.type = src; + } + + // Put explicitly provided properties onto the event object + if ( props ) { + jQuery.extend( this, props ); + } + + // Create a timestamp if incoming event doesn't have one + this.timeStamp = src && src.timeStamp || Date.now(); + + // Mark it as fixed + this[ jQuery.expando ] = true; +}; + +// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding +// https://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html +jQuery.Event.prototype = { + constructor: jQuery.Event, + isDefaultPrevented: returnFalse, + isPropagationStopped: returnFalse, + isImmediatePropagationStopped: returnFalse, + isSimulated: false, + + preventDefault: function() { + var e = this.originalEvent; + + this.isDefaultPrevented = returnTrue; + + if ( e && !this.isSimulated ) { + e.preventDefault(); + } + }, + stopPropagation: function() { + var e = this.originalEvent; + + this.isPropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopPropagation(); + } + }, + stopImmediatePropagation: function() { + var e = this.originalEvent; + + this.isImmediatePropagationStopped = returnTrue; + + if ( e && !this.isSimulated ) { + e.stopImmediatePropagation(); + } + + this.stopPropagation(); + } +}; + +// Includes all common event props including KeyEvent and MouseEvent specific props +jQuery.each( { + altKey: true, + bubbles: true, + cancelable: true, + changedTouches: true, + ctrlKey: true, + detail: true, + eventPhase: true, + metaKey: true, + pageX: true, + pageY: true, + shiftKey: true, + view: true, + "char": true, + code: true, + charCode: true, + key: true, + keyCode: true, + button: true, + buttons: true, + clientX: true, + clientY: true, + offsetX: true, + offsetY: true, + pointerId: true, + pointerType: true, + screenX: true, + screenY: true, + targetTouches: true, + toElement: true, + touches: true, + + which: function( event ) { + var button = event.button; + + // Add which for key events + if ( event.which == null && rkeyEvent.test( event.type ) ) { + return event.charCode != null ? event.charCode : event.keyCode; + } + + // Add which for click: 1 === left; 2 === middle; 3 === right + if ( !event.which && button !== undefined && rmouseEvent.test( event.type ) ) { + if ( button & 1 ) { + return 1; + } + + if ( button & 2 ) { + return 3; + } + + if ( button & 4 ) { + return 2; + } + + return 0; + } + + return event.which; + } +}, jQuery.event.addProp ); + +jQuery.each( { focus: "focusin", blur: "focusout" }, function( type, delegateType ) { + jQuery.event.special[ type ] = { + + // Utilize native event if possible so blur/focus sequence is correct + setup: function() { + + // Claim the first handler + // dataPriv.set( this, "focus", ... ) + // dataPriv.set( this, "blur", ... ) + leverageNative( this, type, expectSync ); + + // Return false to allow normal processing in the caller + return false; + }, + trigger: function() { + + // Force setup before trigger + leverageNative( this, type ); + + // Return non-false to allow normal event-path propagation + return true; + }, + + delegateType: delegateType + }; +} ); + +// Create mouseenter/leave events using mouseover/out and event-time checks +// so that event delegation works in jQuery. +// Do the same for pointerenter/pointerleave and pointerover/pointerout +// +// Support: Safari 7 only +// Safari sends mouseenter too often; see: +// https://bugs.chromium.org/p/chromium/issues/detail?id=470258 +// for the description of the bug (it existed in older Chrome versions as well). +jQuery.each( { + mouseenter: "mouseover", + mouseleave: "mouseout", + pointerenter: "pointerover", + pointerleave: "pointerout" +}, function( orig, fix ) { + jQuery.event.special[ orig ] = { + delegateType: fix, + bindType: fix, + + handle: function( event ) { + var ret, + target = this, + related = event.relatedTarget, + handleObj = event.handleObj; + + // For mouseenter/leave call the handler if related is outside the target. + // NB: No relatedTarget if the mouse left/entered the browser window + if ( !related || ( related !== target && !jQuery.contains( target, related ) ) ) { + event.type = handleObj.origType; + ret = handleObj.handler.apply( this, arguments ); + event.type = fix; + } + return ret; + } + }; +} ); + +jQuery.fn.extend( { + + on: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn ); + }, + one: function( types, selector, data, fn ) { + return on( this, types, selector, data, fn, 1 ); + }, + off: function( types, selector, fn ) { + var handleObj, type; + if ( types && types.preventDefault && types.handleObj ) { + + // ( event ) dispatched jQuery.Event + handleObj = types.handleObj; + jQuery( types.delegateTarget ).off( + handleObj.namespace ? + handleObj.origType + "." + handleObj.namespace : + handleObj.origType, + handleObj.selector, + handleObj.handler + ); + return this; + } + if ( typeof types === "object" ) { + + // ( types-object [, selector] ) + for ( type in types ) { + this.off( type, selector, types[ type ] ); + } + return this; + } + if ( selector === false || typeof selector === "function" ) { + + // ( types [, fn] ) + fn = selector; + selector = undefined; + } + if ( fn === false ) { + fn = returnFalse; + } + return this.each( function() { + jQuery.event.remove( this, types, fn, selector ); + } ); + } +} ); + + +var + + // Support: IE <=10 - 11, Edge 12 - 13 only + // In IE/Edge using regex groups here causes severe slowdowns. + // See https://connect.microsoft.com/IE/feedback/details/1736512/ + rnoInnerhtml = /<script|<style|<link/i, + + // checked="checked" or checked + rchecked = /checked\s*(?:[^=]|=\s*.checked.)/i, + rcleanScript = /^\s*<!(?:\[CDATA\[|--)|(?:\]\]|--)>\s*$/g; + +// Prefer a tbody over its parent table for containing new rows +function manipulationTarget( elem, content ) { + if ( nodeName( elem, "table" ) && + nodeName( content.nodeType !== 11 ? content : content.firstChild, "tr" ) ) { + + return jQuery( elem ).children( "tbody" )[ 0 ] || elem; + } + + return elem; +} + +// Replace/restore the type attribute of script elements for safe DOM manipulation +function disableScript( elem ) { + elem.type = ( elem.getAttribute( "type" ) !== null ) + "/" + elem.type; + return elem; +} +function restoreScript( elem ) { + if ( ( elem.type || "" ).slice( 0, 5 ) === "true/" ) { + elem.type = elem.type.slice( 5 ); + } else { + elem.removeAttribute( "type" ); + } + + return elem; +} + +function cloneCopyEvent( src, dest ) { + var i, l, type, pdataOld, udataOld, udataCur, events; + + if ( dest.nodeType !== 1 ) { + return; + } + + // 1. Copy private data: events, handlers, etc. + if ( dataPriv.hasData( src ) ) { + pdataOld = dataPriv.get( src ); + events = pdataOld.events; + + if ( events ) { + dataPriv.remove( dest, "handle events" ); + + for ( type in events ) { + for ( i = 0, l = events[ type ].length; i < l; i++ ) { + jQuery.event.add( dest, type, events[ type ][ i ] ); + } + } + } + } + + // 2. Copy user data + if ( dataUser.hasData( src ) ) { + udataOld = dataUser.access( src ); + udataCur = jQuery.extend( {}, udataOld ); + + dataUser.set( dest, udataCur ); + } +} + +// Fix IE bugs, see support tests +function fixInput( src, dest ) { + var nodeName = dest.nodeName.toLowerCase(); + + // Fails to persist the checked state of a cloned checkbox or radio button. + if ( nodeName === "input" && rcheckableType.test( src.type ) ) { + dest.checked = src.checked; + + // Fails to return the selected option to the default selected state when cloning options + } else if ( nodeName === "input" || nodeName === "textarea" ) { + dest.defaultValue = src.defaultValue; + } +} + +function domManip( collection, args, callback, ignored ) { + + // Flatten any nested arrays + args = flat( args ); + + var fragment, first, scripts, hasScripts, node, doc, + i = 0, + l = collection.length, + iNoClone = l - 1, + value = args[ 0 ], + valueIsFunction = isFunction( value ); + + // We can't cloneNode fragments that contain checked, in WebKit + if ( valueIsFunction || + ( l > 1 && typeof value === "string" && + !support.checkClone && rchecked.test( value ) ) ) { + return collection.each( function( index ) { + var self = collection.eq( index ); + if ( valueIsFunction ) { + args[ 0 ] = value.call( this, index, self.html() ); + } + domManip( self, args, callback, ignored ); + } ); + } + + if ( l ) { + fragment = buildFragment( args, collection[ 0 ].ownerDocument, false, collection, ignored ); + first = fragment.firstChild; + + if ( fragment.childNodes.length === 1 ) { + fragment = first; + } + + // Require either new content or an interest in ignored elements to invoke the callback + if ( first || ignored ) { + scripts = jQuery.map( getAll( fragment, "script" ), disableScript ); + hasScripts = scripts.length; + + // Use the original fragment for the last item + // instead of the first because it can end up + // being emptied incorrectly in certain situations (#8070). + for ( ; i < l; i++ ) { + node = fragment; + + if ( i !== iNoClone ) { + node = jQuery.clone( node, true, true ); + + // Keep references to cloned scripts for later restoration + if ( hasScripts ) { + + // Support: Android <=4.0 only, PhantomJS 1 only + // push.apply(_, arraylike) throws on ancient WebKit + jQuery.merge( scripts, getAll( node, "script" ) ); + } + } + + callback.call( collection[ i ], node, i ); + } + + if ( hasScripts ) { + doc = scripts[ scripts.length - 1 ].ownerDocument; + + // Reenable scripts + jQuery.map( scripts, restoreScript ); + + // Evaluate executable scripts on first document insertion + for ( i = 0; i < hasScripts; i++ ) { + node = scripts[ i ]; + if ( rscriptType.test( node.type || "" ) && + !dataPriv.access( node, "globalEval" ) && + jQuery.contains( doc, node ) ) { + + if ( node.src && ( node.type || "" ).toLowerCase() !== "module" ) { + + // Optional AJAX dependency, but won't run scripts if not present + if ( jQuery._evalUrl && !node.noModule ) { + jQuery._evalUrl( node.src, { + nonce: node.nonce || node.getAttribute( "nonce" ) + }, doc ); + } + } else { + DOMEval( node.textContent.replace( rcleanScript, "" ), node, doc ); + } + } + } + } + } + } + + return collection; +} + +function remove( elem, selector, keepData ) { + var node, + nodes = selector ? jQuery.filter( selector, elem ) : elem, + i = 0; + + for ( ; ( node = nodes[ i ] ) != null; i++ ) { + if ( !keepData && node.nodeType === 1 ) { + jQuery.cleanData( getAll( node ) ); + } + + if ( node.parentNode ) { + if ( keepData && isAttached( node ) ) { + setGlobalEval( getAll( node, "script" ) ); + } + node.parentNode.removeChild( node ); + } + } + + return elem; +} + +jQuery.extend( { + htmlPrefilter: function( html ) { + return html; + }, + + clone: function( elem, dataAndEvents, deepDataAndEvents ) { + var i, l, srcElements, destElements, + clone = elem.cloneNode( true ), + inPage = isAttached( elem ); + + // Fix IE cloning issues + if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) && + !jQuery.isXMLDoc( elem ) ) { + + // We eschew Sizzle here for performance reasons: https://jsperf.com/getall-vs-sizzle/2 + destElements = getAll( clone ); + srcElements = getAll( elem ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + fixInput( srcElements[ i ], destElements[ i ] ); + } + } + + // Copy the events from the original to the clone + if ( dataAndEvents ) { + if ( deepDataAndEvents ) { + srcElements = srcElements || getAll( elem ); + destElements = destElements || getAll( clone ); + + for ( i = 0, l = srcElements.length; i < l; i++ ) { + cloneCopyEvent( srcElements[ i ], destElements[ i ] ); + } + } else { + cloneCopyEvent( elem, clone ); + } + } + + // Preserve script evaluation history + destElements = getAll( clone, "script" ); + if ( destElements.length > 0 ) { + setGlobalEval( destElements, !inPage && getAll( elem, "script" ) ); + } + + // Return the cloned set + return clone; + }, + + cleanData: function( elems ) { + var data, elem, type, + special = jQuery.event.special, + i = 0; + + for ( ; ( elem = elems[ i ] ) !== undefined; i++ ) { + if ( acceptData( elem ) ) { + if ( ( data = elem[ dataPriv.expando ] ) ) { + if ( data.events ) { + for ( type in data.events ) { + if ( special[ type ] ) { + jQuery.event.remove( elem, type ); + + // This is a shortcut to avoid jQuery.event.remove's overhead + } else { + jQuery.removeEvent( elem, type, data.handle ); + } + } + } + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataPriv.expando ] = undefined; + } + if ( elem[ dataUser.expando ] ) { + + // Support: Chrome <=35 - 45+ + // Assign undefined instead of using delete, see Data#remove + elem[ dataUser.expando ] = undefined; + } + } + } + } +} ); + +jQuery.fn.extend( { + detach: function( selector ) { + return remove( this, selector, true ); + }, + + remove: function( selector ) { + return remove( this, selector ); + }, + + text: function( value ) { + return access( this, function( value ) { + return value === undefined ? + jQuery.text( this ) : + this.empty().each( function() { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + this.textContent = value; + } + } ); + }, null, value, arguments.length ); + }, + + append: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.appendChild( elem ); + } + } ); + }, + + prepend: function() { + return domManip( this, arguments, function( elem ) { + if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) { + var target = manipulationTarget( this, elem ); + target.insertBefore( elem, target.firstChild ); + } + } ); + }, + + before: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this ); + } + } ); + }, + + after: function() { + return domManip( this, arguments, function( elem ) { + if ( this.parentNode ) { + this.parentNode.insertBefore( elem, this.nextSibling ); + } + } ); + }, + + empty: function() { + var elem, + i = 0; + + for ( ; ( elem = this[ i ] ) != null; i++ ) { + if ( elem.nodeType === 1 ) { + + // Prevent memory leaks + jQuery.cleanData( getAll( elem, false ) ); + + // Remove any remaining nodes + elem.textContent = ""; + } + } + + return this; + }, + + clone: function( dataAndEvents, deepDataAndEvents ) { + dataAndEvents = dataAndEvents == null ? false : dataAndEvents; + deepDataAndEvents = deepDataAndEvents == null ? dataAndEvents : deepDataAndEvents; + + return this.map( function() { + return jQuery.clone( this, dataAndEvents, deepDataAndEvents ); + } ); + }, + + html: function( value ) { + return access( this, function( value ) { + var elem = this[ 0 ] || {}, + i = 0, + l = this.length; + + if ( value === undefined && elem.nodeType === 1 ) { + return elem.innerHTML; + } + + // See if we can take a shortcut and just use innerHTML + if ( typeof value === "string" && !rnoInnerhtml.test( value ) && + !wrapMap[ ( rtagName.exec( value ) || [ "", "" ] )[ 1 ].toLowerCase() ] ) { + + value = jQuery.htmlPrefilter( value ); + + try { + for ( ; i < l; i++ ) { + elem = this[ i ] || {}; + + // Remove element nodes and prevent memory leaks + if ( elem.nodeType === 1 ) { + jQuery.cleanData( getAll( elem, false ) ); + elem.innerHTML = value; + } + } + + elem = 0; + + // If using innerHTML throws an exception, use the fallback method + } catch ( e ) {} + } + + if ( elem ) { + this.empty().append( value ); + } + }, null, value, arguments.length ); + }, + + replaceWith: function() { + var ignored = []; + + // Make the changes, replacing each non-ignored context element with the new content + return domManip( this, arguments, function( elem ) { + var parent = this.parentNode; + + if ( jQuery.inArray( this, ignored ) < 0 ) { + jQuery.cleanData( getAll( this ) ); + if ( parent ) { + parent.replaceChild( elem, this ); + } + } + + // Force callback invocation + }, ignored ); + } +} ); + +jQuery.each( { + appendTo: "append", + prependTo: "prepend", + insertBefore: "before", + insertAfter: "after", + replaceAll: "replaceWith" +}, function( name, original ) { + jQuery.fn[ name ] = function( selector ) { + var elems, + ret = [], + insert = jQuery( selector ), + last = insert.length - 1, + i = 0; + + for ( ; i <= last; i++ ) { + elems = i === last ? this : this.clone( true ); + jQuery( insert[ i ] )[ original ]( elems ); + + // Support: Android <=4.0 only, PhantomJS 1 only + // .get() because push.apply(_, arraylike) throws on ancient WebKit + push.apply( ret, elems.get() ); + } + + return this.pushStack( ret ); + }; +} ); +var rnumnonpx = new RegExp( "^(" + pnum + ")(?!px)[a-z%]+$", "i" ); + +var getStyles = function( elem ) { + + // Support: IE <=11 only, Firefox <=30 (#15098, #14150) + // IE throws on elements created in popups + // FF meanwhile throws on frame elements through "defaultView.getComputedStyle" + var view = elem.ownerDocument.defaultView; + + if ( !view || !view.opener ) { + view = window; + } + + return view.getComputedStyle( elem ); + }; + +var swap = function( elem, options, callback ) { + var ret, name, + old = {}; + + // Remember the old values, and insert the new ones + for ( name in options ) { + old[ name ] = elem.style[ name ]; + elem.style[ name ] = options[ name ]; + } + + ret = callback.call( elem ); + + // Revert the old values + for ( name in options ) { + elem.style[ name ] = old[ name ]; + } + + return ret; +}; + + +var rboxStyle = new RegExp( cssExpand.join( "|" ), "i" ); + + + +( function() { + + // Executing both pixelPosition & boxSizingReliable tests require only one layout + // so they're executed at the same time to save the second computation. + function computeStyleTests() { + + // This is a singleton, we need to execute it only once + if ( !div ) { + return; + } + + container.style.cssText = "position:absolute;left:-11111px;width:60px;" + + "margin-top:1px;padding:0;border:0"; + div.style.cssText = + "position:relative;display:block;box-sizing:border-box;overflow:scroll;" + + "margin:auto;border:1px;padding:1px;" + + "width:60%;top:1%"; + documentElement.appendChild( container ).appendChild( div ); + + var divStyle = window.getComputedStyle( div ); + pixelPositionVal = divStyle.top !== "1%"; + + // Support: Android 4.0 - 4.3 only, Firefox <=3 - 44 + reliableMarginLeftVal = roundPixelMeasures( divStyle.marginLeft ) === 12; + + // Support: Android 4.0 - 4.3 only, Safari <=9.1 - 10.1, iOS <=7.0 - 9.3 + // Some styles come back with percentage values, even though they shouldn't + div.style.right = "60%"; + pixelBoxStylesVal = roundPixelMeasures( divStyle.right ) === 36; + + // Support: IE 9 - 11 only + // Detect misreporting of content dimensions for box-sizing:border-box elements + boxSizingReliableVal = roundPixelMeasures( divStyle.width ) === 36; + + // Support: IE 9 only + // Detect overflow:scroll screwiness (gh-3699) + // Support: Chrome <=64 + // Don't get tricked when zoom affects offsetWidth (gh-4029) + div.style.position = "absolute"; + scrollboxSizeVal = roundPixelMeasures( div.offsetWidth / 3 ) === 12; + + documentElement.removeChild( container ); + + // Nullify the div so it wouldn't be stored in the memory and + // it will also be a sign that checks already performed + div = null; + } + + function roundPixelMeasures( measure ) { + return Math.round( parseFloat( measure ) ); + } + + var pixelPositionVal, boxSizingReliableVal, scrollboxSizeVal, pixelBoxStylesVal, + reliableTrDimensionsVal, reliableMarginLeftVal, + container = document.createElement( "div" ), + div = document.createElement( "div" ); + + // Finish early in limited (non-browser) environments + if ( !div.style ) { + return; + } + + // Support: IE <=9 - 11 only + // Style of cloned element affects source element cloned (#8908) + div.style.backgroundClip = "content-box"; + div.cloneNode( true ).style.backgroundClip = ""; + support.clearCloneStyle = div.style.backgroundClip === "content-box"; + + jQuery.extend( support, { + boxSizingReliable: function() { + computeStyleTests(); + return boxSizingReliableVal; + }, + pixelBoxStyles: function() { + computeStyleTests(); + return pixelBoxStylesVal; + }, + pixelPosition: function() { + computeStyleTests(); + return pixelPositionVal; + }, + reliableMarginLeft: function() { + computeStyleTests(); + return reliableMarginLeftVal; + }, + scrollboxSize: function() { + computeStyleTests(); + return scrollboxSizeVal; + }, + + // Support: IE 9 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Behavior in IE 9 is more subtle than in newer versions & it passes + // some versions of this test; make sure not to make it pass there! + reliableTrDimensions: function() { + var table, tr, trChild, trStyle; + if ( reliableTrDimensionsVal == null ) { + table = document.createElement( "table" ); + tr = document.createElement( "tr" ); + trChild = document.createElement( "div" ); + + table.style.cssText = "position:absolute;left:-11111px"; + tr.style.height = "1px"; + trChild.style.height = "9px"; + + documentElement + .appendChild( table ) + .appendChild( tr ) + .appendChild( trChild ); + + trStyle = window.getComputedStyle( tr ); + reliableTrDimensionsVal = parseInt( trStyle.height ) > 3; + + documentElement.removeChild( table ); + } + return reliableTrDimensionsVal; + } + } ); +} )(); + + +function curCSS( elem, name, computed ) { + var width, minWidth, maxWidth, ret, + + // Support: Firefox 51+ + // Retrieving style before computed somehow + // fixes an issue with getting wrong values + // on detached elements + style = elem.style; + + computed = computed || getStyles( elem ); + + // getPropertyValue is needed for: + // .css('filter') (IE 9 only, #12537) + // .css('--customProperty) (#3144) + if ( computed ) { + ret = computed.getPropertyValue( name ) || computed[ name ]; + + if ( ret === "" && !isAttached( elem ) ) { + ret = jQuery.style( elem, name ); + } + + // A tribute to the "awesome hack by Dean Edwards" + // Android Browser returns percentage for some values, + // but width seems to be reliably pixels. + // This is against the CSSOM draft spec: + // https://drafts.csswg.org/cssom/#resolved-values + if ( !support.pixelBoxStyles() && rnumnonpx.test( ret ) && rboxStyle.test( name ) ) { + + // Remember the original values + width = style.width; + minWidth = style.minWidth; + maxWidth = style.maxWidth; + + // Put in the new values to get a computed value out + style.minWidth = style.maxWidth = style.width = ret; + ret = computed.width; + + // Revert the changed values + style.width = width; + style.minWidth = minWidth; + style.maxWidth = maxWidth; + } + } + + return ret !== undefined ? + + // Support: IE <=9 - 11 only + // IE returns zIndex value as an integer. + ret + "" : + ret; +} + + +function addGetHookIf( conditionFn, hookFn ) { + + // Define the hook, we'll check on the first run if it's really needed. + return { + get: function() { + if ( conditionFn() ) { + + // Hook not needed (or it's not possible to use it due + // to missing dependency), remove it. + delete this.get; + return; + } + + // Hook needed; redefine it so that the support test is not executed again. + return ( this.get = hookFn ).apply( this, arguments ); + } + }; +} + + +var cssPrefixes = [ "Webkit", "Moz", "ms" ], + emptyStyle = document.createElement( "div" ).style, + vendorProps = {}; + +// Return a vendor-prefixed property or undefined +function vendorPropName( name ) { + + // Check for vendor prefixed names + var capName = name[ 0 ].toUpperCase() + name.slice( 1 ), + i = cssPrefixes.length; + + while ( i-- ) { + name = cssPrefixes[ i ] + capName; + if ( name in emptyStyle ) { + return name; + } + } +} + +// Return a potentially-mapped jQuery.cssProps or vendor prefixed property +function finalPropName( name ) { + var final = jQuery.cssProps[ name ] || vendorProps[ name ]; + + if ( final ) { + return final; + } + if ( name in emptyStyle ) { + return name; + } + return vendorProps[ name ] = vendorPropName( name ) || name; +} + + +var + + // Swappable if display is none or starts with table + // except "table", "table-cell", or "table-caption" + // See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display + rdisplayswap = /^(none|table(?!-c[ea]).+)/, + rcustomProp = /^--/, + cssShow = { position: "absolute", visibility: "hidden", display: "block" }, + cssNormalTransform = { + letterSpacing: "0", + fontWeight: "400" + }; + +function setPositiveNumber( _elem, value, subtract ) { + + // Any relative (+/-) values have already been + // normalized at this point + var matches = rcssNum.exec( value ); + return matches ? + + // Guard against undefined "subtract", e.g., when used as in cssHooks + Math.max( 0, matches[ 2 ] - ( subtract || 0 ) ) + ( matches[ 3 ] || "px" ) : + value; +} + +function boxModelAdjustment( elem, dimension, box, isBorderBox, styles, computedVal ) { + var i = dimension === "width" ? 1 : 0, + extra = 0, + delta = 0; + + // Adjustment may not be necessary + if ( box === ( isBorderBox ? "border" : "content" ) ) { + return 0; + } + + for ( ; i < 4; i += 2 ) { + + // Both box models exclude margin + if ( box === "margin" ) { + delta += jQuery.css( elem, box + cssExpand[ i ], true, styles ); + } + + // If we get here with a content-box, we're seeking "padding" or "border" or "margin" + if ( !isBorderBox ) { + + // Add padding + delta += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + + // For "border" or "margin", add border + if ( box !== "padding" ) { + delta += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + + // But still keep track of it otherwise + } else { + extra += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + + // If we get here with a border-box (content + padding + border), we're seeking "content" or + // "padding" or "margin" + } else { + + // For "content", subtract padding + if ( box === "content" ) { + delta -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); + } + + // For "content" or "padding", subtract border + if ( box !== "margin" ) { + delta -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); + } + } + } + + // Account for positive content-box scroll gutter when requested by providing computedVal + if ( !isBorderBox && computedVal >= 0 ) { + + // offsetWidth/offsetHeight is a rounded sum of content, padding, scroll gutter, and border + // Assuming integer scroll gutter, subtract the rest and round down + delta += Math.max( 0, Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + computedVal - + delta - + extra - + 0.5 + + // If offsetWidth/offsetHeight is unknown, then we can't determine content-box scroll gutter + // Use an explicit zero to avoid NaN (gh-3964) + ) ) || 0; + } + + return delta; +} + +function getWidthOrHeight( elem, dimension, extra ) { + + // Start with computed style + var styles = getStyles( elem ), + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-4322). + // Fake content-box until we know it's needed to know the true value. + boxSizingNeeded = !support.boxSizingReliable() || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + valueIsBorderBox = isBorderBox, + + val = curCSS( elem, dimension, styles ), + offsetProp = "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ); + + // Support: Firefox <=54 + // Return a confounding non-pixel value or feign ignorance, as appropriate. + if ( rnumnonpx.test( val ) ) { + if ( !extra ) { + return val; + } + val = "auto"; + } + + + // Support: IE 9 - 11 only + // Use offsetWidth/offsetHeight for when box sizing is unreliable. + // In those cases, the computed value can be trusted to be border-box. + if ( ( !support.boxSizingReliable() && isBorderBox || + + // Support: IE 10 - 11+, Edge 15 - 18+ + // IE/Edge misreport `getComputedStyle` of table rows with width/height + // set in CSS while `offset*` properties report correct values. + // Interestingly, in some cases IE 9 doesn't suffer from this issue. + !support.reliableTrDimensions() && nodeName( elem, "tr" ) || + + // Fall back to offsetWidth/offsetHeight when value is "auto" + // This happens for inline elements with no explicit setting (gh-3571) + val === "auto" || + + // Support: Android <=4.1 - 4.3 only + // Also use offsetWidth/offsetHeight for misreported inline dimensions (gh-3602) + !parseFloat( val ) && jQuery.css( elem, "display", false, styles ) === "inline" ) && + + // Make sure the element is visible & connected + elem.getClientRects().length ) { + + isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box"; + + // Where available, offsetWidth/offsetHeight approximate border box dimensions. + // Where not available (e.g., SVG), assume unreliable box-sizing and interpret the + // retrieved value as a content box dimension. + valueIsBorderBox = offsetProp in elem; + if ( valueIsBorderBox ) { + val = elem[ offsetProp ]; + } + } + + // Normalize "" and auto + val = parseFloat( val ) || 0; + + // Adjust for the element's box model + return ( val + + boxModelAdjustment( + elem, + dimension, + extra || ( isBorderBox ? "border" : "content" ), + valueIsBorderBox, + styles, + + // Provide the current computed size to request scroll gutter calculation (gh-3589) + val + ) + ) + "px"; +} + +jQuery.extend( { + + // Add in style property hooks for overriding the default + // behavior of getting and setting a style property + cssHooks: { + opacity: { + get: function( elem, computed ) { + if ( computed ) { + + // We should always get a number back from opacity + var ret = curCSS( elem, "opacity" ); + return ret === "" ? "1" : ret; + } + } + } + }, + + // Don't automatically add "px" to these possibly-unitless properties + cssNumber: { + "animationIterationCount": true, + "columnCount": true, + "fillOpacity": true, + "flexGrow": true, + "flexShrink": true, + "fontWeight": true, + "gridArea": true, + "gridColumn": true, + "gridColumnEnd": true, + "gridColumnStart": true, + "gridRow": true, + "gridRowEnd": true, + "gridRowStart": true, + "lineHeight": true, + "opacity": true, + "order": true, + "orphans": true, + "widows": true, + "zIndex": true, + "zoom": true + }, + + // Add in properties whose names you wish to fix before + // setting or getting the value + cssProps: {}, + + // Get and set the style property on a DOM Node + style: function( elem, name, value, extra ) { + + // Don't set styles on text and comment nodes + if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) { + return; + } + + // Make sure that we're working with the right name + var ret, type, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ), + style = elem.style; + + // Make sure that we're working with the right name. We don't + // want to query the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Gets hook for the prefixed version, then unprefixed version + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // Check if we're setting a value + if ( value !== undefined ) { + type = typeof value; + + // Convert "+=" or "-=" to relative numbers (#7345) + if ( type === "string" && ( ret = rcssNum.exec( value ) ) && ret[ 1 ] ) { + value = adjustCSS( elem, name, ret ); + + // Fixes bug #9237 + type = "number"; + } + + // Make sure that null and NaN values aren't set (#7116) + if ( value == null || value !== value ) { + return; + } + + // If a number was passed in, add the unit (except for certain CSS properties) + // The isCustomProp check can be removed in jQuery 4.0 when we only auto-append + // "px" to a few hardcoded values. + if ( type === "number" && !isCustomProp ) { + value += ret && ret[ 3 ] || ( jQuery.cssNumber[ origName ] ? "" : "px" ); + } + + // background-* props affect original clone's values + if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) { + style[ name ] = "inherit"; + } + + // If a hook was provided, use that value, otherwise just set the specified value + if ( !hooks || !( "set" in hooks ) || + ( value = hooks.set( elem, value, extra ) ) !== undefined ) { + + if ( isCustomProp ) { + style.setProperty( name, value ); + } else { + style[ name ] = value; + } + } + + } else { + + // If a hook was provided get the non-computed value from there + if ( hooks && "get" in hooks && + ( ret = hooks.get( elem, false, extra ) ) !== undefined ) { + + return ret; + } + + // Otherwise just get the value from the style object + return style[ name ]; + } + }, + + css: function( elem, name, extra, styles ) { + var val, num, hooks, + origName = camelCase( name ), + isCustomProp = rcustomProp.test( name ); + + // Make sure that we're working with the right name. We don't + // want to modify the value if it is a CSS custom property + // since they are user-defined. + if ( !isCustomProp ) { + name = finalPropName( origName ); + } + + // Try prefixed name followed by the unprefixed name + hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; + + // If a hook was provided get the computed value from there + if ( hooks && "get" in hooks ) { + val = hooks.get( elem, true, extra ); + } + + // Otherwise, if a way to get the computed value exists, use that + if ( val === undefined ) { + val = curCSS( elem, name, styles ); + } + + // Convert "normal" to computed value + if ( val === "normal" && name in cssNormalTransform ) { + val = cssNormalTransform[ name ]; + } + + // Make numeric if forced or a qualifier was provided and val looks numeric + if ( extra === "" || extra ) { + num = parseFloat( val ); + return extra === true || isFinite( num ) ? num || 0 : val; + } + + return val; + } +} ); + +jQuery.each( [ "height", "width" ], function( _i, dimension ) { + jQuery.cssHooks[ dimension ] = { + get: function( elem, computed, extra ) { + if ( computed ) { + + // Certain elements can have dimension info if we invisibly show them + // but it must have a current display style that would benefit + return rdisplayswap.test( jQuery.css( elem, "display" ) ) && + + // Support: Safari 8+ + // Table columns in Safari have non-zero offsetWidth & zero + // getBoundingClientRect().width unless display is changed. + // Support: IE <=11 only + // Running getBoundingClientRect on a disconnected node + // in IE throws an error. + ( !elem.getClientRects().length || !elem.getBoundingClientRect().width ) ? + swap( elem, cssShow, function() { + return getWidthOrHeight( elem, dimension, extra ); + } ) : + getWidthOrHeight( elem, dimension, extra ); + } + }, + + set: function( elem, value, extra ) { + var matches, + styles = getStyles( elem ), + + // Only read styles.position if the test has a chance to fail + // to avoid forcing a reflow. + scrollboxSizeBuggy = !support.scrollboxSize() && + styles.position === "absolute", + + // To avoid forcing a reflow, only fetch boxSizing if we need it (gh-3991) + boxSizingNeeded = scrollboxSizeBuggy || extra, + isBorderBox = boxSizingNeeded && + jQuery.css( elem, "boxSizing", false, styles ) === "border-box", + subtract = extra ? + boxModelAdjustment( + elem, + dimension, + extra, + isBorderBox, + styles + ) : + 0; + + // Account for unreliable border-box dimensions by comparing offset* to computed and + // faking a content-box to get border and padding (gh-3699) + if ( isBorderBox && scrollboxSizeBuggy ) { + subtract -= Math.ceil( + elem[ "offset" + dimension[ 0 ].toUpperCase() + dimension.slice( 1 ) ] - + parseFloat( styles[ dimension ] ) - + boxModelAdjustment( elem, dimension, "border", false, styles ) - + 0.5 + ); + } + + // Convert to pixels if value adjustment is needed + if ( subtract && ( matches = rcssNum.exec( value ) ) && + ( matches[ 3 ] || "px" ) !== "px" ) { + + elem.style[ dimension ] = value; + value = jQuery.css( elem, dimension ); + } + + return setPositiveNumber( elem, value, subtract ); + } + }; +} ); + +jQuery.cssHooks.marginLeft = addGetHookIf( support.reliableMarginLeft, + function( elem, computed ) { + if ( computed ) { + return ( parseFloat( curCSS( elem, "marginLeft" ) ) || + elem.getBoundingClientRect().left - + swap( elem, { marginLeft: 0 }, function() { + return elem.getBoundingClientRect().left; + } ) + ) + "px"; + } + } +); + +// These hooks are used by animate to expand properties +jQuery.each( { + margin: "", + padding: "", + border: "Width" +}, function( prefix, suffix ) { + jQuery.cssHooks[ prefix + suffix ] = { + expand: function( value ) { + var i = 0, + expanded = {}, + + // Assumes a single number if not a string + parts = typeof value === "string" ? value.split( " " ) : [ value ]; + + for ( ; i < 4; i++ ) { + expanded[ prefix + cssExpand[ i ] + suffix ] = + parts[ i ] || parts[ i - 2 ] || parts[ 0 ]; + } + + return expanded; + } + }; + + if ( prefix !== "margin" ) { + jQuery.cssHooks[ prefix + suffix ].set = setPositiveNumber; + } +} ); + +jQuery.fn.extend( { + css: function( name, value ) { + return access( this, function( elem, name, value ) { + var styles, len, + map = {}, + i = 0; + + if ( Array.isArray( name ) ) { + styles = getStyles( elem ); + len = name.length; + + for ( ; i < len; i++ ) { + map[ name[ i ] ] = jQuery.css( elem, name[ i ], false, styles ); + } + + return map; + } + + return value !== undefined ? + jQuery.style( elem, name, value ) : + jQuery.css( elem, name ); + }, name, value, arguments.length > 1 ); + } +} ); + + +function Tween( elem, options, prop, end, easing ) { + return new Tween.prototype.init( elem, options, prop, end, easing ); +} +jQuery.Tween = Tween; + +Tween.prototype = { + constructor: Tween, + init: function( elem, options, prop, end, easing, unit ) { + this.elem = elem; + this.prop = prop; + this.easing = easing || jQuery.easing._default; + this.options = options; + this.start = this.now = this.cur(); + this.end = end; + this.unit = unit || ( jQuery.cssNumber[ prop ] ? "" : "px" ); + }, + cur: function() { + var hooks = Tween.propHooks[ this.prop ]; + + return hooks && hooks.get ? + hooks.get( this ) : + Tween.propHooks._default.get( this ); + }, + run: function( percent ) { + var eased, + hooks = Tween.propHooks[ this.prop ]; + + if ( this.options.duration ) { + this.pos = eased = jQuery.easing[ this.easing ]( + percent, this.options.duration * percent, 0, 1, this.options.duration + ); + } else { + this.pos = eased = percent; + } + this.now = ( this.end - this.start ) * eased + this.start; + + if ( this.options.step ) { + this.options.step.call( this.elem, this.now, this ); + } + + if ( hooks && hooks.set ) { + hooks.set( this ); + } else { + Tween.propHooks._default.set( this ); + } + return this; + } +}; + +Tween.prototype.init.prototype = Tween.prototype; + +Tween.propHooks = { + _default: { + get: function( tween ) { + var result; + + // Use a property on the element directly when it is not a DOM element, + // or when there is no matching style property that exists. + if ( tween.elem.nodeType !== 1 || + tween.elem[ tween.prop ] != null && tween.elem.style[ tween.prop ] == null ) { + return tween.elem[ tween.prop ]; + } + + // Passing an empty string as a 3rd parameter to .css will automatically + // attempt a parseFloat and fallback to a string if the parse fails. + // Simple values such as "10px" are parsed to Float; + // complex values such as "rotate(1rad)" are returned as-is. + result = jQuery.css( tween.elem, tween.prop, "" ); + + // Empty strings, null, undefined and "auto" are converted to 0. + return !result || result === "auto" ? 0 : result; + }, + set: function( tween ) { + + // Use step hook for back compat. + // Use cssHook if its there. + // Use .style if available and use plain properties where available. + if ( jQuery.fx.step[ tween.prop ] ) { + jQuery.fx.step[ tween.prop ]( tween ); + } else if ( tween.elem.nodeType === 1 && ( + jQuery.cssHooks[ tween.prop ] || + tween.elem.style[ finalPropName( tween.prop ) ] != null ) ) { + jQuery.style( tween.elem, tween.prop, tween.now + tween.unit ); + } else { + tween.elem[ tween.prop ] = tween.now; + } + } + } +}; + +// Support: IE <=9 only +// Panic based approach to setting things on disconnected nodes +Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = { + set: function( tween ) { + if ( tween.elem.nodeType && tween.elem.parentNode ) { + tween.elem[ tween.prop ] = tween.now; + } + } +}; + +jQuery.easing = { + linear: function( p ) { + return p; + }, + swing: function( p ) { + return 0.5 - Math.cos( p * Math.PI ) / 2; + }, + _default: "swing" +}; + +jQuery.fx = Tween.prototype.init; + +// Back compat <1.8 extension point +jQuery.fx.step = {}; + + + + +var + fxNow, inProgress, + rfxtypes = /^(?:toggle|show|hide)$/, + rrun = /queueHooks$/; + +function schedule() { + if ( inProgress ) { + if ( document.hidden === false && window.requestAnimationFrame ) { + window.requestAnimationFrame( schedule ); + } else { + window.setTimeout( schedule, jQuery.fx.interval ); + } + + jQuery.fx.tick(); + } +} + +// Animations created synchronously will run synchronously +function createFxNow() { + window.setTimeout( function() { + fxNow = undefined; + } ); + return ( fxNow = Date.now() ); +} + +// Generate parameters to create a standard animation +function genFx( type, includeWidth ) { + var which, + i = 0, + attrs = { height: type }; + + // If we include width, step value is 1 to do all cssExpand values, + // otherwise step value is 2 to skip over Left and Right + includeWidth = includeWidth ? 1 : 0; + for ( ; i < 4; i += 2 - includeWidth ) { + which = cssExpand[ i ]; + attrs[ "margin" + which ] = attrs[ "padding" + which ] = type; + } + + if ( includeWidth ) { + attrs.opacity = attrs.width = type; + } + + return attrs; +} + +function createTween( value, prop, animation ) { + var tween, + collection = ( Animation.tweeners[ prop ] || [] ).concat( Animation.tweeners[ "*" ] ), + index = 0, + length = collection.length; + for ( ; index < length; index++ ) { + if ( ( tween = collection[ index ].call( animation, prop, value ) ) ) { + + // We're done with this property + return tween; + } + } +} + +function defaultPrefilter( elem, props, opts ) { + var prop, value, toggle, hooks, oldfire, propTween, restoreDisplay, display, + isBox = "width" in props || "height" in props, + anim = this, + orig = {}, + style = elem.style, + hidden = elem.nodeType && isHiddenWithinTree( elem ), + dataShow = dataPriv.get( elem, "fxshow" ); + + // Queue-skipping animations hijack the fx hooks + if ( !opts.queue ) { + hooks = jQuery._queueHooks( elem, "fx" ); + if ( hooks.unqueued == null ) { + hooks.unqueued = 0; + oldfire = hooks.empty.fire; + hooks.empty.fire = function() { + if ( !hooks.unqueued ) { + oldfire(); + } + }; + } + hooks.unqueued++; + + anim.always( function() { + + // Ensure the complete handler is called before this completes + anim.always( function() { + hooks.unqueued--; + if ( !jQuery.queue( elem, "fx" ).length ) { + hooks.empty.fire(); + } + } ); + } ); + } + + // Detect show/hide animations + for ( prop in props ) { + value = props[ prop ]; + if ( rfxtypes.test( value ) ) { + delete props[ prop ]; + toggle = toggle || value === "toggle"; + if ( value === ( hidden ? "hide" : "show" ) ) { + + // Pretend to be hidden if this is a "show" and + // there is still data from a stopped show/hide + if ( value === "show" && dataShow && dataShow[ prop ] !== undefined ) { + hidden = true; + + // Ignore all other no-op show/hide data + } else { + continue; + } + } + orig[ prop ] = dataShow && dataShow[ prop ] || jQuery.style( elem, prop ); + } + } + + // Bail out if this is a no-op like .hide().hide() + propTween = !jQuery.isEmptyObject( props ); + if ( !propTween && jQuery.isEmptyObject( orig ) ) { + return; + } + + // Restrict "overflow" and "display" styles during box animations + if ( isBox && elem.nodeType === 1 ) { + + // Support: IE <=9 - 11, Edge 12 - 15 + // Record all 3 overflow attributes because IE does not infer the shorthand + // from identically-valued overflowX and overflowY and Edge just mirrors + // the overflowX value there. + opts.overflow = [ style.overflow, style.overflowX, style.overflowY ]; + + // Identify a display type, preferring old show/hide data over the CSS cascade + restoreDisplay = dataShow && dataShow.display; + if ( restoreDisplay == null ) { + restoreDisplay = dataPriv.get( elem, "display" ); + } + display = jQuery.css( elem, "display" ); + if ( display === "none" ) { + if ( restoreDisplay ) { + display = restoreDisplay; + } else { + + // Get nonempty value(s) by temporarily forcing visibility + showHide( [ elem ], true ); + restoreDisplay = elem.style.display || restoreDisplay; + display = jQuery.css( elem, "display" ); + showHide( [ elem ] ); + } + } + + // Animate inline elements as inline-block + if ( display === "inline" || display === "inline-block" && restoreDisplay != null ) { + if ( jQuery.css( elem, "float" ) === "none" ) { + + // Restore the original display value at the end of pure show/hide animations + if ( !propTween ) { + anim.done( function() { + style.display = restoreDisplay; + } ); + if ( restoreDisplay == null ) { + display = style.display; + restoreDisplay = display === "none" ? "" : display; + } + } + style.display = "inline-block"; + } + } + } + + if ( opts.overflow ) { + style.overflow = "hidden"; + anim.always( function() { + style.overflow = opts.overflow[ 0 ]; + style.overflowX = opts.overflow[ 1 ]; + style.overflowY = opts.overflow[ 2 ]; + } ); + } + + // Implement show/hide animations + propTween = false; + for ( prop in orig ) { + + // General show/hide setup for this element animation + if ( !propTween ) { + if ( dataShow ) { + if ( "hidden" in dataShow ) { + hidden = dataShow.hidden; + } + } else { + dataShow = dataPriv.access( elem, "fxshow", { display: restoreDisplay } ); + } + + // Store hidden/visible for toggle so `.stop().toggle()` "reverses" + if ( toggle ) { + dataShow.hidden = !hidden; + } + + // Show elements before animating them + if ( hidden ) { + showHide( [ elem ], true ); + } + + /* eslint-disable no-loop-func */ + + anim.done( function() { + + /* eslint-enable no-loop-func */ + + // The final step of a "hide" animation is actually hiding the element + if ( !hidden ) { + showHide( [ elem ] ); + } + dataPriv.remove( elem, "fxshow" ); + for ( prop in orig ) { + jQuery.style( elem, prop, orig[ prop ] ); + } + } ); + } + + // Per-property setup + propTween = createTween( hidden ? dataShow[ prop ] : 0, prop, anim ); + if ( !( prop in dataShow ) ) { + dataShow[ prop ] = propTween.start; + if ( hidden ) { + propTween.end = propTween.start; + propTween.start = 0; + } + } + } +} + +function propFilter( props, specialEasing ) { + var index, name, easing, value, hooks; + + // camelCase, specialEasing and expand cssHook pass + for ( index in props ) { + name = camelCase( index ); + easing = specialEasing[ name ]; + value = props[ index ]; + if ( Array.isArray( value ) ) { + easing = value[ 1 ]; + value = props[ index ] = value[ 0 ]; + } + + if ( index !== name ) { + props[ name ] = value; + delete props[ index ]; + } + + hooks = jQuery.cssHooks[ name ]; + if ( hooks && "expand" in hooks ) { + value = hooks.expand( value ); + delete props[ name ]; + + // Not quite $.extend, this won't overwrite existing keys. + // Reusing 'index' because we have the correct "name" + for ( index in value ) { + if ( !( index in props ) ) { + props[ index ] = value[ index ]; + specialEasing[ index ] = easing; + } + } + } else { + specialEasing[ name ] = easing; + } + } +} + +function Animation( elem, properties, options ) { + var result, + stopped, + index = 0, + length = Animation.prefilters.length, + deferred = jQuery.Deferred().always( function() { + + // Don't match elem in the :animated selector + delete tick.elem; + } ), + tick = function() { + if ( stopped ) { + return false; + } + var currentTime = fxNow || createFxNow(), + remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ), + + // Support: Android 2.3 only + // Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497) + temp = remaining / animation.duration || 0, + percent = 1 - temp, + index = 0, + length = animation.tweens.length; + + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( percent ); + } + + deferred.notifyWith( elem, [ animation, percent, remaining ] ); + + // If there's more to do, yield + if ( percent < 1 && length ) { + return remaining; + } + + // If this was an empty animation, synthesize a final progress notification + if ( !length ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + } + + // Resolve the animation and report its conclusion + deferred.resolveWith( elem, [ animation ] ); + return false; + }, + animation = deferred.promise( { + elem: elem, + props: jQuery.extend( {}, properties ), + opts: jQuery.extend( true, { + specialEasing: {}, + easing: jQuery.easing._default + }, options ), + originalProperties: properties, + originalOptions: options, + startTime: fxNow || createFxNow(), + duration: options.duration, + tweens: [], + createTween: function( prop, end ) { + var tween = jQuery.Tween( elem, animation.opts, prop, end, + animation.opts.specialEasing[ prop ] || animation.opts.easing ); + animation.tweens.push( tween ); + return tween; + }, + stop: function( gotoEnd ) { + var index = 0, + + // If we are going to the end, we want to run all the tweens + // otherwise we skip this part + length = gotoEnd ? animation.tweens.length : 0; + if ( stopped ) { + return this; + } + stopped = true; + for ( ; index < length; index++ ) { + animation.tweens[ index ].run( 1 ); + } + + // Resolve when we played the last frame; otherwise, reject + if ( gotoEnd ) { + deferred.notifyWith( elem, [ animation, 1, 0 ] ); + deferred.resolveWith( elem, [ animation, gotoEnd ] ); + } else { + deferred.rejectWith( elem, [ animation, gotoEnd ] ); + } + return this; + } + } ), + props = animation.props; + + propFilter( props, animation.opts.specialEasing ); + + for ( ; index < length; index++ ) { + result = Animation.prefilters[ index ].call( animation, elem, props, animation.opts ); + if ( result ) { + if ( isFunction( result.stop ) ) { + jQuery._queueHooks( animation.elem, animation.opts.queue ).stop = + result.stop.bind( result ); + } + return result; + } + } + + jQuery.map( props, createTween, animation ); + + if ( isFunction( animation.opts.start ) ) { + animation.opts.start.call( elem, animation ); + } + + // Attach callbacks from options + animation + .progress( animation.opts.progress ) + .done( animation.opts.done, animation.opts.complete ) + .fail( animation.opts.fail ) + .always( animation.opts.always ); + + jQuery.fx.timer( + jQuery.extend( tick, { + elem: elem, + anim: animation, + queue: animation.opts.queue + } ) + ); + + return animation; +} + +jQuery.Animation = jQuery.extend( Animation, { + + tweeners: { + "*": [ function( prop, value ) { + var tween = this.createTween( prop, value ); + adjustCSS( tween.elem, prop, rcssNum.exec( value ), tween ); + return tween; + } ] + }, + + tweener: function( props, callback ) { + if ( isFunction( props ) ) { + callback = props; + props = [ "*" ]; + } else { + props = props.match( rnothtmlwhite ); + } + + var prop, + index = 0, + length = props.length; + + for ( ; index < length; index++ ) { + prop = props[ index ]; + Animation.tweeners[ prop ] = Animation.tweeners[ prop ] || []; + Animation.tweeners[ prop ].unshift( callback ); + } + }, + + prefilters: [ defaultPrefilter ], + + prefilter: function( callback, prepend ) { + if ( prepend ) { + Animation.prefilters.unshift( callback ); + } else { + Animation.prefilters.push( callback ); + } + } +} ); + +jQuery.speed = function( speed, easing, fn ) { + var opt = speed && typeof speed === "object" ? jQuery.extend( {}, speed ) : { + complete: fn || !fn && easing || + isFunction( speed ) && speed, + duration: speed, + easing: fn && easing || easing && !isFunction( easing ) && easing + }; + + // Go to the end state if fx are off + if ( jQuery.fx.off ) { + opt.duration = 0; + + } else { + if ( typeof opt.duration !== "number" ) { + if ( opt.duration in jQuery.fx.speeds ) { + opt.duration = jQuery.fx.speeds[ opt.duration ]; + + } else { + opt.duration = jQuery.fx.speeds._default; + } + } + } + + // Normalize opt.queue - true/undefined/null -> "fx" + if ( opt.queue == null || opt.queue === true ) { + opt.queue = "fx"; + } + + // Queueing + opt.old = opt.complete; + + opt.complete = function() { + if ( isFunction( opt.old ) ) { + opt.old.call( this ); + } + + if ( opt.queue ) { + jQuery.dequeue( this, opt.queue ); + } + }; + + return opt; +}; + +jQuery.fn.extend( { + fadeTo: function( speed, to, easing, callback ) { + + // Show any hidden elements after setting opacity to 0 + return this.filter( isHiddenWithinTree ).css( "opacity", 0 ).show() + + // Animate to the value specified + .end().animate( { opacity: to }, speed, easing, callback ); + }, + animate: function( prop, speed, easing, callback ) { + var empty = jQuery.isEmptyObject( prop ), + optall = jQuery.speed( speed, easing, callback ), + doAnimation = function() { + + // Operate on a copy of prop so per-property easing won't be lost + var anim = Animation( this, jQuery.extend( {}, prop ), optall ); + + // Empty animations, or finishing resolves immediately + if ( empty || dataPriv.get( this, "finish" ) ) { + anim.stop( true ); + } + }; + doAnimation.finish = doAnimation; + + return empty || optall.queue === false ? + this.each( doAnimation ) : + this.queue( optall.queue, doAnimation ); + }, + stop: function( type, clearQueue, gotoEnd ) { + var stopQueue = function( hooks ) { + var stop = hooks.stop; + delete hooks.stop; + stop( gotoEnd ); + }; + + if ( typeof type !== "string" ) { + gotoEnd = clearQueue; + clearQueue = type; + type = undefined; + } + if ( clearQueue ) { + this.queue( type || "fx", [] ); + } + + return this.each( function() { + var dequeue = true, + index = type != null && type + "queueHooks", + timers = jQuery.timers, + data = dataPriv.get( this ); + + if ( index ) { + if ( data[ index ] && data[ index ].stop ) { + stopQueue( data[ index ] ); + } + } else { + for ( index in data ) { + if ( data[ index ] && data[ index ].stop && rrun.test( index ) ) { + stopQueue( data[ index ] ); + } + } + } + + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && + ( type == null || timers[ index ].queue === type ) ) { + + timers[ index ].anim.stop( gotoEnd ); + dequeue = false; + timers.splice( index, 1 ); + } + } + + // Start the next in the queue if the last step wasn't forced. + // Timers currently will call their complete callbacks, which + // will dequeue but only if they were gotoEnd. + if ( dequeue || !gotoEnd ) { + jQuery.dequeue( this, type ); + } + } ); + }, + finish: function( type ) { + if ( type !== false ) { + type = type || "fx"; + } + return this.each( function() { + var index, + data = dataPriv.get( this ), + queue = data[ type + "queue" ], + hooks = data[ type + "queueHooks" ], + timers = jQuery.timers, + length = queue ? queue.length : 0; + + // Enable finishing flag on private data + data.finish = true; + + // Empty the queue first + jQuery.queue( this, type, [] ); + + if ( hooks && hooks.stop ) { + hooks.stop.call( this, true ); + } + + // Look for any active animations, and finish them + for ( index = timers.length; index--; ) { + if ( timers[ index ].elem === this && timers[ index ].queue === type ) { + timers[ index ].anim.stop( true ); + timers.splice( index, 1 ); + } + } + + // Look for any animations in the old queue and finish them + for ( index = 0; index < length; index++ ) { + if ( queue[ index ] && queue[ index ].finish ) { + queue[ index ].finish.call( this ); + } + } + + // Turn off finishing flag + delete data.finish; + } ); + } +} ); + +jQuery.each( [ "toggle", "show", "hide" ], function( _i, name ) { + var cssFn = jQuery.fn[ name ]; + jQuery.fn[ name ] = function( speed, easing, callback ) { + return speed == null || typeof speed === "boolean" ? + cssFn.apply( this, arguments ) : + this.animate( genFx( name, true ), speed, easing, callback ); + }; +} ); + +// Generate shortcuts for custom animations +jQuery.each( { + slideDown: genFx( "show" ), + slideUp: genFx( "hide" ), + slideToggle: genFx( "toggle" ), + fadeIn: { opacity: "show" }, + fadeOut: { opacity: "hide" }, + fadeToggle: { opacity: "toggle" } +}, function( name, props ) { + jQuery.fn[ name ] = function( speed, easing, callback ) { + return this.animate( props, speed, easing, callback ); + }; +} ); + +jQuery.timers = []; +jQuery.fx.tick = function() { + var timer, + i = 0, + timers = jQuery.timers; + + fxNow = Date.now(); + + for ( ; i < timers.length; i++ ) { + timer = timers[ i ]; + + // Run the timer and safely remove it when done (allowing for external removal) + if ( !timer() && timers[ i ] === timer ) { + timers.splice( i--, 1 ); + } + } + + if ( !timers.length ) { + jQuery.fx.stop(); + } + fxNow = undefined; +}; + +jQuery.fx.timer = function( timer ) { + jQuery.timers.push( timer ); + jQuery.fx.start(); +}; + +jQuery.fx.interval = 13; +jQuery.fx.start = function() { + if ( inProgress ) { + return; + } + + inProgress = true; + schedule(); +}; + +jQuery.fx.stop = function() { + inProgress = null; +}; + +jQuery.fx.speeds = { + slow: 600, + fast: 200, + + // Default speed + _default: 400 +}; + + +// Based off of the plugin by Clint Helfers, with permission. +// https://web.archive.org/web/20100324014747/http://blindsignals.com/index.php/2009/07/jquery-delay/ +jQuery.fn.delay = function( time, type ) { + time = jQuery.fx ? jQuery.fx.speeds[ time ] || time : time; + type = type || "fx"; + + return this.queue( type, function( next, hooks ) { + var timeout = window.setTimeout( next, time ); + hooks.stop = function() { + window.clearTimeout( timeout ); + }; + } ); +}; + + +( function() { + var input = document.createElement( "input" ), + select = document.createElement( "select" ), + opt = select.appendChild( document.createElement( "option" ) ); + + input.type = "checkbox"; + + // Support: Android <=4.3 only + // Default value for a checkbox should be "on" + support.checkOn = input.value !== ""; + + // Support: IE <=11 only + // Must access selectedIndex to make default options select + support.optSelected = opt.selected; + + // Support: IE <=11 only + // An input loses its value after becoming a radio + input = document.createElement( "input" ); + input.value = "t"; + input.type = "radio"; + support.radioValue = input.value === "t"; +} )(); + + +var boolHook, + attrHandle = jQuery.expr.attrHandle; + +jQuery.fn.extend( { + attr: function( name, value ) { + return access( this, jQuery.attr, name, value, arguments.length > 1 ); + }, + + removeAttr: function( name ) { + return this.each( function() { + jQuery.removeAttr( this, name ); + } ); + } +} ); + +jQuery.extend( { + attr: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set attributes on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + // Fallback to prop when attributes are not supported + if ( typeof elem.getAttribute === "undefined" ) { + return jQuery.prop( elem, name, value ); + } + + // Attribute hooks are determined by the lowercase version + // Grab necessary hook if one is defined + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + hooks = jQuery.attrHooks[ name.toLowerCase() ] || + ( jQuery.expr.match.bool.test( name ) ? boolHook : undefined ); + } + + if ( value !== undefined ) { + if ( value === null ) { + jQuery.removeAttr( elem, name ); + return; + } + + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + elem.setAttribute( name, value + "" ); + return value; + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + ret = jQuery.find.attr( elem, name ); + + // Non-existent attributes return null, we normalize to undefined + return ret == null ? undefined : ret; + }, + + attrHooks: { + type: { + set: function( elem, value ) { + if ( !support.radioValue && value === "radio" && + nodeName( elem, "input" ) ) { + var val = elem.value; + elem.setAttribute( "type", value ); + if ( val ) { + elem.value = val; + } + return value; + } + } + } + }, + + removeAttr: function( elem, value ) { + var name, + i = 0, + + // Attribute names can contain non-HTML whitespace characters + // https://html.spec.whatwg.org/multipage/syntax.html#attributes-2 + attrNames = value && value.match( rnothtmlwhite ); + + if ( attrNames && elem.nodeType === 1 ) { + while ( ( name = attrNames[ i++ ] ) ) { + elem.removeAttribute( name ); + } + } + } +} ); + +// Hooks for boolean attributes +boolHook = { + set: function( elem, value, name ) { + if ( value === false ) { + + // Remove boolean attributes when set to false + jQuery.removeAttr( elem, name ); + } else { + elem.setAttribute( name, name ); + } + return name; + } +}; + +jQuery.each( jQuery.expr.match.bool.source.match( /\w+/g ), function( _i, name ) { + var getter = attrHandle[ name ] || jQuery.find.attr; + + attrHandle[ name ] = function( elem, name, isXML ) { + var ret, handle, + lowercaseName = name.toLowerCase(); + + if ( !isXML ) { + + // Avoid an infinite loop by temporarily removing this function from the getter + handle = attrHandle[ lowercaseName ]; + attrHandle[ lowercaseName ] = ret; + ret = getter( elem, name, isXML ) != null ? + lowercaseName : + null; + attrHandle[ lowercaseName ] = handle; + } + return ret; + }; +} ); + + + + +var rfocusable = /^(?:input|select|textarea|button)$/i, + rclickable = /^(?:a|area)$/i; + +jQuery.fn.extend( { + prop: function( name, value ) { + return access( this, jQuery.prop, name, value, arguments.length > 1 ); + }, + + removeProp: function( name ) { + return this.each( function() { + delete this[ jQuery.propFix[ name ] || name ]; + } ); + } +} ); + +jQuery.extend( { + prop: function( elem, name, value ) { + var ret, hooks, + nType = elem.nodeType; + + // Don't get/set properties on text, comment and attribute nodes + if ( nType === 3 || nType === 8 || nType === 2 ) { + return; + } + + if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) { + + // Fix name and attach hooks + name = jQuery.propFix[ name ] || name; + hooks = jQuery.propHooks[ name ]; + } + + if ( value !== undefined ) { + if ( hooks && "set" in hooks && + ( ret = hooks.set( elem, value, name ) ) !== undefined ) { + return ret; + } + + return ( elem[ name ] = value ); + } + + if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) { + return ret; + } + + return elem[ name ]; + }, + + propHooks: { + tabIndex: { + get: function( elem ) { + + // Support: IE <=9 - 11 only + // elem.tabIndex doesn't always return the + // correct value when it hasn't been explicitly set + // https://web.archive.org/web/20141116233347/http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/ + // Use proper attribute retrieval(#12072) + var tabindex = jQuery.find.attr( elem, "tabindex" ); + + if ( tabindex ) { + return parseInt( tabindex, 10 ); + } + + if ( + rfocusable.test( elem.nodeName ) || + rclickable.test( elem.nodeName ) && + elem.href + ) { + return 0; + } + + return -1; + } + } + }, + + propFix: { + "for": "htmlFor", + "class": "className" + } +} ); + +// Support: IE <=11 only +// Accessing the selectedIndex property +// forces the browser to respect setting selected +// on the option +// The getter ensures a default option is selected +// when in an optgroup +// eslint rule "no-unused-expressions" is disabled for this code +// since it considers such accessions noop +if ( !support.optSelected ) { + jQuery.propHooks.selected = { + get: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent && parent.parentNode ) { + parent.parentNode.selectedIndex; + } + return null; + }, + set: function( elem ) { + + /* eslint no-unused-expressions: "off" */ + + var parent = elem.parentNode; + if ( parent ) { + parent.selectedIndex; + + if ( parent.parentNode ) { + parent.parentNode.selectedIndex; + } + } + } + }; +} + +jQuery.each( [ + "tabIndex", + "readOnly", + "maxLength", + "cellSpacing", + "cellPadding", + "rowSpan", + "colSpan", + "useMap", + "frameBorder", + "contentEditable" +], function() { + jQuery.propFix[ this.toLowerCase() ] = this; +} ); + + + + + // Strip and collapse whitespace according to HTML spec + // https://infra.spec.whatwg.org/#strip-and-collapse-ascii-whitespace + function stripAndCollapse( value ) { + var tokens = value.match( rnothtmlwhite ) || []; + return tokens.join( " " ); + } + + +function getClass( elem ) { + return elem.getAttribute && elem.getAttribute( "class" ) || ""; +} + +function classesToArray( value ) { + if ( Array.isArray( value ) ) { + return value; + } + if ( typeof value === "string" ) { + return value.match( rnothtmlwhite ) || []; + } + return []; +} + +jQuery.fn.extend( { + addClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).addClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + if ( cur.indexOf( " " + clazz + " " ) < 0 ) { + cur += clazz + " "; + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + removeClass: function( value ) { + var classes, elem, cur, curValue, clazz, j, finalValue, + i = 0; + + if ( isFunction( value ) ) { + return this.each( function( j ) { + jQuery( this ).removeClass( value.call( this, j, getClass( this ) ) ); + } ); + } + + if ( !arguments.length ) { + return this.attr( "class", "" ); + } + + classes = classesToArray( value ); + + if ( classes.length ) { + while ( ( elem = this[ i++ ] ) ) { + curValue = getClass( elem ); + + // This expression is here for better compressibility (see addClass) + cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " ); + + if ( cur ) { + j = 0; + while ( ( clazz = classes[ j++ ] ) ) { + + // Remove *all* instances + while ( cur.indexOf( " " + clazz + " " ) > -1 ) { + cur = cur.replace( " " + clazz + " ", " " ); + } + } + + // Only assign if different to avoid unneeded rendering. + finalValue = stripAndCollapse( cur ); + if ( curValue !== finalValue ) { + elem.setAttribute( "class", finalValue ); + } + } + } + } + + return this; + }, + + toggleClass: function( value, stateVal ) { + var type = typeof value, + isValidValue = type === "string" || Array.isArray( value ); + + if ( typeof stateVal === "boolean" && isValidValue ) { + return stateVal ? this.addClass( value ) : this.removeClass( value ); + } + + if ( isFunction( value ) ) { + return this.each( function( i ) { + jQuery( this ).toggleClass( + value.call( this, i, getClass( this ), stateVal ), + stateVal + ); + } ); + } + + return this.each( function() { + var className, i, self, classNames; + + if ( isValidValue ) { + + // Toggle individual class names + i = 0; + self = jQuery( this ); + classNames = classesToArray( value ); + + while ( ( className = classNames[ i++ ] ) ) { + + // Check each className given, space separated list + if ( self.hasClass( className ) ) { + self.removeClass( className ); + } else { + self.addClass( className ); + } + } + + // Toggle whole class name + } else if ( value === undefined || type === "boolean" ) { + className = getClass( this ); + if ( className ) { + + // Store className if set + dataPriv.set( this, "__className__", className ); + } + + // If the element has a class name or if we're passed `false`, + // then remove the whole classname (if there was one, the above saved it). + // Otherwise bring back whatever was previously saved (if anything), + // falling back to the empty string if nothing was stored. + if ( this.setAttribute ) { + this.setAttribute( "class", + className || value === false ? + "" : + dataPriv.get( this, "__className__" ) || "" + ); + } + } + } ); + }, + + hasClass: function( selector ) { + var className, elem, + i = 0; + + className = " " + selector + " "; + while ( ( elem = this[ i++ ] ) ) { + if ( elem.nodeType === 1 && + ( " " + stripAndCollapse( getClass( elem ) ) + " " ).indexOf( className ) > -1 ) { + return true; + } + } + + return false; + } +} ); + + + + +var rreturn = /\r/g; + +jQuery.fn.extend( { + val: function( value ) { + var hooks, ret, valueIsFunction, + elem = this[ 0 ]; + + if ( !arguments.length ) { + if ( elem ) { + hooks = jQuery.valHooks[ elem.type ] || + jQuery.valHooks[ elem.nodeName.toLowerCase() ]; + + if ( hooks && + "get" in hooks && + ( ret = hooks.get( elem, "value" ) ) !== undefined + ) { + return ret; + } + + ret = elem.value; + + // Handle most common string cases + if ( typeof ret === "string" ) { + return ret.replace( rreturn, "" ); + } + + // Handle cases where value is null/undef or number + return ret == null ? "" : ret; + } + + return; + } + + valueIsFunction = isFunction( value ); + + return this.each( function( i ) { + var val; + + if ( this.nodeType !== 1 ) { + return; + } + + if ( valueIsFunction ) { + val = value.call( this, i, jQuery( this ).val() ); + } else { + val = value; + } + + // Treat null/undefined as ""; convert numbers to string + if ( val == null ) { + val = ""; + + } else if ( typeof val === "number" ) { + val += ""; + + } else if ( Array.isArray( val ) ) { + val = jQuery.map( val, function( value ) { + return value == null ? "" : value + ""; + } ); + } + + hooks = jQuery.valHooks[ this.type ] || jQuery.valHooks[ this.nodeName.toLowerCase() ]; + + // If set returns undefined, fall back to normal setting + if ( !hooks || !( "set" in hooks ) || hooks.set( this, val, "value" ) === undefined ) { + this.value = val; + } + } ); + } +} ); + +jQuery.extend( { + valHooks: { + option: { + get: function( elem ) { + + var val = jQuery.find.attr( elem, "value" ); + return val != null ? + val : + + // Support: IE <=10 - 11 only + // option.text throws exceptions (#14686, #14858) + // Strip and collapse whitespace + // https://html.spec.whatwg.org/#strip-and-collapse-whitespace + stripAndCollapse( jQuery.text( elem ) ); + } + }, + select: { + get: function( elem ) { + var value, option, i, + options = elem.options, + index = elem.selectedIndex, + one = elem.type === "select-one", + values = one ? null : [], + max = one ? index + 1 : options.length; + + if ( index < 0 ) { + i = max; + + } else { + i = one ? index : 0; + } + + // Loop through all the selected options + for ( ; i < max; i++ ) { + option = options[ i ]; + + // Support: IE <=9 only + // IE8-9 doesn't update selected after form reset (#2551) + if ( ( option.selected || i === index ) && + + // Don't return options that are disabled or in a disabled optgroup + !option.disabled && + ( !option.parentNode.disabled || + !nodeName( option.parentNode, "optgroup" ) ) ) { + + // Get the specific value for the option + value = jQuery( option ).val(); + + // We don't need an array for one selects + if ( one ) { + return value; + } + + // Multi-Selects return an array + values.push( value ); + } + } + + return values; + }, + + set: function( elem, value ) { + var optionSet, option, + options = elem.options, + values = jQuery.makeArray( value ), + i = options.length; + + while ( i-- ) { + option = options[ i ]; + + /* eslint-disable no-cond-assign */ + + if ( option.selected = + jQuery.inArray( jQuery.valHooks.option.get( option ), values ) > -1 + ) { + optionSet = true; + } + + /* eslint-enable no-cond-assign */ + } + + // Force browsers to behave consistently when non-matching value is set + if ( !optionSet ) { + elem.selectedIndex = -1; + } + return values; + } + } + } +} ); + +// Radios and checkboxes getter/setter +jQuery.each( [ "radio", "checkbox" ], function() { + jQuery.valHooks[ this ] = { + set: function( elem, value ) { + if ( Array.isArray( value ) ) { + return ( elem.checked = jQuery.inArray( jQuery( elem ).val(), value ) > -1 ); + } + } + }; + if ( !support.checkOn ) { + jQuery.valHooks[ this ].get = function( elem ) { + return elem.getAttribute( "value" ) === null ? "on" : elem.value; + }; + } +} ); + + + + +// Return jQuery for attributes-only inclusion + + +support.focusin = "onfocusin" in window; + + +var rfocusMorph = /^(?:focusinfocus|focusoutblur)$/, + stopPropagationCallback = function( e ) { + e.stopPropagation(); + }; + +jQuery.extend( jQuery.event, { + + trigger: function( event, data, elem, onlyHandlers ) { + + var i, cur, tmp, bubbleType, ontype, handle, special, lastElement, + eventPath = [ elem || document ], + type = hasOwn.call( event, "type" ) ? event.type : event, + namespaces = hasOwn.call( event, "namespace" ) ? event.namespace.split( "." ) : []; + + cur = lastElement = tmp = elem = elem || document; + + // Don't do events on text and comment nodes + if ( elem.nodeType === 3 || elem.nodeType === 8 ) { + return; + } + + // focus/blur morphs to focusin/out; ensure we're not firing them right now + if ( rfocusMorph.test( type + jQuery.event.triggered ) ) { + return; + } + + if ( type.indexOf( "." ) > -1 ) { + + // Namespaced trigger; create a regexp to match event type in handle() + namespaces = type.split( "." ); + type = namespaces.shift(); + namespaces.sort(); + } + ontype = type.indexOf( ":" ) < 0 && "on" + type; + + // Caller can pass in a jQuery.Event object, Object, or just an event type string + event = event[ jQuery.expando ] ? + event : + new jQuery.Event( type, typeof event === "object" && event ); + + // Trigger bitmask: & 1 for native handlers; & 2 for jQuery (always true) + event.isTrigger = onlyHandlers ? 2 : 3; + event.namespace = namespaces.join( "." ); + event.rnamespace = event.namespace ? + new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ) : + null; + + // Clean up the event in case it is being reused + event.result = undefined; + if ( !event.target ) { + event.target = elem; + } + + // Clone any incoming data and prepend the event, creating the handler arg list + data = data == null ? + [ event ] : + jQuery.makeArray( data, [ event ] ); + + // Allow special events to draw outside the lines + special = jQuery.event.special[ type ] || {}; + if ( !onlyHandlers && special.trigger && special.trigger.apply( elem, data ) === false ) { + return; + } + + // Determine event propagation path in advance, per W3C events spec (#9951) + // Bubble up to document, then to window; watch for a global ownerDocument var (#9724) + if ( !onlyHandlers && !special.noBubble && !isWindow( elem ) ) { + + bubbleType = special.delegateType || type; + if ( !rfocusMorph.test( bubbleType + type ) ) { + cur = cur.parentNode; + } + for ( ; cur; cur = cur.parentNode ) { + eventPath.push( cur ); + tmp = cur; + } + + // Only add window if we got to document (e.g., not plain obj or detached DOM) + if ( tmp === ( elem.ownerDocument || document ) ) { + eventPath.push( tmp.defaultView || tmp.parentWindow || window ); + } + } + + // Fire handlers on the event path + i = 0; + while ( ( cur = eventPath[ i++ ] ) && !event.isPropagationStopped() ) { + lastElement = cur; + event.type = i > 1 ? + bubbleType : + special.bindType || type; + + // jQuery handler + handle = ( + dataPriv.get( cur, "events" ) || Object.create( null ) + )[ event.type ] && + dataPriv.get( cur, "handle" ); + if ( handle ) { + handle.apply( cur, data ); + } + + // Native handler + handle = ontype && cur[ ontype ]; + if ( handle && handle.apply && acceptData( cur ) ) { + event.result = handle.apply( cur, data ); + if ( event.result === false ) { + event.preventDefault(); + } + } + } + event.type = type; + + // If nobody prevented the default action, do it now + if ( !onlyHandlers && !event.isDefaultPrevented() ) { + + if ( ( !special._default || + special._default.apply( eventPath.pop(), data ) === false ) && + acceptData( elem ) ) { + + // Call a native DOM method on the target with the same name as the event. + // Don't do default actions on window, that's where global variables be (#6170) + if ( ontype && isFunction( elem[ type ] ) && !isWindow( elem ) ) { + + // Don't re-trigger an onFOO event when we call its FOO() method + tmp = elem[ ontype ]; + + if ( tmp ) { + elem[ ontype ] = null; + } + + // Prevent re-triggering of the same event, since we already bubbled it above + jQuery.event.triggered = type; + + if ( event.isPropagationStopped() ) { + lastElement.addEventListener( type, stopPropagationCallback ); + } + + elem[ type ](); + + if ( event.isPropagationStopped() ) { + lastElement.removeEventListener( type, stopPropagationCallback ); + } + + jQuery.event.triggered = undefined; + + if ( tmp ) { + elem[ ontype ] = tmp; + } + } + } + } + + return event.result; + }, + + // Piggyback on a donor event to simulate a different one + // Used only for `focus(in | out)` events + simulate: function( type, elem, event ) { + var e = jQuery.extend( + new jQuery.Event(), + event, + { + type: type, + isSimulated: true + } + ); + + jQuery.event.trigger( e, null, elem ); + } + +} ); + +jQuery.fn.extend( { + + trigger: function( type, data ) { + return this.each( function() { + jQuery.event.trigger( type, data, this ); + } ); + }, + triggerHandler: function( type, data ) { + var elem = this[ 0 ]; + if ( elem ) { + return jQuery.event.trigger( type, data, elem, true ); + } + } +} ); + + +// Support: Firefox <=44 +// Firefox doesn't have focus(in | out) events +// Related ticket - https://bugzilla.mozilla.org/show_bug.cgi?id=687787 +// +// Support: Chrome <=48 - 49, Safari <=9.0 - 9.1 +// focus(in | out) events fire after focus & blur events, +// which is spec violation - http://www.w3.org/TR/DOM-Level-3-Events/#events-focusevent-event-order +// Related ticket - https://bugs.chromium.org/p/chromium/issues/detail?id=449857 +if ( !support.focusin ) { + jQuery.each( { focus: "focusin", blur: "focusout" }, function( orig, fix ) { + + // Attach a single capturing handler on the document while someone wants focusin/focusout + var handler = function( event ) { + jQuery.event.simulate( fix, event.target, jQuery.event.fix( event ) ); + }; + + jQuery.event.special[ fix ] = { + setup: function() { + + // Handle: regular nodes (via `this.ownerDocument`), window + // (via `this.document`) & document (via `this`). + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ); + + if ( !attaches ) { + doc.addEventListener( orig, handler, true ); + } + dataPriv.access( doc, fix, ( attaches || 0 ) + 1 ); + }, + teardown: function() { + var doc = this.ownerDocument || this.document || this, + attaches = dataPriv.access( doc, fix ) - 1; + + if ( !attaches ) { + doc.removeEventListener( orig, handler, true ); + dataPriv.remove( doc, fix ); + + } else { + dataPriv.access( doc, fix, attaches ); + } + } + }; + } ); +} +var location = window.location; + +var nonce = { guid: Date.now() }; + +var rquery = ( /\?/ ); + + + +// Cross-browser xml parsing +jQuery.parseXML = function( data ) { + var xml; + if ( !data || typeof data !== "string" ) { + return null; + } + + // Support: IE 9 - 11 only + // IE throws on parseFromString with invalid input. + try { + xml = ( new window.DOMParser() ).parseFromString( data, "text/xml" ); + } catch ( e ) { + xml = undefined; + } + + if ( !xml || xml.getElementsByTagName( "parsererror" ).length ) { + jQuery.error( "Invalid XML: " + data ); + } + return xml; +}; + + +var + rbracket = /\[\]$/, + rCRLF = /\r?\n/g, + rsubmitterTypes = /^(?:submit|button|image|reset|file)$/i, + rsubmittable = /^(?:input|select|textarea|keygen)/i; + +function buildParams( prefix, obj, traditional, add ) { + var name; + + if ( Array.isArray( obj ) ) { + + // Serialize array item. + jQuery.each( obj, function( i, v ) { + if ( traditional || rbracket.test( prefix ) ) { + + // Treat each array item as a scalar. + add( prefix, v ); + + } else { + + // Item is non-scalar (array or object), encode its numeric index. + buildParams( + prefix + "[" + ( typeof v === "object" && v != null ? i : "" ) + "]", + v, + traditional, + add + ); + } + } ); + + } else if ( !traditional && toType( obj ) === "object" ) { + + // Serialize object item. + for ( name in obj ) { + buildParams( prefix + "[" + name + "]", obj[ name ], traditional, add ); + } + + } else { + + // Serialize scalar item. + add( prefix, obj ); + } +} + +// Serialize an array of form elements or a set of +// key/values into a query string +jQuery.param = function( a, traditional ) { + var prefix, + s = [], + add = function( key, valueOrFunction ) { + + // If value is a function, invoke it and use its return value + var value = isFunction( valueOrFunction ) ? + valueOrFunction() : + valueOrFunction; + + s[ s.length ] = encodeURIComponent( key ) + "=" + + encodeURIComponent( value == null ? "" : value ); + }; + + if ( a == null ) { + return ""; + } + + // If an array was passed in, assume that it is an array of form elements. + if ( Array.isArray( a ) || ( a.jquery && !jQuery.isPlainObject( a ) ) ) { + + // Serialize the form elements + jQuery.each( a, function() { + add( this.name, this.value ); + } ); + + } else { + + // If traditional, encode the "old" way (the way 1.3.2 or older + // did it), otherwise encode params recursively. + for ( prefix in a ) { + buildParams( prefix, a[ prefix ], traditional, add ); + } + } + + // Return the resulting serialization + return s.join( "&" ); +}; + +jQuery.fn.extend( { + serialize: function() { + return jQuery.param( this.serializeArray() ); + }, + serializeArray: function() { + return this.map( function() { + + // Can add propHook for "elements" to filter or add form elements + var elements = jQuery.prop( this, "elements" ); + return elements ? jQuery.makeArray( elements ) : this; + } ) + .filter( function() { + var type = this.type; + + // Use .is( ":disabled" ) so that fieldset[disabled] works + return this.name && !jQuery( this ).is( ":disabled" ) && + rsubmittable.test( this.nodeName ) && !rsubmitterTypes.test( type ) && + ( this.checked || !rcheckableType.test( type ) ); + } ) + .map( function( _i, elem ) { + var val = jQuery( this ).val(); + + if ( val == null ) { + return null; + } + + if ( Array.isArray( val ) ) { + return jQuery.map( val, function( val ) { + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ); + } + + return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) }; + } ).get(); + } +} ); + + +var + r20 = /%20/g, + rhash = /#.*$/, + rantiCache = /([?&])_=[^&]*/, + rheaders = /^(.*?):[ \t]*([^\r\n]*)$/mg, + + // #7653, #8125, #8152: local protocol detection + rlocalProtocol = /^(?:about|app|app-storage|.+-extension|file|res|widget):$/, + rnoContent = /^(?:GET|HEAD)$/, + rprotocol = /^\/\//, + + /* Prefilters + * 1) They are useful to introduce custom dataTypes (see ajax/jsonp.js for an example) + * 2) These are called: + * - BEFORE asking for a transport + * - AFTER param serialization (s.data is a string if s.processData is true) + * 3) key is the dataType + * 4) the catchall symbol "*" can be used + * 5) execution will start with transport dataType and THEN continue down to "*" if needed + */ + prefilters = {}, + + /* Transports bindings + * 1) key is the dataType + * 2) the catchall symbol "*" can be used + * 3) selection will start with transport dataType and THEN go to "*" if needed + */ + transports = {}, + + // Avoid comment-prolog char sequence (#10098); must appease lint and evade compression + allTypes = "*/".concat( "*" ), + + // Anchor tag for parsing the document origin + originAnchor = document.createElement( "a" ); + originAnchor.href = location.href; + +// Base "constructor" for jQuery.ajaxPrefilter and jQuery.ajaxTransport +function addToPrefiltersOrTransports( structure ) { + + // dataTypeExpression is optional and defaults to "*" + return function( dataTypeExpression, func ) { + + if ( typeof dataTypeExpression !== "string" ) { + func = dataTypeExpression; + dataTypeExpression = "*"; + } + + var dataType, + i = 0, + dataTypes = dataTypeExpression.toLowerCase().match( rnothtmlwhite ) || []; + + if ( isFunction( func ) ) { + + // For each dataType in the dataTypeExpression + while ( ( dataType = dataTypes[ i++ ] ) ) { + + // Prepend if requested + if ( dataType[ 0 ] === "+" ) { + dataType = dataType.slice( 1 ) || "*"; + ( structure[ dataType ] = structure[ dataType ] || [] ).unshift( func ); + + // Otherwise append + } else { + ( structure[ dataType ] = structure[ dataType ] || [] ).push( func ); + } + } + } + }; +} + +// Base inspection function for prefilters and transports +function inspectPrefiltersOrTransports( structure, options, originalOptions, jqXHR ) { + + var inspected = {}, + seekingTransport = ( structure === transports ); + + function inspect( dataType ) { + var selected; + inspected[ dataType ] = true; + jQuery.each( structure[ dataType ] || [], function( _, prefilterOrFactory ) { + var dataTypeOrTransport = prefilterOrFactory( options, originalOptions, jqXHR ); + if ( typeof dataTypeOrTransport === "string" && + !seekingTransport && !inspected[ dataTypeOrTransport ] ) { + + options.dataTypes.unshift( dataTypeOrTransport ); + inspect( dataTypeOrTransport ); + return false; + } else if ( seekingTransport ) { + return !( selected = dataTypeOrTransport ); + } + } ); + return selected; + } + + return inspect( options.dataTypes[ 0 ] ) || !inspected[ "*" ] && inspect( "*" ); +} + +// A special extend for ajax options +// that takes "flat" options (not to be deep extended) +// Fixes #9887 +function ajaxExtend( target, src ) { + var key, deep, + flatOptions = jQuery.ajaxSettings.flatOptions || {}; + + for ( key in src ) { + if ( src[ key ] !== undefined ) { + ( flatOptions[ key ] ? target : ( deep || ( deep = {} ) ) )[ key ] = src[ key ]; + } + } + if ( deep ) { + jQuery.extend( true, target, deep ); + } + + return target; +} + +/* Handles responses to an ajax request: + * - finds the right dataType (mediates between content-type and expected dataType) + * - returns the corresponding response + */ +function ajaxHandleResponses( s, jqXHR, responses ) { + + var ct, type, finalDataType, firstDataType, + contents = s.contents, + dataTypes = s.dataTypes; + + // Remove auto dataType and get content-type in the process + while ( dataTypes[ 0 ] === "*" ) { + dataTypes.shift(); + if ( ct === undefined ) { + ct = s.mimeType || jqXHR.getResponseHeader( "Content-Type" ); + } + } + + // Check if we're dealing with a known content-type + if ( ct ) { + for ( type in contents ) { + if ( contents[ type ] && contents[ type ].test( ct ) ) { + dataTypes.unshift( type ); + break; + } + } + } + + // Check to see if we have a response for the expected dataType + if ( dataTypes[ 0 ] in responses ) { + finalDataType = dataTypes[ 0 ]; + } else { + + // Try convertible dataTypes + for ( type in responses ) { + if ( !dataTypes[ 0 ] || s.converters[ type + " " + dataTypes[ 0 ] ] ) { + finalDataType = type; + break; + } + if ( !firstDataType ) { + firstDataType = type; + } + } + + // Or just use first one + finalDataType = finalDataType || firstDataType; + } + + // If we found a dataType + // We add the dataType to the list if needed + // and return the corresponding response + if ( finalDataType ) { + if ( finalDataType !== dataTypes[ 0 ] ) { + dataTypes.unshift( finalDataType ); + } + return responses[ finalDataType ]; + } +} + +/* Chain conversions given the request and the original response + * Also sets the responseXXX fields on the jqXHR instance + */ +function ajaxConvert( s, response, jqXHR, isSuccess ) { + var conv2, current, conv, tmp, prev, + converters = {}, + + // Work with a copy of dataTypes in case we need to modify it for conversion + dataTypes = s.dataTypes.slice(); + + // Create converters map with lowercased keys + if ( dataTypes[ 1 ] ) { + for ( conv in s.converters ) { + converters[ conv.toLowerCase() ] = s.converters[ conv ]; + } + } + + current = dataTypes.shift(); + + // Convert to each sequential dataType + while ( current ) { + + if ( s.responseFields[ current ] ) { + jqXHR[ s.responseFields[ current ] ] = response; + } + + // Apply the dataFilter if provided + if ( !prev && isSuccess && s.dataFilter ) { + response = s.dataFilter( response, s.dataType ); + } + + prev = current; + current = dataTypes.shift(); + + if ( current ) { + + // There's only work to do if current dataType is non-auto + if ( current === "*" ) { + + current = prev; + + // Convert response if prev dataType is non-auto and differs from current + } else if ( prev !== "*" && prev !== current ) { + + // Seek a direct converter + conv = converters[ prev + " " + current ] || converters[ "* " + current ]; + + // If none found, seek a pair + if ( !conv ) { + for ( conv2 in converters ) { + + // If conv2 outputs current + tmp = conv2.split( " " ); + if ( tmp[ 1 ] === current ) { + + // If prev can be converted to accepted input + conv = converters[ prev + " " + tmp[ 0 ] ] || + converters[ "* " + tmp[ 0 ] ]; + if ( conv ) { + + // Condense equivalence converters + if ( conv === true ) { + conv = converters[ conv2 ]; + + // Otherwise, insert the intermediate dataType + } else if ( converters[ conv2 ] !== true ) { + current = tmp[ 0 ]; + dataTypes.unshift( tmp[ 1 ] ); + } + break; + } + } + } + } + + // Apply converter (if not an equivalence) + if ( conv !== true ) { + + // Unless errors are allowed to bubble, catch and return them + if ( conv && s.throws ) { + response = conv( response ); + } else { + try { + response = conv( response ); + } catch ( e ) { + return { + state: "parsererror", + error: conv ? e : "No conversion from " + prev + " to " + current + }; + } + } + } + } + } + } + + return { state: "success", data: response }; +} + +jQuery.extend( { + + // Counter for holding the number of active queries + active: 0, + + // Last-Modified header cache for next request + lastModified: {}, + etag: {}, + + ajaxSettings: { + url: location.href, + type: "GET", + isLocal: rlocalProtocol.test( location.protocol ), + global: true, + processData: true, + async: true, + contentType: "application/x-www-form-urlencoded; charset=UTF-8", + + /* + timeout: 0, + data: null, + dataType: null, + username: null, + password: null, + cache: null, + throws: false, + traditional: false, + headers: {}, + */ + + accepts: { + "*": allTypes, + text: "text/plain", + html: "text/html", + xml: "application/xml, text/xml", + json: "application/json, text/javascript" + }, + + contents: { + xml: /\bxml\b/, + html: /\bhtml/, + json: /\bjson\b/ + }, + + responseFields: { + xml: "responseXML", + text: "responseText", + json: "responseJSON" + }, + + // Data converters + // Keys separate source (or catchall "*") and destination types with a single space + converters: { + + // Convert anything to text + "* text": String, + + // Text to html (true = no transformation) + "text html": true, + + // Evaluate text as a json expression + "text json": JSON.parse, + + // Parse text as xml + "text xml": jQuery.parseXML + }, + + // For options that shouldn't be deep extended: + // you can add your own custom options here if + // and when you create one that shouldn't be + // deep extended (see ajaxExtend) + flatOptions: { + url: true, + context: true + } + }, + + // Creates a full fledged settings object into target + // with both ajaxSettings and settings fields. + // If target is omitted, writes into ajaxSettings. + ajaxSetup: function( target, settings ) { + return settings ? + + // Building a settings object + ajaxExtend( ajaxExtend( target, jQuery.ajaxSettings ), settings ) : + + // Extending ajaxSettings + ajaxExtend( jQuery.ajaxSettings, target ); + }, + + ajaxPrefilter: addToPrefiltersOrTransports( prefilters ), + ajaxTransport: addToPrefiltersOrTransports( transports ), + + // Main method + ajax: function( url, options ) { + + // If url is an object, simulate pre-1.5 signature + if ( typeof url === "object" ) { + options = url; + url = undefined; + } + + // Force options to be an object + options = options || {}; + + var transport, + + // URL without anti-cache param + cacheURL, + + // Response headers + responseHeadersString, + responseHeaders, + + // timeout handle + timeoutTimer, + + // Url cleanup var + urlAnchor, + + // Request state (becomes false upon send and true upon completion) + completed, + + // To know if global events are to be dispatched + fireGlobals, + + // Loop variable + i, + + // uncached part of the url + uncached, + + // Create the final options object + s = jQuery.ajaxSetup( {}, options ), + + // Callbacks context + callbackContext = s.context || s, + + // Context for global events is callbackContext if it is a DOM node or jQuery collection + globalEventContext = s.context && + ( callbackContext.nodeType || callbackContext.jquery ) ? + jQuery( callbackContext ) : + jQuery.event, + + // Deferreds + deferred = jQuery.Deferred(), + completeDeferred = jQuery.Callbacks( "once memory" ), + + // Status-dependent callbacks + statusCode = s.statusCode || {}, + + // Headers (they are sent all at once) + requestHeaders = {}, + requestHeadersNames = {}, + + // Default abort message + strAbort = "canceled", + + // Fake xhr + jqXHR = { + readyState: 0, + + // Builds headers hashtable if needed + getResponseHeader: function( key ) { + var match; + if ( completed ) { + if ( !responseHeaders ) { + responseHeaders = {}; + while ( ( match = rheaders.exec( responseHeadersString ) ) ) { + responseHeaders[ match[ 1 ].toLowerCase() + " " ] = + ( responseHeaders[ match[ 1 ].toLowerCase() + " " ] || [] ) + .concat( match[ 2 ] ); + } + } + match = responseHeaders[ key.toLowerCase() + " " ]; + } + return match == null ? null : match.join( ", " ); + }, + + // Raw string + getAllResponseHeaders: function() { + return completed ? responseHeadersString : null; + }, + + // Caches the header + setRequestHeader: function( name, value ) { + if ( completed == null ) { + name = requestHeadersNames[ name.toLowerCase() ] = + requestHeadersNames[ name.toLowerCase() ] || name; + requestHeaders[ name ] = value; + } + return this; + }, + + // Overrides response content-type header + overrideMimeType: function( type ) { + if ( completed == null ) { + s.mimeType = type; + } + return this; + }, + + // Status-dependent callbacks + statusCode: function( map ) { + var code; + if ( map ) { + if ( completed ) { + + // Execute the appropriate callbacks + jqXHR.always( map[ jqXHR.status ] ); + } else { + + // Lazy-add the new callbacks in a way that preserves old ones + for ( code in map ) { + statusCode[ code ] = [ statusCode[ code ], map[ code ] ]; + } + } + } + return this; + }, + + // Cancel the request + abort: function( statusText ) { + var finalText = statusText || strAbort; + if ( transport ) { + transport.abort( finalText ); + } + done( 0, finalText ); + return this; + } + }; + + // Attach deferreds + deferred.promise( jqXHR ); + + // Add protocol if not provided (prefilters might expect it) + // Handle falsy url in the settings object (#10093: consistency with old signature) + // We also use the url parameter if available + s.url = ( ( url || s.url || location.href ) + "" ) + .replace( rprotocol, location.protocol + "//" ); + + // Alias method option to type as per ticket #12004 + s.type = options.method || options.type || s.method || s.type; + + // Extract dataTypes list + s.dataTypes = ( s.dataType || "*" ).toLowerCase().match( rnothtmlwhite ) || [ "" ]; + + // A cross-domain request is in order when the origin doesn't match the current origin. + if ( s.crossDomain == null ) { + urlAnchor = document.createElement( "a" ); + + // Support: IE <=8 - 11, Edge 12 - 15 + // IE throws exception on accessing the href property if url is malformed, + // e.g. http://example.com:80x/ + try { + urlAnchor.href = s.url; + + // Support: IE <=8 - 11 only + // Anchor's host property isn't correctly set when s.url is relative + urlAnchor.href = urlAnchor.href; + s.crossDomain = originAnchor.protocol + "//" + originAnchor.host !== + urlAnchor.protocol + "//" + urlAnchor.host; + } catch ( e ) { + + // If there is an error parsing the URL, assume it is crossDomain, + // it can be rejected by the transport if it is invalid + s.crossDomain = true; + } + } + + // Convert data if not already a string + if ( s.data && s.processData && typeof s.data !== "string" ) { + s.data = jQuery.param( s.data, s.traditional ); + } + + // Apply prefilters + inspectPrefiltersOrTransports( prefilters, s, options, jqXHR ); + + // If request was aborted inside a prefilter, stop there + if ( completed ) { + return jqXHR; + } + + // We can fire global events as of now if asked to + // Don't fire events if jQuery.event is undefined in an AMD-usage scenario (#15118) + fireGlobals = jQuery.event && s.global; + + // Watch for a new set of requests + if ( fireGlobals && jQuery.active++ === 0 ) { + jQuery.event.trigger( "ajaxStart" ); + } + + // Uppercase the type + s.type = s.type.toUpperCase(); + + // Determine if request has content + s.hasContent = !rnoContent.test( s.type ); + + // Save the URL in case we're toying with the If-Modified-Since + // and/or If-None-Match header later on + // Remove hash to simplify url manipulation + cacheURL = s.url.replace( rhash, "" ); + + // More options handling for requests with no content + if ( !s.hasContent ) { + + // Remember the hash so we can put it back + uncached = s.url.slice( cacheURL.length ); + + // If data is available and should be processed, append data to url + if ( s.data && ( s.processData || typeof s.data === "string" ) ) { + cacheURL += ( rquery.test( cacheURL ) ? "&" : "?" ) + s.data; + + // #9682: remove data so that it's not used in an eventual retry + delete s.data; + } + + // Add or update anti-cache param if needed + if ( s.cache === false ) { + cacheURL = cacheURL.replace( rantiCache, "$1" ); + uncached = ( rquery.test( cacheURL ) ? "&" : "?" ) + "_=" + ( nonce.guid++ ) + + uncached; + } + + // Put hash and anti-cache on the URL that will be requested (gh-1732) + s.url = cacheURL + uncached; + + // Change '%20' to '+' if this is encoded form body content (gh-2658) + } else if ( s.data && s.processData && + ( s.contentType || "" ).indexOf( "application/x-www-form-urlencoded" ) === 0 ) { + s.data = s.data.replace( r20, "+" ); + } + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + if ( jQuery.lastModified[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-Modified-Since", jQuery.lastModified[ cacheURL ] ); + } + if ( jQuery.etag[ cacheURL ] ) { + jqXHR.setRequestHeader( "If-None-Match", jQuery.etag[ cacheURL ] ); + } + } + + // Set the correct header, if data is being sent + if ( s.data && s.hasContent && s.contentType !== false || options.contentType ) { + jqXHR.setRequestHeader( "Content-Type", s.contentType ); + } + + // Set the Accepts header for the server, depending on the dataType + jqXHR.setRequestHeader( + "Accept", + s.dataTypes[ 0 ] && s.accepts[ s.dataTypes[ 0 ] ] ? + s.accepts[ s.dataTypes[ 0 ] ] + + ( s.dataTypes[ 0 ] !== "*" ? ", " + allTypes + "; q=0.01" : "" ) : + s.accepts[ "*" ] + ); + + // Check for headers option + for ( i in s.headers ) { + jqXHR.setRequestHeader( i, s.headers[ i ] ); + } + + // Allow custom headers/mimetypes and early abort + if ( s.beforeSend && + ( s.beforeSend.call( callbackContext, jqXHR, s ) === false || completed ) ) { + + // Abort if not done already and return + return jqXHR.abort(); + } + + // Aborting is no longer a cancellation + strAbort = "abort"; + + // Install callbacks on deferreds + completeDeferred.add( s.complete ); + jqXHR.done( s.success ); + jqXHR.fail( s.error ); + + // Get transport + transport = inspectPrefiltersOrTransports( transports, s, options, jqXHR ); + + // If no transport, we auto-abort + if ( !transport ) { + done( -1, "No Transport" ); + } else { + jqXHR.readyState = 1; + + // Send global event + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxSend", [ jqXHR, s ] ); + } + + // If request was aborted inside ajaxSend, stop there + if ( completed ) { + return jqXHR; + } + + // Timeout + if ( s.async && s.timeout > 0 ) { + timeoutTimer = window.setTimeout( function() { + jqXHR.abort( "timeout" ); + }, s.timeout ); + } + + try { + completed = false; + transport.send( requestHeaders, done ); + } catch ( e ) { + + // Rethrow post-completion exceptions + if ( completed ) { + throw e; + } + + // Propagate others as results + done( -1, e ); + } + } + + // Callback for when everything is done + function done( status, nativeStatusText, responses, headers ) { + var isSuccess, success, error, response, modified, + statusText = nativeStatusText; + + // Ignore repeat invocations + if ( completed ) { + return; + } + + completed = true; + + // Clear timeout if it exists + if ( timeoutTimer ) { + window.clearTimeout( timeoutTimer ); + } + + // Dereference transport for early garbage collection + // (no matter how long the jqXHR object will be used) + transport = undefined; + + // Cache response headers + responseHeadersString = headers || ""; + + // Set readyState + jqXHR.readyState = status > 0 ? 4 : 0; + + // Determine if successful + isSuccess = status >= 200 && status < 300 || status === 304; + + // Get response data + if ( responses ) { + response = ajaxHandleResponses( s, jqXHR, responses ); + } + + // Use a noop converter for missing script + if ( !isSuccess && jQuery.inArray( "script", s.dataTypes ) > -1 ) { + s.converters[ "text script" ] = function() {}; + } + + // Convert no matter what (that way responseXXX fields are always set) + response = ajaxConvert( s, response, jqXHR, isSuccess ); + + // If successful, handle type chaining + if ( isSuccess ) { + + // Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode. + if ( s.ifModified ) { + modified = jqXHR.getResponseHeader( "Last-Modified" ); + if ( modified ) { + jQuery.lastModified[ cacheURL ] = modified; + } + modified = jqXHR.getResponseHeader( "etag" ); + if ( modified ) { + jQuery.etag[ cacheURL ] = modified; + } + } + + // if no content + if ( status === 204 || s.type === "HEAD" ) { + statusText = "nocontent"; + + // if not modified + } else if ( status === 304 ) { + statusText = "notmodified"; + + // If we have data, let's convert it + } else { + statusText = response.state; + success = response.data; + error = response.error; + isSuccess = !error; + } + } else { + + // Extract error from statusText and normalize for non-aborts + error = statusText; + if ( status || !statusText ) { + statusText = "error"; + if ( status < 0 ) { + status = 0; + } + } + } + + // Set data for the fake xhr object + jqXHR.status = status; + jqXHR.statusText = ( nativeStatusText || statusText ) + ""; + + // Success/Error + if ( isSuccess ) { + deferred.resolveWith( callbackContext, [ success, statusText, jqXHR ] ); + } else { + deferred.rejectWith( callbackContext, [ jqXHR, statusText, error ] ); + } + + // Status-dependent callbacks + jqXHR.statusCode( statusCode ); + statusCode = undefined; + + if ( fireGlobals ) { + globalEventContext.trigger( isSuccess ? "ajaxSuccess" : "ajaxError", + [ jqXHR, s, isSuccess ? success : error ] ); + } + + // Complete + completeDeferred.fireWith( callbackContext, [ jqXHR, statusText ] ); + + if ( fireGlobals ) { + globalEventContext.trigger( "ajaxComplete", [ jqXHR, s ] ); + + // Handle the global AJAX counter + if ( !( --jQuery.active ) ) { + jQuery.event.trigger( "ajaxStop" ); + } + } + } + + return jqXHR; + }, + + getJSON: function( url, data, callback ) { + return jQuery.get( url, data, callback, "json" ); + }, + + getScript: function( url, callback ) { + return jQuery.get( url, undefined, callback, "script" ); + } +} ); + +jQuery.each( [ "get", "post" ], function( _i, method ) { + jQuery[ method ] = function( url, data, callback, type ) { + + // Shift arguments if data argument was omitted + if ( isFunction( data ) ) { + type = type || callback; + callback = data; + data = undefined; + } + + // The url can be an options object (which then must have .url) + return jQuery.ajax( jQuery.extend( { + url: url, + type: method, + dataType: type, + data: data, + success: callback + }, jQuery.isPlainObject( url ) && url ) ); + }; +} ); + +jQuery.ajaxPrefilter( function( s ) { + var i; + for ( i in s.headers ) { + if ( i.toLowerCase() === "content-type" ) { + s.contentType = s.headers[ i ] || ""; + } + } +} ); + + +jQuery._evalUrl = function( url, options, doc ) { + return jQuery.ajax( { + url: url, + + // Make this explicit, since user can override this through ajaxSetup (#11264) + type: "GET", + dataType: "script", + cache: true, + async: false, + global: false, + + // Only evaluate the response if it is successful (gh-4126) + // dataFilter is not invoked for failure responses, so using it instead + // of the default converter is kludgy but it works. + converters: { + "text script": function() {} + }, + dataFilter: function( response ) { + jQuery.globalEval( response, options, doc ); + } + } ); +}; + + +jQuery.fn.extend( { + wrapAll: function( html ) { + var wrap; + + if ( this[ 0 ] ) { + if ( isFunction( html ) ) { + html = html.call( this[ 0 ] ); + } + + // The elements to wrap the target around + wrap = jQuery( html, this[ 0 ].ownerDocument ).eq( 0 ).clone( true ); + + if ( this[ 0 ].parentNode ) { + wrap.insertBefore( this[ 0 ] ); + } + + wrap.map( function() { + var elem = this; + + while ( elem.firstElementChild ) { + elem = elem.firstElementChild; + } + + return elem; + } ).append( this ); + } + + return this; + }, + + wrapInner: function( html ) { + if ( isFunction( html ) ) { + return this.each( function( i ) { + jQuery( this ).wrapInner( html.call( this, i ) ); + } ); + } + + return this.each( function() { + var self = jQuery( this ), + contents = self.contents(); + + if ( contents.length ) { + contents.wrapAll( html ); + + } else { + self.append( html ); + } + } ); + }, + + wrap: function( html ) { + var htmlIsFunction = isFunction( html ); + + return this.each( function( i ) { + jQuery( this ).wrapAll( htmlIsFunction ? html.call( this, i ) : html ); + } ); + }, + + unwrap: function( selector ) { + this.parent( selector ).not( "body" ).each( function() { + jQuery( this ).replaceWith( this.childNodes ); + } ); + return this; + } +} ); + + +jQuery.expr.pseudos.hidden = function( elem ) { + return !jQuery.expr.pseudos.visible( elem ); +}; +jQuery.expr.pseudos.visible = function( elem ) { + return !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length ); +}; + + + + +jQuery.ajaxSettings.xhr = function() { + try { + return new window.XMLHttpRequest(); + } catch ( e ) {} +}; + +var xhrSuccessStatus = { + + // File protocol always yields status code 0, assume 200 + 0: 200, + + // Support: IE <=9 only + // #1450: sometimes IE returns 1223 when it should be 204 + 1223: 204 + }, + xhrSupported = jQuery.ajaxSettings.xhr(); + +support.cors = !!xhrSupported && ( "withCredentials" in xhrSupported ); +support.ajax = xhrSupported = !!xhrSupported; + +jQuery.ajaxTransport( function( options ) { + var callback, errorCallback; + + // Cross domain only allowed if supported through XMLHttpRequest + if ( support.cors || xhrSupported && !options.crossDomain ) { + return { + send: function( headers, complete ) { + var i, + xhr = options.xhr(); + + xhr.open( + options.type, + options.url, + options.async, + options.username, + options.password + ); + + // Apply custom fields if provided + if ( options.xhrFields ) { + for ( i in options.xhrFields ) { + xhr[ i ] = options.xhrFields[ i ]; + } + } + + // Override mime type if needed + if ( options.mimeType && xhr.overrideMimeType ) { + xhr.overrideMimeType( options.mimeType ); + } + + // X-Requested-With header + // For cross-domain requests, seeing as conditions for a preflight are + // akin to a jigsaw puzzle, we simply never set it to be sure. + // (it can always be set on a per-request basis or even using ajaxSetup) + // For same-domain requests, won't change header if already provided. + if ( !options.crossDomain && !headers[ "X-Requested-With" ] ) { + headers[ "X-Requested-With" ] = "XMLHttpRequest"; + } + + // Set headers + for ( i in headers ) { + xhr.setRequestHeader( i, headers[ i ] ); + } + + // Callback + callback = function( type ) { + return function() { + if ( callback ) { + callback = errorCallback = xhr.onload = + xhr.onerror = xhr.onabort = xhr.ontimeout = + xhr.onreadystatechange = null; + + if ( type === "abort" ) { + xhr.abort(); + } else if ( type === "error" ) { + + // Support: IE <=9 only + // On a manual native abort, IE9 throws + // errors on any property access that is not readyState + if ( typeof xhr.status !== "number" ) { + complete( 0, "error" ); + } else { + complete( + + // File: protocol always yields status 0; see #8605, #14207 + xhr.status, + xhr.statusText + ); + } + } else { + complete( + xhrSuccessStatus[ xhr.status ] || xhr.status, + xhr.statusText, + + // Support: IE <=9 only + // IE9 has no XHR2 but throws on binary (trac-11426) + // For XHR2 non-text, let the caller handle it (gh-2498) + ( xhr.responseType || "text" ) !== "text" || + typeof xhr.responseText !== "string" ? + { binary: xhr.response } : + { text: xhr.responseText }, + xhr.getAllResponseHeaders() + ); + } + } + }; + }; + + // Listen to events + xhr.onload = callback(); + errorCallback = xhr.onerror = xhr.ontimeout = callback( "error" ); + + // Support: IE 9 only + // Use onreadystatechange to replace onabort + // to handle uncaught aborts + if ( xhr.onabort !== undefined ) { + xhr.onabort = errorCallback; + } else { + xhr.onreadystatechange = function() { + + // Check readyState before timeout as it changes + if ( xhr.readyState === 4 ) { + + // Allow onerror to be called first, + // but that will not handle a native abort + // Also, save errorCallback to a variable + // as xhr.onerror cannot be accessed + window.setTimeout( function() { + if ( callback ) { + errorCallback(); + } + } ); + } + }; + } + + // Create the abort callback + callback = callback( "abort" ); + + try { + + // Do send the request (this may raise an exception) + xhr.send( options.hasContent && options.data || null ); + } catch ( e ) { + + // #14683: Only rethrow if this hasn't been notified as an error yet + if ( callback ) { + throw e; + } + } + }, + + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +// Prevent auto-execution of scripts when no explicit dataType was provided (See gh-2432) +jQuery.ajaxPrefilter( function( s ) { + if ( s.crossDomain ) { + s.contents.script = false; + } +} ); + +// Install script dataType +jQuery.ajaxSetup( { + accepts: { + script: "text/javascript, application/javascript, " + + "application/ecmascript, application/x-ecmascript" + }, + contents: { + script: /\b(?:java|ecma)script\b/ + }, + converters: { + "text script": function( text ) { + jQuery.globalEval( text ); + return text; + } + } +} ); + +// Handle cache's special case and crossDomain +jQuery.ajaxPrefilter( "script", function( s ) { + if ( s.cache === undefined ) { + s.cache = false; + } + if ( s.crossDomain ) { + s.type = "GET"; + } +} ); + +// Bind script tag hack transport +jQuery.ajaxTransport( "script", function( s ) { + + // This transport only deals with cross domain or forced-by-attrs requests + if ( s.crossDomain || s.scriptAttrs ) { + var script, callback; + return { + send: function( _, complete ) { + script = jQuery( "<script>" ) + .attr( s.scriptAttrs || {} ) + .prop( { charset: s.scriptCharset, src: s.url } ) + .on( "load error", callback = function( evt ) { + script.remove(); + callback = null; + if ( evt ) { + complete( evt.type === "error" ? 404 : 200, evt.type ); + } + } ); + + // Use native DOM manipulation to avoid our domManip AJAX trickery + document.head.appendChild( script[ 0 ] ); + }, + abort: function() { + if ( callback ) { + callback(); + } + } + }; + } +} ); + + + + +var oldCallbacks = [], + rjsonp = /(=)\?(?=&|$)|\?\?/; + +// Default jsonp settings +jQuery.ajaxSetup( { + jsonp: "callback", + jsonpCallback: function() { + var callback = oldCallbacks.pop() || ( jQuery.expando + "_" + ( nonce.guid++ ) ); + this[ callback ] = true; + return callback; + } +} ); + +// Detect, normalize options and install callbacks for jsonp requests +jQuery.ajaxPrefilter( "json jsonp", function( s, originalSettings, jqXHR ) { + + var callbackName, overwritten, responseContainer, + jsonProp = s.jsonp !== false && ( rjsonp.test( s.url ) ? + "url" : + typeof s.data === "string" && + ( s.contentType || "" ) + .indexOf( "application/x-www-form-urlencoded" ) === 0 && + rjsonp.test( s.data ) && "data" + ); + + // Handle iff the expected data type is "jsonp" or we have a parameter to set + if ( jsonProp || s.dataTypes[ 0 ] === "jsonp" ) { + + // Get callback name, remembering preexisting value associated with it + callbackName = s.jsonpCallback = isFunction( s.jsonpCallback ) ? + s.jsonpCallback() : + s.jsonpCallback; + + // Insert callback into url or form data + if ( jsonProp ) { + s[ jsonProp ] = s[ jsonProp ].replace( rjsonp, "$1" + callbackName ); + } else if ( s.jsonp !== false ) { + s.url += ( rquery.test( s.url ) ? "&" : "?" ) + s.jsonp + "=" + callbackName; + } + + // Use data converter to retrieve json after script execution + s.converters[ "script json" ] = function() { + if ( !responseContainer ) { + jQuery.error( callbackName + " was not called" ); + } + return responseContainer[ 0 ]; + }; + + // Force json dataType + s.dataTypes[ 0 ] = "json"; + + // Install callback + overwritten = window[ callbackName ]; + window[ callbackName ] = function() { + responseContainer = arguments; + }; + + // Clean-up function (fires after converters) + jqXHR.always( function() { + + // If previous value didn't exist - remove it + if ( overwritten === undefined ) { + jQuery( window ).removeProp( callbackName ); + + // Otherwise restore preexisting value + } else { + window[ callbackName ] = overwritten; + } + + // Save back as free + if ( s[ callbackName ] ) { + + // Make sure that re-using the options doesn't screw things around + s.jsonpCallback = originalSettings.jsonpCallback; + + // Save the callback name for future use + oldCallbacks.push( callbackName ); + } + + // Call if it was a function and we have a response + if ( responseContainer && isFunction( overwritten ) ) { + overwritten( responseContainer[ 0 ] ); + } + + responseContainer = overwritten = undefined; + } ); + + // Delegate to script + return "script"; + } +} ); + + + + +// Support: Safari 8 only +// In Safari 8 documents created via document.implementation.createHTMLDocument +// collapse sibling forms: the second one becomes a child of the first one. +// Because of that, this security measure has to be disabled in Safari 8. +// https://bugs.webkit.org/show_bug.cgi?id=137337 +support.createHTMLDocument = ( function() { + var body = document.implementation.createHTMLDocument( "" ).body; + body.innerHTML = "<form></form><form></form>"; + return body.childNodes.length === 2; +} )(); + + +// Argument "data" should be string of html +// context (optional): If specified, the fragment will be created in this context, +// defaults to document +// keepScripts (optional): If true, will include scripts passed in the html string +jQuery.parseHTML = function( data, context, keepScripts ) { + if ( typeof data !== "string" ) { + return []; + } + if ( typeof context === "boolean" ) { + keepScripts = context; + context = false; + } + + var base, parsed, scripts; + + if ( !context ) { + + // Stop scripts or inline event handlers from being executed immediately + // by using document.implementation + if ( support.createHTMLDocument ) { + context = document.implementation.createHTMLDocument( "" ); + + // Set the base href for the created document + // so any parsed elements with URLs + // are based on the document's URL (gh-2965) + base = context.createElement( "base" ); + base.href = document.location.href; + context.head.appendChild( base ); + } else { + context = document; + } + } + + parsed = rsingleTag.exec( data ); + scripts = !keepScripts && []; + + // Single tag + if ( parsed ) { + return [ context.createElement( parsed[ 1 ] ) ]; + } + + parsed = buildFragment( [ data ], context, scripts ); + + if ( scripts && scripts.length ) { + jQuery( scripts ).remove(); + } + + return jQuery.merge( [], parsed.childNodes ); +}; + + +/** + * Load a url into a page + */ +jQuery.fn.load = function( url, params, callback ) { + var selector, type, response, + self = this, + off = url.indexOf( " " ); + + if ( off > -1 ) { + selector = stripAndCollapse( url.slice( off ) ); + url = url.slice( 0, off ); + } + + // If it's a function + if ( isFunction( params ) ) { + + // We assume that it's the callback + callback = params; + params = undefined; + + // Otherwise, build a param string + } else if ( params && typeof params === "object" ) { + type = "POST"; + } + + // If we have elements to modify, make the request + if ( self.length > 0 ) { + jQuery.ajax( { + url: url, + + // If "type" variable is undefined, then "GET" method will be used. + // Make value of this field explicit since + // user can override it through ajaxSetup method + type: type || "GET", + dataType: "html", + data: params + } ).done( function( responseText ) { + + // Save response for use in complete callback + response = arguments; + + self.html( selector ? + + // If a selector was specified, locate the right elements in a dummy div + // Exclude scripts to avoid IE 'Permission Denied' errors + jQuery( "<div>" ).append( jQuery.parseHTML( responseText ) ).find( selector ) : + + // Otherwise use the full result + responseText ); + + // If the request succeeds, this function gets "data", "status", "jqXHR" + // but they are ignored because response was set above. + // If it fails, this function gets "jqXHR", "status", "error" + } ).always( callback && function( jqXHR, status ) { + self.each( function() { + callback.apply( this, response || [ jqXHR.responseText, status, jqXHR ] ); + } ); + } ); + } + + return this; +}; + + + + +jQuery.expr.pseudos.animated = function( elem ) { + return jQuery.grep( jQuery.timers, function( fn ) { + return elem === fn.elem; + } ).length; +}; + + + + +jQuery.offset = { + setOffset: function( elem, options, i ) { + var curPosition, curLeft, curCSSTop, curTop, curOffset, curCSSLeft, calculatePosition, + position = jQuery.css( elem, "position" ), + curElem = jQuery( elem ), + props = {}; + + // Set position first, in-case top/left are set even on static elem + if ( position === "static" ) { + elem.style.position = "relative"; + } + + curOffset = curElem.offset(); + curCSSTop = jQuery.css( elem, "top" ); + curCSSLeft = jQuery.css( elem, "left" ); + calculatePosition = ( position === "absolute" || position === "fixed" ) && + ( curCSSTop + curCSSLeft ).indexOf( "auto" ) > -1; + + // Need to be able to calculate position if either + // top or left is auto and position is either absolute or fixed + if ( calculatePosition ) { + curPosition = curElem.position(); + curTop = curPosition.top; + curLeft = curPosition.left; + + } else { + curTop = parseFloat( curCSSTop ) || 0; + curLeft = parseFloat( curCSSLeft ) || 0; + } + + if ( isFunction( options ) ) { + + // Use jQuery.extend here to allow modification of coordinates argument (gh-1848) + options = options.call( elem, i, jQuery.extend( {}, curOffset ) ); + } + + if ( options.top != null ) { + props.top = ( options.top - curOffset.top ) + curTop; + } + if ( options.left != null ) { + props.left = ( options.left - curOffset.left ) + curLeft; + } + + if ( "using" in options ) { + options.using.call( elem, props ); + + } else { + if ( typeof props.top === "number" ) { + props.top += "px"; + } + if ( typeof props.left === "number" ) { + props.left += "px"; + } + curElem.css( props ); + } + } +}; + +jQuery.fn.extend( { + + // offset() relates an element's border box to the document origin + offset: function( options ) { + + // Preserve chaining for setter + if ( arguments.length ) { + return options === undefined ? + this : + this.each( function( i ) { + jQuery.offset.setOffset( this, options, i ); + } ); + } + + var rect, win, + elem = this[ 0 ]; + + if ( !elem ) { + return; + } + + // Return zeros for disconnected and hidden (display: none) elements (gh-2310) + // Support: IE <=11 only + // Running getBoundingClientRect on a + // disconnected node in IE throws an error + if ( !elem.getClientRects().length ) { + return { top: 0, left: 0 }; + } + + // Get document-relative position by adding viewport scroll to viewport-relative gBCR + rect = elem.getBoundingClientRect(); + win = elem.ownerDocument.defaultView; + return { + top: rect.top + win.pageYOffset, + left: rect.left + win.pageXOffset + }; + }, + + // position() relates an element's margin box to its offset parent's padding box + // This corresponds to the behavior of CSS absolute positioning + position: function() { + if ( !this[ 0 ] ) { + return; + } + + var offsetParent, offset, doc, + elem = this[ 0 ], + parentOffset = { top: 0, left: 0 }; + + // position:fixed elements are offset from the viewport, which itself always has zero offset + if ( jQuery.css( elem, "position" ) === "fixed" ) { + + // Assume position:fixed implies availability of getBoundingClientRect + offset = elem.getBoundingClientRect(); + + } else { + offset = this.offset(); + + // Account for the *real* offset parent, which can be the document or its root element + // when a statically positioned element is identified + doc = elem.ownerDocument; + offsetParent = elem.offsetParent || doc.documentElement; + while ( offsetParent && + ( offsetParent === doc.body || offsetParent === doc.documentElement ) && + jQuery.css( offsetParent, "position" ) === "static" ) { + + offsetParent = offsetParent.parentNode; + } + if ( offsetParent && offsetParent !== elem && offsetParent.nodeType === 1 ) { + + // Incorporate borders into its offset, since they are outside its content origin + parentOffset = jQuery( offsetParent ).offset(); + parentOffset.top += jQuery.css( offsetParent, "borderTopWidth", true ); + parentOffset.left += jQuery.css( offsetParent, "borderLeftWidth", true ); + } + } + + // Subtract parent offsets and element margins + return { + top: offset.top - parentOffset.top - jQuery.css( elem, "marginTop", true ), + left: offset.left - parentOffset.left - jQuery.css( elem, "marginLeft", true ) + }; + }, + + // This method will return documentElement in the following cases: + // 1) For the element inside the iframe without offsetParent, this method will return + // documentElement of the parent window + // 2) For the hidden or detached element + // 3) For body or html element, i.e. in case of the html node - it will return itself + // + // but those exceptions were never presented as a real life use-cases + // and might be considered as more preferable results. + // + // This logic, however, is not guaranteed and can change at any point in the future + offsetParent: function() { + return this.map( function() { + var offsetParent = this.offsetParent; + + while ( offsetParent && jQuery.css( offsetParent, "position" ) === "static" ) { + offsetParent = offsetParent.offsetParent; + } + + return offsetParent || documentElement; + } ); + } +} ); + +// Create scrollLeft and scrollTop methods +jQuery.each( { scrollLeft: "pageXOffset", scrollTop: "pageYOffset" }, function( method, prop ) { + var top = "pageYOffset" === prop; + + jQuery.fn[ method ] = function( val ) { + return access( this, function( elem, method, val ) { + + // Coalesce documents and windows + var win; + if ( isWindow( elem ) ) { + win = elem; + } else if ( elem.nodeType === 9 ) { + win = elem.defaultView; + } + + if ( val === undefined ) { + return win ? win[ prop ] : elem[ method ]; + } + + if ( win ) { + win.scrollTo( + !top ? val : win.pageXOffset, + top ? val : win.pageYOffset + ); + + } else { + elem[ method ] = val; + } + }, method, val, arguments.length ); + }; +} ); + +// Support: Safari <=7 - 9.1, Chrome <=37 - 49 +// Add the top/left cssHooks using jQuery.fn.position +// Webkit bug: https://bugs.webkit.org/show_bug.cgi?id=29084 +// Blink bug: https://bugs.chromium.org/p/chromium/issues/detail?id=589347 +// getComputedStyle returns percent when specified for top/left/bottom/right; +// rather than make the css module depend on the offset module, just check for it here +jQuery.each( [ "top", "left" ], function( _i, prop ) { + jQuery.cssHooks[ prop ] = addGetHookIf( support.pixelPosition, + function( elem, computed ) { + if ( computed ) { + computed = curCSS( elem, prop ); + + // If curCSS returns percentage, fallback to offset + return rnumnonpx.test( computed ) ? + jQuery( elem ).position()[ prop ] + "px" : + computed; + } + } + ); +} ); + + +// Create innerHeight, innerWidth, height, width, outerHeight and outerWidth methods +jQuery.each( { Height: "height", Width: "width" }, function( name, type ) { + jQuery.each( { padding: "inner" + name, content: type, "": "outer" + name }, + function( defaultExtra, funcName ) { + + // Margin is only for outerHeight, outerWidth + jQuery.fn[ funcName ] = function( margin, value ) { + var chainable = arguments.length && ( defaultExtra || typeof margin !== "boolean" ), + extra = defaultExtra || ( margin === true || value === true ? "margin" : "border" ); + + return access( this, function( elem, type, value ) { + var doc; + + if ( isWindow( elem ) ) { + + // $( window ).outerWidth/Height return w/h including scrollbars (gh-1729) + return funcName.indexOf( "outer" ) === 0 ? + elem[ "inner" + name ] : + elem.document.documentElement[ "client" + name ]; + } + + // Get document width or height + if ( elem.nodeType === 9 ) { + doc = elem.documentElement; + + // Either scroll[Width/Height] or offset[Width/Height] or client[Width/Height], + // whichever is greatest + return Math.max( + elem.body[ "scroll" + name ], doc[ "scroll" + name ], + elem.body[ "offset" + name ], doc[ "offset" + name ], + doc[ "client" + name ] + ); + } + + return value === undefined ? + + // Get width or height on the element, requesting but not forcing parseFloat + jQuery.css( elem, type, extra ) : + + // Set width or height on the element + jQuery.style( elem, type, value, extra ); + }, type, chainable ? margin : undefined, chainable ); + }; + } ); +} ); + + +jQuery.each( [ + "ajaxStart", + "ajaxStop", + "ajaxComplete", + "ajaxError", + "ajaxSuccess", + "ajaxSend" +], function( _i, type ) { + jQuery.fn[ type ] = function( fn ) { + return this.on( type, fn ); + }; +} ); + + + + +jQuery.fn.extend( { + + bind: function( types, data, fn ) { + return this.on( types, null, data, fn ); + }, + unbind: function( types, fn ) { + return this.off( types, null, fn ); + }, + + delegate: function( selector, types, data, fn ) { + return this.on( types, selector, data, fn ); + }, + undelegate: function( selector, types, fn ) { + + // ( namespace ) or ( selector, types [, fn] ) + return arguments.length === 1 ? + this.off( selector, "**" ) : + this.off( types, selector || "**", fn ); + }, + + hover: function( fnOver, fnOut ) { + return this.mouseenter( fnOver ).mouseleave( fnOut || fnOver ); + } +} ); + +jQuery.each( ( "blur focus focusin focusout resize scroll click dblclick " + + "mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave " + + "change select submit keydown keypress keyup contextmenu" ).split( " " ), + function( _i, name ) { + + // Handle event binding + jQuery.fn[ name ] = function( data, fn ) { + return arguments.length > 0 ? + this.on( name, null, data, fn ) : + this.trigger( name ); + }; + } ); + + + + +// Support: Android <=4.0 only +// Make sure we trim BOM and NBSP +var rtrim = /^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g; + +// Bind a function to a context, optionally partially applying any +// arguments. +// jQuery.proxy is deprecated to promote standards (specifically Function#bind) +// However, it is not slated for removal any time soon +jQuery.proxy = function( fn, context ) { + var tmp, args, proxy; + + if ( typeof context === "string" ) { + tmp = fn[ context ]; + context = fn; + fn = tmp; + } + + // Quick check to determine if target is callable, in the spec + // this throws a TypeError, but we will just return undefined. + if ( !isFunction( fn ) ) { + return undefined; + } + + // Simulated bind + args = slice.call( arguments, 2 ); + proxy = function() { + return fn.apply( context || this, args.concat( slice.call( arguments ) ) ); + }; + + // Set the guid of unique handler to the same of original handler, so it can be removed + proxy.guid = fn.guid = fn.guid || jQuery.guid++; + + return proxy; +}; + +jQuery.holdReady = function( hold ) { + if ( hold ) { + jQuery.readyWait++; + } else { + jQuery.ready( true ); + } +}; +jQuery.isArray = Array.isArray; +jQuery.parseJSON = JSON.parse; +jQuery.nodeName = nodeName; +jQuery.isFunction = isFunction; +jQuery.isWindow = isWindow; +jQuery.camelCase = camelCase; +jQuery.type = toType; + +jQuery.now = Date.now; + +jQuery.isNumeric = function( obj ) { + + // As of jQuery 3.0, isNumeric is limited to + // strings and numbers (primitives or objects) + // that can be coerced to finite numbers (gh-2662) + var type = jQuery.type( obj ); + return ( type === "number" || type === "string" ) && + + // parseFloat NaNs numeric-cast false positives ("") + // ...but misinterprets leading-number strings, particularly hex literals ("0x...") + // subtraction forces infinities to NaN + !isNaN( obj - parseFloat( obj ) ); +}; + +jQuery.trim = function( text ) { + return text == null ? + "" : + ( text + "" ).replace( rtrim, "" ); +}; + + + +// Register as a named AMD module, since jQuery can be concatenated with other +// files that may use define, but not via a proper concatenation script that +// understands anonymous AMD modules. A named AMD is safest and most robust +// way to register. Lowercase jquery is used because AMD module names are +// derived from file names, and jQuery is normally delivered in a lowercase +// file name. Do this after creating the global so that if an AMD module wants +// to call noConflict to hide this version of jQuery, it will work. + +// Note that for maximum portability, libraries that are not jQuery should +// declare themselves as anonymous modules, and avoid setting a global if an +// AMD loader is present. jQuery is a special case. For more information, see +// https://github.com/jrburke/requirejs/wiki/Updating-existing-libraries#wiki-anon + +if ( typeof define === "function" && define.amd ) { + define( "jquery", [], function() { + return jQuery; + } ); +} + + + + +var + + // Map over jQuery in case of overwrite + _jQuery = window.jQuery, + + // Map over the $ in case of overwrite + _$ = window.$; + +jQuery.noConflict = function( deep ) { + if ( window.$ === jQuery ) { + window.$ = _$; + } + + if ( deep && window.jQuery === jQuery ) { + window.jQuery = _jQuery; + } + + return jQuery; +}; + +// Expose jQuery and $ identifiers, even in AMD +// (#7102#comment:10, https://github.com/jquery/jquery/pull/557) +// and CommonJS for browser emulators (#13566) +if ( typeof noGlobal === "undefined" ) { + window.jQuery = window.$ = jQuery; +} + + + + +return jQuery; +} ); diff --git a/ctags/docs/_static/jquery.js b/ctags/docs/_static/jquery.js new file mode 100644 index 0000000..b061403 --- /dev/null +++ b/ctags/docs/_static/jquery.js @@ -0,0 +1,2 @@ +/*! jQuery v3.5.1 | (c) JS Foundation and other contributors | jquery.org/license */ +!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.5.1",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0<t&&t-1 in e)}S.fn=S.prototype={jquery:f,constructor:S,length:0,toArray:function(){return s.call(this)},get:function(e){return null==e?s.call(this):e<0?this[e+this.length]:this[e]},pushStack:function(e){var t=S.merge(this.constructor(),e);return t.prevObject=this,t},each:function(e){return S.each(this,e)},map:function(n){return this.pushStack(S.map(this,function(e,t){return n.call(e,t,e)}))},slice:function(){return this.pushStack(s.apply(this,arguments))},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},even:function(){return this.pushStack(S.grep(this,function(e,t){return(t+1)%2}))},odd:function(){return this.pushStack(S.grep(this,function(e,t){return t%2}))},eq:function(e){var t=this.length,n=+e+(e<0?t:0);return this.pushStack(0<=n&&n<t?[this[n]]:[])},end:function(){return this.prevObject||this.constructor()},push:u,sort:t.sort,splice:t.splice},S.extend=S.fn.extend=function(){var e,t,n,r,i,o,a=arguments[0]||{},s=1,u=arguments.length,l=!1;for("boolean"==typeof a&&(l=a,a=arguments[s]||{},s++),"object"==typeof a||m(a)||(a={}),s===u&&(a=this,s--);s<u;s++)if(null!=(e=arguments[s]))for(t in e)r=e[t],"__proto__"!==t&&a!==r&&(l&&r&&(S.isPlainObject(r)||(i=Array.isArray(r)))?(n=a[t],o=i&&!Array.isArray(n)?[]:i||S.isPlainObject(n)?n:{},i=!1,a[t]=S.extend(l,o,r)):void 0!==r&&(a[t]=r));return a},S.extend({expando:"jQuery"+(f+Math.random()).replace(/\D/g,""),isReady:!0,error:function(e){throw new Error(e)},noop:function(){},isPlainObject:function(e){var t,n;return!(!e||"[object Object]"!==o.call(e))&&(!(t=r(e))||"function"==typeof(n=v.call(t,"constructor")&&t.constructor)&&a.call(n)===l)},isEmptyObject:function(e){var t;for(t in e)return!1;return!0},globalEval:function(e,t,n){b(e,{nonce:t&&t.nonce},n)},each:function(e,t){var n,r=0;if(p(e)){for(n=e.length;r<n;r++)if(!1===t.call(e[r],r,e[r]))break}else for(r in e)if(!1===t.call(e[r],r,e[r]))break;return e},makeArray:function(e,t){var n=t||[];return null!=e&&(p(Object(e))?S.merge(n,"string"==typeof e?[e]:e):u.call(n,e)),n},inArray:function(e,t,n){return null==t?-1:i.call(t,e,n)},merge:function(e,t){for(var n=+t.length,r=0,i=e.length;r<n;r++)e[i++]=t[r];return e.length=i,e},grep:function(e,t,n){for(var r=[],i=0,o=e.length,a=!n;i<o;i++)!t(e[i],i)!==a&&r.push(e[i]);return r},map:function(e,t,n){var r,i,o=0,a=[];if(p(e))for(r=e.length;o<r;o++)null!=(i=t(e[o],o,n))&&a.push(i);else for(o in e)null!=(i=t(e[o],o,n))&&a.push(i);return g(a)},guid:1,support:y}),"function"==typeof Symbol&&(S.fn[Symbol.iterator]=t[Symbol.iterator]),S.each("Boolean Number String Function Array Date RegExp Object Error Symbol".split(" "),function(e,t){n["[object "+t+"]"]=t.toLowerCase()});var d=function(n){var e,d,b,o,i,h,f,g,w,u,l,T,C,a,E,v,s,c,y,S="sizzle"+1*new Date,p=n.document,k=0,r=0,m=ue(),x=ue(),A=ue(),N=ue(),D=function(e,t){return e===t&&(l=!0),0},j={}.hasOwnProperty,t=[],q=t.pop,L=t.push,H=t.push,O=t.slice,P=function(e,t){for(var n=0,r=e.length;n<r;n++)if(e[n]===t)return n;return-1},R="checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped",M="[\\x20\\t\\r\\n\\f]",I="(?:\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+",W="\\["+M+"*("+I+")(?:"+M+"*([*^$|!~]?=)"+M+"*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|("+I+"))|)"+M+"*\\]",F=":("+I+")(?:\\((('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|((?:\\\\.|[^\\\\()[\\]]|"+W+")*)|.*)\\)|)",B=new RegExp(M+"+","g"),$=new RegExp("^"+M+"+|((?:^|[^\\\\])(?:\\\\.)*)"+M+"+$","g"),_=new RegExp("^"+M+"*,"+M+"*"),z=new RegExp("^"+M+"*([>+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+M+"*(even|odd|(([+-]|)(\\d*)n|)"+M+"*(?:([+-]|)"+M+"*(\\d+)|))"+M+"*\\)|)","i"),bool:new RegExp("^(?:"+R+")$","i"),needsContext:new RegExp("^"+M+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+M+"*((?:-\\d)?\\d*)"+M+"*\\)|)(?=[^-]|$)","i")},Y=/HTML$/i,Q=/^(?:input|select|textarea|button)$/i,J=/^h\d$/i,K=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,ee=/[+~]/,te=new RegExp("\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\([^\\r\\n\\f])","g"),ne=function(e,t){var n="0x"+e.slice(1)-65536;return t||(n<0?String.fromCharCode(n+65536):String.fromCharCode(n>>10|55296,1023&n|56320))},re=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ie=function(e,t){return t?"\0"===e?"\ufffd":e.slice(0,-1)+"\\"+e.charCodeAt(e.length-1).toString(16)+" ":"\\"+e},oe=function(){T()},ae=be(function(e){return!0===e.disabled&&"fieldset"===e.nodeName.toLowerCase()},{dir:"parentNode",next:"legend"});try{H.apply(t=O.call(p.childNodes),p.childNodes),t[p.childNodes.length].nodeType}catch(e){H={apply:t.length?function(e,t){L.apply(e,O.call(t))}:function(e,t){var n=e.length,r=0;while(e[n++]=t[r++]);e.length=n-1}}}function se(t,e,n,r){var i,o,a,s,u,l,c,f=e&&e.ownerDocument,p=e?e.nodeType:9;if(n=n||[],"string"!=typeof t||!t||1!==p&&9!==p&&11!==p)return n;if(!r&&(T(e),e=e||C,E)){if(11!==p&&(u=Z.exec(t)))if(i=u[1]){if(9===p){if(!(a=e.getElementById(i)))return n;if(a.id===i)return n.push(a),n}else if(f&&(a=f.getElementById(i))&&y(e,a)&&a.id===i)return n.push(a),n}else{if(u[2])return H.apply(n,e.getElementsByTagName(t)),n;if((i=u[3])&&d.getElementsByClassName&&e.getElementsByClassName)return H.apply(n,e.getElementsByClassName(i)),n}if(d.qsa&&!N[t+" "]&&(!v||!v.test(t))&&(1!==p||"object"!==e.nodeName.toLowerCase())){if(c=t,f=e,1===p&&(U.test(t)||z.test(t))){(f=ee.test(t)&&ye(e.parentNode)||e)===e&&d.scope||((s=e.getAttribute("id"))?s=s.replace(re,ie):e.setAttribute("id",s=S)),o=(l=h(t)).length;while(o--)l[o]=(s?"#"+s:":scope")+" "+xe(l[o]);c=l.join(",")}try{return H.apply(n,f.querySelectorAll(c)),n}catch(e){N(t,!0)}finally{s===S&&e.removeAttribute("id")}}}return g(t.replace($,"$1"),e,n,r)}function ue(){var r=[];return function e(t,n){return r.push(t+" ")>b.cacheLength&&delete e[r.shift()],e[t+" "]=n}}function le(e){return e[S]=!0,e}function ce(e){var t=C.createElement("fieldset");try{return!!e(t)}catch(e){return!1}finally{t.parentNode&&t.parentNode.removeChild(t),t=null}}function fe(e,t){var n=e.split("|"),r=n.length;while(r--)b.attrHandle[n[r]]=t}function pe(e,t){var n=t&&e,r=n&&1===e.nodeType&&1===t.nodeType&&e.sourceIndex-t.sourceIndex;if(r)return r;if(n)while(n=n.nextSibling)if(n===t)return-1;return e?1:-1}function de(t){return function(e){return"input"===e.nodeName.toLowerCase()&&e.type===t}}function he(n){return function(e){var t=e.nodeName.toLowerCase();return("input"===t||"button"===t)&&e.type===n}}function ge(t){return function(e){return"form"in e?e.parentNode&&!1===e.disabled?"label"in e?"label"in e.parentNode?e.parentNode.disabled===t:e.disabled===t:e.isDisabled===t||e.isDisabled!==!t&&ae(e)===t:e.disabled===t:"label"in e&&e.disabled===t}}function ve(a){return le(function(o){return o=+o,le(function(e,t){var n,r=a([],e.length,o),i=r.length;while(i--)e[n=r[i]]&&(e[n]=!(t[n]=e[n]))})})}function ye(e){return e&&"undefined"!=typeof e.getElementsByTagName&&e}for(e in d=se.support={},i=se.isXML=function(e){var t=e.namespaceURI,n=(e.ownerDocument||e).documentElement;return!Y.test(t||n&&n.nodeName||"HTML")},T=se.setDocument=function(e){var t,n,r=e?e.ownerDocument||e:p;return r!=C&&9===r.nodeType&&r.documentElement&&(a=(C=r).documentElement,E=!i(C),p!=C&&(n=C.defaultView)&&n.top!==n&&(n.addEventListener?n.addEventListener("unload",oe,!1):n.attachEvent&&n.attachEvent("onunload",oe)),d.scope=ce(function(e){return a.appendChild(e).appendChild(C.createElement("div")),"undefined"!=typeof e.querySelectorAll&&!e.querySelectorAll(":scope fieldset div").length}),d.attributes=ce(function(e){return e.className="i",!e.getAttribute("className")}),d.getElementsByTagName=ce(function(e){return e.appendChild(C.createComment("")),!e.getElementsByTagName("*").length}),d.getElementsByClassName=K.test(C.getElementsByClassName),d.getById=ce(function(e){return a.appendChild(e).id=S,!C.getElementsByName||!C.getElementsByName(S).length}),d.getById?(b.filter.ID=function(e){var t=e.replace(te,ne);return function(e){return e.getAttribute("id")===t}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n=t.getElementById(e);return n?[n]:[]}}):(b.filter.ID=function(e){var n=e.replace(te,ne);return function(e){var t="undefined"!=typeof e.getAttributeNode&&e.getAttributeNode("id");return t&&t.value===n}},b.find.ID=function(e,t){if("undefined"!=typeof t.getElementById&&E){var n,r,i,o=t.getElementById(e);if(o){if((n=o.getAttributeNode("id"))&&n.value===e)return[o];i=t.getElementsByName(e),r=0;while(o=i[r++])if((n=o.getAttributeNode("id"))&&n.value===e)return[o]}return[]}}),b.find.TAG=d.getElementsByTagName?function(e,t){return"undefined"!=typeof t.getElementsByTagName?t.getElementsByTagName(e):d.qsa?t.querySelectorAll(e):void 0}:function(e,t){var n,r=[],i=0,o=t.getElementsByTagName(e);if("*"===e){while(n=o[i++])1===n.nodeType&&r.push(n);return r}return o},b.find.CLASS=d.getElementsByClassName&&function(e,t){if("undefined"!=typeof t.getElementsByClassName&&E)return t.getElementsByClassName(e)},s=[],v=[],(d.qsa=K.test(C.querySelectorAll))&&(ce(function(e){var t;a.appendChild(e).innerHTML="<a id='"+S+"'></a><select id='"+S+"-\r\\' msallowcapture=''><option selected=''></option></select>",e.querySelectorAll("[msallowcapture^='']").length&&v.push("[*^$]="+M+"*(?:''|\"\")"),e.querySelectorAll("[selected]").length||v.push("\\["+M+"*(?:value|"+R+")"),e.querySelectorAll("[id~="+S+"-]").length||v.push("~="),(t=C.createElement("input")).setAttribute("name",""),e.appendChild(t),e.querySelectorAll("[name='']").length||v.push("\\["+M+"*name"+M+"*="+M+"*(?:''|\"\")"),e.querySelectorAll(":checked").length||v.push(":checked"),e.querySelectorAll("a#"+S+"+*").length||v.push(".#.+[+~]"),e.querySelectorAll("\\\f"),v.push("[\\r\\n\\f]")}),ce(function(e){e.innerHTML="<a href='' disabled='disabled'></a><select disabled='disabled'><option/></select>";var t=C.createElement("input");t.setAttribute("type","hidden"),e.appendChild(t).setAttribute("name","D"),e.querySelectorAll("[name=d]").length&&v.push("name"+M+"*[*^$|!~]?="),2!==e.querySelectorAll(":enabled").length&&v.push(":enabled",":disabled"),a.appendChild(e).disabled=!0,2!==e.querySelectorAll(":disabled").length&&v.push(":enabled",":disabled"),e.querySelectorAll("*,:x"),v.push(",.*:")})),(d.matchesSelector=K.test(c=a.matches||a.webkitMatchesSelector||a.mozMatchesSelector||a.oMatchesSelector||a.msMatchesSelector))&&ce(function(e){d.disconnectedMatch=c.call(e,"*"),c.call(e,"[s!='']:x"),s.push("!=",F)}),v=v.length&&new RegExp(v.join("|")),s=s.length&&new RegExp(s.join("|")),t=K.test(a.compareDocumentPosition),y=t||K.test(a.contains)?function(e,t){var n=9===e.nodeType?e.documentElement:e,r=t&&t.parentNode;return e===r||!(!r||1!==r.nodeType||!(n.contains?n.contains(r):e.compareDocumentPosition&&16&e.compareDocumentPosition(r)))}:function(e,t){if(t)while(t=t.parentNode)if(t===e)return!0;return!1},D=t?function(e,t){if(e===t)return l=!0,0;var n=!e.compareDocumentPosition-!t.compareDocumentPosition;return n||(1&(n=(e.ownerDocument||e)==(t.ownerDocument||t)?e.compareDocumentPosition(t):1)||!d.sortDetached&&t.compareDocumentPosition(e)===n?e==C||e.ownerDocument==p&&y(p,e)?-1:t==C||t.ownerDocument==p&&y(p,t)?1:u?P(u,e)-P(u,t):0:4&n?-1:1)}:function(e,t){if(e===t)return l=!0,0;var n,r=0,i=e.parentNode,o=t.parentNode,a=[e],s=[t];if(!i||!o)return e==C?-1:t==C?1:i?-1:o?1:u?P(u,e)-P(u,t):0;if(i===o)return pe(e,t);n=e;while(n=n.parentNode)a.unshift(n);n=t;while(n=n.parentNode)s.unshift(n);while(a[r]===s[r])r++;return r?pe(a[r],s[r]):a[r]==p?-1:s[r]==p?1:0}),C},se.matches=function(e,t){return se(e,null,null,t)},se.matchesSelector=function(e,t){if(T(e),d.matchesSelector&&E&&!N[t+" "]&&(!s||!s.test(t))&&(!v||!v.test(t)))try{var n=c.call(e,t);if(n||d.disconnectedMatch||e.document&&11!==e.document.nodeType)return n}catch(e){N(t,!0)}return 0<se(t,C,null,[e]).length},se.contains=function(e,t){return(e.ownerDocument||e)!=C&&T(e),y(e,t)},se.attr=function(e,t){(e.ownerDocument||e)!=C&&T(e);var n=b.attrHandle[t.toLowerCase()],r=n&&j.call(b.attrHandle,t.toLowerCase())?n(e,t,!E):void 0;return void 0!==r?r:d.attributes||!E?e.getAttribute(t):(r=e.getAttributeNode(t))&&r.specified?r.value:null},se.escape=function(e){return(e+"").replace(re,ie)},se.error=function(e){throw new Error("Syntax error, unrecognized expression: "+e)},se.uniqueSort=function(e){var t,n=[],r=0,i=0;if(l=!d.detectDuplicates,u=!d.sortStable&&e.slice(0),e.sort(D),l){while(t=e[i++])t===e[i]&&(r=n.push(i));while(r--)e.splice(n[r],1)}return u=null,e},o=se.getText=function(e){var t,n="",r=0,i=e.nodeType;if(i){if(1===i||9===i||11===i){if("string"==typeof e.textContent)return e.textContent;for(e=e.firstChild;e;e=e.nextSibling)n+=o(e)}else if(3===i||4===i)return e.nodeValue}else while(t=e[r++])n+=o(t);return n},(b=se.selectors={cacheLength:50,createPseudo:le,match:G,attrHandle:{},find:{},relative:{">":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace(te,ne),e[3]=(e[3]||e[4]||e[5]||"").replace(te,ne),"~="===e[2]&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),"nth"===e[1].slice(0,3)?(e[3]||se.error(e[0]),e[4]=+(e[4]?e[5]+(e[6]||1):2*("even"===e[3]||"odd"===e[3])),e[5]=+(e[7]+e[8]||"odd"===e[3])):e[3]&&se.error(e[0]),e},PSEUDO:function(e){var t,n=!e[6]&&e[2];return G.CHILD.test(e[0])?null:(e[3]?e[2]=e[4]||e[5]||"":n&&X.test(n)&&(t=h(n,!0))&&(t=n.indexOf(")",n.length-t)-n.length)&&(e[0]=e[0].slice(0,t),e[2]=n.slice(0,t)),e.slice(0,3))}},filter:{TAG:function(e){var t=e.replace(te,ne).toLowerCase();return"*"===e?function(){return!0}:function(e){return e.nodeName&&e.nodeName.toLowerCase()===t}},CLASS:function(e){var t=m[e+" "];return t||(t=new RegExp("(^|"+M+")"+e+"("+M+"|$)"))&&m(e,function(e){return t.test("string"==typeof e.className&&e.className||"undefined"!=typeof e.getAttribute&&e.getAttribute("class")||"")})},ATTR:function(n,r,i){return function(e){var t=se.attr(e,n);return null==t?"!="===r:!r||(t+="","="===r?t===i:"!="===r?t!==i:"^="===r?i&&0===t.indexOf(i):"*="===r?i&&-1<t.indexOf(i):"$="===r?i&&t.slice(-i.length)===i:"~="===r?-1<(" "+t.replace(B," ")+" ").indexOf(i):"|="===r&&(t===i||t.slice(0,i.length+1)===i+"-"))}},CHILD:function(h,e,t,g,v){var y="nth"!==h.slice(0,3),m="last"!==h.slice(-4),x="of-type"===e;return 1===g&&0===v?function(e){return!!e.parentNode}:function(e,t,n){var r,i,o,a,s,u,l=y!==m?"nextSibling":"previousSibling",c=e.parentNode,f=x&&e.nodeName.toLowerCase(),p=!n&&!x,d=!1;if(c){if(y){while(l){a=e;while(a=a[l])if(x?a.nodeName.toLowerCase()===f:1===a.nodeType)return!1;u=l="only"===h&&!u&&"nextSibling"}return!0}if(u=[m?c.firstChild:c.lastChild],m&&p){d=(s=(r=(i=(o=(a=c)[S]||(a[S]={}))[a.uniqueID]||(o[a.uniqueID]={}))[h]||[])[0]===k&&r[1])&&r[2],a=s&&c.childNodes[s];while(a=++s&&a&&a[l]||(d=s=0)||u.pop())if(1===a.nodeType&&++d&&a===e){i[h]=[k,s,d];break}}else if(p&&(d=s=(r=(i=(o=(a=e)[S]||(a[S]={}))[a.uniqueID]||(o[a.uniqueID]={}))[h]||[])[0]===k&&r[1]),!1===d)while(a=++s&&a&&a[l]||(d=s=0)||u.pop())if((x?a.nodeName.toLowerCase()===f:1===a.nodeType)&&++d&&(p&&((i=(o=a[S]||(a[S]={}))[a.uniqueID]||(o[a.uniqueID]={}))[h]=[k,d]),a===e))break;return(d-=v)===g||d%g==0&&0<=d/g}}},PSEUDO:function(e,o){var t,a=b.pseudos[e]||b.setFilters[e.toLowerCase()]||se.error("unsupported pseudo: "+e);return a[S]?a(o):1<a.length?(t=[e,e,"",o],b.setFilters.hasOwnProperty(e.toLowerCase())?le(function(e,t){var n,r=a(e,o),i=r.length;while(i--)e[n=P(e,r[i])]=!(t[n]=r[i])}):function(e){return a(e,0,t)}):a}},pseudos:{not:le(function(e){var r=[],i=[],s=f(e.replace($,"$1"));return s[S]?le(function(e,t,n,r){var i,o=s(e,null,r,[]),a=e.length;while(a--)(i=o[a])&&(e[a]=!(t[a]=i))}):function(e,t,n){return r[0]=e,s(r,null,n,i),r[0]=null,!i.pop()}}),has:le(function(t){return function(e){return 0<se(t,e).length}}),contains:le(function(t){return t=t.replace(te,ne),function(e){return-1<(e.textContent||o(e)).indexOf(t)}}),lang:le(function(n){return V.test(n||"")||se.error("unsupported lang: "+n),n=n.replace(te,ne).toLowerCase(),function(e){var t;do{if(t=E?e.lang:e.getAttribute("xml:lang")||e.getAttribute("lang"))return(t=t.toLowerCase())===n||0===t.indexOf(n+"-")}while((e=e.parentNode)&&1===e.nodeType);return!1}}),target:function(e){var t=n.location&&n.location.hash;return t&&t.slice(1)===e.id},root:function(e){return e===a},focus:function(e){return e===C.activeElement&&(!C.hasFocus||C.hasFocus())&&!!(e.type||e.href||~e.tabIndex)},enabled:ge(!1),disabled:ge(!0),checked:function(e){var t=e.nodeName.toLowerCase();return"input"===t&&!!e.checked||"option"===t&&!!e.selected},selected:function(e){return e.parentNode&&e.parentNode.selectedIndex,!0===e.selected},empty:function(e){for(e=e.firstChild;e;e=e.nextSibling)if(e.nodeType<6)return!1;return!0},parent:function(e){return!b.pseudos.empty(e)},header:function(e){return J.test(e.nodeName)},input:function(e){return Q.test(e.nodeName)},button:function(e){var t=e.nodeName.toLowerCase();return"input"===t&&"button"===e.type||"button"===t},text:function(e){var t;return"input"===e.nodeName.toLowerCase()&&"text"===e.type&&(null==(t=e.getAttribute("type"))||"text"===t.toLowerCase())},first:ve(function(){return[0]}),last:ve(function(e,t){return[t-1]}),eq:ve(function(e,t,n){return[n<0?n+t:n]}),even:ve(function(e,t){for(var n=0;n<t;n+=2)e.push(n);return e}),odd:ve(function(e,t){for(var n=1;n<t;n+=2)e.push(n);return e}),lt:ve(function(e,t,n){for(var r=n<0?n+t:t<n?t:n;0<=--r;)e.push(r);return e}),gt:ve(function(e,t,n){for(var r=n<0?n+t:n;++r<t;)e.push(r);return e})}}).pseudos.nth=b.pseudos.eq,{radio:!0,checkbox:!0,file:!0,password:!0,image:!0})b.pseudos[e]=de(e);for(e in{submit:!0,reset:!0})b.pseudos[e]=he(e);function me(){}function xe(e){for(var t=0,n=e.length,r="";t<n;t++)r+=e[t].value;return r}function be(s,e,t){var u=e.dir,l=e.next,c=l||u,f=t&&"parentNode"===c,p=r++;return e.first?function(e,t,n){while(e=e[u])if(1===e.nodeType||f)return s(e,t,n);return!1}:function(e,t,n){var r,i,o,a=[k,p];if(n){while(e=e[u])if((1===e.nodeType||f)&&s(e,t,n))return!0}else while(e=e[u])if(1===e.nodeType||f)if(i=(o=e[S]||(e[S]={}))[e.uniqueID]||(o[e.uniqueID]={}),l&&l===e.nodeName.toLowerCase())e=e[u]||e;else{if((r=i[c])&&r[0]===k&&r[1]===p)return a[2]=r[2];if((i[c]=a)[2]=s(e,t,n))return!0}return!1}}function we(i){return 1<i.length?function(e,t,n){var r=i.length;while(r--)if(!i[r](e,t,n))return!1;return!0}:i[0]}function Te(e,t,n,r,i){for(var o,a=[],s=0,u=e.length,l=null!=t;s<u;s++)(o=e[s])&&(n&&!n(o,r,i)||(a.push(o),l&&t.push(s)));return a}function Ce(d,h,g,v,y,e){return v&&!v[S]&&(v=Ce(v)),y&&!y[S]&&(y=Ce(y,e)),le(function(e,t,n,r){var i,o,a,s=[],u=[],l=t.length,c=e||function(e,t,n){for(var r=0,i=t.length;r<i;r++)se(e,t[r],n);return n}(h||"*",n.nodeType?[n]:n,[]),f=!d||!e&&h?c:Te(c,s,d,n,r),p=g?y||(e?d:l||v)?[]:t:f;if(g&&g(f,p,n,r),v){i=Te(p,u),v(i,[],n,r),o=i.length;while(o--)(a=i[o])&&(p[u[o]]=!(f[u[o]]=a))}if(e){if(y||d){if(y){i=[],o=p.length;while(o--)(a=p[o])&&i.push(f[o]=a);y(null,p=[],i,r)}o=p.length;while(o--)(a=p[o])&&-1<(i=y?P(e,a):s[o])&&(e[i]=!(t[i]=a))}}else p=Te(p===t?p.splice(l,p.length):p),y?y(null,t,p,r):H.apply(t,p)})}function Ee(e){for(var i,t,n,r=e.length,o=b.relative[e[0].type],a=o||b.relative[" "],s=o?1:0,u=be(function(e){return e===i},a,!0),l=be(function(e){return-1<P(i,e)},a,!0),c=[function(e,t,n){var r=!o&&(n||t!==w)||((i=t).nodeType?u(e,t,n):l(e,t,n));return i=null,r}];s<r;s++)if(t=b.relative[e[s].type])c=[be(we(c),t)];else{if((t=b.filter[e[s].type].apply(null,e[s].matches))[S]){for(n=++s;n<r;n++)if(b.relative[e[n].type])break;return Ce(1<s&&we(c),1<s&&xe(e.slice(0,s-1).concat({value:" "===e[s-2].type?"*":""})).replace($,"$1"),t,s<n&&Ee(e.slice(s,n)),n<r&&Ee(e=e.slice(n)),n<r&&xe(e))}c.push(t)}return we(c)}return me.prototype=b.filters=b.pseudos,b.setFilters=new me,h=se.tokenize=function(e,t){var n,r,i,o,a,s,u,l=x[e+" "];if(l)return t?0:l.slice(0);a=e,s=[],u=b.preFilter;while(a){for(o in n&&!(r=_.exec(a))||(r&&(a=a.slice(r[0].length)||a),s.push(i=[])),n=!1,(r=z.exec(a))&&(n=r.shift(),i.push({value:n,type:r[0].replace($," ")}),a=a.slice(n.length)),b.filter)!(r=G[o].exec(a))||u[o]&&!(r=u[o](r))||(n=r.shift(),i.push({value:n,type:o,matches:r}),a=a.slice(n.length));if(!n)break}return t?a.length:a?se.error(e):x(e,s).slice(0)},f=se.compile=function(e,t){var n,v,y,m,x,r,i=[],o=[],a=A[e+" "];if(!a){t||(t=h(e)),n=t.length;while(n--)(a=Ee(t[n]))[S]?i.push(a):o.push(a);(a=A(e,(v=o,m=0<(y=i).length,x=0<v.length,r=function(e,t,n,r,i){var o,a,s,u=0,l="0",c=e&&[],f=[],p=w,d=e||x&&b.find.TAG("*",i),h=k+=null==p?1:Math.random()||.1,g=d.length;for(i&&(w=t==C||t||i);l!==g&&null!=(o=d[l]);l++){if(x&&o){a=0,t||o.ownerDocument==C||(T(o),n=!E);while(s=v[a++])if(s(o,t||C,n)){r.push(o);break}i&&(k=h)}m&&((o=!s&&o)&&u--,e&&c.push(o))}if(u+=l,m&&l!==u){a=0;while(s=y[a++])s(c,f,t,n);if(e){if(0<u)while(l--)c[l]||f[l]||(f[l]=q.call(r));f=Te(f)}H.apply(r,f),i&&!e&&0<f.length&&1<u+y.length&&se.uniqueSort(r)}return i&&(k=h,w=p),c},m?le(r):r))).selector=e}return a},g=se.select=function(e,t,n,r){var i,o,a,s,u,l="function"==typeof e&&e,c=!r&&h(e=l.selector||e);if(n=n||[],1===c.length){if(2<(o=c[0]=c[0].slice(0)).length&&"ID"===(a=o[0]).type&&9===t.nodeType&&E&&b.relative[o[1].type]){if(!(t=(b.find.ID(a.matches[0].replace(te,ne),t)||[])[0]))return n;l&&(t=t.parentNode),e=e.slice(o.shift().value.length)}i=G.needsContext.test(e)?0:o.length;while(i--){if(a=o[i],b.relative[s=a.type])break;if((u=b.find[s])&&(r=u(a.matches[0].replace(te,ne),ee.test(o[0].type)&&ye(t.parentNode)||t))){if(o.splice(i,1),!(e=r.length&&xe(o)))return H.apply(n,r),n;break}}}return(l||f(e,c))(r,t,!E,n,!t||ee.test(e)&&ye(t.parentNode)||t),n},d.sortStable=S.split("").sort(D).join("")===S,d.detectDuplicates=!!l,T(),d.sortDetached=ce(function(e){return 1&e.compareDocumentPosition(C.createElement("fieldset"))}),ce(function(e){return e.innerHTML="<a href='#'></a>","#"===e.firstChild.getAttribute("href")})||fe("type|href|height|width",function(e,t,n){if(!n)return e.getAttribute(t,"type"===t.toLowerCase()?1:2)}),d.attributes&&ce(function(e){return e.innerHTML="<input/>",e.firstChild.setAttribute("value",""),""===e.firstChild.getAttribute("value")})||fe("value",function(e,t,n){if(!n&&"input"===e.nodeName.toLowerCase())return e.defaultValue}),ce(function(e){return null==e.getAttribute("disabled")})||fe(R,function(e,t,n){var r;if(!n)return!0===e[t]?t.toLowerCase():(r=e.getAttributeNode(t))&&r.specified?r.value:null}),se}(C);S.find=d,S.expr=d.selectors,S.expr[":"]=S.expr.pseudos,S.uniqueSort=S.unique=d.uniqueSort,S.text=d.getText,S.isXMLDoc=d.isXML,S.contains=d.contains,S.escapeSelector=d.escape;var h=function(e,t,n){var r=[],i=void 0!==n;while((e=e[t])&&9!==e.nodeType)if(1===e.nodeType){if(i&&S(e).is(n))break;r.push(e)}return r},T=function(e,t){for(var n=[];e;e=e.nextSibling)1===e.nodeType&&e!==t&&n.push(e);return n},k=S.expr.match.needsContext;function A(e,t){return e.nodeName&&e.nodeName.toLowerCase()===t.toLowerCase()}var N=/^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i;function D(e,n,r){return m(n)?S.grep(e,function(e,t){return!!n.call(e,t,e)!==r}):n.nodeType?S.grep(e,function(e){return e===n!==r}):"string"!=typeof n?S.grep(e,function(e){return-1<i.call(n,e)!==r}):S.filter(n,e,r)}S.filter=function(e,t,n){var r=t[0];return n&&(e=":not("+e+")"),1===t.length&&1===r.nodeType?S.find.matchesSelector(r,e)?[r]:[]:S.find.matches(e,S.grep(t,function(e){return 1===e.nodeType}))},S.fn.extend({find:function(e){var t,n,r=this.length,i=this;if("string"!=typeof e)return this.pushStack(S(e).filter(function(){for(t=0;t<r;t++)if(S.contains(i[t],this))return!0}));for(n=this.pushStack([]),t=0;t<r;t++)S.find(e,i[t],n);return 1<r?S.uniqueSort(n):n},filter:function(e){return this.pushStack(D(this,e||[],!1))},not:function(e){return this.pushStack(D(this,e||[],!0))},is:function(e){return!!D(this,"string"==typeof e&&k.test(e)?S(e):e||[],!1).length}});var j,q=/^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/;(S.fn.init=function(e,t,n){var r,i;if(!e)return this;if(n=n||j,"string"==typeof e){if(!(r="<"===e[0]&&">"===e[e.length-1]&&3<=e.length?[null,e,null]:q.exec(e))||!r[1]&&t)return!t||t.jquery?(t||n).find(e):this.constructor(t).find(e);if(r[1]){if(t=t instanceof S?t[0]:t,S.merge(this,S.parseHTML(r[1],t&&t.nodeType?t.ownerDocument||t:E,!0)),N.test(r[1])&&S.isPlainObject(t))for(r in t)m(this[r])?this[r](t[r]):this.attr(r,t[r]);return this}return(i=E.getElementById(r[2]))&&(this[0]=i,this.length=1),this}return e.nodeType?(this[0]=e,this.length=1,this):m(e)?void 0!==n.ready?n.ready(e):e(S):S.makeArray(e,this)}).prototype=S.fn,j=S(E);var L=/^(?:parents|prev(?:Until|All))/,H={children:!0,contents:!0,next:!0,prev:!0};function O(e,t){while((e=e[t])&&1!==e.nodeType);return e}S.fn.extend({has:function(e){var t=S(e,this),n=t.length;return this.filter(function(){for(var e=0;e<n;e++)if(S.contains(this,t[e]))return!0})},closest:function(e,t){var n,r=0,i=this.length,o=[],a="string"!=typeof e&&S(e);if(!k.test(e))for(;r<i;r++)for(n=this[r];n&&n!==t;n=n.parentNode)if(n.nodeType<11&&(a?-1<a.index(n):1===n.nodeType&&S.find.matchesSelector(n,e))){o.push(n);break}return this.pushStack(1<o.length?S.uniqueSort(o):o)},index:function(e){return e?"string"==typeof e?i.call(S(e),this[0]):i.call(this,e.jquery?e[0]:e):this[0]&&this[0].parentNode?this.first().prevAll().length:-1},add:function(e,t){return this.pushStack(S.uniqueSort(S.merge(this.get(),S(e,t))))},addBack:function(e){return this.add(null==e?this.prevObject:this.prevObject.filter(e))}}),S.each({parent:function(e){var t=e.parentNode;return t&&11!==t.nodeType?t:null},parents:function(e){return h(e,"parentNode")},parentsUntil:function(e,t,n){return h(e,"parentNode",n)},next:function(e){return O(e,"nextSibling")},prev:function(e){return O(e,"previousSibling")},nextAll:function(e){return h(e,"nextSibling")},prevAll:function(e){return h(e,"previousSibling")},nextUntil:function(e,t,n){return h(e,"nextSibling",n)},prevUntil:function(e,t,n){return h(e,"previousSibling",n)},siblings:function(e){return T((e.parentNode||{}).firstChild,e)},children:function(e){return T(e.firstChild)},contents:function(e){return null!=e.contentDocument&&r(e.contentDocument)?e.contentDocument:(A(e,"template")&&(e=e.content||e),S.merge([],e.childNodes))}},function(r,i){S.fn[r]=function(e,t){var n=S.map(this,i,e);return"Until"!==r.slice(-5)&&(t=e),t&&"string"==typeof t&&(n=S.filter(t,n)),1<this.length&&(H[r]||S.uniqueSort(n),L.test(r)&&n.reverse()),this.pushStack(n)}});var P=/[^\x20\t\r\n\f]+/g;function R(e){return e}function M(e){throw e}function I(e,t,n,r){var i;try{e&&m(i=e.promise)?i.call(e).done(t).fail(n):e&&m(i=e.then)?i.call(e,t,n):t.apply(void 0,[e].slice(r))}catch(e){n.apply(void 0,[e])}}S.Callbacks=function(r){var e,n;r="string"==typeof r?(e=r,n={},S.each(e.match(P)||[],function(e,t){n[t]=!0}),n):S.extend({},r);var i,t,o,a,s=[],u=[],l=-1,c=function(){for(a=a||r.once,o=i=!0;u.length;l=-1){t=u.shift();while(++l<s.length)!1===s[l].apply(t[0],t[1])&&r.stopOnFalse&&(l=s.length,t=!1)}r.memory||(t=!1),i=!1,a&&(s=t?[]:"")},f={add:function(){return s&&(t&&!i&&(l=s.length-1,u.push(t)),function n(e){S.each(e,function(e,t){m(t)?r.unique&&f.has(t)||s.push(t):t&&t.length&&"string"!==w(t)&&n(t)})}(arguments),t&&!i&&c()),this},remove:function(){return S.each(arguments,function(e,t){var n;while(-1<(n=S.inArray(t,s,n)))s.splice(n,1),n<=l&&l--}),this},has:function(e){return e?-1<S.inArray(e,s):0<s.length},empty:function(){return s&&(s=[]),this},disable:function(){return a=u=[],s=t="",this},disabled:function(){return!s},lock:function(){return a=u=[],t||i||(s=t=""),this},locked:function(){return!!a},fireWith:function(e,t){return a||(t=[e,(t=t||[]).slice?t.slice():t],u.push(t),i||c()),this},fire:function(){return f.fireWith(this,arguments),this},fired:function(){return!!o}};return f},S.extend({Deferred:function(e){var o=[["notify","progress",S.Callbacks("memory"),S.Callbacks("memory"),2],["resolve","done",S.Callbacks("once memory"),S.Callbacks("once memory"),0,"resolved"],["reject","fail",S.Callbacks("once memory"),S.Callbacks("once memory"),1,"rejected"]],i="pending",a={state:function(){return i},always:function(){return s.done(arguments).fail(arguments),this},"catch":function(e){return a.then(null,e)},pipe:function(){var i=arguments;return S.Deferred(function(r){S.each(o,function(e,t){var n=m(i[t[4]])&&i[t[4]];s[t[1]](function(){var e=n&&n.apply(this,arguments);e&&m(e.promise)?e.promise().progress(r.notify).done(r.resolve).fail(r.reject):r[t[0]+"With"](this,n?[e]:arguments)})}),i=null}).promise()},then:function(t,n,r){var u=0;function l(i,o,a,s){return function(){var n=this,r=arguments,e=function(){var e,t;if(!(i<u)){if((e=a.apply(n,r))===o.promise())throw new TypeError("Thenable self-resolution");t=e&&("object"==typeof e||"function"==typeof e)&&e.then,m(t)?s?t.call(e,l(u,o,R,s),l(u,o,M,s)):(u++,t.call(e,l(u,o,R,s),l(u,o,M,s),l(u,o,R,o.notifyWith))):(a!==R&&(n=void 0,r=[e]),(s||o.resolveWith)(n,r))}},t=s?e:function(){try{e()}catch(e){S.Deferred.exceptionHook&&S.Deferred.exceptionHook(e,t.stackTrace),u<=i+1&&(a!==M&&(n=void 0,r=[e]),o.rejectWith(n,r))}};i?t():(S.Deferred.getStackHook&&(t.stackTrace=S.Deferred.getStackHook()),C.setTimeout(t))}}return S.Deferred(function(e){o[0][3].add(l(0,e,m(r)?r:R,e.notifyWith)),o[1][3].add(l(0,e,m(t)?t:R)),o[2][3].add(l(0,e,m(n)?n:M))}).promise()},promise:function(e){return null!=e?S.extend(e,a):a}},s={};return S.each(o,function(e,t){var n=t[2],r=t[5];a[t[1]]=n.add,r&&n.add(function(){i=r},o[3-e][2].disable,o[3-e][3].disable,o[0][2].lock,o[0][3].lock),n.add(t[3].fire),s[t[0]]=function(){return s[t[0]+"With"](this===s?void 0:this,arguments),this},s[t[0]+"With"]=n.fireWith}),a.promise(s),e&&e.call(s,s),s},when:function(e){var n=arguments.length,t=n,r=Array(t),i=s.call(arguments),o=S.Deferred(),a=function(t){return function(e){r[t]=this,i[t]=1<arguments.length?s.call(arguments):e,--n||o.resolveWith(r,i)}};if(n<=1&&(I(e,o.done(a(t)).resolve,o.reject,!n),"pending"===o.state()||m(i[t]&&i[t].then)))return o.then();while(t--)I(i[t],a(t),o.reject);return o.promise()}});var W=/^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/;S.Deferred.exceptionHook=function(e,t){C.console&&C.console.warn&&e&&W.test(e.name)&&C.console.warn("jQuery.Deferred exception: "+e.message,e.stack,t)},S.readyException=function(e){C.setTimeout(function(){throw e})};var F=S.Deferred();function B(){E.removeEventListener("DOMContentLoaded",B),C.removeEventListener("load",B),S.ready()}S.fn.ready=function(e){return F.then(e)["catch"](function(e){S.readyException(e)}),this},S.extend({isReady:!1,readyWait:1,ready:function(e){(!0===e?--S.readyWait:S.isReady)||(S.isReady=!0)!==e&&0<--S.readyWait||F.resolveWith(E,[S])}}),S.ready.then=F.then,"complete"===E.readyState||"loading"!==E.readyState&&!E.documentElement.doScroll?C.setTimeout(S.ready):(E.addEventListener("DOMContentLoaded",B),C.addEventListener("load",B));var $=function(e,t,n,r,i,o,a){var s=0,u=e.length,l=null==n;if("object"===w(n))for(s in i=!0,n)$(e,t,s,n[s],!0,o,a);else if(void 0!==r&&(i=!0,m(r)||(a=!0),l&&(a?(t.call(e,r),t=null):(l=t,t=function(e,t,n){return l.call(S(e),n)})),t))for(;s<u;s++)t(e[s],n,a?r:r.call(e[s],s,t(e[s],n)));return i?e:l?t.call(e):u?t(e[0],n):o},_=/^-ms-/,z=/-([a-z])/g;function U(e,t){return t.toUpperCase()}function X(e){return e.replace(_,"ms-").replace(z,U)}var V=function(e){return 1===e.nodeType||9===e.nodeType||!+e.nodeType};function G(){this.expando=S.expando+G.uid++}G.uid=1,G.prototype={cache:function(e){var t=e[this.expando];return t||(t={},V(e)&&(e.nodeType?e[this.expando]=t:Object.defineProperty(e,this.expando,{value:t,configurable:!0}))),t},set:function(e,t,n){var r,i=this.cache(e);if("string"==typeof t)i[X(t)]=n;else for(r in t)i[X(r)]=t[r];return i},get:function(e,t){return void 0===t?this.cache(e):e[this.expando]&&e[this.expando][X(t)]},access:function(e,t,n){return void 0===t||t&&"string"==typeof t&&void 0===n?this.get(e,t):(this.set(e,t,n),void 0!==n?n:t)},remove:function(e,t){var n,r=e[this.expando];if(void 0!==r){if(void 0!==t){n=(t=Array.isArray(t)?t.map(X):(t=X(t))in r?[t]:t.match(P)||[]).length;while(n--)delete r[t[n]]}(void 0===t||S.isEmptyObject(r))&&(e.nodeType?e[this.expando]=void 0:delete e[this.expando])}},hasData:function(e){var t=e[this.expando];return void 0!==t&&!S.isEmptyObject(t)}};var Y=new G,Q=new G,J=/^(?:\{[\w\W]*\}|\[[\w\W]*\])$/,K=/[A-Z]/g;function Z(e,t,n){var r,i;if(void 0===n&&1===e.nodeType)if(r="data-"+t.replace(K,"-$&").toLowerCase(),"string"==typeof(n=e.getAttribute(r))){try{n="true"===(i=n)||"false"!==i&&("null"===i?null:i===+i+""?+i:J.test(i)?JSON.parse(i):i)}catch(e){}Q.set(e,t,n)}else n=void 0;return n}S.extend({hasData:function(e){return Q.hasData(e)||Y.hasData(e)},data:function(e,t,n){return Q.access(e,t,n)},removeData:function(e,t){Q.remove(e,t)},_data:function(e,t,n){return Y.access(e,t,n)},_removeData:function(e,t){Y.remove(e,t)}}),S.fn.extend({data:function(n,e){var t,r,i,o=this[0],a=o&&o.attributes;if(void 0===n){if(this.length&&(i=Q.get(o),1===o.nodeType&&!Y.get(o,"hasDataAttrs"))){t=a.length;while(t--)a[t]&&0===(r=a[t].name).indexOf("data-")&&(r=X(r.slice(5)),Z(o,r,i[r]));Y.set(o,"hasDataAttrs",!0)}return i}return"object"==typeof n?this.each(function(){Q.set(this,n)}):$(this,function(e){var t;if(o&&void 0===e)return void 0!==(t=Q.get(o,n))?t:void 0!==(t=Z(o,n))?t:void 0;this.each(function(){Q.set(this,n,e)})},null,e,1<arguments.length,null,!0)},removeData:function(e){return this.each(function(){Q.remove(this,e)})}}),S.extend({queue:function(e,t,n){var r;if(e)return t=(t||"fx")+"queue",r=Y.get(e,t),n&&(!r||Array.isArray(n)?r=Y.access(e,t,S.makeArray(n)):r.push(n)),r||[]},dequeue:function(e,t){t=t||"fx";var n=S.queue(e,t),r=n.length,i=n.shift(),o=S._queueHooks(e,t);"inprogress"===i&&(i=n.shift(),r--),i&&("fx"===t&&n.unshift("inprogress"),delete o.stop,i.call(e,function(){S.dequeue(e,t)},o)),!r&&o&&o.empty.fire()},_queueHooks:function(e,t){var n=t+"queueHooks";return Y.get(e,n)||Y.access(e,n,{empty:S.Callbacks("once memory").add(function(){Y.remove(e,[t+"queue",n])})})}}),S.fn.extend({queue:function(t,n){var e=2;return"string"!=typeof t&&(n=t,t="fx",e--),arguments.length<e?S.queue(this[0],t):void 0===n?this:this.each(function(){var e=S.queue(this,t,n);S._queueHooks(this,t),"fx"===t&&"inprogress"!==e[0]&&S.dequeue(this,t)})},dequeue:function(e){return this.each(function(){S.dequeue(this,e)})},clearQueue:function(e){return this.queue(e||"fx",[])},promise:function(e,t){var n,r=1,i=S.Deferred(),o=this,a=this.length,s=function(){--r||i.resolveWith(o,[o])};"string"!=typeof e&&(t=e,e=void 0),e=e||"fx";while(a--)(n=Y.get(o[a],e+"queueHooks"))&&n.empty&&(r++,n.empty.add(s));return s(),i.promise(t)}});var ee=/[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/.source,te=new RegExp("^(?:([+-])=|)("+ee+")([a-z%]*)$","i"),ne=["Top","Right","Bottom","Left"],re=E.documentElement,ie=function(e){return S.contains(e.ownerDocument,e)},oe={composed:!0};re.getRootNode&&(ie=function(e){return S.contains(e.ownerDocument,e)||e.getRootNode(oe)===e.ownerDocument});var ae=function(e,t){return"none"===(e=t||e).style.display||""===e.style.display&&ie(e)&&"none"===S.css(e,"display")};function se(e,t,n,r){var i,o,a=20,s=r?function(){return r.cur()}:function(){return S.css(e,t,"")},u=s(),l=n&&n[3]||(S.cssNumber[t]?"":"px"),c=e.nodeType&&(S.cssNumber[t]||"px"!==l&&+u)&&te.exec(S.css(e,t));if(c&&c[3]!==l){u/=2,l=l||c[3],c=+u||1;while(a--)S.style(e,t,c+l),(1-o)*(1-(o=s()/u||.5))<=0&&(a=0),c/=o;c*=2,S.style(e,t,c+l),n=n||[]}return n&&(c=+c||+u||0,i=n[1]?c+(n[1]+1)*n[2]:+n[2],r&&(r.unit=l,r.start=c,r.end=i)),i}var ue={};function le(e,t){for(var n,r,i,o,a,s,u,l=[],c=0,f=e.length;c<f;c++)(r=e[c]).style&&(n=r.style.display,t?("none"===n&&(l[c]=Y.get(r,"display")||null,l[c]||(r.style.display="")),""===r.style.display&&ae(r)&&(l[c]=(u=a=o=void 0,a=(i=r).ownerDocument,s=i.nodeName,(u=ue[s])||(o=a.body.appendChild(a.createElement(s)),u=S.css(o,"display"),o.parentNode.removeChild(o),"none"===u&&(u="block"),ue[s]=u)))):"none"!==n&&(l[c]="none",Y.set(r,"display",n)));for(c=0;c<f;c++)null!=l[c]&&(e[c].style.display=l[c]);return e}S.fn.extend({show:function(){return le(this,!0)},hide:function(){return le(this)},toggle:function(e){return"boolean"==typeof e?e?this.show():this.hide():this.each(function(){ae(this)?S(this).show():S(this).hide()})}});var ce,fe,pe=/^(?:checkbox|radio)$/i,de=/<([a-z][^\/\0>\x20\t\r\n\f]*)/i,he=/^$|^module$|\/(?:java|ecma)script/i;ce=E.createDocumentFragment().appendChild(E.createElement("div")),(fe=E.createElement("input")).setAttribute("type","radio"),fe.setAttribute("checked","checked"),fe.setAttribute("name","t"),ce.appendChild(fe),y.checkClone=ce.cloneNode(!0).cloneNode(!0).lastChild.checked,ce.innerHTML="<textarea>x</textarea>",y.noCloneChecked=!!ce.cloneNode(!0).lastChild.defaultValue,ce.innerHTML="<option></option>",y.option=!!ce.lastChild;var ge={thead:[1,"<table>","</table>"],col:[2,"<table><colgroup>","</colgroup></table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"],_default:[0,"",""]};function ve(e,t){var n;return n="undefined"!=typeof e.getElementsByTagName?e.getElementsByTagName(t||"*"):"undefined"!=typeof e.querySelectorAll?e.querySelectorAll(t||"*"):[],void 0===t||t&&A(e,t)?S.merge([e],n):n}function ye(e,t){for(var n=0,r=e.length;n<r;n++)Y.set(e[n],"globalEval",!t||Y.get(t[n],"globalEval"))}ge.tbody=ge.tfoot=ge.colgroup=ge.caption=ge.thead,ge.th=ge.td,y.option||(ge.optgroup=ge.option=[1,"<select multiple='multiple'>","</select>"]);var me=/<|&#?\w+;/;function xe(e,t,n,r,i){for(var o,a,s,u,l,c,f=t.createDocumentFragment(),p=[],d=0,h=e.length;d<h;d++)if((o=e[d])||0===o)if("object"===w(o))S.merge(p,o.nodeType?[o]:o);else if(me.test(o)){a=a||f.appendChild(t.createElement("div")),s=(de.exec(o)||["",""])[1].toLowerCase(),u=ge[s]||ge._default,a.innerHTML=u[1]+S.htmlPrefilter(o)+u[2],c=u[0];while(c--)a=a.lastChild;S.merge(p,a.childNodes),(a=f.firstChild).textContent=""}else p.push(t.createTextNode(o));f.textContent="",d=0;while(o=p[d++])if(r&&-1<S.inArray(o,r))i&&i.push(o);else if(l=ie(o),a=ve(f.appendChild(o),"script"),l&&ye(a),n){c=0;while(o=a[c++])he.test(o.type||"")&&n.push(o)}return f}var be=/^key/,we=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,Te=/^([^.]*)(?:\.(.+)|)/;function Ce(){return!0}function Ee(){return!1}function Se(e,t){return e===function(){try{return E.activeElement}catch(e){}}()==("focus"===t)}function ke(e,t,n,r,i,o){var a,s;if("object"==typeof t){for(s in"string"!=typeof n&&(r=r||n,n=void 0),t)ke(e,s,n,r,t[s],o);return e}if(null==r&&null==i?(i=n,r=n=void 0):null==i&&("string"==typeof n?(i=r,r=void 0):(i=r,r=n,n=void 0)),!1===i)i=Ee;else if(!i)return e;return 1===o&&(a=i,(i=function(e){return S().off(e),a.apply(this,arguments)}).guid=a.guid||(a.guid=S.guid++)),e.each(function(){S.event.add(this,t,i,r,n)})}function Ae(e,i,o){o?(Y.set(e,i,!1),S.event.add(e,i,{namespace:!1,handler:function(e){var t,n,r=Y.get(this,i);if(1&e.isTrigger&&this[i]){if(r.length)(S.event.special[i]||{}).delegateType&&e.stopPropagation();else if(r=s.call(arguments),Y.set(this,i,r),t=o(this,i),this[i](),r!==(n=Y.get(this,i))||t?Y.set(this,i,!1):n={},r!==n)return e.stopImmediatePropagation(),e.preventDefault(),n.value}else r.length&&(Y.set(this,i,{value:S.event.trigger(S.extend(r[0],S.Event.prototype),r.slice(1),this)}),e.stopImmediatePropagation())}})):void 0===Y.get(e,i)&&S.event.add(e,i,Ce)}S.event={global:{},add:function(t,e,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Y.get(t);if(V(t)){n.handler&&(n=(o=n).handler,i=o.selector),i&&S.find.matchesSelector(re,i),n.guid||(n.guid=S.guid++),(u=v.events)||(u=v.events=Object.create(null)),(a=v.handle)||(a=v.handle=function(e){return"undefined"!=typeof S&&S.event.triggered!==e.type?S.event.dispatch.apply(t,arguments):void 0}),l=(e=(e||"").match(P)||[""]).length;while(l--)d=g=(s=Te.exec(e[l])||[])[1],h=(s[2]||"").split(".").sort(),d&&(f=S.event.special[d]||{},d=(i?f.delegateType:f.bindType)||d,f=S.event.special[d]||{},c=S.extend({type:d,origType:g,data:r,handler:n,guid:n.guid,selector:i,needsContext:i&&S.expr.match.needsContext.test(i),namespace:h.join(".")},o),(p=u[d])||((p=u[d]=[]).delegateCount=0,f.setup&&!1!==f.setup.call(t,r,h,a)||t.addEventListener&&t.addEventListener(d,a)),f.add&&(f.add.call(t,c),c.handler.guid||(c.handler.guid=n.guid)),i?p.splice(p.delegateCount++,0,c):p.push(c),S.event.global[d]=!0)}},remove:function(e,t,n,r,i){var o,a,s,u,l,c,f,p,d,h,g,v=Y.hasData(e)&&Y.get(e);if(v&&(u=v.events)){l=(t=(t||"").match(P)||[""]).length;while(l--)if(d=g=(s=Te.exec(t[l])||[])[1],h=(s[2]||"").split(".").sort(),d){f=S.event.special[d]||{},p=u[d=(r?f.delegateType:f.bindType)||d]||[],s=s[2]&&new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"),a=o=p.length;while(o--)c=p[o],!i&&g!==c.origType||n&&n.guid!==c.guid||s&&!s.test(c.namespace)||r&&r!==c.selector&&("**"!==r||!c.selector)||(p.splice(o,1),c.selector&&p.delegateCount--,f.remove&&f.remove.call(e,c));a&&!p.length&&(f.teardown&&!1!==f.teardown.call(e,h,v.handle)||S.removeEvent(e,d,v.handle),delete u[d])}else for(d in u)S.event.remove(e,d+t[l],n,r,!0);S.isEmptyObject(u)&&Y.remove(e,"handle events")}},dispatch:function(e){var t,n,r,i,o,a,s=new Array(arguments.length),u=S.event.fix(e),l=(Y.get(this,"events")||Object.create(null))[u.type]||[],c=S.event.special[u.type]||{};for(s[0]=u,t=1;t<arguments.length;t++)s[t]=arguments[t];if(u.delegateTarget=this,!c.preDispatch||!1!==c.preDispatch.call(this,u)){a=S.event.handlers.call(this,u,l),t=0;while((i=a[t++])&&!u.isPropagationStopped()){u.currentTarget=i.elem,n=0;while((o=i.handlers[n++])&&!u.isImmediatePropagationStopped())u.rnamespace&&!1!==o.namespace&&!u.rnamespace.test(o.namespace)||(u.handleObj=o,u.data=o.data,void 0!==(r=((S.event.special[o.origType]||{}).handle||o.handler).apply(i.elem,s))&&!1===(u.result=r)&&(u.preventDefault(),u.stopPropagation()))}return c.postDispatch&&c.postDispatch.call(this,u),u.result}},handlers:function(e,t){var n,r,i,o,a,s=[],u=t.delegateCount,l=e.target;if(u&&l.nodeType&&!("click"===e.type&&1<=e.button))for(;l!==this;l=l.parentNode||this)if(1===l.nodeType&&("click"!==e.type||!0!==l.disabled)){for(o=[],a={},n=0;n<u;n++)void 0===a[i=(r=t[n]).selector+" "]&&(a[i]=r.needsContext?-1<S(i,this).index(l):S.find(i,this,null,[l]).length),a[i]&&o.push(r);o.length&&s.push({elem:l,handlers:o})}return l=this,u<t.length&&s.push({elem:l,handlers:t.slice(u)}),s},addProp:function(t,e){Object.defineProperty(S.Event.prototype,t,{enumerable:!0,configurable:!0,get:m(e)?function(){if(this.originalEvent)return e(this.originalEvent)}:function(){if(this.originalEvent)return this.originalEvent[t]},set:function(e){Object.defineProperty(this,t,{enumerable:!0,configurable:!0,writable:!0,value:e})}})},fix:function(e){return e[S.expando]?e:new S.Event(e)},special:{load:{noBubble:!0},click:{setup:function(e){var t=this||e;return pe.test(t.type)&&t.click&&A(t,"input")&&Ae(t,"click",Ce),!1},trigger:function(e){var t=this||e;return pe.test(t.type)&&t.click&&A(t,"input")&&Ae(t,"click"),!0},_default:function(e){var t=e.target;return pe.test(t.type)&&t.click&&A(t,"input")&&Y.get(t,"click")||A(t,"a")}},beforeunload:{postDispatch:function(e){void 0!==e.result&&e.originalEvent&&(e.originalEvent.returnValue=e.result)}}}},S.removeEvent=function(e,t,n){e.removeEventListener&&e.removeEventListener(t,n)},S.Event=function(e,t){if(!(this instanceof S.Event))return new S.Event(e,t);e&&e.type?(this.originalEvent=e,this.type=e.type,this.isDefaultPrevented=e.defaultPrevented||void 0===e.defaultPrevented&&!1===e.returnValue?Ce:Ee,this.target=e.target&&3===e.target.nodeType?e.target.parentNode:e.target,this.currentTarget=e.currentTarget,this.relatedTarget=e.relatedTarget):this.type=e,t&&S.extend(this,t),this.timeStamp=e&&e.timeStamp||Date.now(),this[S.expando]=!0},S.Event.prototype={constructor:S.Event,isDefaultPrevented:Ee,isPropagationStopped:Ee,isImmediatePropagationStopped:Ee,isSimulated:!1,preventDefault:function(){var e=this.originalEvent;this.isDefaultPrevented=Ce,e&&!this.isSimulated&&e.preventDefault()},stopPropagation:function(){var e=this.originalEvent;this.isPropagationStopped=Ce,e&&!this.isSimulated&&e.stopPropagation()},stopImmediatePropagation:function(){var e=this.originalEvent;this.isImmediatePropagationStopped=Ce,e&&!this.isSimulated&&e.stopImmediatePropagation(),this.stopPropagation()}},S.each({altKey:!0,bubbles:!0,cancelable:!0,changedTouches:!0,ctrlKey:!0,detail:!0,eventPhase:!0,metaKey:!0,pageX:!0,pageY:!0,shiftKey:!0,view:!0,"char":!0,code:!0,charCode:!0,key:!0,keyCode:!0,button:!0,buttons:!0,clientX:!0,clientY:!0,offsetX:!0,offsetY:!0,pointerId:!0,pointerType:!0,screenX:!0,screenY:!0,targetTouches:!0,toElement:!0,touches:!0,which:function(e){var t=e.button;return null==e.which&&be.test(e.type)?null!=e.charCode?e.charCode:e.keyCode:!e.which&&void 0!==t&&we.test(e.type)?1&t?1:2&t?3:4&t?2:0:e.which}},S.event.addProp),S.each({focus:"focusin",blur:"focusout"},function(e,t){S.event.special[e]={setup:function(){return Ae(this,e,Se),!1},trigger:function(){return Ae(this,e),!0},delegateType:t}}),S.each({mouseenter:"mouseover",mouseleave:"mouseout",pointerenter:"pointerover",pointerleave:"pointerout"},function(e,i){S.event.special[e]={delegateType:i,bindType:i,handle:function(e){var t,n=e.relatedTarget,r=e.handleObj;return n&&(n===this||S.contains(this,n))||(e.type=r.origType,t=r.handler.apply(this,arguments),e.type=i),t}}}),S.fn.extend({on:function(e,t,n,r){return ke(this,e,t,n,r)},one:function(e,t,n,r){return ke(this,e,t,n,r,1)},off:function(e,t,n){var r,i;if(e&&e.preventDefault&&e.handleObj)return r=e.handleObj,S(e.delegateTarget).off(r.namespace?r.origType+"."+r.namespace:r.origType,r.selector,r.handler),this;if("object"==typeof e){for(i in e)this.off(i,t,e[i]);return this}return!1!==t&&"function"!=typeof t||(n=t,t=void 0),!1===n&&(n=Ee),this.each(function(){S.event.remove(this,e,n,t)})}});var Ne=/<script|<style|<link/i,De=/checked\s*(?:[^=]|=\s*.checked.)/i,je=/^\s*<!(?:\[CDATA\[|--)|(?:\]\]|--)>\s*$/g;function qe(e,t){return A(e,"table")&&A(11!==t.nodeType?t:t.firstChild,"tr")&&S(e).children("tbody")[0]||e}function Le(e){return e.type=(null!==e.getAttribute("type"))+"/"+e.type,e}function He(e){return"true/"===(e.type||"").slice(0,5)?e.type=e.type.slice(5):e.removeAttribute("type"),e}function Oe(e,t){var n,r,i,o,a,s;if(1===t.nodeType){if(Y.hasData(e)&&(s=Y.get(e).events))for(i in Y.remove(t,"handle events"),s)for(n=0,r=s[i].length;n<r;n++)S.event.add(t,i,s[i][n]);Q.hasData(e)&&(o=Q.access(e),a=S.extend({},o),Q.set(t,a))}}function Pe(n,r,i,o){r=g(r);var e,t,a,s,u,l,c=0,f=n.length,p=f-1,d=r[0],h=m(d);if(h||1<f&&"string"==typeof d&&!y.checkClone&&De.test(d))return n.each(function(e){var t=n.eq(e);h&&(r[0]=d.call(this,e,t.html())),Pe(t,r,i,o)});if(f&&(t=(e=xe(r,n[0].ownerDocument,!1,n,o)).firstChild,1===e.childNodes.length&&(e=t),t||o)){for(s=(a=S.map(ve(e,"script"),Le)).length;c<f;c++)u=e,c!==p&&(u=S.clone(u,!0,!0),s&&S.merge(a,ve(u,"script"))),i.call(n[c],u,c);if(s)for(l=a[a.length-1].ownerDocument,S.map(a,He),c=0;c<s;c++)u=a[c],he.test(u.type||"")&&!Y.access(u,"globalEval")&&S.contains(l,u)&&(u.src&&"module"!==(u.type||"").toLowerCase()?S._evalUrl&&!u.noModule&&S._evalUrl(u.src,{nonce:u.nonce||u.getAttribute("nonce")},l):b(u.textContent.replace(je,""),u,l))}return n}function Re(e,t,n){for(var r,i=t?S.filter(t,e):e,o=0;null!=(r=i[o]);o++)n||1!==r.nodeType||S.cleanData(ve(r)),r.parentNode&&(n&&ie(r)&&ye(ve(r,"script")),r.parentNode.removeChild(r));return e}S.extend({htmlPrefilter:function(e){return e},clone:function(e,t,n){var r,i,o,a,s,u,l,c=e.cloneNode(!0),f=ie(e);if(!(y.noCloneChecked||1!==e.nodeType&&11!==e.nodeType||S.isXMLDoc(e)))for(a=ve(c),r=0,i=(o=ve(e)).length;r<i;r++)s=o[r],u=a[r],void 0,"input"===(l=u.nodeName.toLowerCase())&&pe.test(s.type)?u.checked=s.checked:"input"!==l&&"textarea"!==l||(u.defaultValue=s.defaultValue);if(t)if(n)for(o=o||ve(e),a=a||ve(c),r=0,i=o.length;r<i;r++)Oe(o[r],a[r]);else Oe(e,c);return 0<(a=ve(c,"script")).length&&ye(a,!f&&ve(e,"script")),c},cleanData:function(e){for(var t,n,r,i=S.event.special,o=0;void 0!==(n=e[o]);o++)if(V(n)){if(t=n[Y.expando]){if(t.events)for(r in t.events)i[r]?S.event.remove(n,r):S.removeEvent(n,r,t.handle);n[Y.expando]=void 0}n[Q.expando]&&(n[Q.expando]=void 0)}}}),S.fn.extend({detach:function(e){return Re(this,e,!0)},remove:function(e){return Re(this,e)},text:function(e){return $(this,function(e){return void 0===e?S.text(this):this.empty().each(function(){1!==this.nodeType&&11!==this.nodeType&&9!==this.nodeType||(this.textContent=e)})},null,e,arguments.length)},append:function(){return Pe(this,arguments,function(e){1!==this.nodeType&&11!==this.nodeType&&9!==this.nodeType||qe(this,e).appendChild(e)})},prepend:function(){return Pe(this,arguments,function(e){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var t=qe(this,e);t.insertBefore(e,t.firstChild)}})},before:function(){return Pe(this,arguments,function(e){this.parentNode&&this.parentNode.insertBefore(e,this)})},after:function(){return Pe(this,arguments,function(e){this.parentNode&&this.parentNode.insertBefore(e,this.nextSibling)})},empty:function(){for(var e,t=0;null!=(e=this[t]);t++)1===e.nodeType&&(S.cleanData(ve(e,!1)),e.textContent="");return this},clone:function(e,t){return e=null!=e&&e,t=null==t?e:t,this.map(function(){return S.clone(this,e,t)})},html:function(e){return $(this,function(e){var t=this[0]||{},n=0,r=this.length;if(void 0===e&&1===t.nodeType)return t.innerHTML;if("string"==typeof e&&!Ne.test(e)&&!ge[(de.exec(e)||["",""])[1].toLowerCase()]){e=S.htmlPrefilter(e);try{for(;n<r;n++)1===(t=this[n]||{}).nodeType&&(S.cleanData(ve(t,!1)),t.innerHTML=e);t=0}catch(e){}}t&&this.empty().append(e)},null,e,arguments.length)},replaceWith:function(){var n=[];return Pe(this,arguments,function(e){var t=this.parentNode;S.inArray(this,n)<0&&(S.cleanData(ve(this)),t&&t.replaceChild(e,this))},n)}}),S.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(e,a){S.fn[e]=function(e){for(var t,n=[],r=S(e),i=r.length-1,o=0;o<=i;o++)t=o===i?this:this.clone(!0),S(r[o])[a](t),u.apply(n,t.get());return this.pushStack(n)}});var Me=new RegExp("^("+ee+")(?!px)[a-z%]+$","i"),Ie=function(e){var t=e.ownerDocument.defaultView;return t&&t.opener||(t=C),t.getComputedStyle(e)},We=function(e,t,n){var r,i,o={};for(i in t)o[i]=e.style[i],e.style[i]=t[i];for(i in r=n.call(e),t)e.style[i]=o[i];return r},Fe=new RegExp(ne.join("|"),"i");function Be(e,t,n){var r,i,o,a,s=e.style;return(n=n||Ie(e))&&(""!==(a=n.getPropertyValue(t)||n[t])||ie(e)||(a=S.style(e,t)),!y.pixelBoxStyles()&&Me.test(a)&&Fe.test(t)&&(r=s.width,i=s.minWidth,o=s.maxWidth,s.minWidth=s.maxWidth=s.width=a,a=n.width,s.width=r,s.minWidth=i,s.maxWidth=o)),void 0!==a?a+"":a}function $e(e,t){return{get:function(){if(!e())return(this.get=t).apply(this,arguments);delete this.get}}}!function(){function e(){if(l){u.style.cssText="position:absolute;left:-11111px;width:60px;margin-top:1px;padding:0;border:0",l.style.cssText="position:relative;display:block;box-sizing:border-box;overflow:scroll;margin:auto;border:1px;padding:1px;width:60%;top:1%",re.appendChild(u).appendChild(l);var e=C.getComputedStyle(l);n="1%"!==e.top,s=12===t(e.marginLeft),l.style.right="60%",o=36===t(e.right),r=36===t(e.width),l.style.position="absolute",i=12===t(l.offsetWidth/3),re.removeChild(u),l=null}}function t(e){return Math.round(parseFloat(e))}var n,r,i,o,a,s,u=E.createElement("div"),l=E.createElement("div");l.style&&(l.style.backgroundClip="content-box",l.cloneNode(!0).style.backgroundClip="",y.clearCloneStyle="content-box"===l.style.backgroundClip,S.extend(y,{boxSizingReliable:function(){return e(),r},pixelBoxStyles:function(){return e(),o},pixelPosition:function(){return e(),n},reliableMarginLeft:function(){return e(),s},scrollboxSize:function(){return e(),i},reliableTrDimensions:function(){var e,t,n,r;return null==a&&(e=E.createElement("table"),t=E.createElement("tr"),n=E.createElement("div"),e.style.cssText="position:absolute;left:-11111px",t.style.height="1px",n.style.height="9px",re.appendChild(e).appendChild(t).appendChild(n),r=C.getComputedStyle(t),a=3<parseInt(r.height),re.removeChild(e)),a}}))}();var _e=["Webkit","Moz","ms"],ze=E.createElement("div").style,Ue={};function Xe(e){var t=S.cssProps[e]||Ue[e];return t||(e in ze?e:Ue[e]=function(e){var t=e[0].toUpperCase()+e.slice(1),n=_e.length;while(n--)if((e=_e[n]+t)in ze)return e}(e)||e)}var Ve=/^(none|table(?!-c[ea]).+)/,Ge=/^--/,Ye={position:"absolute",visibility:"hidden",display:"block"},Qe={letterSpacing:"0",fontWeight:"400"};function Je(e,t,n){var r=te.exec(t);return r?Math.max(0,r[2]-(n||0))+(r[3]||"px"):t}function Ke(e,t,n,r,i,o){var a="width"===t?1:0,s=0,u=0;if(n===(r?"border":"content"))return 0;for(;a<4;a+=2)"margin"===n&&(u+=S.css(e,n+ne[a],!0,i)),r?("content"===n&&(u-=S.css(e,"padding"+ne[a],!0,i)),"margin"!==n&&(u-=S.css(e,"border"+ne[a]+"Width",!0,i))):(u+=S.css(e,"padding"+ne[a],!0,i),"padding"!==n?u+=S.css(e,"border"+ne[a]+"Width",!0,i):s+=S.css(e,"border"+ne[a]+"Width",!0,i));return!r&&0<=o&&(u+=Math.max(0,Math.ceil(e["offset"+t[0].toUpperCase()+t.slice(1)]-o-u-s-.5))||0),u}function Ze(e,t,n){var r=Ie(e),i=(!y.boxSizingReliable()||n)&&"border-box"===S.css(e,"boxSizing",!1,r),o=i,a=Be(e,t,r),s="offset"+t[0].toUpperCase()+t.slice(1);if(Me.test(a)){if(!n)return a;a="auto"}return(!y.boxSizingReliable()&&i||!y.reliableTrDimensions()&&A(e,"tr")||"auto"===a||!parseFloat(a)&&"inline"===S.css(e,"display",!1,r))&&e.getClientRects().length&&(i="border-box"===S.css(e,"boxSizing",!1,r),(o=s in e)&&(a=e[s])),(a=parseFloat(a)||0)+Ke(e,t,n||(i?"border":"content"),o,r,a)+"px"}function et(e,t,n,r,i){return new et.prototype.init(e,t,n,r,i)}S.extend({cssHooks:{opacity:{get:function(e,t){if(t){var n=Be(e,"opacity");return""===n?"1":n}}}},cssNumber:{animationIterationCount:!0,columnCount:!0,fillOpacity:!0,flexGrow:!0,flexShrink:!0,fontWeight:!0,gridArea:!0,gridColumn:!0,gridColumnEnd:!0,gridColumnStart:!0,gridRow:!0,gridRowEnd:!0,gridRowStart:!0,lineHeight:!0,opacity:!0,order:!0,orphans:!0,widows:!0,zIndex:!0,zoom:!0},cssProps:{},style:function(e,t,n,r){if(e&&3!==e.nodeType&&8!==e.nodeType&&e.style){var i,o,a,s=X(t),u=Ge.test(t),l=e.style;if(u||(t=Xe(s)),a=S.cssHooks[t]||S.cssHooks[s],void 0===n)return a&&"get"in a&&void 0!==(i=a.get(e,!1,r))?i:l[t];"string"===(o=typeof n)&&(i=te.exec(n))&&i[1]&&(n=se(e,t,i),o="number"),null!=n&&n==n&&("number"!==o||u||(n+=i&&i[3]||(S.cssNumber[s]?"":"px")),y.clearCloneStyle||""!==n||0!==t.indexOf("background")||(l[t]="inherit"),a&&"set"in a&&void 0===(n=a.set(e,n,r))||(u?l.setProperty(t,n):l[t]=n))}},css:function(e,t,n,r){var i,o,a,s=X(t);return Ge.test(t)||(t=Xe(s)),(a=S.cssHooks[t]||S.cssHooks[s])&&"get"in a&&(i=a.get(e,!0,n)),void 0===i&&(i=Be(e,t,r)),"normal"===i&&t in Qe&&(i=Qe[t]),""===n||n?(o=parseFloat(i),!0===n||isFinite(o)?o||0:i):i}}),S.each(["height","width"],function(e,u){S.cssHooks[u]={get:function(e,t,n){if(t)return!Ve.test(S.css(e,"display"))||e.getClientRects().length&&e.getBoundingClientRect().width?Ze(e,u,n):We(e,Ye,function(){return Ze(e,u,n)})},set:function(e,t,n){var r,i=Ie(e),o=!y.scrollboxSize()&&"absolute"===i.position,a=(o||n)&&"border-box"===S.css(e,"boxSizing",!1,i),s=n?Ke(e,u,n,a,i):0;return a&&o&&(s-=Math.ceil(e["offset"+u[0].toUpperCase()+u.slice(1)]-parseFloat(i[u])-Ke(e,u,"border",!1,i)-.5)),s&&(r=te.exec(t))&&"px"!==(r[3]||"px")&&(e.style[u]=t,t=S.css(e,u)),Je(0,t,s)}}}),S.cssHooks.marginLeft=$e(y.reliableMarginLeft,function(e,t){if(t)return(parseFloat(Be(e,"marginLeft"))||e.getBoundingClientRect().left-We(e,{marginLeft:0},function(){return e.getBoundingClientRect().left}))+"px"}),S.each({margin:"",padding:"",border:"Width"},function(i,o){S.cssHooks[i+o]={expand:function(e){for(var t=0,n={},r="string"==typeof e?e.split(" "):[e];t<4;t++)n[i+ne[t]+o]=r[t]||r[t-2]||r[0];return n}},"margin"!==i&&(S.cssHooks[i+o].set=Je)}),S.fn.extend({css:function(e,t){return $(this,function(e,t,n){var r,i,o={},a=0;if(Array.isArray(t)){for(r=Ie(e),i=t.length;a<i;a++)o[t[a]]=S.css(e,t[a],!1,r);return o}return void 0!==n?S.style(e,t,n):S.css(e,t)},e,t,1<arguments.length)}}),((S.Tween=et).prototype={constructor:et,init:function(e,t,n,r,i,o){this.elem=e,this.prop=n,this.easing=i||S.easing._default,this.options=t,this.start=this.now=this.cur(),this.end=r,this.unit=o||(S.cssNumber[n]?"":"px")},cur:function(){var e=et.propHooks[this.prop];return e&&e.get?e.get(this):et.propHooks._default.get(this)},run:function(e){var t,n=et.propHooks[this.prop];return this.options.duration?this.pos=t=S.easing[this.easing](e,this.options.duration*e,0,1,this.options.duration):this.pos=t=e,this.now=(this.end-this.start)*t+this.start,this.options.step&&this.options.step.call(this.elem,this.now,this),n&&n.set?n.set(this):et.propHooks._default.set(this),this}}).init.prototype=et.prototype,(et.propHooks={_default:{get:function(e){var t;return 1!==e.elem.nodeType||null!=e.elem[e.prop]&&null==e.elem.style[e.prop]?e.elem[e.prop]:(t=S.css(e.elem,e.prop,""))&&"auto"!==t?t:0},set:function(e){S.fx.step[e.prop]?S.fx.step[e.prop](e):1!==e.elem.nodeType||!S.cssHooks[e.prop]&&null==e.elem.style[Xe(e.prop)]?e.elem[e.prop]=e.now:S.style(e.elem,e.prop,e.now+e.unit)}}}).scrollTop=et.propHooks.scrollLeft={set:function(e){e.elem.nodeType&&e.elem.parentNode&&(e.elem[e.prop]=e.now)}},S.easing={linear:function(e){return e},swing:function(e){return.5-Math.cos(e*Math.PI)/2},_default:"swing"},S.fx=et.prototype.init,S.fx.step={};var tt,nt,rt,it,ot=/^(?:toggle|show|hide)$/,at=/queueHooks$/;function st(){nt&&(!1===E.hidden&&C.requestAnimationFrame?C.requestAnimationFrame(st):C.setTimeout(st,S.fx.interval),S.fx.tick())}function ut(){return C.setTimeout(function(){tt=void 0}),tt=Date.now()}function lt(e,t){var n,r=0,i={height:e};for(t=t?1:0;r<4;r+=2-t)i["margin"+(n=ne[r])]=i["padding"+n]=e;return t&&(i.opacity=i.width=e),i}function ct(e,t,n){for(var r,i=(ft.tweeners[t]||[]).concat(ft.tweeners["*"]),o=0,a=i.length;o<a;o++)if(r=i[o].call(n,t,e))return r}function ft(o,e,t){var n,a,r=0,i=ft.prefilters.length,s=S.Deferred().always(function(){delete u.elem}),u=function(){if(a)return!1;for(var e=tt||ut(),t=Math.max(0,l.startTime+l.duration-e),n=1-(t/l.duration||0),r=0,i=l.tweens.length;r<i;r++)l.tweens[r].run(n);return s.notifyWith(o,[l,n,t]),n<1&&i?t:(i||s.notifyWith(o,[l,1,0]),s.resolveWith(o,[l]),!1)},l=s.promise({elem:o,props:S.extend({},e),opts:S.extend(!0,{specialEasing:{},easing:S.easing._default},t),originalProperties:e,originalOptions:t,startTime:tt||ut(),duration:t.duration,tweens:[],createTween:function(e,t){var n=S.Tween(o,l.opts,e,t,l.opts.specialEasing[e]||l.opts.easing);return l.tweens.push(n),n},stop:function(e){var t=0,n=e?l.tweens.length:0;if(a)return this;for(a=!0;t<n;t++)l.tweens[t].run(1);return e?(s.notifyWith(o,[l,1,0]),s.resolveWith(o,[l,e])):s.rejectWith(o,[l,e]),this}}),c=l.props;for(!function(e,t){var n,r,i,o,a;for(n in e)if(i=t[r=X(n)],o=e[n],Array.isArray(o)&&(i=o[1],o=e[n]=o[0]),n!==r&&(e[r]=o,delete e[n]),(a=S.cssHooks[r])&&"expand"in a)for(n in o=a.expand(o),delete e[r],o)n in e||(e[n]=o[n],t[n]=i);else t[r]=i}(c,l.opts.specialEasing);r<i;r++)if(n=ft.prefilters[r].call(l,o,c,l.opts))return m(n.stop)&&(S._queueHooks(l.elem,l.opts.queue).stop=n.stop.bind(n)),n;return S.map(c,ct,l),m(l.opts.start)&&l.opts.start.call(o,l),l.progress(l.opts.progress).done(l.opts.done,l.opts.complete).fail(l.opts.fail).always(l.opts.always),S.fx.timer(S.extend(u,{elem:o,anim:l,queue:l.opts.queue})),l}S.Animation=S.extend(ft,{tweeners:{"*":[function(e,t){var n=this.createTween(e,t);return se(n.elem,e,te.exec(t),n),n}]},tweener:function(e,t){m(e)?(t=e,e=["*"]):e=e.match(P);for(var n,r=0,i=e.length;r<i;r++)n=e[r],ft.tweeners[n]=ft.tweeners[n]||[],ft.tweeners[n].unshift(t)},prefilters:[function(e,t,n){var r,i,o,a,s,u,l,c,f="width"in t||"height"in t,p=this,d={},h=e.style,g=e.nodeType&&ae(e),v=Y.get(e,"fxshow");for(r in n.queue||(null==(a=S._queueHooks(e,"fx")).unqueued&&(a.unqueued=0,s=a.empty.fire,a.empty.fire=function(){a.unqueued||s()}),a.unqueued++,p.always(function(){p.always(function(){a.unqueued--,S.queue(e,"fx").length||a.empty.fire()})})),t)if(i=t[r],ot.test(i)){if(delete t[r],o=o||"toggle"===i,i===(g?"hide":"show")){if("show"!==i||!v||void 0===v[r])continue;g=!0}d[r]=v&&v[r]||S.style(e,r)}if((u=!S.isEmptyObject(t))||!S.isEmptyObject(d))for(r in f&&1===e.nodeType&&(n.overflow=[h.overflow,h.overflowX,h.overflowY],null==(l=v&&v.display)&&(l=Y.get(e,"display")),"none"===(c=S.css(e,"display"))&&(l?c=l:(le([e],!0),l=e.style.display||l,c=S.css(e,"display"),le([e]))),("inline"===c||"inline-block"===c&&null!=l)&&"none"===S.css(e,"float")&&(u||(p.done(function(){h.display=l}),null==l&&(c=h.display,l="none"===c?"":c)),h.display="inline-block")),n.overflow&&(h.overflow="hidden",p.always(function(){h.overflow=n.overflow[0],h.overflowX=n.overflow[1],h.overflowY=n.overflow[2]})),u=!1,d)u||(v?"hidden"in v&&(g=v.hidden):v=Y.access(e,"fxshow",{display:l}),o&&(v.hidden=!g),g&&le([e],!0),p.done(function(){for(r in g||le([e]),Y.remove(e,"fxshow"),d)S.style(e,r,d[r])})),u=ct(g?v[r]:0,r,p),r in v||(v[r]=u.start,g&&(u.end=u.start,u.start=0))}],prefilter:function(e,t){t?ft.prefilters.unshift(e):ft.prefilters.push(e)}}),S.speed=function(e,t,n){var r=e&&"object"==typeof e?S.extend({},e):{complete:n||!n&&t||m(e)&&e,duration:e,easing:n&&t||t&&!m(t)&&t};return S.fx.off?r.duration=0:"number"!=typeof r.duration&&(r.duration in S.fx.speeds?r.duration=S.fx.speeds[r.duration]:r.duration=S.fx.speeds._default),null!=r.queue&&!0!==r.queue||(r.queue="fx"),r.old=r.complete,r.complete=function(){m(r.old)&&r.old.call(this),r.queue&&S.dequeue(this,r.queue)},r},S.fn.extend({fadeTo:function(e,t,n,r){return this.filter(ae).css("opacity",0).show().end().animate({opacity:t},e,n,r)},animate:function(t,e,n,r){var i=S.isEmptyObject(t),o=S.speed(e,n,r),a=function(){var e=ft(this,S.extend({},t),o);(i||Y.get(this,"finish"))&&e.stop(!0)};return a.finish=a,i||!1===o.queue?this.each(a):this.queue(o.queue,a)},stop:function(i,e,o){var a=function(e){var t=e.stop;delete e.stop,t(o)};return"string"!=typeof i&&(o=e,e=i,i=void 0),e&&this.queue(i||"fx",[]),this.each(function(){var e=!0,t=null!=i&&i+"queueHooks",n=S.timers,r=Y.get(this);if(t)r[t]&&r[t].stop&&a(r[t]);else for(t in r)r[t]&&r[t].stop&&at.test(t)&&a(r[t]);for(t=n.length;t--;)n[t].elem!==this||null!=i&&n[t].queue!==i||(n[t].anim.stop(o),e=!1,n.splice(t,1));!e&&o||S.dequeue(this,i)})},finish:function(a){return!1!==a&&(a=a||"fx"),this.each(function(){var e,t=Y.get(this),n=t[a+"queue"],r=t[a+"queueHooks"],i=S.timers,o=n?n.length:0;for(t.finish=!0,S.queue(this,a,[]),r&&r.stop&&r.stop.call(this,!0),e=i.length;e--;)i[e].elem===this&&i[e].queue===a&&(i[e].anim.stop(!0),i.splice(e,1));for(e=0;e<o;e++)n[e]&&n[e].finish&&n[e].finish.call(this);delete t.finish})}}),S.each(["toggle","show","hide"],function(e,r){var i=S.fn[r];S.fn[r]=function(e,t,n){return null==e||"boolean"==typeof e?i.apply(this,arguments):this.animate(lt(r,!0),e,t,n)}}),S.each({slideDown:lt("show"),slideUp:lt("hide"),slideToggle:lt("toggle"),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"},fadeToggle:{opacity:"toggle"}},function(e,r){S.fn[e]=function(e,t,n){return this.animate(r,e,t,n)}}),S.timers=[],S.fx.tick=function(){var e,t=0,n=S.timers;for(tt=Date.now();t<n.length;t++)(e=n[t])()||n[t]!==e||n.splice(t--,1);n.length||S.fx.stop(),tt=void 0},S.fx.timer=function(e){S.timers.push(e),S.fx.start()},S.fx.interval=13,S.fx.start=function(){nt||(nt=!0,st())},S.fx.stop=function(){nt=null},S.fx.speeds={slow:600,fast:200,_default:400},S.fn.delay=function(r,e){return r=S.fx&&S.fx.speeds[r]||r,e=e||"fx",this.queue(e,function(e,t){var n=C.setTimeout(e,r);t.stop=function(){C.clearTimeout(n)}})},rt=E.createElement("input"),it=E.createElement("select").appendChild(E.createElement("option")),rt.type="checkbox",y.checkOn=""!==rt.value,y.optSelected=it.selected,(rt=E.createElement("input")).value="t",rt.type="radio",y.radioValue="t"===rt.value;var pt,dt=S.expr.attrHandle;S.fn.extend({attr:function(e,t){return $(this,S.attr,e,t,1<arguments.length)},removeAttr:function(e){return this.each(function(){S.removeAttr(this,e)})}}),S.extend({attr:function(e,t,n){var r,i,o=e.nodeType;if(3!==o&&8!==o&&2!==o)return"undefined"==typeof e.getAttribute?S.prop(e,t,n):(1===o&&S.isXMLDoc(e)||(i=S.attrHooks[t.toLowerCase()]||(S.expr.match.bool.test(t)?pt:void 0)),void 0!==n?null===n?void S.removeAttr(e,t):i&&"set"in i&&void 0!==(r=i.set(e,n,t))?r:(e.setAttribute(t,n+""),n):i&&"get"in i&&null!==(r=i.get(e,t))?r:null==(r=S.find.attr(e,t))?void 0:r)},attrHooks:{type:{set:function(e,t){if(!y.radioValue&&"radio"===t&&A(e,"input")){var n=e.value;return e.setAttribute("type",t),n&&(e.value=n),t}}}},removeAttr:function(e,t){var n,r=0,i=t&&t.match(P);if(i&&1===e.nodeType)while(n=i[r++])e.removeAttribute(n)}}),pt={set:function(e,t,n){return!1===t?S.removeAttr(e,n):e.setAttribute(n,n),n}},S.each(S.expr.match.bool.source.match(/\w+/g),function(e,t){var a=dt[t]||S.find.attr;dt[t]=function(e,t,n){var r,i,o=t.toLowerCase();return n||(i=dt[o],dt[o]=r,r=null!=a(e,t,n)?o:null,dt[o]=i),r}});var ht=/^(?:input|select|textarea|button)$/i,gt=/^(?:a|area)$/i;function vt(e){return(e.match(P)||[]).join(" ")}function yt(e){return e.getAttribute&&e.getAttribute("class")||""}function mt(e){return Array.isArray(e)?e:"string"==typeof e&&e.match(P)||[]}S.fn.extend({prop:function(e,t){return $(this,S.prop,e,t,1<arguments.length)},removeProp:function(e){return this.each(function(){delete this[S.propFix[e]||e]})}}),S.extend({prop:function(e,t,n){var r,i,o=e.nodeType;if(3!==o&&8!==o&&2!==o)return 1===o&&S.isXMLDoc(e)||(t=S.propFix[t]||t,i=S.propHooks[t]),void 0!==n?i&&"set"in i&&void 0!==(r=i.set(e,n,t))?r:e[t]=n:i&&"get"in i&&null!==(r=i.get(e,t))?r:e[t]},propHooks:{tabIndex:{get:function(e){var t=S.find.attr(e,"tabindex");return t?parseInt(t,10):ht.test(e.nodeName)||gt.test(e.nodeName)&&e.href?0:-1}}},propFix:{"for":"htmlFor","class":"className"}}),y.optSelected||(S.propHooks.selected={get:function(e){var t=e.parentNode;return t&&t.parentNode&&t.parentNode.selectedIndex,null},set:function(e){var t=e.parentNode;t&&(t.selectedIndex,t.parentNode&&t.parentNode.selectedIndex)}}),S.each(["tabIndex","readOnly","maxLength","cellSpacing","cellPadding","rowSpan","colSpan","useMap","frameBorder","contentEditable"],function(){S.propFix[this.toLowerCase()]=this}),S.fn.extend({addClass:function(t){var e,n,r,i,o,a,s,u=0;if(m(t))return this.each(function(e){S(this).addClass(t.call(this,e,yt(this)))});if((e=mt(t)).length)while(n=this[u++])if(i=yt(n),r=1===n.nodeType&&" "+vt(i)+" "){a=0;while(o=e[a++])r.indexOf(" "+o+" ")<0&&(r+=o+" ");i!==(s=vt(r))&&n.setAttribute("class",s)}return this},removeClass:function(t){var e,n,r,i,o,a,s,u=0;if(m(t))return this.each(function(e){S(this).removeClass(t.call(this,e,yt(this)))});if(!arguments.length)return this.attr("class","");if((e=mt(t)).length)while(n=this[u++])if(i=yt(n),r=1===n.nodeType&&" "+vt(i)+" "){a=0;while(o=e[a++])while(-1<r.indexOf(" "+o+" "))r=r.replace(" "+o+" "," ");i!==(s=vt(r))&&n.setAttribute("class",s)}return this},toggleClass:function(i,t){var o=typeof i,a="string"===o||Array.isArray(i);return"boolean"==typeof t&&a?t?this.addClass(i):this.removeClass(i):m(i)?this.each(function(e){S(this).toggleClass(i.call(this,e,yt(this),t),t)}):this.each(function(){var e,t,n,r;if(a){t=0,n=S(this),r=mt(i);while(e=r[t++])n.hasClass(e)?n.removeClass(e):n.addClass(e)}else void 0!==i&&"boolean"!==o||((e=yt(this))&&Y.set(this,"__className__",e),this.setAttribute&&this.setAttribute("class",e||!1===i?"":Y.get(this,"__className__")||""))})},hasClass:function(e){var t,n,r=0;t=" "+e+" ";while(n=this[r++])if(1===n.nodeType&&-1<(" "+vt(yt(n))+" ").indexOf(t))return!0;return!1}});var xt=/\r/g;S.fn.extend({val:function(n){var r,e,i,t=this[0];return arguments.length?(i=m(n),this.each(function(e){var t;1===this.nodeType&&(null==(t=i?n.call(this,e,S(this).val()):n)?t="":"number"==typeof t?t+="":Array.isArray(t)&&(t=S.map(t,function(e){return null==e?"":e+""})),(r=S.valHooks[this.type]||S.valHooks[this.nodeName.toLowerCase()])&&"set"in r&&void 0!==r.set(this,t,"value")||(this.value=t))})):t?(r=S.valHooks[t.type]||S.valHooks[t.nodeName.toLowerCase()])&&"get"in r&&void 0!==(e=r.get(t,"value"))?e:"string"==typeof(e=t.value)?e.replace(xt,""):null==e?"":e:void 0}}),S.extend({valHooks:{option:{get:function(e){var t=S.find.attr(e,"value");return null!=t?t:vt(S.text(e))}},select:{get:function(e){var t,n,r,i=e.options,o=e.selectedIndex,a="select-one"===e.type,s=a?null:[],u=a?o+1:i.length;for(r=o<0?u:a?o:0;r<u;r++)if(((n=i[r]).selected||r===o)&&!n.disabled&&(!n.parentNode.disabled||!A(n.parentNode,"optgroup"))){if(t=S(n).val(),a)return t;s.push(t)}return s},set:function(e,t){var n,r,i=e.options,o=S.makeArray(t),a=i.length;while(a--)((r=i[a]).selected=-1<S.inArray(S.valHooks.option.get(r),o))&&(n=!0);return n||(e.selectedIndex=-1),o}}}}),S.each(["radio","checkbox"],function(){S.valHooks[this]={set:function(e,t){if(Array.isArray(t))return e.checked=-1<S.inArray(S(e).val(),t)}},y.checkOn||(S.valHooks[this].get=function(e){return null===e.getAttribute("value")?"on":e.value})}),y.focusin="onfocusin"in C;var bt=/^(?:focusinfocus|focusoutblur)$/,wt=function(e){e.stopPropagation()};S.extend(S.event,{trigger:function(e,t,n,r){var i,o,a,s,u,l,c,f,p=[n||E],d=v.call(e,"type")?e.type:e,h=v.call(e,"namespace")?e.namespace.split("."):[];if(o=f=a=n=n||E,3!==n.nodeType&&8!==n.nodeType&&!bt.test(d+S.event.triggered)&&(-1<d.indexOf(".")&&(d=(h=d.split(".")).shift(),h.sort()),u=d.indexOf(":")<0&&"on"+d,(e=e[S.expando]?e:new S.Event(d,"object"==typeof e&&e)).isTrigger=r?2:3,e.namespace=h.join("."),e.rnamespace=e.namespace?new RegExp("(^|\\.)"+h.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,e.result=void 0,e.target||(e.target=n),t=null==t?[e]:S.makeArray(t,[e]),c=S.event.special[d]||{},r||!c.trigger||!1!==c.trigger.apply(n,t))){if(!r&&!c.noBubble&&!x(n)){for(s=c.delegateType||d,bt.test(s+d)||(o=o.parentNode);o;o=o.parentNode)p.push(o),a=o;a===(n.ownerDocument||E)&&p.push(a.defaultView||a.parentWindow||C)}i=0;while((o=p[i++])&&!e.isPropagationStopped())f=o,e.type=1<i?s:c.bindType||d,(l=(Y.get(o,"events")||Object.create(null))[e.type]&&Y.get(o,"handle"))&&l.apply(o,t),(l=u&&o[u])&&l.apply&&V(o)&&(e.result=l.apply(o,t),!1===e.result&&e.preventDefault());return e.type=d,r||e.isDefaultPrevented()||c._default&&!1!==c._default.apply(p.pop(),t)||!V(n)||u&&m(n[d])&&!x(n)&&((a=n[u])&&(n[u]=null),S.event.triggered=d,e.isPropagationStopped()&&f.addEventListener(d,wt),n[d](),e.isPropagationStopped()&&f.removeEventListener(d,wt),S.event.triggered=void 0,a&&(n[u]=a)),e.result}},simulate:function(e,t,n){var r=S.extend(new S.Event,n,{type:e,isSimulated:!0});S.event.trigger(r,null,t)}}),S.fn.extend({trigger:function(e,t){return this.each(function(){S.event.trigger(e,t,this)})},triggerHandler:function(e,t){var n=this[0];if(n)return S.event.trigger(e,t,n,!0)}}),y.focusin||S.each({focus:"focusin",blur:"focusout"},function(n,r){var i=function(e){S.event.simulate(r,e.target,S.event.fix(e))};S.event.special[r]={setup:function(){var e=this.ownerDocument||this.document||this,t=Y.access(e,r);t||e.addEventListener(n,i,!0),Y.access(e,r,(t||0)+1)},teardown:function(){var e=this.ownerDocument||this.document||this,t=Y.access(e,r)-1;t?Y.access(e,r,t):(e.removeEventListener(n,i,!0),Y.remove(e,r))}}});var Tt=C.location,Ct={guid:Date.now()},Et=/\?/;S.parseXML=function(e){var t;if(!e||"string"!=typeof e)return null;try{t=(new C.DOMParser).parseFromString(e,"text/xml")}catch(e){t=void 0}return t&&!t.getElementsByTagName("parsererror").length||S.error("Invalid XML: "+e),t};var St=/\[\]$/,kt=/\r?\n/g,At=/^(?:submit|button|image|reset|file)$/i,Nt=/^(?:input|select|textarea|keygen)/i;function Dt(n,e,r,i){var t;if(Array.isArray(e))S.each(e,function(e,t){r||St.test(n)?i(n,t):Dt(n+"["+("object"==typeof t&&null!=t?e:"")+"]",t,r,i)});else if(r||"object"!==w(e))i(n,e);else for(t in e)Dt(n+"["+t+"]",e[t],r,i)}S.param=function(e,t){var n,r=[],i=function(e,t){var n=m(t)?t():t;r[r.length]=encodeURIComponent(e)+"="+encodeURIComponent(null==n?"":n)};if(null==e)return"";if(Array.isArray(e)||e.jquery&&!S.isPlainObject(e))S.each(e,function(){i(this.name,this.value)});else for(n in e)Dt(n,e[n],t,i);return r.join("&")},S.fn.extend({serialize:function(){return S.param(this.serializeArray())},serializeArray:function(){return this.map(function(){var e=S.prop(this,"elements");return e?S.makeArray(e):this}).filter(function(){var e=this.type;return this.name&&!S(this).is(":disabled")&&Nt.test(this.nodeName)&&!At.test(e)&&(this.checked||!pe.test(e))}).map(function(e,t){var n=S(this).val();return null==n?null:Array.isArray(n)?S.map(n,function(e){return{name:t.name,value:e.replace(kt,"\r\n")}}):{name:t.name,value:n.replace(kt,"\r\n")}}).get()}});var jt=/%20/g,qt=/#.*$/,Lt=/([?&])_=[^&]*/,Ht=/^(.*?):[ \t]*([^\r\n]*)$/gm,Ot=/^(?:GET|HEAD)$/,Pt=/^\/\//,Rt={},Mt={},It="*/".concat("*"),Wt=E.createElement("a");function Ft(o){return function(e,t){"string"!=typeof e&&(t=e,e="*");var n,r=0,i=e.toLowerCase().match(P)||[];if(m(t))while(n=i[r++])"+"===n[0]?(n=n.slice(1)||"*",(o[n]=o[n]||[]).unshift(t)):(o[n]=o[n]||[]).push(t)}}function Bt(t,i,o,a){var s={},u=t===Mt;function l(e){var r;return s[e]=!0,S.each(t[e]||[],function(e,t){var n=t(i,o,a);return"string"!=typeof n||u||s[n]?u?!(r=n):void 0:(i.dataTypes.unshift(n),l(n),!1)}),r}return l(i.dataTypes[0])||!s["*"]&&l("*")}function $t(e,t){var n,r,i=S.ajaxSettings.flatOptions||{};for(n in t)void 0!==t[n]&&((i[n]?e:r||(r={}))[n]=t[n]);return r&&S.extend(!0,e,r),e}Wt.href=Tt.href,S.extend({active:0,lastModified:{},etag:{},ajaxSettings:{url:Tt.href,type:"GET",isLocal:/^(?:about|app|app-storage|.+-extension|file|res|widget):$/.test(Tt.protocol),global:!0,processData:!0,async:!0,contentType:"application/x-www-form-urlencoded; charset=UTF-8",accepts:{"*":It,text:"text/plain",html:"text/html",xml:"application/xml, text/xml",json:"application/json, text/javascript"},contents:{xml:/\bxml\b/,html:/\bhtml/,json:/\bjson\b/},responseFields:{xml:"responseXML",text:"responseText",json:"responseJSON"},converters:{"* text":String,"text html":!0,"text json":JSON.parse,"text xml":S.parseXML},flatOptions:{url:!0,context:!0}},ajaxSetup:function(e,t){return t?$t($t(e,S.ajaxSettings),t):$t(S.ajaxSettings,e)},ajaxPrefilter:Ft(Rt),ajaxTransport:Ft(Mt),ajax:function(e,t){"object"==typeof e&&(t=e,e=void 0),t=t||{};var c,f,p,n,d,r,h,g,i,o,v=S.ajaxSetup({},t),y=v.context||v,m=v.context&&(y.nodeType||y.jquery)?S(y):S.event,x=S.Deferred(),b=S.Callbacks("once memory"),w=v.statusCode||{},a={},s={},u="canceled",T={readyState:0,getResponseHeader:function(e){var t;if(h){if(!n){n={};while(t=Ht.exec(p))n[t[1].toLowerCase()+" "]=(n[t[1].toLowerCase()+" "]||[]).concat(t[2])}t=n[e.toLowerCase()+" "]}return null==t?null:t.join(", ")},getAllResponseHeaders:function(){return h?p:null},setRequestHeader:function(e,t){return null==h&&(e=s[e.toLowerCase()]=s[e.toLowerCase()]||e,a[e]=t),this},overrideMimeType:function(e){return null==h&&(v.mimeType=e),this},statusCode:function(e){var t;if(e)if(h)T.always(e[T.status]);else for(t in e)w[t]=[w[t],e[t]];return this},abort:function(e){var t=e||u;return c&&c.abort(t),l(0,t),this}};if(x.promise(T),v.url=((e||v.url||Tt.href)+"").replace(Pt,Tt.protocol+"//"),v.type=t.method||t.type||v.method||v.type,v.dataTypes=(v.dataType||"*").toLowerCase().match(P)||[""],null==v.crossDomain){r=E.createElement("a");try{r.href=v.url,r.href=r.href,v.crossDomain=Wt.protocol+"//"+Wt.host!=r.protocol+"//"+r.host}catch(e){v.crossDomain=!0}}if(v.data&&v.processData&&"string"!=typeof v.data&&(v.data=S.param(v.data,v.traditional)),Bt(Rt,v,t,T),h)return T;for(i in(g=S.event&&v.global)&&0==S.active++&&S.event.trigger("ajaxStart"),v.type=v.type.toUpperCase(),v.hasContent=!Ot.test(v.type),f=v.url.replace(qt,""),v.hasContent?v.data&&v.processData&&0===(v.contentType||"").indexOf("application/x-www-form-urlencoded")&&(v.data=v.data.replace(jt,"+")):(o=v.url.slice(f.length),v.data&&(v.processData||"string"==typeof v.data)&&(f+=(Et.test(f)?"&":"?")+v.data,delete v.data),!1===v.cache&&(f=f.replace(Lt,"$1"),o=(Et.test(f)?"&":"?")+"_="+Ct.guid+++o),v.url=f+o),v.ifModified&&(S.lastModified[f]&&T.setRequestHeader("If-Modified-Since",S.lastModified[f]),S.etag[f]&&T.setRequestHeader("If-None-Match",S.etag[f])),(v.data&&v.hasContent&&!1!==v.contentType||t.contentType)&&T.setRequestHeader("Content-Type",v.contentType),T.setRequestHeader("Accept",v.dataTypes[0]&&v.accepts[v.dataTypes[0]]?v.accepts[v.dataTypes[0]]+("*"!==v.dataTypes[0]?", "+It+"; q=0.01":""):v.accepts["*"]),v.headers)T.setRequestHeader(i,v.headers[i]);if(v.beforeSend&&(!1===v.beforeSend.call(y,T,v)||h))return T.abort();if(u="abort",b.add(v.complete),T.done(v.success),T.fail(v.error),c=Bt(Mt,v,t,T)){if(T.readyState=1,g&&m.trigger("ajaxSend",[T,v]),h)return T;v.async&&0<v.timeout&&(d=C.setTimeout(function(){T.abort("timeout")},v.timeout));try{h=!1,c.send(a,l)}catch(e){if(h)throw e;l(-1,e)}}else l(-1,"No Transport");function l(e,t,n,r){var i,o,a,s,u,l=t;h||(h=!0,d&&C.clearTimeout(d),c=void 0,p=r||"",T.readyState=0<e?4:0,i=200<=e&&e<300||304===e,n&&(s=function(e,t,n){var r,i,o,a,s=e.contents,u=e.dataTypes;while("*"===u[0])u.shift(),void 0===r&&(r=e.mimeType||t.getResponseHeader("Content-Type"));if(r)for(i in s)if(s[i]&&s[i].test(r)){u.unshift(i);break}if(u[0]in n)o=u[0];else{for(i in n){if(!u[0]||e.converters[i+" "+u[0]]){o=i;break}a||(a=i)}o=o||a}if(o)return o!==u[0]&&u.unshift(o),n[o]}(v,T,n)),!i&&-1<S.inArray("script",v.dataTypes)&&(v.converters["text script"]=function(){}),s=function(e,t,n,r){var i,o,a,s,u,l={},c=e.dataTypes.slice();if(c[1])for(a in e.converters)l[a.toLowerCase()]=e.converters[a];o=c.shift();while(o)if(e.responseFields[o]&&(n[e.responseFields[o]]=t),!u&&r&&e.dataFilter&&(t=e.dataFilter(t,e.dataType)),u=o,o=c.shift())if("*"===o)o=u;else if("*"!==u&&u!==o){if(!(a=l[u+" "+o]||l["* "+o]))for(i in l)if((s=i.split(" "))[1]===o&&(a=l[u+" "+s[0]]||l["* "+s[0]])){!0===a?a=l[i]:!0!==l[i]&&(o=s[0],c.unshift(s[1]));break}if(!0!==a)if(a&&e["throws"])t=a(t);else try{t=a(t)}catch(e){return{state:"parsererror",error:a?e:"No conversion from "+u+" to "+o}}}return{state:"success",data:t}}(v,s,T,i),i?(v.ifModified&&((u=T.getResponseHeader("Last-Modified"))&&(S.lastModified[f]=u),(u=T.getResponseHeader("etag"))&&(S.etag[f]=u)),204===e||"HEAD"===v.type?l="nocontent":304===e?l="notmodified":(l=s.state,o=s.data,i=!(a=s.error))):(a=l,!e&&l||(l="error",e<0&&(e=0))),T.status=e,T.statusText=(t||l)+"",i?x.resolveWith(y,[o,l,T]):x.rejectWith(y,[T,l,a]),T.statusCode(w),w=void 0,g&&m.trigger(i?"ajaxSuccess":"ajaxError",[T,v,i?o:a]),b.fireWith(y,[T,l]),g&&(m.trigger("ajaxComplete",[T,v]),--S.active||S.event.trigger("ajaxStop")))}return T},getJSON:function(e,t,n){return S.get(e,t,n,"json")},getScript:function(e,t){return S.get(e,void 0,t,"script")}}),S.each(["get","post"],function(e,i){S[i]=function(e,t,n,r){return m(t)&&(r=r||n,n=t,t=void 0),S.ajax(S.extend({url:e,type:i,dataType:r,data:t,success:n},S.isPlainObject(e)&&e))}}),S.ajaxPrefilter(function(e){var t;for(t in e.headers)"content-type"===t.toLowerCase()&&(e.contentType=e.headers[t]||"")}),S._evalUrl=function(e,t,n){return S.ajax({url:e,type:"GET",dataType:"script",cache:!0,async:!1,global:!1,converters:{"text script":function(){}},dataFilter:function(e){S.globalEval(e,t,n)}})},S.fn.extend({wrapAll:function(e){var t;return this[0]&&(m(e)&&(e=e.call(this[0])),t=S(e,this[0].ownerDocument).eq(0).clone(!0),this[0].parentNode&&t.insertBefore(this[0]),t.map(function(){var e=this;while(e.firstElementChild)e=e.firstElementChild;return e}).append(this)),this},wrapInner:function(n){return m(n)?this.each(function(e){S(this).wrapInner(n.call(this,e))}):this.each(function(){var e=S(this),t=e.contents();t.length?t.wrapAll(n):e.append(n)})},wrap:function(t){var n=m(t);return this.each(function(e){S(this).wrapAll(n?t.call(this,e):t)})},unwrap:function(e){return this.parent(e).not("body").each(function(){S(this).replaceWith(this.childNodes)}),this}}),S.expr.pseudos.hidden=function(e){return!S.expr.pseudos.visible(e)},S.expr.pseudos.visible=function(e){return!!(e.offsetWidth||e.offsetHeight||e.getClientRects().length)},S.ajaxSettings.xhr=function(){try{return new C.XMLHttpRequest}catch(e){}};var _t={0:200,1223:204},zt=S.ajaxSettings.xhr();y.cors=!!zt&&"withCredentials"in zt,y.ajax=zt=!!zt,S.ajaxTransport(function(i){var o,a;if(y.cors||zt&&!i.crossDomain)return{send:function(e,t){var n,r=i.xhr();if(r.open(i.type,i.url,i.async,i.username,i.password),i.xhrFields)for(n in i.xhrFields)r[n]=i.xhrFields[n];for(n in i.mimeType&&r.overrideMimeType&&r.overrideMimeType(i.mimeType),i.crossDomain||e["X-Requested-With"]||(e["X-Requested-With"]="XMLHttpRequest"),e)r.setRequestHeader(n,e[n]);o=function(e){return function(){o&&(o=a=r.onload=r.onerror=r.onabort=r.ontimeout=r.onreadystatechange=null,"abort"===e?r.abort():"error"===e?"number"!=typeof r.status?t(0,"error"):t(r.status,r.statusText):t(_t[r.status]||r.status,r.statusText,"text"!==(r.responseType||"text")||"string"!=typeof r.responseText?{binary:r.response}:{text:r.responseText},r.getAllResponseHeaders()))}},r.onload=o(),a=r.onerror=r.ontimeout=o("error"),void 0!==r.onabort?r.onabort=a:r.onreadystatechange=function(){4===r.readyState&&C.setTimeout(function(){o&&a()})},o=o("abort");try{r.send(i.hasContent&&i.data||null)}catch(e){if(o)throw e}},abort:function(){o&&o()}}}),S.ajaxPrefilter(function(e){e.crossDomain&&(e.contents.script=!1)}),S.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/\b(?:java|ecma)script\b/},converters:{"text script":function(e){return S.globalEval(e),e}}}),S.ajaxPrefilter("script",function(e){void 0===e.cache&&(e.cache=!1),e.crossDomain&&(e.type="GET")}),S.ajaxTransport("script",function(n){var r,i;if(n.crossDomain||n.scriptAttrs)return{send:function(e,t){r=S("<script>").attr(n.scriptAttrs||{}).prop({charset:n.scriptCharset,src:n.url}).on("load error",i=function(e){r.remove(),i=null,e&&t("error"===e.type?404:200,e.type)}),E.head.appendChild(r[0])},abort:function(){i&&i()}}});var Ut,Xt=[],Vt=/(=)\?(?=&|$)|\?\?/;S.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Xt.pop()||S.expando+"_"+Ct.guid++;return this[e]=!0,e}}),S.ajaxPrefilter("json jsonp",function(e,t,n){var r,i,o,a=!1!==e.jsonp&&(Vt.test(e.url)?"url":"string"==typeof e.data&&0===(e.contentType||"").indexOf("application/x-www-form-urlencoded")&&Vt.test(e.data)&&"data");if(a||"jsonp"===e.dataTypes[0])return r=e.jsonpCallback=m(e.jsonpCallback)?e.jsonpCallback():e.jsonpCallback,a?e[a]=e[a].replace(Vt,"$1"+r):!1!==e.jsonp&&(e.url+=(Et.test(e.url)?"&":"?")+e.jsonp+"="+r),e.converters["script json"]=function(){return o||S.error(r+" was not called"),o[0]},e.dataTypes[0]="json",i=C[r],C[r]=function(){o=arguments},n.always(function(){void 0===i?S(C).removeProp(r):C[r]=i,e[r]&&(e.jsonpCallback=t.jsonpCallback,Xt.push(r)),o&&m(i)&&i(o[0]),o=i=void 0}),"script"}),y.createHTMLDocument=((Ut=E.implementation.createHTMLDocument("").body).innerHTML="<form></form><form></form>",2===Ut.childNodes.length),S.parseHTML=function(e,t,n){return"string"!=typeof e?[]:("boolean"==typeof t&&(n=t,t=!1),t||(y.createHTMLDocument?((r=(t=E.implementation.createHTMLDocument("")).createElement("base")).href=E.location.href,t.head.appendChild(r)):t=E),o=!n&&[],(i=N.exec(e))?[t.createElement(i[1])]:(i=xe([e],t,o),o&&o.length&&S(o).remove(),S.merge([],i.childNodes)));var r,i,o},S.fn.load=function(e,t,n){var r,i,o,a=this,s=e.indexOf(" ");return-1<s&&(r=vt(e.slice(s)),e=e.slice(0,s)),m(t)?(n=t,t=void 0):t&&"object"==typeof t&&(i="POST"),0<a.length&&S.ajax({url:e,type:i||"GET",dataType:"html",data:t}).done(function(e){o=arguments,a.html(r?S("<div>").append(S.parseHTML(e)).find(r):e)}).always(n&&function(e,t){a.each(function(){n.apply(this,o||[e.responseText,t,e])})}),this},S.expr.pseudos.animated=function(t){return S.grep(S.timers,function(e){return t===e.elem}).length},S.offset={setOffset:function(e,t,n){var r,i,o,a,s,u,l=S.css(e,"position"),c=S(e),f={};"static"===l&&(e.style.position="relative"),s=c.offset(),o=S.css(e,"top"),u=S.css(e,"left"),("absolute"===l||"fixed"===l)&&-1<(o+u).indexOf("auto")?(a=(r=c.position()).top,i=r.left):(a=parseFloat(o)||0,i=parseFloat(u)||0),m(t)&&(t=t.call(e,n,S.extend({},s))),null!=t.top&&(f.top=t.top-s.top+a),null!=t.left&&(f.left=t.left-s.left+i),"using"in t?t.using.call(e,f):("number"==typeof f.top&&(f.top+="px"),"number"==typeof f.left&&(f.left+="px"),c.css(f))}},S.fn.extend({offset:function(t){if(arguments.length)return void 0===t?this:this.each(function(e){S.offset.setOffset(this,t,e)});var e,n,r=this[0];return r?r.getClientRects().length?(e=r.getBoundingClientRect(),n=r.ownerDocument.defaultView,{top:e.top+n.pageYOffset,left:e.left+n.pageXOffset}):{top:0,left:0}:void 0},position:function(){if(this[0]){var e,t,n,r=this[0],i={top:0,left:0};if("fixed"===S.css(r,"position"))t=r.getBoundingClientRect();else{t=this.offset(),n=r.ownerDocument,e=r.offsetParent||n.documentElement;while(e&&(e===n.body||e===n.documentElement)&&"static"===S.css(e,"position"))e=e.parentNode;e&&e!==r&&1===e.nodeType&&((i=S(e).offset()).top+=S.css(e,"borderTopWidth",!0),i.left+=S.css(e,"borderLeftWidth",!0))}return{top:t.top-i.top-S.css(r,"marginTop",!0),left:t.left-i.left-S.css(r,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var e=this.offsetParent;while(e&&"static"===S.css(e,"position"))e=e.offsetParent;return e||re})}}),S.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(t,i){var o="pageYOffset"===i;S.fn[t]=function(e){return $(this,function(e,t,n){var r;if(x(e)?r=e:9===e.nodeType&&(r=e.defaultView),void 0===n)return r?r[i]:e[t];r?r.scrollTo(o?r.pageXOffset:n,o?n:r.pageYOffset):e[t]=n},t,e,arguments.length)}}),S.each(["top","left"],function(e,n){S.cssHooks[n]=$e(y.pixelPosition,function(e,t){if(t)return t=Be(e,n),Me.test(t)?S(e).position()[n]+"px":t})}),S.each({Height:"height",Width:"width"},function(a,s){S.each({padding:"inner"+a,content:s,"":"outer"+a},function(r,o){S.fn[o]=function(e,t){var n=arguments.length&&(r||"boolean"!=typeof e),i=r||(!0===e||!0===t?"margin":"border");return $(this,function(e,t,n){var r;return x(e)?0===o.indexOf("outer")?e["inner"+a]:e.document.documentElement["client"+a]:9===e.nodeType?(r=e.documentElement,Math.max(e.body["scroll"+a],r["scroll"+a],e.body["offset"+a],r["offset"+a],r["client"+a])):void 0===n?S.css(e,t,i):S.style(e,t,n,i)},s,n?e:void 0,n)}})}),S.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(e,t){S.fn[t]=function(e){return this.on(t,e)}}),S.fn.extend({bind:function(e,t,n){return this.on(e,null,t,n)},unbind:function(e,t){return this.off(e,null,t)},delegate:function(e,t,n,r){return this.on(t,e,n,r)},undelegate:function(e,t,n){return 1===arguments.length?this.off(e,"**"):this.off(t,e||"**",n)},hover:function(e,t){return this.mouseenter(e).mouseleave(t||e)}}),S.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(e,n){S.fn[n]=function(e,t){return 0<arguments.length?this.on(n,null,e,t):this.trigger(n)}});var Gt=/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g;S.proxy=function(e,t){var n,r,i;if("string"==typeof t&&(n=e[t],t=e,e=n),m(e))return r=s.call(arguments,2),(i=function(){return e.apply(t||this,r.concat(s.call(arguments)))}).guid=e.guid=e.guid||S.guid++,i},S.holdReady=function(e){e?S.readyWait++:S.ready(!0)},S.isArray=Array.isArray,S.parseJSON=JSON.parse,S.nodeName=A,S.isFunction=m,S.isWindow=x,S.camelCase=X,S.type=w,S.now=Date.now,S.isNumeric=function(e){var t=S.type(e);return("number"===t||"string"===t)&&!isNaN(e-parseFloat(e))},S.trim=function(e){return null==e?"":(e+"").replace(Gt,"")},"function"==typeof define&&define.amd&&define("jquery",[],function(){return S});var Yt=C.jQuery,Qt=C.$;return S.noConflict=function(e){return C.$===S&&(C.$=Qt),e&&C.jQuery===S&&(C.jQuery=Yt),S},"undefined"==typeof e&&(C.jQuery=C.$=S),S}); diff --git a/ctags/docs/_static/language_data.js b/ctags/docs/_static/language_data.js new file mode 100644 index 0000000..863704b --- /dev/null +++ b/ctags/docs/_static/language_data.js @@ -0,0 +1,297 @@ +/* + * language_data.js + * ~~~~~~~~~~~~~~~~ + * + * This script contains the language-specific data used by searchtools.js, + * namely the list of stopwords, stemmer, scorer and splitter. + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"]; + + +/* Non-minified version is copied as a separate JS file, is available */ + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + + + +var splitChars = (function() { + var result = {}; + var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648, + 1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702, + 2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971, + 2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345, + 3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761, + 3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823, + 4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125, + 8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695, + 11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587, + 43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141]; + var i, j, start, end; + for (i = 0; i < singles.length; i++) { + result[singles[i]] = true; + } + var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709], + [722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161], + [1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568], + [1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807], + [1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047], + [2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383], + [2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450], + [2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547], + [2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673], + [2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820], + [2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946], + [2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023], + [3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173], + [3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332], + [3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481], + [3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718], + [3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791], + [3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095], + [4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205], + [4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687], + [4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968], + [4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869], + [5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102], + [6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271], + [6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592], + [6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822], + [6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167], + [7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959], + [7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143], + [8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318], + [8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483], + [8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101], + [10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567], + [11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292], + [12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444], + [12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783], + [12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311], + [19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511], + [42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774], + [42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071], + [43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263], + [43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519], + [43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647], + [43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967], + [44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295], + [57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274], + [64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007], + [65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381], + [65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]]; + for (i = 0; i < ranges.length; i++) { + start = ranges[i][0]; + end = ranges[i][1]; + for (j = start; j <= end; j++) { + result[j] = true; + } + } + return result; +})(); + +function splitQuery(query) { + var result = []; + var start = -1; + for (var i = 0; i < query.length; i++) { + if (splitChars[query.charCodeAt(i)]) { + if (start !== -1) { + result.push(query.slice(start, i)); + start = -1; + } + } else if (start === -1) { + start = i; + } + } + if (start !== -1) { + result.push(query.slice(start)); + } + return result; +} + + diff --git a/ctags/docs/_static/minus.png b/ctags/docs/_static/minus.png Binary files differnew file mode 100644 index 0000000..d96755f --- /dev/null +++ b/ctags/docs/_static/minus.png diff --git a/ctags/docs/_static/plus.png b/ctags/docs/_static/plus.png Binary files differnew file mode 100644 index 0000000..7107cec --- /dev/null +++ b/ctags/docs/_static/plus.png diff --git a/ctags/docs/_static/pygments.css b/ctags/docs/_static/pygments.css new file mode 100644 index 0000000..691aeb8 --- /dev/null +++ b/ctags/docs/_static/pygments.css @@ -0,0 +1,74 @@ +pre { line-height: 125%; } +td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; } +td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; } +.highlight .hll { background-color: #ffffcc } +.highlight { background: #eeffcc; } +.highlight .c { color: #408090; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */ +.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */ +.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #333333 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #208050 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mb { color: #208050 } /* Literal.Number.Bin */ +.highlight .mf { color: #208050 } /* Literal.Number.Float */ +.highlight .mh { color: #208050 } /* Literal.Number.Hex */ +.highlight .mi { color: #208050 } /* Literal.Number.Integer */ +.highlight .mo { color: #208050 } /* Literal.Number.Oct */ +.highlight .sa { color: #4070a0 } /* Literal.String.Affix */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .fm { color: #06287e } /* Name.Function.Magic */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */ +.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */
\ No newline at end of file diff --git a/ctags/docs/_static/searchtools.js b/ctags/docs/_static/searchtools.js new file mode 100644 index 0000000..e09f926 --- /dev/null +++ b/ctags/docs/_static/searchtools.js @@ -0,0 +1,522 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +if (!Scorer) { + /** + * Simple result scoring code. + */ + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [filename, title, anchor, descr, score] + // and returns the new score. + /* + score: function(result) { + return result[4]; + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: {0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5}, // used to be unimportantResults + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2 + }; +} + +if (!splitQuery) { + function splitQuery(query) { + return query.split(/\s+/); + } +} + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + htmlToText : function(htmlString) { + var virtualDocument = document.implementation.createHTMLDocument('virtual'); + var htmlElement = $(htmlString, virtualDocument); + htmlElement.find('.headerlink').remove(); + docContent = htmlElement.find('[role=main]')[0]; + if(docContent === undefined) { + console.warn("Content block not found. Sphinx search tries to obtain it " + + "via '[role=main]'. Could you check your theme or template."); + return ""; + } + return docContent.textContent || docContent.innerText; + }, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + loadIndex : function(url) { + $.ajax({type: "GET", url: url, data: null, + dataType: "script", cache: true, + complete: function(jqxhr, textstatus) { + if (textstatus != "success") { + document.getElementById("searchindexloader").src = url; + } + }}); + }, + + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + var i; + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + } + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out); + this.dots = $('<span></span>').appendTo(this.title); + this.status = $('<p class="search-summary"> </p>').appendTo(this.out); + this.output = $('<ul class="search"/>').appendTo(this.out); + + $('#search-progress').text(_('Preparing search...')); + this.startPulse(); + + // index already loaded, the browser was quick! + if (this.hasIndex()) + this.query(query); + else + this.deferQuery(query); + }, + + /** + * execute search (requires search index to be loaded) + */ + query : function(query) { + var i; + + // stem the searchterms and add them to the correct list + var stemmer = new Stemmer(); + var searchterms = []; + var excluded = []; + var hlterms = []; + var tmp = splitQuery(query); + var objectterms = []; + for (i = 0; i < tmp.length; i++) { + if (tmp[i] !== "") { + objectterms.push(tmp[i].toLowerCase()); + } + + if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") { + // skip this "word" + continue; + } + // stem the word + var word = stemmer.stemWord(tmp[i].toLowerCase()); + // prevent stemmer from cutting word smaller than two chars + if(word.length < 3 && tmp[i].length >= 3) { + word = tmp[i]; + } + var toAppend; + // select the correct list + if (word[0] == '-') { + toAppend = excluded; + word = word.substr(1); + } + else { + toAppend = searchterms; + hlterms.push(tmp[i].toLowerCase()); + } + // only add if not already in the list + if (!$u.contains(toAppend, word)) + toAppend.push(word); + } + var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); + + // console.debug('SEARCH: searching for:'); + // console.info('required: ', searchterms); + // console.info('excluded: ', excluded); + + // prepare search + var terms = this._index.terms; + var titleterms = this._index.titleterms; + + // array of [filename, title, anchor, descr, score] + var results = []; + $('#search-progress').empty(); + + // lookup as object + for (i = 0; i < objectterms.length; i++) { + var others = [].concat(objectterms.slice(0, i), + objectterms.slice(i+1, objectterms.length)); + results = results.concat(this.performObjectSearch(objectterms[i], others)); + } + + // lookup as search terms in fulltext + results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms)); + + // let the scorer override scores with a custom scoring function + if (Scorer.score) { + for (i = 0; i < results.length; i++) + results[i][4] = Scorer.score(results[i]); + } + + // now sort the results by score (in opposite order of appearance, since the + // display function below uses pop() to retrieve items) and then + // alphabetically + results.sort(function(a, b) { + var left = a[4]; + var right = b[4]; + if (left > right) { + return 1; + } else if (left < right) { + return -1; + } else { + // same score: sort alphabetically + left = a[1].toLowerCase(); + right = b[1].toLowerCase(); + return (left > right) ? -1 : ((left < right) ? 1 : 0); + } + }); + + // for debugging + //Search.lastresults = results.slice(); // a copy + //console.info('search results:', Search.lastresults); + + // print the results + var resultCount = results.length; + function displayNextItem() { + // results left, load the summary and display it + if (results.length) { + var item = results.pop(); + var listItem = $('<li></li>'); + var requestUrl = ""; + var linkUrl = ""; + if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') { + // dirhtml builder + var dirname = item[0] + '/'; + if (dirname.match(/\/index\/$/)) { + dirname = dirname.substring(0, dirname.length-6); + } else if (dirname == 'index/') { + dirname = ''; + } + requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname; + linkUrl = requestUrl; + + } else { + // normal html builders + requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX; + linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX; + } + listItem.append($('<a/>').attr('href', + linkUrl + + highlightstring + item[2]).html(item[1])); + if (item[3]) { + listItem.append($('<span> (' + item[3] + ')</span>')); + Search.output.append(listItem); + setTimeout(function() { + displayNextItem(); + }, 5); + } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { + $.ajax({url: requestUrl, + dataType: "text", + complete: function(jqxhr, textstatus) { + var data = jqxhr.responseText; + if (data !== '' && data !== undefined) { + listItem.append(Search.makeSearchSummary(data, searchterms, hlterms)); + } + Search.output.append(listItem); + setTimeout(function() { + displayNextItem(); + }, 5); + }}); + } else { + // no source available, just display title + Search.output.append(listItem); + setTimeout(function() { + displayNextItem(); + }, 5); + } + } + // search finished, update title and status message + else { + Search.stopPulse(); + Search.title.text(_('Search Results')); + if (!resultCount) + Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); + else + Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); + Search.status.fadeIn(500); + } + } + displayNextItem(); + }, + + /** + * search for object names + */ + performObjectSearch : function(object, otherterms) { + var filenames = this._index.filenames; + var docnames = this._index.docnames; + var objects = this._index.objects; + var objnames = this._index.objnames; + var titles = this._index.titles; + + var i; + var results = []; + + for (var prefix in objects) { + for (var name in objects[prefix]) { + var fullname = (prefix ? prefix + '.' : '') + name; + var fullnameLower = fullname.toLowerCase() + if (fullnameLower.indexOf(object) > -1) { + var score = 0; + var parts = fullnameLower.split('.'); + // check for different match types: exact matches of full name or + // "last name" (i.e. last dotted part) + if (fullnameLower == object || parts[parts.length - 1] == object) { + score += Scorer.objNameMatch; + // matches in last name + } else if (parts[parts.length - 1].indexOf(object) > -1) { + score += Scorer.objPartialMatch; + } + var match = objects[prefix][name]; + var objname = objnames[match[1]][2]; + var title = titles[match[0]]; + // If more than one term searched for, we require other words to be + // found in the name/title/description + if (otherterms.length > 0) { + var haystack = (prefix + ' ' + name + ' ' + + objname + ' ' + title).toLowerCase(); + var allfound = true; + for (i = 0; i < otherterms.length; i++) { + if (haystack.indexOf(otherterms[i]) == -1) { + allfound = false; + break; + } + } + if (!allfound) { + continue; + } + } + var descr = objname + _(', in ') + title; + + var anchor = match[3]; + if (anchor === '') + anchor = fullname; + else if (anchor == '-') + anchor = objnames[match[1]][1] + '-' + fullname; + // add custom score for some objects according to scorer + if (Scorer.objPrio.hasOwnProperty(match[2])) { + score += Scorer.objPrio[match[2]]; + } else { + score += Scorer.objPrioDefault; + } + results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]); + } + } + } + + return results; + }, + + /** + * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions + */ + escapeRegExp : function(string) { + return string.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string + }, + + /** + * search for full-text terms in the index + */ + performTermsSearch : function(searchterms, excluded, terms, titleterms) { + var docnames = this._index.docnames; + var filenames = this._index.filenames; + var titles = this._index.titles; + + var i, j, file; + var fileMap = {}; + var scoreMap = {}; + var results = []; + + // perform the search on the required terms + for (i = 0; i < searchterms.length; i++) { + var word = searchterms[i]; + var files = []; + var _o = [ + {files: terms[word], score: Scorer.term}, + {files: titleterms[word], score: Scorer.title} + ]; + // add support for partial matches + if (word.length > 2) { + var word_regex = this.escapeRegExp(word); + for (var w in terms) { + if (w.match(word_regex) && !terms[word]) { + _o.push({files: terms[w], score: Scorer.partialTerm}) + } + } + for (var w in titleterms) { + if (w.match(word_regex) && !titleterms[word]) { + _o.push({files: titleterms[w], score: Scorer.partialTitle}) + } + } + } + + // no match but word was a required one + if ($u.every(_o, function(o){return o.files === undefined;})) { + break; + } + // found search word in contents + $u.each(_o, function(o) { + var _files = o.files; + if (_files === undefined) + return + + if (_files.length === undefined) + _files = [_files]; + files = files.concat(_files); + + // set score for the word in each file to Scorer.term + for (j = 0; j < _files.length; j++) { + file = _files[j]; + if (!(file in scoreMap)) + scoreMap[file] = {}; + scoreMap[file][word] = o.score; + } + }); + + // create the mapping + for (j = 0; j < files.length; j++) { + file = files[j]; + if (file in fileMap && fileMap[file].indexOf(word) === -1) + fileMap[file].push(word); + else + fileMap[file] = [word]; + } + } + + // now check if the files don't contain excluded terms + for (file in fileMap) { + var valid = true; + + // check if all requirements are matched + var filteredTermCount = // as search terms with length < 3 are discarded: ignore + searchterms.filter(function(term){return term.length > 2}).length + if ( + fileMap[file].length != searchterms.length && + fileMap[file].length != filteredTermCount + ) continue; + + // ensure that none of the excluded terms is in the search result + for (i = 0; i < excluded.length; i++) { + if (terms[excluded[i]] == file || + titleterms[excluded[i]] == file || + $u.contains(terms[excluded[i]] || [], file) || + $u.contains(titleterms[excluded[i]] || [], file)) { + valid = false; + break; + } + } + + // if we have still a valid result we can add it to the result list + if (valid) { + // select one (max) score for the file. + // for better ranking, we should calculate ranking by using words statistics like basic tf-idf... + var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]})); + results.push([docnames[file], titles[file], '', null, score, filenames[file]]); + } + } + return results; + }, + + /** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurrence, the + * latter for highlighting it. + */ + makeSearchSummary : function(htmlText, keywords, hlwords) { + var text = Search.htmlToText(htmlText); + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('<p class="context"></p>').text(excerpt); + $.each(hlwords, function() { + rv = rv.highlightText(this, 'highlighted'); + }); + return rv; + } +}; + +$(document).ready(function() { + Search.init(); +}); diff --git a/ctags/docs/_static/sidebar.js b/ctags/docs/_static/sidebar.js new file mode 100644 index 0000000..599639f --- /dev/null +++ b/ctags/docs/_static/sidebar.js @@ -0,0 +1,159 @@ +/* + * sidebar.js + * ~~~~~~~~~~ + * + * This script makes the Sphinx sidebar collapsible. + * + * .sphinxsidebar contains .sphinxsidebarwrapper. This script adds + * in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton + * used to collapse and expand the sidebar. + * + * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden + * and the width of the sidebar and the margin-left of the document + * are decreased. When the sidebar is expanded the opposite happens. + * This script saves a per-browser/per-session cookie used to + * remember the position of the sidebar among the pages. + * Once the browser is closed the cookie is deleted and the position + * reset to the default (expanded). + * + * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +$(function() { + + + + + + + + + // global elements used by the functions. + // the 'sidebarbutton' element is defined as global after its + // creation, in the add_sidebar_button function + var bodywrapper = $('.bodywrapper'); + var sidebar = $('.sphinxsidebar'); + var sidebarwrapper = $('.sphinxsidebarwrapper'); + + // for some reason, the document has no sidebar; do not run into errors + if (!sidebar.length) return; + + // original margin-left of the bodywrapper and width of the sidebar + // with the sidebar expanded + var bw_margin_expanded = bodywrapper.css('margin-left'); + var ssb_width_expanded = sidebar.width(); + + // margin-left of the bodywrapper and width of the sidebar + // with the sidebar collapsed + var bw_margin_collapsed = '.8em'; + var ssb_width_collapsed = '.8em'; + + // colors used by the current theme + var dark_color = $('.related').css('background-color'); + var light_color = $('.document').css('background-color'); + + function sidebar_is_collapsed() { + return sidebarwrapper.is(':not(:visible)'); + } + + function toggle_sidebar() { + if (sidebar_is_collapsed()) + expand_sidebar(); + else + collapse_sidebar(); + } + + function collapse_sidebar() { + sidebarwrapper.hide(); + sidebar.css('width', ssb_width_collapsed); + bodywrapper.css('margin-left', bw_margin_collapsed); + sidebarbutton.css({ + 'margin-left': '0', + 'height': bodywrapper.height() + }); + sidebarbutton.find('span').text('»'); + sidebarbutton.attr('title', _('Expand sidebar')); + document.cookie = 'sidebar=collapsed'; + } + + function expand_sidebar() { + bodywrapper.css('margin-left', bw_margin_expanded); + sidebar.css('width', ssb_width_expanded); + sidebarwrapper.show(); + sidebarbutton.css({ + 'margin-left': ssb_width_expanded-12, + 'height': bodywrapper.height() + }); + sidebarbutton.find('span').text('«'); + sidebarbutton.attr('title', _('Collapse sidebar')); + document.cookie = 'sidebar=expanded'; + } + + function add_sidebar_button() { + sidebarwrapper.css({ + 'float': 'left', + 'margin-right': '0', + 'width': ssb_width_expanded - 28 + }); + // create the button + sidebar.append( + '<div id="sidebarbutton"><span>«</span></div>' + ); + var sidebarbutton = $('#sidebarbutton'); + light_color = sidebarbutton.css('background-color'); + // find the height of the viewport to center the '<<' in the page + var viewport_height; + if (window.innerHeight) + viewport_height = window.innerHeight; + else + viewport_height = $(window).height(); + sidebarbutton.find('span').css({ + 'display': 'block', + 'margin-top': (viewport_height - sidebar.position().top - 20) / 2 + }); + + sidebarbutton.click(toggle_sidebar); + sidebarbutton.attr('title', _('Collapse sidebar')); + sidebarbutton.css({ + 'color': '#FFFFFF', + 'border-left': '1px solid ' + dark_color, + 'font-size': '1.2em', + 'cursor': 'pointer', + 'height': bodywrapper.height(), + 'padding-top': '1px', + 'margin-left': ssb_width_expanded - 12 + }); + + sidebarbutton.hover( + function () { + $(this).css('background-color', dark_color); + }, + function () { + $(this).css('background-color', light_color); + } + ); + } + + function set_position_from_cookie() { + if (!document.cookie) + return; + var items = document.cookie.split(';'); + for(var k=0; k<items.length; k++) { + var key_val = items[k].split('='); + var key = key_val[0].replace(/ /, ""); // strip leading spaces + if (key == 'sidebar') { + var value = key_val[1]; + if ((value == 'collapsed') && (!sidebar_is_collapsed())) + collapse_sidebar(); + else if ((value == 'expanded') && (sidebar_is_collapsed())) + expand_sidebar(); + } + } + } + + add_sidebar_button(); + var sidebarbutton = $('#sidebarbutton'); + set_position_from_cookie(); +});
\ No newline at end of file diff --git a/ctags/docs/_static/underscore-1.13.1.js b/ctags/docs/_static/underscore-1.13.1.js new file mode 100644 index 0000000..ffd77af --- /dev/null +++ b/ctags/docs/_static/underscore-1.13.1.js @@ -0,0 +1,2042 @@ +(function (global, factory) { + typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() : + typeof define === 'function' && define.amd ? define('underscore', factory) : + (global = typeof globalThis !== 'undefined' ? globalThis : global || self, (function () { + var current = global._; + var exports = global._ = factory(); + exports.noConflict = function () { global._ = current; return exports; }; + }())); +}(this, (function () { + // Underscore.js 1.13.1 + // https://underscorejs.org + // (c) 2009-2021 Jeremy Ashkenas, Julian Gonggrijp, and DocumentCloud and Investigative Reporters & Editors + // Underscore may be freely distributed under the MIT license. + + // Current version. + var VERSION = '1.13.1'; + + // Establish the root object, `window` (`self`) in the browser, `global` + // on the server, or `this` in some virtual machines. We use `self` + // instead of `window` for `WebWorker` support. + var root = typeof self == 'object' && self.self === self && self || + typeof global == 'object' && global.global === global && global || + Function('return this')() || + {}; + + // Save bytes in the minified (but not gzipped) version: + var ArrayProto = Array.prototype, ObjProto = Object.prototype; + var SymbolProto = typeof Symbol !== 'undefined' ? Symbol.prototype : null; + + // Create quick reference variables for speed access to core prototypes. + var push = ArrayProto.push, + slice = ArrayProto.slice, + toString = ObjProto.toString, + hasOwnProperty = ObjProto.hasOwnProperty; + + // Modern feature detection. + var supportsArrayBuffer = typeof ArrayBuffer !== 'undefined', + supportsDataView = typeof DataView !== 'undefined'; + + // All **ECMAScript 5+** native function implementations that we hope to use + // are declared here. + var nativeIsArray = Array.isArray, + nativeKeys = Object.keys, + nativeCreate = Object.create, + nativeIsView = supportsArrayBuffer && ArrayBuffer.isView; + + // Create references to these builtin functions because we override them. + var _isNaN = isNaN, + _isFinite = isFinite; + + // Keys in IE < 9 that won't be iterated by `for key in ...` and thus missed. + var hasEnumBug = !{toString: null}.propertyIsEnumerable('toString'); + var nonEnumerableProps = ['valueOf', 'isPrototypeOf', 'toString', + 'propertyIsEnumerable', 'hasOwnProperty', 'toLocaleString']; + + // The largest integer that can be represented exactly. + var MAX_ARRAY_INDEX = Math.pow(2, 53) - 1; + + // Some functions take a variable number of arguments, or a few expected + // arguments at the beginning and then a variable number of values to operate + // on. This helper accumulates all remaining arguments past the function’s + // argument length (or an explicit `startIndex`), into an array that becomes + // the last argument. Similar to ES6’s "rest parameter". + function restArguments(func, startIndex) { + startIndex = startIndex == null ? func.length - 1 : +startIndex; + return function() { + var length = Math.max(arguments.length - startIndex, 0), + rest = Array(length), + index = 0; + for (; index < length; index++) { + rest[index] = arguments[index + startIndex]; + } + switch (startIndex) { + case 0: return func.call(this, rest); + case 1: return func.call(this, arguments[0], rest); + case 2: return func.call(this, arguments[0], arguments[1], rest); + } + var args = Array(startIndex + 1); + for (index = 0; index < startIndex; index++) { + args[index] = arguments[index]; + } + args[startIndex] = rest; + return func.apply(this, args); + }; + } + + // Is a given variable an object? + function isObject(obj) { + var type = typeof obj; + return type === 'function' || type === 'object' && !!obj; + } + + // Is a given value equal to null? + function isNull(obj) { + return obj === null; + } + + // Is a given variable undefined? + function isUndefined(obj) { + return obj === void 0; + } + + // Is a given value a boolean? + function isBoolean(obj) { + return obj === true || obj === false || toString.call(obj) === '[object Boolean]'; + } + + // Is a given value a DOM element? + function isElement(obj) { + return !!(obj && obj.nodeType === 1); + } + + // Internal function for creating a `toString`-based type tester. + function tagTester(name) { + var tag = '[object ' + name + ']'; + return function(obj) { + return toString.call(obj) === tag; + }; + } + + var isString = tagTester('String'); + + var isNumber = tagTester('Number'); + + var isDate = tagTester('Date'); + + var isRegExp = tagTester('RegExp'); + + var isError = tagTester('Error'); + + var isSymbol = tagTester('Symbol'); + + var isArrayBuffer = tagTester('ArrayBuffer'); + + var isFunction = tagTester('Function'); + + // Optimize `isFunction` if appropriate. Work around some `typeof` bugs in old + // v8, IE 11 (#1621), Safari 8 (#1929), and PhantomJS (#2236). + var nodelist = root.document && root.document.childNodes; + if (typeof /./ != 'function' && typeof Int8Array != 'object' && typeof nodelist != 'function') { + isFunction = function(obj) { + return typeof obj == 'function' || false; + }; + } + + var isFunction$1 = isFunction; + + var hasObjectTag = tagTester('Object'); + + // In IE 10 - Edge 13, `DataView` has string tag `'[object Object]'`. + // In IE 11, the most common among them, this problem also applies to + // `Map`, `WeakMap` and `Set`. + var hasStringTagBug = ( + supportsDataView && hasObjectTag(new DataView(new ArrayBuffer(8))) + ), + isIE11 = (typeof Map !== 'undefined' && hasObjectTag(new Map)); + + var isDataView = tagTester('DataView'); + + // In IE 10 - Edge 13, we need a different heuristic + // to determine whether an object is a `DataView`. + function ie10IsDataView(obj) { + return obj != null && isFunction$1(obj.getInt8) && isArrayBuffer(obj.buffer); + } + + var isDataView$1 = (hasStringTagBug ? ie10IsDataView : isDataView); + + // Is a given value an array? + // Delegates to ECMA5's native `Array.isArray`. + var isArray = nativeIsArray || tagTester('Array'); + + // Internal function to check whether `key` is an own property name of `obj`. + function has$1(obj, key) { + return obj != null && hasOwnProperty.call(obj, key); + } + + var isArguments = tagTester('Arguments'); + + // Define a fallback version of the method in browsers (ahem, IE < 9), where + // there isn't any inspectable "Arguments" type. + (function() { + if (!isArguments(arguments)) { + isArguments = function(obj) { + return has$1(obj, 'callee'); + }; + } + }()); + + var isArguments$1 = isArguments; + + // Is a given object a finite number? + function isFinite$1(obj) { + return !isSymbol(obj) && _isFinite(obj) && !isNaN(parseFloat(obj)); + } + + // Is the given value `NaN`? + function isNaN$1(obj) { + return isNumber(obj) && _isNaN(obj); + } + + // Predicate-generating function. Often useful outside of Underscore. + function constant(value) { + return function() { + return value; + }; + } + + // Common internal logic for `isArrayLike` and `isBufferLike`. + function createSizePropertyCheck(getSizeProperty) { + return function(collection) { + var sizeProperty = getSizeProperty(collection); + return typeof sizeProperty == 'number' && sizeProperty >= 0 && sizeProperty <= MAX_ARRAY_INDEX; + } + } + + // Internal helper to generate a function to obtain property `key` from `obj`. + function shallowProperty(key) { + return function(obj) { + return obj == null ? void 0 : obj[key]; + }; + } + + // Internal helper to obtain the `byteLength` property of an object. + var getByteLength = shallowProperty('byteLength'); + + // Internal helper to determine whether we should spend extensive checks against + // `ArrayBuffer` et al. + var isBufferLike = createSizePropertyCheck(getByteLength); + + // Is a given value a typed array? + var typedArrayPattern = /\[object ((I|Ui)nt(8|16|32)|Float(32|64)|Uint8Clamped|Big(I|Ui)nt64)Array\]/; + function isTypedArray(obj) { + // `ArrayBuffer.isView` is the most future-proof, so use it when available. + // Otherwise, fall back on the above regular expression. + return nativeIsView ? (nativeIsView(obj) && !isDataView$1(obj)) : + isBufferLike(obj) && typedArrayPattern.test(toString.call(obj)); + } + + var isTypedArray$1 = supportsArrayBuffer ? isTypedArray : constant(false); + + // Internal helper to obtain the `length` property of an object. + var getLength = shallowProperty('length'); + + // Internal helper to create a simple lookup structure. + // `collectNonEnumProps` used to depend on `_.contains`, but this led to + // circular imports. `emulatedSet` is a one-off solution that only works for + // arrays of strings. + function emulatedSet(keys) { + var hash = {}; + for (var l = keys.length, i = 0; i < l; ++i) hash[keys[i]] = true; + return { + contains: function(key) { return hash[key]; }, + push: function(key) { + hash[key] = true; + return keys.push(key); + } + }; + } + + // Internal helper. Checks `keys` for the presence of keys in IE < 9 that won't + // be iterated by `for key in ...` and thus missed. Extends `keys` in place if + // needed. + function collectNonEnumProps(obj, keys) { + keys = emulatedSet(keys); + var nonEnumIdx = nonEnumerableProps.length; + var constructor = obj.constructor; + var proto = isFunction$1(constructor) && constructor.prototype || ObjProto; + + // Constructor is a special case. + var prop = 'constructor'; + if (has$1(obj, prop) && !keys.contains(prop)) keys.push(prop); + + while (nonEnumIdx--) { + prop = nonEnumerableProps[nonEnumIdx]; + if (prop in obj && obj[prop] !== proto[prop] && !keys.contains(prop)) { + keys.push(prop); + } + } + } + + // Retrieve the names of an object's own properties. + // Delegates to **ECMAScript 5**'s native `Object.keys`. + function keys(obj) { + if (!isObject(obj)) return []; + if (nativeKeys) return nativeKeys(obj); + var keys = []; + for (var key in obj) if (has$1(obj, key)) keys.push(key); + // Ahem, IE < 9. + if (hasEnumBug) collectNonEnumProps(obj, keys); + return keys; + } + + // Is a given array, string, or object empty? + // An "empty" object has no enumerable own-properties. + function isEmpty(obj) { + if (obj == null) return true; + // Skip the more expensive `toString`-based type checks if `obj` has no + // `.length`. + var length = getLength(obj); + if (typeof length == 'number' && ( + isArray(obj) || isString(obj) || isArguments$1(obj) + )) return length === 0; + return getLength(keys(obj)) === 0; + } + + // Returns whether an object has a given set of `key:value` pairs. + function isMatch(object, attrs) { + var _keys = keys(attrs), length = _keys.length; + if (object == null) return !length; + var obj = Object(object); + for (var i = 0; i < length; i++) { + var key = _keys[i]; + if (attrs[key] !== obj[key] || !(key in obj)) return false; + } + return true; + } + + // If Underscore is called as a function, it returns a wrapped object that can + // be used OO-style. This wrapper holds altered versions of all functions added + // through `_.mixin`. Wrapped objects may be chained. + function _$1(obj) { + if (obj instanceof _$1) return obj; + if (!(this instanceof _$1)) return new _$1(obj); + this._wrapped = obj; + } + + _$1.VERSION = VERSION; + + // Extracts the result from a wrapped and chained object. + _$1.prototype.value = function() { + return this._wrapped; + }; + + // Provide unwrapping proxies for some methods used in engine operations + // such as arithmetic and JSON stringification. + _$1.prototype.valueOf = _$1.prototype.toJSON = _$1.prototype.value; + + _$1.prototype.toString = function() { + return String(this._wrapped); + }; + + // Internal function to wrap or shallow-copy an ArrayBuffer, + // typed array or DataView to a new view, reusing the buffer. + function toBufferView(bufferSource) { + return new Uint8Array( + bufferSource.buffer || bufferSource, + bufferSource.byteOffset || 0, + getByteLength(bufferSource) + ); + } + + // We use this string twice, so give it a name for minification. + var tagDataView = '[object DataView]'; + + // Internal recursive comparison function for `_.isEqual`. + function eq(a, b, aStack, bStack) { + // Identical objects are equal. `0 === -0`, but they aren't identical. + // See the [Harmony `egal` proposal](https://wiki.ecmascript.org/doku.php?id=harmony:egal). + if (a === b) return a !== 0 || 1 / a === 1 / b; + // `null` or `undefined` only equal to itself (strict comparison). + if (a == null || b == null) return false; + // `NaN`s are equivalent, but non-reflexive. + if (a !== a) return b !== b; + // Exhaust primitive checks + var type = typeof a; + if (type !== 'function' && type !== 'object' && typeof b != 'object') return false; + return deepEq(a, b, aStack, bStack); + } + + // Internal recursive comparison function for `_.isEqual`. + function deepEq(a, b, aStack, bStack) { + // Unwrap any wrapped objects. + if (a instanceof _$1) a = a._wrapped; + if (b instanceof _$1) b = b._wrapped; + // Compare `[[Class]]` names. + var className = toString.call(a); + if (className !== toString.call(b)) return false; + // Work around a bug in IE 10 - Edge 13. + if (hasStringTagBug && className == '[object Object]' && isDataView$1(a)) { + if (!isDataView$1(b)) return false; + className = tagDataView; + } + switch (className) { + // These types are compared by value. + case '[object RegExp]': + // RegExps are coerced to strings for comparison (Note: '' + /a/i === '/a/i') + case '[object String]': + // Primitives and their corresponding object wrappers are equivalent; thus, `"5"` is + // equivalent to `new String("5")`. + return '' + a === '' + b; + case '[object Number]': + // `NaN`s are equivalent, but non-reflexive. + // Object(NaN) is equivalent to NaN. + if (+a !== +a) return +b !== +b; + // An `egal` comparison is performed for other numeric values. + return +a === 0 ? 1 / +a === 1 / b : +a === +b; + case '[object Date]': + case '[object Boolean]': + // Coerce dates and booleans to numeric primitive values. Dates are compared by their + // millisecond representations. Note that invalid dates with millisecond representations + // of `NaN` are not equivalent. + return +a === +b; + case '[object Symbol]': + return SymbolProto.valueOf.call(a) === SymbolProto.valueOf.call(b); + case '[object ArrayBuffer]': + case tagDataView: + // Coerce to typed array so we can fall through. + return deepEq(toBufferView(a), toBufferView(b), aStack, bStack); + } + + var areArrays = className === '[object Array]'; + if (!areArrays && isTypedArray$1(a)) { + var byteLength = getByteLength(a); + if (byteLength !== getByteLength(b)) return false; + if (a.buffer === b.buffer && a.byteOffset === b.byteOffset) return true; + areArrays = true; + } + if (!areArrays) { + if (typeof a != 'object' || typeof b != 'object') return false; + + // Objects with different constructors are not equivalent, but `Object`s or `Array`s + // from different frames are. + var aCtor = a.constructor, bCtor = b.constructor; + if (aCtor !== bCtor && !(isFunction$1(aCtor) && aCtor instanceof aCtor && + isFunction$1(bCtor) && bCtor instanceof bCtor) + && ('constructor' in a && 'constructor' in b)) { + return false; + } + } + // Assume equality for cyclic structures. The algorithm for detecting cyclic + // structures is adapted from ES 5.1 section 15.12.3, abstract operation `JO`. + + // Initializing stack of traversed objects. + // It's done here since we only need them for objects and arrays comparison. + aStack = aStack || []; + bStack = bStack || []; + var length = aStack.length; + while (length--) { + // Linear search. Performance is inversely proportional to the number of + // unique nested structures. + if (aStack[length] === a) return bStack[length] === b; + } + + // Add the first object to the stack of traversed objects. + aStack.push(a); + bStack.push(b); + + // Recursively compare objects and arrays. + if (areArrays) { + // Compare array lengths to determine if a deep comparison is necessary. + length = a.length; + if (length !== b.length) return false; + // Deep compare the contents, ignoring non-numeric properties. + while (length--) { + if (!eq(a[length], b[length], aStack, bStack)) return false; + } + } else { + // Deep compare objects. + var _keys = keys(a), key; + length = _keys.length; + // Ensure that both objects contain the same number of properties before comparing deep equality. + if (keys(b).length !== length) return false; + while (length--) { + // Deep compare each member + key = _keys[length]; + if (!(has$1(b, key) && eq(a[key], b[key], aStack, bStack))) return false; + } + } + // Remove the first object from the stack of traversed objects. + aStack.pop(); + bStack.pop(); + return true; + } + + // Perform a deep comparison to check if two objects are equal. + function isEqual(a, b) { + return eq(a, b); + } + + // Retrieve all the enumerable property names of an object. + function allKeys(obj) { + if (!isObject(obj)) return []; + var keys = []; + for (var key in obj) keys.push(key); + // Ahem, IE < 9. + if (hasEnumBug) collectNonEnumProps(obj, keys); + return keys; + } + + // Since the regular `Object.prototype.toString` type tests don't work for + // some types in IE 11, we use a fingerprinting heuristic instead, based + // on the methods. It's not great, but it's the best we got. + // The fingerprint method lists are defined below. + function ie11fingerprint(methods) { + var length = getLength(methods); + return function(obj) { + if (obj == null) return false; + // `Map`, `WeakMap` and `Set` have no enumerable keys. + var keys = allKeys(obj); + if (getLength(keys)) return false; + for (var i = 0; i < length; i++) { + if (!isFunction$1(obj[methods[i]])) return false; + } + // If we are testing against `WeakMap`, we need to ensure that + // `obj` doesn't have a `forEach` method in order to distinguish + // it from a regular `Map`. + return methods !== weakMapMethods || !isFunction$1(obj[forEachName]); + }; + } + + // In the interest of compact minification, we write + // each string in the fingerprints only once. + var forEachName = 'forEach', + hasName = 'has', + commonInit = ['clear', 'delete'], + mapTail = ['get', hasName, 'set']; + + // `Map`, `WeakMap` and `Set` each have slightly different + // combinations of the above sublists. + var mapMethods = commonInit.concat(forEachName, mapTail), + weakMapMethods = commonInit.concat(mapTail), + setMethods = ['add'].concat(commonInit, forEachName, hasName); + + var isMap = isIE11 ? ie11fingerprint(mapMethods) : tagTester('Map'); + + var isWeakMap = isIE11 ? ie11fingerprint(weakMapMethods) : tagTester('WeakMap'); + + var isSet = isIE11 ? ie11fingerprint(setMethods) : tagTester('Set'); + + var isWeakSet = tagTester('WeakSet'); + + // Retrieve the values of an object's properties. + function values(obj) { + var _keys = keys(obj); + var length = _keys.length; + var values = Array(length); + for (var i = 0; i < length; i++) { + values[i] = obj[_keys[i]]; + } + return values; + } + + // Convert an object into a list of `[key, value]` pairs. + // The opposite of `_.object` with one argument. + function pairs(obj) { + var _keys = keys(obj); + var length = _keys.length; + var pairs = Array(length); + for (var i = 0; i < length; i++) { + pairs[i] = [_keys[i], obj[_keys[i]]]; + } + return pairs; + } + + // Invert the keys and values of an object. The values must be serializable. + function invert(obj) { + var result = {}; + var _keys = keys(obj); + for (var i = 0, length = _keys.length; i < length; i++) { + result[obj[_keys[i]]] = _keys[i]; + } + return result; + } + + // Return a sorted list of the function names available on the object. + function functions(obj) { + var names = []; + for (var key in obj) { + if (isFunction$1(obj[key])) names.push(key); + } + return names.sort(); + } + + // An internal function for creating assigner functions. + function createAssigner(keysFunc, defaults) { + return function(obj) { + var length = arguments.length; + if (defaults) obj = Object(obj); + if (length < 2 || obj == null) return obj; + for (var index = 1; index < length; index++) { + var source = arguments[index], + keys = keysFunc(source), + l = keys.length; + for (var i = 0; i < l; i++) { + var key = keys[i]; + if (!defaults || obj[key] === void 0) obj[key] = source[key]; + } + } + return obj; + }; + } + + // Extend a given object with all the properties in passed-in object(s). + var extend = createAssigner(allKeys); + + // Assigns a given object with all the own properties in the passed-in + // object(s). + // (https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) + var extendOwn = createAssigner(keys); + + // Fill in a given object with default properties. + var defaults = createAssigner(allKeys, true); + + // Create a naked function reference for surrogate-prototype-swapping. + function ctor() { + return function(){}; + } + + // An internal function for creating a new object that inherits from another. + function baseCreate(prototype) { + if (!isObject(prototype)) return {}; + if (nativeCreate) return nativeCreate(prototype); + var Ctor = ctor(); + Ctor.prototype = prototype; + var result = new Ctor; + Ctor.prototype = null; + return result; + } + + // Creates an object that inherits from the given prototype object. + // If additional properties are provided then they will be added to the + // created object. + function create(prototype, props) { + var result = baseCreate(prototype); + if (props) extendOwn(result, props); + return result; + } + + // Create a (shallow-cloned) duplicate of an object. + function clone(obj) { + if (!isObject(obj)) return obj; + return isArray(obj) ? obj.slice() : extend({}, obj); + } + + // Invokes `interceptor` with the `obj` and then returns `obj`. + // The primary purpose of this method is to "tap into" a method chain, in + // order to perform operations on intermediate results within the chain. + function tap(obj, interceptor) { + interceptor(obj); + return obj; + } + + // Normalize a (deep) property `path` to array. + // Like `_.iteratee`, this function can be customized. + function toPath$1(path) { + return isArray(path) ? path : [path]; + } + _$1.toPath = toPath$1; + + // Internal wrapper for `_.toPath` to enable minification. + // Similar to `cb` for `_.iteratee`. + function toPath(path) { + return _$1.toPath(path); + } + + // Internal function to obtain a nested property in `obj` along `path`. + function deepGet(obj, path) { + var length = path.length; + for (var i = 0; i < length; i++) { + if (obj == null) return void 0; + obj = obj[path[i]]; + } + return length ? obj : void 0; + } + + // Get the value of the (deep) property on `path` from `object`. + // If any property in `path` does not exist or if the value is + // `undefined`, return `defaultValue` instead. + // The `path` is normalized through `_.toPath`. + function get(object, path, defaultValue) { + var value = deepGet(object, toPath(path)); + return isUndefined(value) ? defaultValue : value; + } + + // Shortcut function for checking if an object has a given property directly on + // itself (in other words, not on a prototype). Unlike the internal `has` + // function, this public version can also traverse nested properties. + function has(obj, path) { + path = toPath(path); + var length = path.length; + for (var i = 0; i < length; i++) { + var key = path[i]; + if (!has$1(obj, key)) return false; + obj = obj[key]; + } + return !!length; + } + + // Keep the identity function around for default iteratees. + function identity(value) { + return value; + } + + // Returns a predicate for checking whether an object has a given set of + // `key:value` pairs. + function matcher(attrs) { + attrs = extendOwn({}, attrs); + return function(obj) { + return isMatch(obj, attrs); + }; + } + + // Creates a function that, when passed an object, will traverse that object’s + // properties down the given `path`, specified as an array of keys or indices. + function property(path) { + path = toPath(path); + return function(obj) { + return deepGet(obj, path); + }; + } + + // Internal function that returns an efficient (for current engines) version + // of the passed-in callback, to be repeatedly applied in other Underscore + // functions. + function optimizeCb(func, context, argCount) { + if (context === void 0) return func; + switch (argCount == null ? 3 : argCount) { + case 1: return function(value) { + return func.call(context, value); + }; + // The 2-argument case is omitted because we’re not using it. + case 3: return function(value, index, collection) { + return func.call(context, value, index, collection); + }; + case 4: return function(accumulator, value, index, collection) { + return func.call(context, accumulator, value, index, collection); + }; + } + return function() { + return func.apply(context, arguments); + }; + } + + // An internal function to generate callbacks that can be applied to each + // element in a collection, returning the desired result — either `_.identity`, + // an arbitrary callback, a property matcher, or a property accessor. + function baseIteratee(value, context, argCount) { + if (value == null) return identity; + if (isFunction$1(value)) return optimizeCb(value, context, argCount); + if (isObject(value) && !isArray(value)) return matcher(value); + return property(value); + } + + // External wrapper for our callback generator. Users may customize + // `_.iteratee` if they want additional predicate/iteratee shorthand styles. + // This abstraction hides the internal-only `argCount` argument. + function iteratee(value, context) { + return baseIteratee(value, context, Infinity); + } + _$1.iteratee = iteratee; + + // The function we call internally to generate a callback. It invokes + // `_.iteratee` if overridden, otherwise `baseIteratee`. + function cb(value, context, argCount) { + if (_$1.iteratee !== iteratee) return _$1.iteratee(value, context); + return baseIteratee(value, context, argCount); + } + + // Returns the results of applying the `iteratee` to each element of `obj`. + // In contrast to `_.map` it returns an object. + function mapObject(obj, iteratee, context) { + iteratee = cb(iteratee, context); + var _keys = keys(obj), + length = _keys.length, + results = {}; + for (var index = 0; index < length; index++) { + var currentKey = _keys[index]; + results[currentKey] = iteratee(obj[currentKey], currentKey, obj); + } + return results; + } + + // Predicate-generating function. Often useful outside of Underscore. + function noop(){} + + // Generates a function for a given object that returns a given property. + function propertyOf(obj) { + if (obj == null) return noop; + return function(path) { + return get(obj, path); + }; + } + + // Run a function **n** times. + function times(n, iteratee, context) { + var accum = Array(Math.max(0, n)); + iteratee = optimizeCb(iteratee, context, 1); + for (var i = 0; i < n; i++) accum[i] = iteratee(i); + return accum; + } + + // Return a random integer between `min` and `max` (inclusive). + function random(min, max) { + if (max == null) { + max = min; + min = 0; + } + return min + Math.floor(Math.random() * (max - min + 1)); + } + + // A (possibly faster) way to get the current timestamp as an integer. + var now = Date.now || function() { + return new Date().getTime(); + }; + + // Internal helper to generate functions for escaping and unescaping strings + // to/from HTML interpolation. + function createEscaper(map) { + var escaper = function(match) { + return map[match]; + }; + // Regexes for identifying a key that needs to be escaped. + var source = '(?:' + keys(map).join('|') + ')'; + var testRegexp = RegExp(source); + var replaceRegexp = RegExp(source, 'g'); + return function(string) { + string = string == null ? '' : '' + string; + return testRegexp.test(string) ? string.replace(replaceRegexp, escaper) : string; + }; + } + + // Internal list of HTML entities for escaping. + var escapeMap = { + '&': '&', + '<': '<', + '>': '>', + '"': '"', + "'": ''', + '`': '`' + }; + + // Function for escaping strings to HTML interpolation. + var _escape = createEscaper(escapeMap); + + // Internal list of HTML entities for unescaping. + var unescapeMap = invert(escapeMap); + + // Function for unescaping strings from HTML interpolation. + var _unescape = createEscaper(unescapeMap); + + // By default, Underscore uses ERB-style template delimiters. Change the + // following template settings to use alternative delimiters. + var templateSettings = _$1.templateSettings = { + evaluate: /<%([\s\S]+?)%>/g, + interpolate: /<%=([\s\S]+?)%>/g, + escape: /<%-([\s\S]+?)%>/g + }; + + // When customizing `_.templateSettings`, if you don't want to define an + // interpolation, evaluation or escaping regex, we need one that is + // guaranteed not to match. + var noMatch = /(.)^/; + + // Certain characters need to be escaped so that they can be put into a + // string literal. + var escapes = { + "'": "'", + '\\': '\\', + '\r': 'r', + '\n': 'n', + '\u2028': 'u2028', + '\u2029': 'u2029' + }; + + var escapeRegExp = /\\|'|\r|\n|\u2028|\u2029/g; + + function escapeChar(match) { + return '\\' + escapes[match]; + } + + // In order to prevent third-party code injection through + // `_.templateSettings.variable`, we test it against the following regular + // expression. It is intentionally a bit more liberal than just matching valid + // identifiers, but still prevents possible loopholes through defaults or + // destructuring assignment. + var bareIdentifier = /^\s*(\w|\$)+\s*$/; + + // JavaScript micro-templating, similar to John Resig's implementation. + // Underscore templating handles arbitrary delimiters, preserves whitespace, + // and correctly escapes quotes within interpolated code. + // NB: `oldSettings` only exists for backwards compatibility. + function template(text, settings, oldSettings) { + if (!settings && oldSettings) settings = oldSettings; + settings = defaults({}, settings, _$1.templateSettings); + + // Combine delimiters into one regular expression via alternation. + var matcher = RegExp([ + (settings.escape || noMatch).source, + (settings.interpolate || noMatch).source, + (settings.evaluate || noMatch).source + ].join('|') + '|$', 'g'); + + // Compile the template source, escaping string literals appropriately. + var index = 0; + var source = "__p+='"; + text.replace(matcher, function(match, escape, interpolate, evaluate, offset) { + source += text.slice(index, offset).replace(escapeRegExp, escapeChar); + index = offset + match.length; + + if (escape) { + source += "'+\n((__t=(" + escape + "))==null?'':_.escape(__t))+\n'"; + } else if (interpolate) { + source += "'+\n((__t=(" + interpolate + "))==null?'':__t)+\n'"; + } else if (evaluate) { + source += "';\n" + evaluate + "\n__p+='"; + } + + // Adobe VMs need the match returned to produce the correct offset. + return match; + }); + source += "';\n"; + + var argument = settings.variable; + if (argument) { + // Insure against third-party code injection. (CVE-2021-23358) + if (!bareIdentifier.test(argument)) throw new Error( + 'variable is not a bare identifier: ' + argument + ); + } else { + // If a variable is not specified, place data values in local scope. + source = 'with(obj||{}){\n' + source + '}\n'; + argument = 'obj'; + } + + source = "var __t,__p='',__j=Array.prototype.join," + + "print=function(){__p+=__j.call(arguments,'');};\n" + + source + 'return __p;\n'; + + var render; + try { + render = new Function(argument, '_', source); + } catch (e) { + e.source = source; + throw e; + } + + var template = function(data) { + return render.call(this, data, _$1); + }; + + // Provide the compiled source as a convenience for precompilation. + template.source = 'function(' + argument + '){\n' + source + '}'; + + return template; + } + + // Traverses the children of `obj` along `path`. If a child is a function, it + // is invoked with its parent as context. Returns the value of the final + // child, or `fallback` if any child is undefined. + function result(obj, path, fallback) { + path = toPath(path); + var length = path.length; + if (!length) { + return isFunction$1(fallback) ? fallback.call(obj) : fallback; + } + for (var i = 0; i < length; i++) { + var prop = obj == null ? void 0 : obj[path[i]]; + if (prop === void 0) { + prop = fallback; + i = length; // Ensure we don't continue iterating. + } + obj = isFunction$1(prop) ? prop.call(obj) : prop; + } + return obj; + } + + // Generate a unique integer id (unique within the entire client session). + // Useful for temporary DOM ids. + var idCounter = 0; + function uniqueId(prefix) { + var id = ++idCounter + ''; + return prefix ? prefix + id : id; + } + + // Start chaining a wrapped Underscore object. + function chain(obj) { + var instance = _$1(obj); + instance._chain = true; + return instance; + } + + // Internal function to execute `sourceFunc` bound to `context` with optional + // `args`. Determines whether to execute a function as a constructor or as a + // normal function. + function executeBound(sourceFunc, boundFunc, context, callingContext, args) { + if (!(callingContext instanceof boundFunc)) return sourceFunc.apply(context, args); + var self = baseCreate(sourceFunc.prototype); + var result = sourceFunc.apply(self, args); + if (isObject(result)) return result; + return self; + } + + // Partially apply a function by creating a version that has had some of its + // arguments pre-filled, without changing its dynamic `this` context. `_` acts + // as a placeholder by default, allowing any combination of arguments to be + // pre-filled. Set `_.partial.placeholder` for a custom placeholder argument. + var partial = restArguments(function(func, boundArgs) { + var placeholder = partial.placeholder; + var bound = function() { + var position = 0, length = boundArgs.length; + var args = Array(length); + for (var i = 0; i < length; i++) { + args[i] = boundArgs[i] === placeholder ? arguments[position++] : boundArgs[i]; + } + while (position < arguments.length) args.push(arguments[position++]); + return executeBound(func, bound, this, this, args); + }; + return bound; + }); + + partial.placeholder = _$1; + + // Create a function bound to a given object (assigning `this`, and arguments, + // optionally). + var bind = restArguments(function(func, context, args) { + if (!isFunction$1(func)) throw new TypeError('Bind must be called on a function'); + var bound = restArguments(function(callArgs) { + return executeBound(func, bound, context, this, args.concat(callArgs)); + }); + return bound; + }); + + // Internal helper for collection methods to determine whether a collection + // should be iterated as an array or as an object. + // Related: https://people.mozilla.org/~jorendorff/es6-draft.html#sec-tolength + // Avoids a very nasty iOS 8 JIT bug on ARM-64. #2094 + var isArrayLike = createSizePropertyCheck(getLength); + + // Internal implementation of a recursive `flatten` function. + function flatten$1(input, depth, strict, output) { + output = output || []; + if (!depth && depth !== 0) { + depth = Infinity; + } else if (depth <= 0) { + return output.concat(input); + } + var idx = output.length; + for (var i = 0, length = getLength(input); i < length; i++) { + var value = input[i]; + if (isArrayLike(value) && (isArray(value) || isArguments$1(value))) { + // Flatten current level of array or arguments object. + if (depth > 1) { + flatten$1(value, depth - 1, strict, output); + idx = output.length; + } else { + var j = 0, len = value.length; + while (j < len) output[idx++] = value[j++]; + } + } else if (!strict) { + output[idx++] = value; + } + } + return output; + } + + // Bind a number of an object's methods to that object. Remaining arguments + // are the method names to be bound. Useful for ensuring that all callbacks + // defined on an object belong to it. + var bindAll = restArguments(function(obj, keys) { + keys = flatten$1(keys, false, false); + var index = keys.length; + if (index < 1) throw new Error('bindAll must be passed function names'); + while (index--) { + var key = keys[index]; + obj[key] = bind(obj[key], obj); + } + return obj; + }); + + // Memoize an expensive function by storing its results. + function memoize(func, hasher) { + var memoize = function(key) { + var cache = memoize.cache; + var address = '' + (hasher ? hasher.apply(this, arguments) : key); + if (!has$1(cache, address)) cache[address] = func.apply(this, arguments); + return cache[address]; + }; + memoize.cache = {}; + return memoize; + } + + // Delays a function for the given number of milliseconds, and then calls + // it with the arguments supplied. + var delay = restArguments(function(func, wait, args) { + return setTimeout(function() { + return func.apply(null, args); + }, wait); + }); + + // Defers a function, scheduling it to run after the current call stack has + // cleared. + var defer = partial(delay, _$1, 1); + + // Returns a function, that, when invoked, will only be triggered at most once + // during a given window of time. Normally, the throttled function will run + // as much as it can, without ever going more than once per `wait` duration; + // but if you'd like to disable the execution on the leading edge, pass + // `{leading: false}`. To disable execution on the trailing edge, ditto. + function throttle(func, wait, options) { + var timeout, context, args, result; + var previous = 0; + if (!options) options = {}; + + var later = function() { + previous = options.leading === false ? 0 : now(); + timeout = null; + result = func.apply(context, args); + if (!timeout) context = args = null; + }; + + var throttled = function() { + var _now = now(); + if (!previous && options.leading === false) previous = _now; + var remaining = wait - (_now - previous); + context = this; + args = arguments; + if (remaining <= 0 || remaining > wait) { + if (timeout) { + clearTimeout(timeout); + timeout = null; + } + previous = _now; + result = func.apply(context, args); + if (!timeout) context = args = null; + } else if (!timeout && options.trailing !== false) { + timeout = setTimeout(later, remaining); + } + return result; + }; + + throttled.cancel = function() { + clearTimeout(timeout); + previous = 0; + timeout = context = args = null; + }; + + return throttled; + } + + // When a sequence of calls of the returned function ends, the argument + // function is triggered. The end of a sequence is defined by the `wait` + // parameter. If `immediate` is passed, the argument function will be + // triggered at the beginning of the sequence instead of at the end. + function debounce(func, wait, immediate) { + var timeout, previous, args, result, context; + + var later = function() { + var passed = now() - previous; + if (wait > passed) { + timeout = setTimeout(later, wait - passed); + } else { + timeout = null; + if (!immediate) result = func.apply(context, args); + // This check is needed because `func` can recursively invoke `debounced`. + if (!timeout) args = context = null; + } + }; + + var debounced = restArguments(function(_args) { + context = this; + args = _args; + previous = now(); + if (!timeout) { + timeout = setTimeout(later, wait); + if (immediate) result = func.apply(context, args); + } + return result; + }); + + debounced.cancel = function() { + clearTimeout(timeout); + timeout = args = context = null; + }; + + return debounced; + } + + // Returns the first function passed as an argument to the second, + // allowing you to adjust arguments, run code before and after, and + // conditionally execute the original function. + function wrap(func, wrapper) { + return partial(wrapper, func); + } + + // Returns a negated version of the passed-in predicate. + function negate(predicate) { + return function() { + return !predicate.apply(this, arguments); + }; + } + + // Returns a function that is the composition of a list of functions, each + // consuming the return value of the function that follows. + function compose() { + var args = arguments; + var start = args.length - 1; + return function() { + var i = start; + var result = args[start].apply(this, arguments); + while (i--) result = args[i].call(this, result); + return result; + }; + } + + // Returns a function that will only be executed on and after the Nth call. + function after(times, func) { + return function() { + if (--times < 1) { + return func.apply(this, arguments); + } + }; + } + + // Returns a function that will only be executed up to (but not including) the + // Nth call. + function before(times, func) { + var memo; + return function() { + if (--times > 0) { + memo = func.apply(this, arguments); + } + if (times <= 1) func = null; + return memo; + }; + } + + // Returns a function that will be executed at most one time, no matter how + // often you call it. Useful for lazy initialization. + var once = partial(before, 2); + + // Returns the first key on an object that passes a truth test. + function findKey(obj, predicate, context) { + predicate = cb(predicate, context); + var _keys = keys(obj), key; + for (var i = 0, length = _keys.length; i < length; i++) { + key = _keys[i]; + if (predicate(obj[key], key, obj)) return key; + } + } + + // Internal function to generate `_.findIndex` and `_.findLastIndex`. + function createPredicateIndexFinder(dir) { + return function(array, predicate, context) { + predicate = cb(predicate, context); + var length = getLength(array); + var index = dir > 0 ? 0 : length - 1; + for (; index >= 0 && index < length; index += dir) { + if (predicate(array[index], index, array)) return index; + } + return -1; + }; + } + + // Returns the first index on an array-like that passes a truth test. + var findIndex = createPredicateIndexFinder(1); + + // Returns the last index on an array-like that passes a truth test. + var findLastIndex = createPredicateIndexFinder(-1); + + // Use a comparator function to figure out the smallest index at which + // an object should be inserted so as to maintain order. Uses binary search. + function sortedIndex(array, obj, iteratee, context) { + iteratee = cb(iteratee, context, 1); + var value = iteratee(obj); + var low = 0, high = getLength(array); + while (low < high) { + var mid = Math.floor((low + high) / 2); + if (iteratee(array[mid]) < value) low = mid + 1; else high = mid; + } + return low; + } + + // Internal function to generate the `_.indexOf` and `_.lastIndexOf` functions. + function createIndexFinder(dir, predicateFind, sortedIndex) { + return function(array, item, idx) { + var i = 0, length = getLength(array); + if (typeof idx == 'number') { + if (dir > 0) { + i = idx >= 0 ? idx : Math.max(idx + length, i); + } else { + length = idx >= 0 ? Math.min(idx + 1, length) : idx + length + 1; + } + } else if (sortedIndex && idx && length) { + idx = sortedIndex(array, item); + return array[idx] === item ? idx : -1; + } + if (item !== item) { + idx = predicateFind(slice.call(array, i, length), isNaN$1); + return idx >= 0 ? idx + i : -1; + } + for (idx = dir > 0 ? i : length - 1; idx >= 0 && idx < length; idx += dir) { + if (array[idx] === item) return idx; + } + return -1; + }; + } + + // Return the position of the first occurrence of an item in an array, + // or -1 if the item is not included in the array. + // If the array is large and already in sort order, pass `true` + // for **isSorted** to use binary search. + var indexOf = createIndexFinder(1, findIndex, sortedIndex); + + // Return the position of the last occurrence of an item in an array, + // or -1 if the item is not included in the array. + var lastIndexOf = createIndexFinder(-1, findLastIndex); + + // Return the first value which passes a truth test. + function find(obj, predicate, context) { + var keyFinder = isArrayLike(obj) ? findIndex : findKey; + var key = keyFinder(obj, predicate, context); + if (key !== void 0 && key !== -1) return obj[key]; + } + + // Convenience version of a common use case of `_.find`: getting the first + // object containing specific `key:value` pairs. + function findWhere(obj, attrs) { + return find(obj, matcher(attrs)); + } + + // The cornerstone for collection functions, an `each` + // implementation, aka `forEach`. + // Handles raw objects in addition to array-likes. Treats all + // sparse array-likes as if they were dense. + function each(obj, iteratee, context) { + iteratee = optimizeCb(iteratee, context); + var i, length; + if (isArrayLike(obj)) { + for (i = 0, length = obj.length; i < length; i++) { + iteratee(obj[i], i, obj); + } + } else { + var _keys = keys(obj); + for (i = 0, length = _keys.length; i < length; i++) { + iteratee(obj[_keys[i]], _keys[i], obj); + } + } + return obj; + } + + // Return the results of applying the iteratee to each element. + function map(obj, iteratee, context) { + iteratee = cb(iteratee, context); + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length, + results = Array(length); + for (var index = 0; index < length; index++) { + var currentKey = _keys ? _keys[index] : index; + results[index] = iteratee(obj[currentKey], currentKey, obj); + } + return results; + } + + // Internal helper to create a reducing function, iterating left or right. + function createReduce(dir) { + // Wrap code that reassigns argument variables in a separate function than + // the one that accesses `arguments.length` to avoid a perf hit. (#1991) + var reducer = function(obj, iteratee, memo, initial) { + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length, + index = dir > 0 ? 0 : length - 1; + if (!initial) { + memo = obj[_keys ? _keys[index] : index]; + index += dir; + } + for (; index >= 0 && index < length; index += dir) { + var currentKey = _keys ? _keys[index] : index; + memo = iteratee(memo, obj[currentKey], currentKey, obj); + } + return memo; + }; + + return function(obj, iteratee, memo, context) { + var initial = arguments.length >= 3; + return reducer(obj, optimizeCb(iteratee, context, 4), memo, initial); + }; + } + + // **Reduce** builds up a single result from a list of values, aka `inject`, + // or `foldl`. + var reduce = createReduce(1); + + // The right-associative version of reduce, also known as `foldr`. + var reduceRight = createReduce(-1); + + // Return all the elements that pass a truth test. + function filter(obj, predicate, context) { + var results = []; + predicate = cb(predicate, context); + each(obj, function(value, index, list) { + if (predicate(value, index, list)) results.push(value); + }); + return results; + } + + // Return all the elements for which a truth test fails. + function reject(obj, predicate, context) { + return filter(obj, negate(cb(predicate)), context); + } + + // Determine whether all of the elements pass a truth test. + function every(obj, predicate, context) { + predicate = cb(predicate, context); + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length; + for (var index = 0; index < length; index++) { + var currentKey = _keys ? _keys[index] : index; + if (!predicate(obj[currentKey], currentKey, obj)) return false; + } + return true; + } + + // Determine if at least one element in the object passes a truth test. + function some(obj, predicate, context) { + predicate = cb(predicate, context); + var _keys = !isArrayLike(obj) && keys(obj), + length = (_keys || obj).length; + for (var index = 0; index < length; index++) { + var currentKey = _keys ? _keys[index] : index; + if (predicate(obj[currentKey], currentKey, obj)) return true; + } + return false; + } + + // Determine if the array or object contains a given item (using `===`). + function contains(obj, item, fromIndex, guard) { + if (!isArrayLike(obj)) obj = values(obj); + if (typeof fromIndex != 'number' || guard) fromIndex = 0; + return indexOf(obj, item, fromIndex) >= 0; + } + + // Invoke a method (with arguments) on every item in a collection. + var invoke = restArguments(function(obj, path, args) { + var contextPath, func; + if (isFunction$1(path)) { + func = path; + } else { + path = toPath(path); + contextPath = path.slice(0, -1); + path = path[path.length - 1]; + } + return map(obj, function(context) { + var method = func; + if (!method) { + if (contextPath && contextPath.length) { + context = deepGet(context, contextPath); + } + if (context == null) return void 0; + method = context[path]; + } + return method == null ? method : method.apply(context, args); + }); + }); + + // Convenience version of a common use case of `_.map`: fetching a property. + function pluck(obj, key) { + return map(obj, property(key)); + } + + // Convenience version of a common use case of `_.filter`: selecting only + // objects containing specific `key:value` pairs. + function where(obj, attrs) { + return filter(obj, matcher(attrs)); + } + + // Return the maximum element (or element-based computation). + function max(obj, iteratee, context) { + var result = -Infinity, lastComputed = -Infinity, + value, computed; + if (iteratee == null || typeof iteratee == 'number' && typeof obj[0] != 'object' && obj != null) { + obj = isArrayLike(obj) ? obj : values(obj); + for (var i = 0, length = obj.length; i < length; i++) { + value = obj[i]; + if (value != null && value > result) { + result = value; + } + } + } else { + iteratee = cb(iteratee, context); + each(obj, function(v, index, list) { + computed = iteratee(v, index, list); + if (computed > lastComputed || computed === -Infinity && result === -Infinity) { + result = v; + lastComputed = computed; + } + }); + } + return result; + } + + // Return the minimum element (or element-based computation). + function min(obj, iteratee, context) { + var result = Infinity, lastComputed = Infinity, + value, computed; + if (iteratee == null || typeof iteratee == 'number' && typeof obj[0] != 'object' && obj != null) { + obj = isArrayLike(obj) ? obj : values(obj); + for (var i = 0, length = obj.length; i < length; i++) { + value = obj[i]; + if (value != null && value < result) { + result = value; + } + } + } else { + iteratee = cb(iteratee, context); + each(obj, function(v, index, list) { + computed = iteratee(v, index, list); + if (computed < lastComputed || computed === Infinity && result === Infinity) { + result = v; + lastComputed = computed; + } + }); + } + return result; + } + + // Sample **n** random values from a collection using the modern version of the + // [Fisher-Yates shuffle](https://en.wikipedia.org/wiki/Fisher–Yates_shuffle). + // If **n** is not specified, returns a single random element. + // The internal `guard` argument allows it to work with `_.map`. + function sample(obj, n, guard) { + if (n == null || guard) { + if (!isArrayLike(obj)) obj = values(obj); + return obj[random(obj.length - 1)]; + } + var sample = isArrayLike(obj) ? clone(obj) : values(obj); + var length = getLength(sample); + n = Math.max(Math.min(n, length), 0); + var last = length - 1; + for (var index = 0; index < n; index++) { + var rand = random(index, last); + var temp = sample[index]; + sample[index] = sample[rand]; + sample[rand] = temp; + } + return sample.slice(0, n); + } + + // Shuffle a collection. + function shuffle(obj) { + return sample(obj, Infinity); + } + + // Sort the object's values by a criterion produced by an iteratee. + function sortBy(obj, iteratee, context) { + var index = 0; + iteratee = cb(iteratee, context); + return pluck(map(obj, function(value, key, list) { + return { + value: value, + index: index++, + criteria: iteratee(value, key, list) + }; + }).sort(function(left, right) { + var a = left.criteria; + var b = right.criteria; + if (a !== b) { + if (a > b || a === void 0) return 1; + if (a < b || b === void 0) return -1; + } + return left.index - right.index; + }), 'value'); + } + + // An internal function used for aggregate "group by" operations. + function group(behavior, partition) { + return function(obj, iteratee, context) { + var result = partition ? [[], []] : {}; + iteratee = cb(iteratee, context); + each(obj, function(value, index) { + var key = iteratee(value, index, obj); + behavior(result, value, key); + }); + return result; + }; + } + + // Groups the object's values by a criterion. Pass either a string attribute + // to group by, or a function that returns the criterion. + var groupBy = group(function(result, value, key) { + if (has$1(result, key)) result[key].push(value); else result[key] = [value]; + }); + + // Indexes the object's values by a criterion, similar to `_.groupBy`, but for + // when you know that your index values will be unique. + var indexBy = group(function(result, value, key) { + result[key] = value; + }); + + // Counts instances of an object that group by a certain criterion. Pass + // either a string attribute to count by, or a function that returns the + // criterion. + var countBy = group(function(result, value, key) { + if (has$1(result, key)) result[key]++; else result[key] = 1; + }); + + // Split a collection into two arrays: one whose elements all pass the given + // truth test, and one whose elements all do not pass the truth test. + var partition = group(function(result, value, pass) { + result[pass ? 0 : 1].push(value); + }, true); + + // Safely create a real, live array from anything iterable. + var reStrSymbol = /[^\ud800-\udfff]|[\ud800-\udbff][\udc00-\udfff]|[\ud800-\udfff]/g; + function toArray(obj) { + if (!obj) return []; + if (isArray(obj)) return slice.call(obj); + if (isString(obj)) { + // Keep surrogate pair characters together. + return obj.match(reStrSymbol); + } + if (isArrayLike(obj)) return map(obj, identity); + return values(obj); + } + + // Return the number of elements in a collection. + function size(obj) { + if (obj == null) return 0; + return isArrayLike(obj) ? obj.length : keys(obj).length; + } + + // Internal `_.pick` helper function to determine whether `key` is an enumerable + // property name of `obj`. + function keyInObj(value, key, obj) { + return key in obj; + } + + // Return a copy of the object only containing the allowed properties. + var pick = restArguments(function(obj, keys) { + var result = {}, iteratee = keys[0]; + if (obj == null) return result; + if (isFunction$1(iteratee)) { + if (keys.length > 1) iteratee = optimizeCb(iteratee, keys[1]); + keys = allKeys(obj); + } else { + iteratee = keyInObj; + keys = flatten$1(keys, false, false); + obj = Object(obj); + } + for (var i = 0, length = keys.length; i < length; i++) { + var key = keys[i]; + var value = obj[key]; + if (iteratee(value, key, obj)) result[key] = value; + } + return result; + }); + + // Return a copy of the object without the disallowed properties. + var omit = restArguments(function(obj, keys) { + var iteratee = keys[0], context; + if (isFunction$1(iteratee)) { + iteratee = negate(iteratee); + if (keys.length > 1) context = keys[1]; + } else { + keys = map(flatten$1(keys, false, false), String); + iteratee = function(value, key) { + return !contains(keys, key); + }; + } + return pick(obj, iteratee, context); + }); + + // Returns everything but the last entry of the array. Especially useful on + // the arguments object. Passing **n** will return all the values in + // the array, excluding the last N. + function initial(array, n, guard) { + return slice.call(array, 0, Math.max(0, array.length - (n == null || guard ? 1 : n))); + } + + // Get the first element of an array. Passing **n** will return the first N + // values in the array. The **guard** check allows it to work with `_.map`. + function first(array, n, guard) { + if (array == null || array.length < 1) return n == null || guard ? void 0 : []; + if (n == null || guard) return array[0]; + return initial(array, array.length - n); + } + + // Returns everything but the first entry of the `array`. Especially useful on + // the `arguments` object. Passing an **n** will return the rest N values in the + // `array`. + function rest(array, n, guard) { + return slice.call(array, n == null || guard ? 1 : n); + } + + // Get the last element of an array. Passing **n** will return the last N + // values in the array. + function last(array, n, guard) { + if (array == null || array.length < 1) return n == null || guard ? void 0 : []; + if (n == null || guard) return array[array.length - 1]; + return rest(array, Math.max(0, array.length - n)); + } + + // Trim out all falsy values from an array. + function compact(array) { + return filter(array, Boolean); + } + + // Flatten out an array, either recursively (by default), or up to `depth`. + // Passing `true` or `false` as `depth` means `1` or `Infinity`, respectively. + function flatten(array, depth) { + return flatten$1(array, depth, false); + } + + // Take the difference between one array and a number of other arrays. + // Only the elements present in just the first array will remain. + var difference = restArguments(function(array, rest) { + rest = flatten$1(rest, true, true); + return filter(array, function(value){ + return !contains(rest, value); + }); + }); + + // Return a version of the array that does not contain the specified value(s). + var without = restArguments(function(array, otherArrays) { + return difference(array, otherArrays); + }); + + // Produce a duplicate-free version of the array. If the array has already + // been sorted, you have the option of using a faster algorithm. + // The faster algorithm will not work with an iteratee if the iteratee + // is not a one-to-one function, so providing an iteratee will disable + // the faster algorithm. + function uniq(array, isSorted, iteratee, context) { + if (!isBoolean(isSorted)) { + context = iteratee; + iteratee = isSorted; + isSorted = false; + } + if (iteratee != null) iteratee = cb(iteratee, context); + var result = []; + var seen = []; + for (var i = 0, length = getLength(array); i < length; i++) { + var value = array[i], + computed = iteratee ? iteratee(value, i, array) : value; + if (isSorted && !iteratee) { + if (!i || seen !== computed) result.push(value); + seen = computed; + } else if (iteratee) { + if (!contains(seen, computed)) { + seen.push(computed); + result.push(value); + } + } else if (!contains(result, value)) { + result.push(value); + } + } + return result; + } + + // Produce an array that contains the union: each distinct element from all of + // the passed-in arrays. + var union = restArguments(function(arrays) { + return uniq(flatten$1(arrays, true, true)); + }); + + // Produce an array that contains every item shared between all the + // passed-in arrays. + function intersection(array) { + var result = []; + var argsLength = arguments.length; + for (var i = 0, length = getLength(array); i < length; i++) { + var item = array[i]; + if (contains(result, item)) continue; + var j; + for (j = 1; j < argsLength; j++) { + if (!contains(arguments[j], item)) break; + } + if (j === argsLength) result.push(item); + } + return result; + } + + // Complement of zip. Unzip accepts an array of arrays and groups + // each array's elements on shared indices. + function unzip(array) { + var length = array && max(array, getLength).length || 0; + var result = Array(length); + + for (var index = 0; index < length; index++) { + result[index] = pluck(array, index); + } + return result; + } + + // Zip together multiple lists into a single array -- elements that share + // an index go together. + var zip = restArguments(unzip); + + // Converts lists into objects. Pass either a single array of `[key, value]` + // pairs, or two parallel arrays of the same length -- one of keys, and one of + // the corresponding values. Passing by pairs is the reverse of `_.pairs`. + function object(list, values) { + var result = {}; + for (var i = 0, length = getLength(list); i < length; i++) { + if (values) { + result[list[i]] = values[i]; + } else { + result[list[i][0]] = list[i][1]; + } + } + return result; + } + + // Generate an integer Array containing an arithmetic progression. A port of + // the native Python `range()` function. See + // [the Python documentation](https://docs.python.org/library/functions.html#range). + function range(start, stop, step) { + if (stop == null) { + stop = start || 0; + start = 0; + } + if (!step) { + step = stop < start ? -1 : 1; + } + + var length = Math.max(Math.ceil((stop - start) / step), 0); + var range = Array(length); + + for (var idx = 0; idx < length; idx++, start += step) { + range[idx] = start; + } + + return range; + } + + // Chunk a single array into multiple arrays, each containing `count` or fewer + // items. + function chunk(array, count) { + if (count == null || count < 1) return []; + var result = []; + var i = 0, length = array.length; + while (i < length) { + result.push(slice.call(array, i, i += count)); + } + return result; + } + + // Helper function to continue chaining intermediate results. + function chainResult(instance, obj) { + return instance._chain ? _$1(obj).chain() : obj; + } + + // Add your own custom functions to the Underscore object. + function mixin(obj) { + each(functions(obj), function(name) { + var func = _$1[name] = obj[name]; + _$1.prototype[name] = function() { + var args = [this._wrapped]; + push.apply(args, arguments); + return chainResult(this, func.apply(_$1, args)); + }; + }); + return _$1; + } + + // Add all mutator `Array` functions to the wrapper. + each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) { + var method = ArrayProto[name]; + _$1.prototype[name] = function() { + var obj = this._wrapped; + if (obj != null) { + method.apply(obj, arguments); + if ((name === 'shift' || name === 'splice') && obj.length === 0) { + delete obj[0]; + } + } + return chainResult(this, obj); + }; + }); + + // Add all accessor `Array` functions to the wrapper. + each(['concat', 'join', 'slice'], function(name) { + var method = ArrayProto[name]; + _$1.prototype[name] = function() { + var obj = this._wrapped; + if (obj != null) obj = method.apply(obj, arguments); + return chainResult(this, obj); + }; + }); + + // Named Exports + + var allExports = { + __proto__: null, + VERSION: VERSION, + restArguments: restArguments, + isObject: isObject, + isNull: isNull, + isUndefined: isUndefined, + isBoolean: isBoolean, + isElement: isElement, + isString: isString, + isNumber: isNumber, + isDate: isDate, + isRegExp: isRegExp, + isError: isError, + isSymbol: isSymbol, + isArrayBuffer: isArrayBuffer, + isDataView: isDataView$1, + isArray: isArray, + isFunction: isFunction$1, + isArguments: isArguments$1, + isFinite: isFinite$1, + isNaN: isNaN$1, + isTypedArray: isTypedArray$1, + isEmpty: isEmpty, + isMatch: isMatch, + isEqual: isEqual, + isMap: isMap, + isWeakMap: isWeakMap, + isSet: isSet, + isWeakSet: isWeakSet, + keys: keys, + allKeys: allKeys, + values: values, + pairs: pairs, + invert: invert, + functions: functions, + methods: functions, + extend: extend, + extendOwn: extendOwn, + assign: extendOwn, + defaults: defaults, + create: create, + clone: clone, + tap: tap, + get: get, + has: has, + mapObject: mapObject, + identity: identity, + constant: constant, + noop: noop, + toPath: toPath$1, + property: property, + propertyOf: propertyOf, + matcher: matcher, + matches: matcher, + times: times, + random: random, + now: now, + escape: _escape, + unescape: _unescape, + templateSettings: templateSettings, + template: template, + result: result, + uniqueId: uniqueId, + chain: chain, + iteratee: iteratee, + partial: partial, + bind: bind, + bindAll: bindAll, + memoize: memoize, + delay: delay, + defer: defer, + throttle: throttle, + debounce: debounce, + wrap: wrap, + negate: negate, + compose: compose, + after: after, + before: before, + once: once, + findKey: findKey, + findIndex: findIndex, + findLastIndex: findLastIndex, + sortedIndex: sortedIndex, + indexOf: indexOf, + lastIndexOf: lastIndexOf, + find: find, + detect: find, + findWhere: findWhere, + each: each, + forEach: each, + map: map, + collect: map, + reduce: reduce, + foldl: reduce, + inject: reduce, + reduceRight: reduceRight, + foldr: reduceRight, + filter: filter, + select: filter, + reject: reject, + every: every, + all: every, + some: some, + any: some, + contains: contains, + includes: contains, + include: contains, + invoke: invoke, + pluck: pluck, + where: where, + max: max, + min: min, + shuffle: shuffle, + sample: sample, + sortBy: sortBy, + groupBy: groupBy, + indexBy: indexBy, + countBy: countBy, + partition: partition, + toArray: toArray, + size: size, + pick: pick, + omit: omit, + first: first, + head: first, + take: first, + initial: initial, + last: last, + rest: rest, + tail: rest, + drop: rest, + compact: compact, + flatten: flatten, + without: without, + uniq: uniq, + unique: uniq, + union: union, + intersection: intersection, + difference: difference, + unzip: unzip, + transpose: unzip, + zip: zip, + object: object, + range: range, + chunk: chunk, + mixin: mixin, + 'default': _$1 + }; + + // Default Export + + // Add all of the Underscore functions to the wrapper object. + var _ = mixin(allExports); + // Legacy Node.js API. + _._ = _; + + return _; + +}))); +//# sourceMappingURL=underscore-umd.js.map diff --git a/ctags/docs/_static/underscore.js b/ctags/docs/_static/underscore.js new file mode 100644 index 0000000..cf177d4 --- /dev/null +++ b/ctags/docs/_static/underscore.js @@ -0,0 +1,6 @@ +!function(n,r){"object"==typeof exports&&"undefined"!=typeof module?module.exports=r():"function"==typeof define&&define.amd?define("underscore",r):(n="undefined"!=typeof globalThis?globalThis:n||self,function(){var t=n._,e=n._=r();e.noConflict=function(){return n._=t,e}}())}(this,(function(){ +// Underscore.js 1.13.1 +// https://underscorejs.org +// (c) 2009-2021 Jeremy Ashkenas, Julian Gonggrijp, and DocumentCloud and Investigative Reporters & Editors +// Underscore may be freely distributed under the MIT license. +var n="1.13.1",r="object"==typeof self&&self.self===self&&self||"object"==typeof global&&global.global===global&&global||Function("return this")()||{},t=Array.prototype,e=Object.prototype,u="undefined"!=typeof Symbol?Symbol.prototype:null,o=t.push,i=t.slice,a=e.toString,f=e.hasOwnProperty,c="undefined"!=typeof ArrayBuffer,l="undefined"!=typeof DataView,s=Array.isArray,p=Object.keys,v=Object.create,h=c&&ArrayBuffer.isView,y=isNaN,d=isFinite,g=!{toString:null}.propertyIsEnumerable("toString"),b=["valueOf","isPrototypeOf","toString","propertyIsEnumerable","hasOwnProperty","toLocaleString"],m=Math.pow(2,53)-1;function j(n,r){return r=null==r?n.length-1:+r,function(){for(var t=Math.max(arguments.length-r,0),e=Array(t),u=0;u<t;u++)e[u]=arguments[u+r];switch(r){case 0:return n.call(this,e);case 1:return n.call(this,arguments[0],e);case 2:return n.call(this,arguments[0],arguments[1],e)}var o=Array(r+1);for(u=0;u<r;u++)o[u]=arguments[u];return o[r]=e,n.apply(this,o)}}function _(n){var r=typeof n;return"function"===r||"object"===r&&!!n}function w(n){return void 0===n}function A(n){return!0===n||!1===n||"[object Boolean]"===a.call(n)}function x(n){var r="[object "+n+"]";return function(n){return a.call(n)===r}}var S=x("String"),O=x("Number"),M=x("Date"),E=x("RegExp"),B=x("Error"),N=x("Symbol"),I=x("ArrayBuffer"),T=x("Function"),k=r.document&&r.document.childNodes;"function"!=typeof/./&&"object"!=typeof Int8Array&&"function"!=typeof k&&(T=function(n){return"function"==typeof n||!1});var D=T,R=x("Object"),F=l&&R(new DataView(new ArrayBuffer(8))),V="undefined"!=typeof Map&&R(new Map),P=x("DataView");var q=F?function(n){return null!=n&&D(n.getInt8)&&I(n.buffer)}:P,U=s||x("Array");function W(n,r){return null!=n&&f.call(n,r)}var z=x("Arguments");!function(){z(arguments)||(z=function(n){return W(n,"callee")})}();var L=z;function $(n){return O(n)&&y(n)}function C(n){return function(){return n}}function K(n){return function(r){var t=n(r);return"number"==typeof t&&t>=0&&t<=m}}function J(n){return function(r){return null==r?void 0:r[n]}}var G=J("byteLength"),H=K(G),Q=/\[object ((I|Ui)nt(8|16|32)|Float(32|64)|Uint8Clamped|Big(I|Ui)nt64)Array\]/;var X=c?function(n){return h?h(n)&&!q(n):H(n)&&Q.test(a.call(n))}:C(!1),Y=J("length");function Z(n,r){r=function(n){for(var r={},t=n.length,e=0;e<t;++e)r[n[e]]=!0;return{contains:function(n){return r[n]},push:function(t){return r[t]=!0,n.push(t)}}}(r);var t=b.length,u=n.constructor,o=D(u)&&u.prototype||e,i="constructor";for(W(n,i)&&!r.contains(i)&&r.push(i);t--;)(i=b[t])in n&&n[i]!==o[i]&&!r.contains(i)&&r.push(i)}function nn(n){if(!_(n))return[];if(p)return p(n);var r=[];for(var t in n)W(n,t)&&r.push(t);return g&&Z(n,r),r}function rn(n,r){var t=nn(r),e=t.length;if(null==n)return!e;for(var u=Object(n),o=0;o<e;o++){var i=t[o];if(r[i]!==u[i]||!(i in u))return!1}return!0}function tn(n){return n instanceof tn?n:this instanceof tn?void(this._wrapped=n):new tn(n)}function en(n){return new Uint8Array(n.buffer||n,n.byteOffset||0,G(n))}tn.VERSION=n,tn.prototype.value=function(){return this._wrapped},tn.prototype.valueOf=tn.prototype.toJSON=tn.prototype.value,tn.prototype.toString=function(){return String(this._wrapped)};var un="[object DataView]";function on(n,r,t,e){if(n===r)return 0!==n||1/n==1/r;if(null==n||null==r)return!1;if(n!=n)return r!=r;var o=typeof n;return("function"===o||"object"===o||"object"==typeof r)&&function n(r,t,e,o){r instanceof tn&&(r=r._wrapped);t instanceof tn&&(t=t._wrapped);var i=a.call(r);if(i!==a.call(t))return!1;if(F&&"[object Object]"==i&&q(r)){if(!q(t))return!1;i=un}switch(i){case"[object RegExp]":case"[object String]":return""+r==""+t;case"[object Number]":return+r!=+r?+t!=+t:0==+r?1/+r==1/t:+r==+t;case"[object Date]":case"[object Boolean]":return+r==+t;case"[object Symbol]":return u.valueOf.call(r)===u.valueOf.call(t);case"[object ArrayBuffer]":case un:return n(en(r),en(t),e,o)}var f="[object Array]"===i;if(!f&&X(r)){if(G(r)!==G(t))return!1;if(r.buffer===t.buffer&&r.byteOffset===t.byteOffset)return!0;f=!0}if(!f){if("object"!=typeof r||"object"!=typeof t)return!1;var c=r.constructor,l=t.constructor;if(c!==l&&!(D(c)&&c instanceof c&&D(l)&&l instanceof l)&&"constructor"in r&&"constructor"in t)return!1}o=o||[];var s=(e=e||[]).length;for(;s--;)if(e[s]===r)return o[s]===t;if(e.push(r),o.push(t),f){if((s=r.length)!==t.length)return!1;for(;s--;)if(!on(r[s],t[s],e,o))return!1}else{var p,v=nn(r);if(s=v.length,nn(t).length!==s)return!1;for(;s--;)if(p=v[s],!W(t,p)||!on(r[p],t[p],e,o))return!1}return e.pop(),o.pop(),!0}(n,r,t,e)}function an(n){if(!_(n))return[];var r=[];for(var t in n)r.push(t);return g&&Z(n,r),r}function fn(n){var r=Y(n);return function(t){if(null==t)return!1;var e=an(t);if(Y(e))return!1;for(var u=0;u<r;u++)if(!D(t[n[u]]))return!1;return n!==hn||!D(t[cn])}}var cn="forEach",ln="has",sn=["clear","delete"],pn=["get",ln,"set"],vn=sn.concat(cn,pn),hn=sn.concat(pn),yn=["add"].concat(sn,cn,ln),dn=V?fn(vn):x("Map"),gn=V?fn(hn):x("WeakMap"),bn=V?fn(yn):x("Set"),mn=x("WeakSet");function jn(n){for(var r=nn(n),t=r.length,e=Array(t),u=0;u<t;u++)e[u]=n[r[u]];return e}function _n(n){for(var r={},t=nn(n),e=0,u=t.length;e<u;e++)r[n[t[e]]]=t[e];return r}function wn(n){var r=[];for(var t in n)D(n[t])&&r.push(t);return r.sort()}function An(n,r){return function(t){var e=arguments.length;if(r&&(t=Object(t)),e<2||null==t)return t;for(var u=1;u<e;u++)for(var o=arguments[u],i=n(o),a=i.length,f=0;f<a;f++){var c=i[f];r&&void 0!==t[c]||(t[c]=o[c])}return t}}var xn=An(an),Sn=An(nn),On=An(an,!0);function Mn(n){if(!_(n))return{};if(v)return v(n);var r=function(){};r.prototype=n;var t=new r;return r.prototype=null,t}function En(n){return _(n)?U(n)?n.slice():xn({},n):n}function Bn(n){return U(n)?n:[n]}function Nn(n){return tn.toPath(n)}function In(n,r){for(var t=r.length,e=0;e<t;e++){if(null==n)return;n=n[r[e]]}return t?n:void 0}function Tn(n,r,t){var e=In(n,Nn(r));return w(e)?t:e}function kn(n){return n}function Dn(n){return n=Sn({},n),function(r){return rn(r,n)}}function Rn(n){return n=Nn(n),function(r){return In(r,n)}}function Fn(n,r,t){if(void 0===r)return n;switch(null==t?3:t){case 1:return function(t){return n.call(r,t)};case 3:return function(t,e,u){return n.call(r,t,e,u)};case 4:return function(t,e,u,o){return n.call(r,t,e,u,o)}}return function(){return n.apply(r,arguments)}}function Vn(n,r,t){return null==n?kn:D(n)?Fn(n,r,t):_(n)&&!U(n)?Dn(n):Rn(n)}function Pn(n,r){return Vn(n,r,1/0)}function qn(n,r,t){return tn.iteratee!==Pn?tn.iteratee(n,r):Vn(n,r,t)}function Un(){}function Wn(n,r){return null==r&&(r=n,n=0),n+Math.floor(Math.random()*(r-n+1))}tn.toPath=Bn,tn.iteratee=Pn;var zn=Date.now||function(){return(new Date).getTime()};function Ln(n){var r=function(r){return n[r]},t="(?:"+nn(n).join("|")+")",e=RegExp(t),u=RegExp(t,"g");return function(n){return n=null==n?"":""+n,e.test(n)?n.replace(u,r):n}}var $n={"&":"&","<":"<",">":">",'"':""","'":"'","`":"`"},Cn=Ln($n),Kn=Ln(_n($n)),Jn=tn.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g,escape:/<%-([\s\S]+?)%>/g},Gn=/(.)^/,Hn={"'":"'","\\":"\\","\r":"r","\n":"n","\u2028":"u2028","\u2029":"u2029"},Qn=/\\|'|\r|\n|\u2028|\u2029/g;function Xn(n){return"\\"+Hn[n]}var Yn=/^\s*(\w|\$)+\s*$/;var Zn=0;function nr(n,r,t,e,u){if(!(e instanceof r))return n.apply(t,u);var o=Mn(n.prototype),i=n.apply(o,u);return _(i)?i:o}var rr=j((function(n,r){var t=rr.placeholder,e=function(){for(var u=0,o=r.length,i=Array(o),a=0;a<o;a++)i[a]=r[a]===t?arguments[u++]:r[a];for(;u<arguments.length;)i.push(arguments[u++]);return nr(n,e,this,this,i)};return e}));rr.placeholder=tn;var tr=j((function(n,r,t){if(!D(n))throw new TypeError("Bind must be called on a function");var e=j((function(u){return nr(n,e,r,this,t.concat(u))}));return e})),er=K(Y);function ur(n,r,t,e){if(e=e||[],r||0===r){if(r<=0)return e.concat(n)}else r=1/0;for(var u=e.length,o=0,i=Y(n);o<i;o++){var a=n[o];if(er(a)&&(U(a)||L(a)))if(r>1)ur(a,r-1,t,e),u=e.length;else for(var f=0,c=a.length;f<c;)e[u++]=a[f++];else t||(e[u++]=a)}return e}var or=j((function(n,r){var t=(r=ur(r,!1,!1)).length;if(t<1)throw new Error("bindAll must be passed function names");for(;t--;){var e=r[t];n[e]=tr(n[e],n)}return n}));var ir=j((function(n,r,t){return setTimeout((function(){return n.apply(null,t)}),r)})),ar=rr(ir,tn,1);function fr(n){return function(){return!n.apply(this,arguments)}}function cr(n,r){var t;return function(){return--n>0&&(t=r.apply(this,arguments)),n<=1&&(r=null),t}}var lr=rr(cr,2);function sr(n,r,t){r=qn(r,t);for(var e,u=nn(n),o=0,i=u.length;o<i;o++)if(r(n[e=u[o]],e,n))return e}function pr(n){return function(r,t,e){t=qn(t,e);for(var u=Y(r),o=n>0?0:u-1;o>=0&&o<u;o+=n)if(t(r[o],o,r))return o;return-1}}var vr=pr(1),hr=pr(-1);function yr(n,r,t,e){for(var u=(t=qn(t,e,1))(r),o=0,i=Y(n);o<i;){var a=Math.floor((o+i)/2);t(n[a])<u?o=a+1:i=a}return o}function dr(n,r,t){return function(e,u,o){var a=0,f=Y(e);if("number"==typeof o)n>0?a=o>=0?o:Math.max(o+f,a):f=o>=0?Math.min(o+1,f):o+f+1;else if(t&&o&&f)return e[o=t(e,u)]===u?o:-1;if(u!=u)return(o=r(i.call(e,a,f),$))>=0?o+a:-1;for(o=n>0?a:f-1;o>=0&&o<f;o+=n)if(e[o]===u)return o;return-1}}var gr=dr(1,vr,yr),br=dr(-1,hr);function mr(n,r,t){var e=(er(n)?vr:sr)(n,r,t);if(void 0!==e&&-1!==e)return n[e]}function jr(n,r,t){var e,u;if(r=Fn(r,t),er(n))for(e=0,u=n.length;e<u;e++)r(n[e],e,n);else{var o=nn(n);for(e=0,u=o.length;e<u;e++)r(n[o[e]],o[e],n)}return n}function _r(n,r,t){r=qn(r,t);for(var e=!er(n)&&nn(n),u=(e||n).length,o=Array(u),i=0;i<u;i++){var a=e?e[i]:i;o[i]=r(n[a],a,n)}return o}function wr(n){var r=function(r,t,e,u){var o=!er(r)&&nn(r),i=(o||r).length,a=n>0?0:i-1;for(u||(e=r[o?o[a]:a],a+=n);a>=0&&a<i;a+=n){var f=o?o[a]:a;e=t(e,r[f],f,r)}return e};return function(n,t,e,u){var o=arguments.length>=3;return r(n,Fn(t,u,4),e,o)}}var Ar=wr(1),xr=wr(-1);function Sr(n,r,t){var e=[];return r=qn(r,t),jr(n,(function(n,t,u){r(n,t,u)&&e.push(n)})),e}function Or(n,r,t){r=qn(r,t);for(var e=!er(n)&&nn(n),u=(e||n).length,o=0;o<u;o++){var i=e?e[o]:o;if(!r(n[i],i,n))return!1}return!0}function Mr(n,r,t){r=qn(r,t);for(var e=!er(n)&&nn(n),u=(e||n).length,o=0;o<u;o++){var i=e?e[o]:o;if(r(n[i],i,n))return!0}return!1}function Er(n,r,t,e){return er(n)||(n=jn(n)),("number"!=typeof t||e)&&(t=0),gr(n,r,t)>=0}var Br=j((function(n,r,t){var e,u;return D(r)?u=r:(r=Nn(r),e=r.slice(0,-1),r=r[r.length-1]),_r(n,(function(n){var o=u;if(!o){if(e&&e.length&&(n=In(n,e)),null==n)return;o=n[r]}return null==o?o:o.apply(n,t)}))}));function Nr(n,r){return _r(n,Rn(r))}function Ir(n,r,t){var e,u,o=-1/0,i=-1/0;if(null==r||"number"==typeof r&&"object"!=typeof n[0]&&null!=n)for(var a=0,f=(n=er(n)?n:jn(n)).length;a<f;a++)null!=(e=n[a])&&e>o&&(o=e);else r=qn(r,t),jr(n,(function(n,t,e){((u=r(n,t,e))>i||u===-1/0&&o===-1/0)&&(o=n,i=u)}));return o}function Tr(n,r,t){if(null==r||t)return er(n)||(n=jn(n)),n[Wn(n.length-1)];var e=er(n)?En(n):jn(n),u=Y(e);r=Math.max(Math.min(r,u),0);for(var o=u-1,i=0;i<r;i++){var a=Wn(i,o),f=e[i];e[i]=e[a],e[a]=f}return e.slice(0,r)}function kr(n,r){return function(t,e,u){var o=r?[[],[]]:{};return e=qn(e,u),jr(t,(function(r,u){var i=e(r,u,t);n(o,r,i)})),o}}var Dr=kr((function(n,r,t){W(n,t)?n[t].push(r):n[t]=[r]})),Rr=kr((function(n,r,t){n[t]=r})),Fr=kr((function(n,r,t){W(n,t)?n[t]++:n[t]=1})),Vr=kr((function(n,r,t){n[t?0:1].push(r)}),!0),Pr=/[^\ud800-\udfff]|[\ud800-\udbff][\udc00-\udfff]|[\ud800-\udfff]/g;function qr(n,r,t){return r in t}var Ur=j((function(n,r){var t={},e=r[0];if(null==n)return t;D(e)?(r.length>1&&(e=Fn(e,r[1])),r=an(n)):(e=qr,r=ur(r,!1,!1),n=Object(n));for(var u=0,o=r.length;u<o;u++){var i=r[u],a=n[i];e(a,i,n)&&(t[i]=a)}return t})),Wr=j((function(n,r){var t,e=r[0];return D(e)?(e=fr(e),r.length>1&&(t=r[1])):(r=_r(ur(r,!1,!1),String),e=function(n,t){return!Er(r,t)}),Ur(n,e,t)}));function zr(n,r,t){return i.call(n,0,Math.max(0,n.length-(null==r||t?1:r)))}function Lr(n,r,t){return null==n||n.length<1?null==r||t?void 0:[]:null==r||t?n[0]:zr(n,n.length-r)}function $r(n,r,t){return i.call(n,null==r||t?1:r)}var Cr=j((function(n,r){return r=ur(r,!0,!0),Sr(n,(function(n){return!Er(r,n)}))})),Kr=j((function(n,r){return Cr(n,r)}));function Jr(n,r,t,e){A(r)||(e=t,t=r,r=!1),null!=t&&(t=qn(t,e));for(var u=[],o=[],i=0,a=Y(n);i<a;i++){var f=n[i],c=t?t(f,i,n):f;r&&!t?(i&&o===c||u.push(f),o=c):t?Er(o,c)||(o.push(c),u.push(f)):Er(u,f)||u.push(f)}return u}var Gr=j((function(n){return Jr(ur(n,!0,!0))}));function Hr(n){for(var r=n&&Ir(n,Y).length||0,t=Array(r),e=0;e<r;e++)t[e]=Nr(n,e);return t}var Qr=j(Hr);function Xr(n,r){return n._chain?tn(r).chain():r}function Yr(n){return jr(wn(n),(function(r){var t=tn[r]=n[r];tn.prototype[r]=function(){var n=[this._wrapped];return o.apply(n,arguments),Xr(this,t.apply(tn,n))}})),tn}jr(["pop","push","reverse","shift","sort","splice","unshift"],(function(n){var r=t[n];tn.prototype[n]=function(){var t=this._wrapped;return null!=t&&(r.apply(t,arguments),"shift"!==n&&"splice"!==n||0!==t.length||delete t[0]),Xr(this,t)}})),jr(["concat","join","slice"],(function(n){var r=t[n];tn.prototype[n]=function(){var n=this._wrapped;return null!=n&&(n=r.apply(n,arguments)),Xr(this,n)}}));var Zr=Yr({__proto__:null,VERSION:n,restArguments:j,isObject:_,isNull:function(n){return null===n},isUndefined:w,isBoolean:A,isElement:function(n){return!(!n||1!==n.nodeType)},isString:S,isNumber:O,isDate:M,isRegExp:E,isError:B,isSymbol:N,isArrayBuffer:I,isDataView:q,isArray:U,isFunction:D,isArguments:L,isFinite:function(n){return!N(n)&&d(n)&&!isNaN(parseFloat(n))},isNaN:$,isTypedArray:X,isEmpty:function(n){if(null==n)return!0;var r=Y(n);return"number"==typeof r&&(U(n)||S(n)||L(n))?0===r:0===Y(nn(n))},isMatch:rn,isEqual:function(n,r){return on(n,r)},isMap:dn,isWeakMap:gn,isSet:bn,isWeakSet:mn,keys:nn,allKeys:an,values:jn,pairs:function(n){for(var r=nn(n),t=r.length,e=Array(t),u=0;u<t;u++)e[u]=[r[u],n[r[u]]];return e},invert:_n,functions:wn,methods:wn,extend:xn,extendOwn:Sn,assign:Sn,defaults:On,create:function(n,r){var t=Mn(n);return r&&Sn(t,r),t},clone:En,tap:function(n,r){return r(n),n},get:Tn,has:function(n,r){for(var t=(r=Nn(r)).length,e=0;e<t;e++){var u=r[e];if(!W(n,u))return!1;n=n[u]}return!!t},mapObject:function(n,r,t){r=qn(r,t);for(var e=nn(n),u=e.length,o={},i=0;i<u;i++){var a=e[i];o[a]=r(n[a],a,n)}return o},identity:kn,constant:C,noop:Un,toPath:Bn,property:Rn,propertyOf:function(n){return null==n?Un:function(r){return Tn(n,r)}},matcher:Dn,matches:Dn,times:function(n,r,t){var e=Array(Math.max(0,n));r=Fn(r,t,1);for(var u=0;u<n;u++)e[u]=r(u);return e},random:Wn,now:zn,escape:Cn,unescape:Kn,templateSettings:Jn,template:function(n,r,t){!r&&t&&(r=t),r=On({},r,tn.templateSettings);var e=RegExp([(r.escape||Gn).source,(r.interpolate||Gn).source,(r.evaluate||Gn).source].join("|")+"|$","g"),u=0,o="__p+='";n.replace(e,(function(r,t,e,i,a){return o+=n.slice(u,a).replace(Qn,Xn),u=a+r.length,t?o+="'+\n((__t=("+t+"))==null?'':_.escape(__t))+\n'":e?o+="'+\n((__t=("+e+"))==null?'':__t)+\n'":i&&(o+="';\n"+i+"\n__p+='"),r})),o+="';\n";var i,a=r.variable;if(a){if(!Yn.test(a))throw new Error("variable is not a bare identifier: "+a)}else o="with(obj||{}){\n"+o+"}\n",a="obj";o="var __t,__p='',__j=Array.prototype.join,"+"print=function(){__p+=__j.call(arguments,'');};\n"+o+"return __p;\n";try{i=new Function(a,"_",o)}catch(n){throw n.source=o,n}var f=function(n){return i.call(this,n,tn)};return f.source="function("+a+"){\n"+o+"}",f},result:function(n,r,t){var e=(r=Nn(r)).length;if(!e)return D(t)?t.call(n):t;for(var u=0;u<e;u++){var o=null==n?void 0:n[r[u]];void 0===o&&(o=t,u=e),n=D(o)?o.call(n):o}return n},uniqueId:function(n){var r=++Zn+"";return n?n+r:r},chain:function(n){var r=tn(n);return r._chain=!0,r},iteratee:Pn,partial:rr,bind:tr,bindAll:or,memoize:function(n,r){var t=function(e){var u=t.cache,o=""+(r?r.apply(this,arguments):e);return W(u,o)||(u[o]=n.apply(this,arguments)),u[o]};return t.cache={},t},delay:ir,defer:ar,throttle:function(n,r,t){var e,u,o,i,a=0;t||(t={});var f=function(){a=!1===t.leading?0:zn(),e=null,i=n.apply(u,o),e||(u=o=null)},c=function(){var c=zn();a||!1!==t.leading||(a=c);var l=r-(c-a);return u=this,o=arguments,l<=0||l>r?(e&&(clearTimeout(e),e=null),a=c,i=n.apply(u,o),e||(u=o=null)):e||!1===t.trailing||(e=setTimeout(f,l)),i};return c.cancel=function(){clearTimeout(e),a=0,e=u=o=null},c},debounce:function(n,r,t){var e,u,o,i,a,f=function(){var c=zn()-u;r>c?e=setTimeout(f,r-c):(e=null,t||(i=n.apply(a,o)),e||(o=a=null))},c=j((function(c){return a=this,o=c,u=zn(),e||(e=setTimeout(f,r),t&&(i=n.apply(a,o))),i}));return c.cancel=function(){clearTimeout(e),e=o=a=null},c},wrap:function(n,r){return rr(r,n)},negate:fr,compose:function(){var n=arguments,r=n.length-1;return function(){for(var t=r,e=n[r].apply(this,arguments);t--;)e=n[t].call(this,e);return e}},after:function(n,r){return function(){if(--n<1)return r.apply(this,arguments)}},before:cr,once:lr,findKey:sr,findIndex:vr,findLastIndex:hr,sortedIndex:yr,indexOf:gr,lastIndexOf:br,find:mr,detect:mr,findWhere:function(n,r){return mr(n,Dn(r))},each:jr,forEach:jr,map:_r,collect:_r,reduce:Ar,foldl:Ar,inject:Ar,reduceRight:xr,foldr:xr,filter:Sr,select:Sr,reject:function(n,r,t){return Sr(n,fr(qn(r)),t)},every:Or,all:Or,some:Mr,any:Mr,contains:Er,includes:Er,include:Er,invoke:Br,pluck:Nr,where:function(n,r){return Sr(n,Dn(r))},max:Ir,min:function(n,r,t){var e,u,o=1/0,i=1/0;if(null==r||"number"==typeof r&&"object"!=typeof n[0]&&null!=n)for(var a=0,f=(n=er(n)?n:jn(n)).length;a<f;a++)null!=(e=n[a])&&e<o&&(o=e);else r=qn(r,t),jr(n,(function(n,t,e){((u=r(n,t,e))<i||u===1/0&&o===1/0)&&(o=n,i=u)}));return o},shuffle:function(n){return Tr(n,1/0)},sample:Tr,sortBy:function(n,r,t){var e=0;return r=qn(r,t),Nr(_r(n,(function(n,t,u){return{value:n,index:e++,criteria:r(n,t,u)}})).sort((function(n,r){var t=n.criteria,e=r.criteria;if(t!==e){if(t>e||void 0===t)return 1;if(t<e||void 0===e)return-1}return n.index-r.index})),"value")},groupBy:Dr,indexBy:Rr,countBy:Fr,partition:Vr,toArray:function(n){return n?U(n)?i.call(n):S(n)?n.match(Pr):er(n)?_r(n,kn):jn(n):[]},size:function(n){return null==n?0:er(n)?n.length:nn(n).length},pick:Ur,omit:Wr,first:Lr,head:Lr,take:Lr,initial:zr,last:function(n,r,t){return null==n||n.length<1?null==r||t?void 0:[]:null==r||t?n[n.length-1]:$r(n,Math.max(0,n.length-r))},rest:$r,tail:$r,drop:$r,compact:function(n){return Sr(n,Boolean)},flatten:function(n,r){return ur(n,r,!1)},without:Kr,uniq:Jr,unique:Jr,union:Gr,intersection:function(n){for(var r=[],t=arguments.length,e=0,u=Y(n);e<u;e++){var o=n[e];if(!Er(r,o)){var i;for(i=1;i<t&&Er(arguments[i],o);i++);i===t&&r.push(o)}}return r},difference:Cr,unzip:Hr,transpose:Hr,zip:Qr,object:function(n,r){for(var t={},e=0,u=Y(n);e<u;e++)r?t[n[e]]=r[e]:t[n[e][0]]=n[e][1];return t},range:function(n,r,t){null==r&&(r=n||0,n=0),t||(t=r<n?-1:1);for(var e=Math.max(Math.ceil((r-n)/t),0),u=Array(e),o=0;o<e;o++,n+=t)u[o]=n;return u},chunk:function(n,r){if(null==r||r<1)return[];for(var t=[],e=0,u=n.length;e<u;)t.push(i.call(n,e,e+=r));return t},mixin:Yr,default:tn});return Zr._=Zr,Zr}));
\ No newline at end of file diff --git a/ctags/docs/autotools.html b/ctags/docs/autotools.html new file mode 100644 index 0000000..7ee30d5 --- /dev/null +++ b/ctags/docs/autotools.html @@ -0,0 +1,210 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Building with configure (*nix including GNU/Linux) — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Building/hacking/using on MS-Windows" href="windows.html" /> + <link rel="prev" title="Building ctags" href="building.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="windows.html" title="Building/hacking/using on MS-Windows" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="building.html" title="Building ctags" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="building.html" accesskey="U">Building ctags</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building with configure (*nix including GNU/Linux)</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="building-with-configure-nix-including-gnu-linux"> +<h1>Building with configure (*nix including GNU/Linux)<a class="headerlink" href="#building-with-configure-nix-including-gnu-linux" title="Permalink to this headline">¶</a></h1> +<p>If you are going to build Universal Ctags on a popular GNU/Linux +distribution, you can install the tools and libraries that Universal Ctags +requires (or may use) as packages. See <a class="reference internal" href="#gnu-linux-distributions">GNU/Linux distributions</a> about +the packages.</p> +<p>Like most Autotools-based projects, you need to do:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git clone https://github.com/universal-ctags/ctags.git +$ cd ctags +$ ./autogen.sh +$ ./configure --prefix=/where/you/want # defaults to /usr/local +$ make +$ make install # may require extra privileges depending on where to install +</pre></div> +</div> +<p>After installation the <cite>ctags</cite> executable will be in <cite>$prefix/bin/</cite>.</p> +<p><cite>autogen.sh</cite> runs <cite>autoreconf</cite> internally. +If you use a (binary oriented) GNU/Linux distribution, <cite>autoreconf</cite> may +be part of the <cite>autoconf</cite> package. In addition you may have to install +<cite>automake</cite> and/or <cite>pkg-config</cite>, too.</p> +<section id="gnu-linux-distributions"> +<h2>GNU/Linux distributions<a class="headerlink" href="#gnu-linux-distributions" title="Permalink to this headline">¶</a></h2> +<p>Before running ./autogen.sh, install some packages.</p> +<p>On Debian-based systems (including Ubuntu), do:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo apt install \ + gcc make \ + pkg-config autoconf automake \ + python3-docutils \ + libseccomp-dev \ + libjansson-dev \ + libyaml-dev \ + libxml2-dev +</pre></div> +</div> +<p>On Fedora systems, do:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo dnf install \ + gcc make \ + pkgconfig autoconf automake \ + python3-docutils \ + libseccomp-devel \ + jansson-devel \ + libyaml-devel \ + libxml2-devel +</pre></div> +</div> +</section> +<section id="changing-the-executable-s-name"> +<h2>Changing the executable’s name<a class="headerlink" href="#changing-the-executable-s-name" title="Permalink to this headline">¶</a></h2> +<p>On some systems, like certain BSDs, there is already a ‘ctags’ program in the base +system, so it is somewhat inconvenient to have the same name for +Universal Ctags. During the <code class="docutils literal notranslate"><span class="pre">configure</span></code> stage you can now change +the name of the created executable.</p> +<p>To add a prefix ‘ex’ which will result in ‘ctags’ being renamed to ‘exctags’:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ./configure --program-prefix<span class="o">=</span>ex +</pre></div> +</div> +<p>To completely change the program’s name run the following:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ./configure --program-transform-name<span class="o">=</span><span class="s1">'s/ctags/my_ctags/; s/etags/myemacs_tags/'</span> +</pre></div> +</div> +<p>Please remember there is also an ‘etags’ installed alongside ‘ctags’ which you may also want to rename as shown above.</p> +</section> +<section id="cross-compilation"> +<h2>Cross-compilation<a class="headerlink" href="#cross-compilation" title="Permalink to this headline">¶</a></h2> +<p>The way of cross-compilation is a bit complicated because the +build-system of ctags uses <cite>packcc</cite>, a code generator written in C +language. It means that two C compilers should be installed on you build machine; +one for compiling <cite>packcc</cite>, another for compiling <cite>ctags</cite>.</p> +<p>We provide two sets of configure variables to affect these two C compilers: +<cite>CC</cite>, <cite>CFLAGS</cite>, <cite>CPPFLAGS</cite>, <cite>LDFLAGS</cite> variables affect the compiler who compiles <cite>ctags</cite>. +<cite>CC_FOR_BUILD</cite>, <cite>CPPFLAGS_FOR_BUILD</cite>, <cite>CPPFLAGS_FOR_BUILD</cite>, <cite>LDFLAGS_FOR_BUILD</cite> variables +affect the compiler who compiles <cite>packcc</cite>.</p> +<p>When native-compiling, <cite>FOO_FOR_BUILD</cite> is the same as <cite>FOO</cite>.</p> +<p>Here is an example show you how to use these configure variables:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ mkdir ./out +$ configure \ + --host=armv7a-linux-androideabi \ + --prefix=`pwd`/out \ + --enable-static \ + --disable-seccomp \ + CC=/usr/local/opt/android-sdk/ndk-bundle/toolchains/llvm/prebuilt/darwin-x86_64/bin/armv7a-linux-androideabi21-clang \ + CFLAGS='-v' \ + CPP='/usr/local/opt/android-sdk/ndk-bundle/toolchains/llvm/prebuilt/darwin-x86_64/bin/armv7a-linux-androideabi21-clang -E' \ + CPPFLAGS='-I/Users/leleliu008/.ndk-pkg/pkg/jansson/armeabi-v7a/include -I/Users/leleliu008/.ndk-pkg/pkg/libyaml/armeabi-v7a/include -I/Users/leleliu008/.ndk-pkg/pkg/libxml2/armeabi-v7a/include -I/Users/leleliu008/.ndk-pkg/pkg/libiconv/armeabi-v7a/include --sysroot /usr/local/opt/android-sdk/ndk-bundle/toolchains/llvm/prebuilt/darwin-x86_64/sysroot -Qunused-arguments -Dftello=ftell -Dfseeko=fseek' \ + LDFLAGS='-L/Users/leleliu008/.ndk-pkg/pkg/jansson/armeabi-v7a/lib -L/Users/leleliu008/.ndk-pkg/pkg/libyaml/armeabi-v7a/lib -L/Users/leleliu008/.ndk-pkg/pkg/libxml2/armeabi-v7a/lib -L/Users/leleliu008/.ndk-pkg/pkg/libiconv/armeabi-v7a/lib --sysroot /usr/local/opt/android-sdk/ndk-bundle/toolchains/llvm/prebuilt/darwin-x86_64/sysroot' \ + AR=/usr/local/opt/android-sdk/ndk-bundle/toolchains/llvm/prebuilt/darwin-x86_64/bin/arm-linux-androideabi-ar \ + RANLIB=/usr/local/opt/android-sdk/ndk-bundle/toolchains/llvm/prebuilt/darwin-x86_64/bin/arm-linux-androideabi-ranlib \ + CC_FOR_BUILD=/usr/bin/cc \ + CFLAGS_FOR_BUILD='-v' \ + PKG_CONFIG_PATH=/Users/leleliu008/.ndk-pkg/pkg/libiconv/armeabi-v7a/lib/pkgconfig:/Users/leleliu008/.ndk-pkg/pkg/libxml2/armeabi-v7a/lib/pkgconfig:/Users/leleliu008/.ndk-pkg/pkg/libyaml/armeabi-v7a/lib/pkgconfig:/Users/leleliu008/.ndk-pkg/pkg/jansson/armeabi-v7a/lib/pkgconfig \ + PKG_CONFIG_LIBDIR=/Users/leleliu008/.ndk-pkg/pkg +... +$ make +... +$ make install +... +$ ls out/bin +ctags readtags +</pre></div> +</div> +<p>Simpler example for <cite>aarch64-linux-gnu</cite> can be found in <cite>circle.yml</cite> in the source tree.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Building with configure (*nix including GNU/Linux)</a><ul> +<li><a class="reference internal" href="#gnu-linux-distributions">GNU/Linux distributions</a></li> +<li><a class="reference internal" href="#changing-the-executable-s-name">Changing the executable’s name</a></li> +<li><a class="reference internal" href="#cross-compilation">Cross-compilation</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="building.html" + title="previous chapter">Building ctags</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="windows.html" + title="next chapter">Building/hacking/using on MS-Windows</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="windows.html" title="Building/hacking/using on MS-Windows" + >next</a> |</li> + <li class="right" > + <a href="building.html" title="Building ctags" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="building.html" >Building ctags</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building with configure (*nix including GNU/Linux)</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/building.html b/ctags/docs/building.html new file mode 100644 index 0000000..863a70b --- /dev/null +++ b/ctags/docs/building.html @@ -0,0 +1,121 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Building ctags — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Building with configure (*nix including GNU/Linux)" href="autotools.html" /> + <link rel="prev" title="Universal Ctags Hacking Guide" href="index.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="autotools.html" title="Building with configure (*nix including GNU/Linux)" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="index.html" title="Universal Ctags Hacking Guide" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building ctags</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="building-ctags"> +<h1>Building ctags<a class="headerlink" href="#building-ctags" title="Permalink to this headline">¶</a></h1> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="autotools.html">Building with configure (*nix including GNU/Linux)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="autotools.html#gnu-linux-distributions">GNU/Linux distributions</a></li> +<li class="toctree-l2"><a class="reference internal" href="autotools.html#changing-the-executable-s-name">Changing the executable’s name</a></li> +<li class="toctree-l2"><a class="reference internal" href="autotools.html#cross-compilation">Cross-compilation</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="windows.html">Building/hacking/using on MS-Windows</a><ul> +<li class="toctree-l2"><a class="reference internal" href="windows.html#compilers">Compilers</a></li> +<li class="toctree-l2"><a class="reference internal" href="windows.html#building-ctags-from-the-command-line">Building ctags from the command line</a></li> +<li class="toctree-l2"><a class="reference internal" href="windows.html#building-ctags-with-ides">Building ctags with IDEs</a></li> +<li class="toctree-l2"><a class="reference internal" href="windows.html#other-differences-between-microsoft-windows-and-gnu-linux">Other differences between Microsoft Windows and GNU/Linux</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="osx.html">Building on Mac OS</a><ul> +<li class="toctree-l2"><a class="reference internal" href="osx.html#build-prerequisites">Build Prerequisites</a></li> +<li class="toctree-l2"><a class="reference internal" href="osx.html#differences-between-osx-and-gnu-linux">Differences between OSX and GNU/Linux</a></li> +<li class="toctree-l2"><a class="reference internal" href="osx.html#contributing">Contributing</a></li> +</ul> +</li> +</ul> +</div> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="index.html" + title="previous chapter">Universal Ctags Hacking Guide</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="autotools.html" + title="next chapter">Building with configure (*nix including GNU/Linux)</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="autotools.html" title="Building with configure (*nix including GNU/Linux)" + >next</a> |</li> + <li class="right" > + <a href="index.html" title="Universal Ctags Hacking Guide" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building ctags</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/contributions.html b/ctags/docs/contributions.html new file mode 100644 index 0000000..98ebbf2 --- /dev/null +++ b/ctags/docs/contributions.html @@ -0,0 +1,636 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Contributions — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Relationship between other projects" href="other-projects.html" /> + <link rel="prev" title="Request for extending a parser (or Reporting a bug of parser)" href="reporting.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="other-projects.html" title="Relationship between other projects" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="reporting.html" title="Request for extending a parser (or Reporting a bug of parser)" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Contributions</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="contributions"> +<span id="id1"></span><h1>Contributions<a class="headerlink" href="#contributions" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#basic-rules" id="id3">Basic rules</a></p></li> +<li><p><a class="reference internal" href="#before-you-start" id="id4">Before You Start</a></p> +<ul> +<li><p><a class="reference internal" href="#what-should-be-tagged" id="id5">What should be tagged?</a></p></li> +<li><p><a class="reference internal" href="#defining-kinds-and-roles" id="id6">Defining kinds and roles</a></p></li> +<li><p><a class="reference internal" href="#scope-information-and-full-qualified-tags" id="id7">Scope information and full qualified tags</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#developing-a-parser" id="id8">Developing a parser</a></p> +<ul> +<li><p><a class="reference internal" href="#origin-of-changes-and-license" id="id9">Origin of changes and license</a></p></li> +<li><p><a class="reference internal" href="#reference" id="id10">Reference</a></p></li> +<li><p><a class="reference internal" href="#c-language" id="id11">C language</a></p> +<ul> +<li><p><a class="reference internal" href="#notes-for-gnu-emacs-users" id="id12">Notes for GNU emacs users</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#compatibility" id="id13">Compatibility</a></p></li> +<li><p><a class="reference internal" href="#command-line-options" id="id14">Command line options</a></p></li> +<li><p><a class="reference internal" href="#writing-parser" id="id15">Writing parser</a></p></li> +<li><p><a class="reference internal" href="#build-script" id="id16">Build script</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#testing" id="id17">Testing</a></p> +<ul> +<li><p><a class="reference internal" href="#test-cases" id="id18">Test cases</a></p></li> +<li><p><a class="reference internal" href="#testing-your-parser" id="id19">Testing your parser</a></p></li> +<li><p><a class="reference internal" href="#add-realistic-examples-for-you-parser-to-codebase" id="id20">Add realistic examples for you parser to <em>codebase</em></a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#writing-documents" id="id21">Writing Documents</a></p> +<ul> +<li><p><a class="reference internal" href="#how-to-add-a-new-man-page-for-your-parser" id="id22">How to add a new man page for your parser</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#committing-and-submitting-a-pull-request" id="id23">Committing and submitting a pull request</a></p> +<ul> +<li><p><a class="reference internal" href="#title-of-commit-log-and-pull-request" id="id24">Title of commit log and pull request</a></p></li> +<li><p><a class="reference internal" href="#commit-log" id="id25">Commit log</a></p></li> +<li><p><a class="reference internal" href="#squashing-commits" id="id26">Squashing commits</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#rules-for-reviewing-a-pull-request" id="id27">Rules for reviewing a pull request</a></p></li> +</ul> +</div> +<hr class="docutils" /> +<p>You are welcome.</p> +<p>Supporting many parsers with few developers is impossible. We invite +the person who contributes a parser to u-ctags team, especially if the +target language is updated frequently. TypeScript is a typical +frequently updated language.</p> +<p>This is what we would like potential contributors to know. In this +section “you” means a contributor, and “we” means reviewers. “I” means +Masatake YAMATO, the author of this section.</p> +<p>This page gathers random notes for newly joined members.</p> +<section id="basic-rules"> +<h2><a class="toc-backref" href="#id3">Basic rules</a><a class="headerlink" href="#basic-rules" title="Permalink to this headline">¶</a></h2> +<p>You are the maintainer of your parser, of course.</p> +<p>You may update your parser as you want under the rules described +later.</p> +<p>You may review pull requests changing your parser.</p> +<p>A parser exists and is maintained independently form other +parsers. However, considering the consistency between parsers are not +bad.</p> +<p>You can put your name to docs/developers.rst.</p> +<p>Read docs.ctags.io.</p> +</section> +<section id="before-you-start"> +<h2><a class="toc-backref" href="#id4">Before You Start</a><a class="headerlink" href="#before-you-start" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div></div></blockquote> +<p>When working on ctags I take into account the following uses for +tags:</p> +<ol class="arabic simple"> +<li><p>inserting the name with completion,</p></li> +<li><p>jumping to the definition of the name (in an editor or similar tool),</p></li> +<li><p>navigating the source code tree,</p></li> +<li><p>summarizing the source code tree, and</p></li> +<li><p>answering a query about the source code tree.</p></li> +</ol> +<p>When I review new parser code, I expect the parser to contribute to +these purposes.</p> +<section id="what-should-be-tagged"> +<h3><a class="toc-backref" href="#id5">What should be tagged?</a><a class="headerlink" href="#what-should-be-tagged" title="Permalink to this headline">¶</a></h3> +<p>There are two classes of tags. The primary class is a <em>definition tag</em>. +If a name is defined in a file, the name and the line and the file +where the name is defined should be tagged (recorded). However, in +some languages answering, “What is a definition?” is not so obvious. +You may have to decide what is tagged in your parser thoughtfully. +The purposes listed at the top of this subsection should help you +decide.</p> +<p>The secondary class is a <em>reference tag</em>. This is newly introduced in +Universal Ctags and is not available in Exuberant Ctags. If a name is +used (or referenced) in a file, it can be tagged as a reference tag.</p> +<p>Don’t be confused by the two tag classes.</p> +</section> +<section id="defining-kinds-and-roles"> +<h3><a class="toc-backref" href="#id6">Defining kinds and roles</a><a class="headerlink" href="#defining-kinds-and-roles" title="Permalink to this headline">¶</a></h3> +<p>Defining kinds is the most important task in writing a new parser. +Once a kind is introduced, we cannot change it because it breaks +tags file compatibility.</p> +<p>See <a class="reference internal" href="man/ctags.1.html#tag-entries"><span class="std std-ref">TAG ENTRIES</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> for more details of kinds +and roles.</p> +</section> +<section id="scope-information-and-full-qualified-tags"> +<h3><a class="toc-backref" href="#id7">Scope information and full qualified tags</a><a class="headerlink" href="#scope-information-and-full-qualified-tags" title="Permalink to this headline">¶</a></h3> +<p>Optional. +TBW.</p> +</section> +</section> +<section id="developing-a-parser"> +<h2><a class="toc-backref" href="#id8">Developing a parser</a><a class="headerlink" href="#developing-a-parser" title="Permalink to this headline">¶</a></h2> +<section id="origin-of-changes-and-license"> +<h3><a class="toc-backref" href="#id9">Origin of changes and license</a><a class="headerlink" href="#origin-of-changes-and-license" title="Permalink to this headline">¶</a></h3> +<p>Make clear where the patches come from and who wrote them.</p> +<p>If you backport patches from Geany or some other project, their +commit IDs should be logged, too.</p> +<p>Include a copyright notice when adding a new +<code class="docutils literal notranslate"><span class="pre">{parsers,main}/*.[ch]</span></code> file. +A new file also requires a license notice at the head of the file.</p> +<p>We expect your change (or new code) to be provided under the terms of +the General Public License version 2 or any later version. We would +like you to express “version 2 or any later version”.</p> +</section> +<section id="reference"> +<h3><a class="toc-backref" href="#id10">Reference</a><a class="headerlink" href="#reference" title="Permalink to this headline">¶</a></h3> +<p>In the comment at the head of your source file, include a URL for a +web page that explains the language your parser deals with. +Especially if the language is not well known.</p> +<p>Here is an example.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="cm">/*</span> +<span class="cm">*</span> +<span class="cm">* Copyright (c) 2016, Masatake YAMATO</span> +<span class="cm">* Copyright (c) 2016, Red Hat, K.K.</span> +<span class="cm">*</span> +<span class="cm">* This source code is released for free distribution under the terms of the</span> +<span class="cm">* GNU General Public License version 2 or (at your option) any later version.</span> +<span class="cm">*</span> +<span class="cm">* This module contains functions for generating tags for property list defined</span> +<span class="cm">* in http://www.apple.com/DTDs/PropertyList-1.0.dtd.</span> +<span class="cm">*/</span> +</pre></div> +</div> +</section> +<section id="c-language"> +<h3><a class="toc-backref" href="#id11">C language</a><a class="headerlink" href="#c-language" title="Permalink to this headline">¶</a></h3> +<p>Don’t forget to use <cite>static</cite> modifiers. Don’t introduce unnecessary +global variables.</p> +<p>Remove unused variables and types. If you want to keep them in your +source code, include a descriptive comment.</p> +<p>Use the available facilities provided by the ctags core. If the +facilities are not enough for writing a parser, consider extending +the core first.</p> +<p>Use underscores in names only in file scope objects. +Don’t use them in function declarations, variable declarations or +macro names in header files.</p> +<p>Basic whitespace settings are specified in the <a class="reference external" href="https://editorconfig.org/">EditorConfig</a> configuration file (<cite>.editorconfig</cite>). +There are <a class="reference external" href="https://editorconfig.org/#download">plugins</a> available +for most popular editors to automatically configure these settings.</p> +<p>Style guidelines are largely captured in the <a class="reference external" href="http://uncrustify.sourceforge.net/">Uncrustify</a> configuration file +(<cite>.uncrustify.cfg</cite>). Formatting can be checked with:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>uncrustify -c .uncrustify.cfg -f parsers/awk.c <span class="p">|</span> diff -u parsers/awk.c - +</pre></div> +</div> +<p>Don’t mix <cite>whitespace cleanup</cite> fixes and other improvements in one +commit when changing the existing code. Style fixes, including +<cite>whitespace cleanup</cite>, should be in a separate commit. Mixing +functional changes with style fixes makes reviewing harder.</p> +<p>If possible, don’t use file static variables. Find an alternative way +that uses parameters.</p> +<section id="notes-for-gnu-emacs-users"> +<h4><a class="toc-backref" href="#id12">Notes for GNU emacs users</a><a class="headerlink" href="#notes-for-gnu-emacs-users" title="Permalink to this headline">¶</a></h4> +<p>If you use GNU emacs, utilize the <cite>.editorconfig</cite> configuration based +on non-GNU C style. Here non-GNU C style means +“align a keyword for control flow and <cite>{</cite> of the block start”.</p> +<p>GNU style:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(...)</span> + <span class="p">{</span> + <span class="p">...</span> +</pre></div> +</div> +<p>non-GNU style:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(...)</span> +<span class="p">{</span> + <span class="p">...</span> +</pre></div> +</div> +<p>For combining the style and <cite>.editorconfig</cite> configuration, put +following code snippet to your .emacs:</p> +<div class="highlight-emacs notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nv">add-hook</span> <span class="ss">'hack-local-variables-hook</span> + <span class="p">(</span><span class="nb">lambda</span> <span class="p">()</span> <span class="p">(</span><span class="nv">editorconfig-apply</span><span class="p">)))</span> +</pre></div> +</div> +<p><cite>.dir-locals.el</cite> in ctags source tree applies “linux” style of <cite>cc-mode</cite>. +Above code snippet applies the <cite>.editorconfig</cite> configuration AFTER +installing the “linux” style to the current buffer.</p> +<p>I like GNU style, but for keeping consistency in existing code of +Exuberant Ctags, the origin of Universal Ctags, I introduced the style +and configuration to my .emacs. Please, do the same.</p> +</section> +</section> +<section id="compatibility"> +<h3><a class="toc-backref" href="#id13">Compatibility</a><a class="headerlink" href="#compatibility" title="Permalink to this headline">¶</a></h3> +<p>We are trying to maintain compatibility with Exuberant-ctags in the +following two areas.</p> +<ul class="simple"> +<li><p>Command line option</p></li> +<li><p>Tag file compatibility</p></li> +</ul> +</section> +<section id="command-line-options"> +<h3><a class="toc-backref" href="#id14">Command line options</a><a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h3> +<p>Don’t introduce <cite>--<LANG>-foo=…</cite> style options. They are less +suitable for command-line completion by the zsh/bash completion +engines. Instead, introduce <cite>--foo-<LANG>=…</cite> style options.</p> +<p>Add an entry to docs/news.rst if you change the behavior of an option +or introduce a new option. If you think the option is stable enough, +add it to ctags.1.in, too.</p> +<p>Use underscore as a prefix for experimental options. Once an option +is introduced, it must be maintained. We don’t want to remove it +later. If you are not sure of the usefulness of the option, use an +underscore at the start of a long option name like: <cite>--_echo</cite>.</p> +<p>Write a test case for Tmain or Units.</p> +<p>Don’t remove an option, especially if it exists in Exuberant Ctags.</p> +</section> +<section id="writing-parser"> +<h3><a class="toc-backref" href="#id15">Writing parser</a><a class="headerlink" href="#writing-parser" title="Permalink to this headline">¶</a></h3> +<p>There are two ways to write a parser, writing in C and using <em>optlib parser</em>.</p> +<p>Universal Ctags extends the <em>optlib parser</em> feature so extensively that it can +implement most of functions of a parser. +<em>optlib parser</em> is also suitable for prototyping.</p> +<p>See <a class="reference internal" href="man/ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> and <a class="reference internal" href="optlib.html#optlib"><span class="std std-ref">Extending ctags with Regex parser (optlib)</span></a> for details. +See <a class="reference internal" href="optlib.html#optlib2c"><span class="std std-ref">Translating an option file into C source code (optlib2c)</span></a> how to add a optlib parser on <code class="docutils literal notranslate"><span class="pre">ctags</span></code>.</p> +<p>For writing a parser in C see <a class="reference internal" href="parser-in-c.html#writing-parser-in-c"><span class="std std-ref">Writing a parser in C</span></a>.</p> +</section> +<section id="build-script"> +<h3><a class="toc-backref" href="#id16">Build script</a><a class="headerlink" href="#build-script" title="Permalink to this headline">¶</a></h3> +<p>To add your optlib parser, <code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code>, into <code class="docutils literal notranslate"><span class="pre">ctags</span></code> do the following steps;</p> +<ul class="simple"> +<li><p>put <code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code> file on <code class="docutils literal notranslate"><span class="pre">optlib/</span></code> directory</p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code> on <code class="docutils literal notranslate"><span class="pre">OPTLIB2C_INPUT</span></code> variable in <code class="docutils literal notranslate"><span class="pre">makefiles/optlib2c_input.mak</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">fooParser</span></code> on <code class="docutils literal notranslate"><span class="pre">PARSER_LIST</span></code> macro variable in <code class="docutils literal notranslate"><span class="pre">main/parser_p.h</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">foo</span></code> on the list in the section “New parsers” in <code class="docutils literal notranslate"><span class="pre">docs/news.rst</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">"..\optlib\foo.c"</span></code> in <code class="docutils literal notranslate"><span class="pre">win32/ctags_vs2013.vcxproj</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">"..\optlib\foo.c"</span></code> in <code class="docutils literal notranslate"><span class="pre">win32/ctags_vs2013.vcxproj.filters</span></code></p></li> +</ul> +<p>Translated C code is also committed to our git repository. The translated code +is useful for building ctags on the platforms where optlib2c doesn’t run.</p> +<p>To add your parser file, <code class="docutils literal notranslate"><span class="pre">foo.c</span></code>, into <code class="docutils literal notranslate"><span class="pre">ctags</span></code> do the following steps;</p> +<ul class="simple"> +<li><p>put <code class="docutils literal notranslate"><span class="pre">foo.c</span></code> file on <code class="docutils literal notranslate"><span class="pre">parsers/</span></code> directory</p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">foo.c</span></code> on <code class="docutils literal notranslate"><span class="pre">PARSER_SRCS</span></code> variable in <code class="docutils literal notranslate"><span class="pre">sources.mak</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">foo</span></code> on the list in the section “New parsers” in <code class="docutils literal notranslate"><span class="pre">docs/news.rst</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">"..\parsers\foo.c"</span></code> in <code class="docutils literal notranslate"><span class="pre">win32/ctags_vs2013.vcxproj</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">"..\parsers\foo.c"</span></code> in <code class="docutils literal notranslate"><span class="pre">win32/ctags_vs2013.vcxproj.filters</span></code></p></li> +</ul> +<p>Without updating win32 files our CI process run on Appveyor will fail.</p> +<p>See <a class="reference external" href="https://github.com/universal-ctags/ctags/pull/2765">this pull request</a> +for the <cite>Meson</cite> parser as an example of optlib parser.</p> +</section> +</section> +<section id="testing"> +<h2><a class="toc-backref" href="#id17">Testing</a><a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2> +<p>Add test cases, and run both existing cases and your new cases.</p> +<p>If you add a new parser or modify an existing parser, add new test +cases to “Units”. If you modify the core, add new test cases to +“Tmain”. The way to write and run test cases is described in +<a class="reference internal" href="tips.html#testing-ctags"><span class="std std-ref">Testing ctags</span></a> and <a class="reference internal" href="testing.html#testing-parser"><span class="std std-ref">Testing a parser</span></a> section of this guide.</p> +<p>With the exception of the tmain test harness, you can specify VG=1 +for running test cases under the Valgrind memory debugger.</p> +<p>A parse should not enter an infinite loop for bad input. +A parse should not crash for bad input. +A parse should return control to its caller for bad input.</p> +<p>Describe what kind of tests are passed in the commit message. +e.g.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">units</span> <span class="n">LANGUAGES</span><span class="o">=</span><span class="n">TTCN</span> <span class="n">VG</span><span class="o">=</span><span class="mi">1</span> <span class="ow">is</span> <span class="n">passed</span><span class="o">.</span> +<span class="n">make</span> <span class="n">fuzz</span> <span class="n">LANGUAGES</span><span class="o">=</span><span class="n">TTCN</span> <span class="n">VG</span><span class="o">=</span><span class="mi">1</span> <span class="ow">is</span> <span class="n">passed</span><span class="o">.</span> +<span class="n">make</span> <span class="n">chop</span> <span class="n">LANGUAGES</span><span class="o">=</span><span class="n">TTCN</span> <span class="n">VG</span><span class="o">=</span><span class="mi">1</span> <span class="ow">is</span> <span class="n">passed</span><span class="o">.</span> +</pre></div> +</div> +<section id="test-cases"> +<h3><a class="toc-backref" href="#id18">Test cases</a><a class="headerlink" href="#test-cases" title="Permalink to this headline">¶</a></h3> +<p>Add a test case to Unit when creating or modifying a parser.</p> +<p>Add a test case to Tmain when modifying the core.</p> +<p>Add a test case to Tinst when modifying the install target in the +Makefile.</p> +</section> +<section id="testing-your-parser"> +<h3><a class="toc-backref" href="#id19">Testing your parser</a><a class="headerlink" href="#testing-your-parser" title="Permalink to this headline">¶</a></h3> +<p>If possible, prepare a simple test and a complex one. The simple one +for helping us, the maintainers, understand the intent of the +modification.</p> +<p>If there are more than 3 test cases for a parser, a parser specific +test case directory should be prepared like <cite>Units/parser-c.r</cite>.</p> +</section> +<section id="add-realistic-examples-for-you-parser-to-codebase"> +<h3><a class="toc-backref" href="#id20">Add realistic examples for you parser to <em>codebase</em></a><a class="headerlink" href="#add-realistic-examples-for-you-parser-to-codebase" title="Permalink to this headline">¶</a></h3> +<p>At <a class="reference external" href="https://github.com/universal-ctags/codebase">codebase</a>, we +collect realistic examples that can be used for evaluating your parser +especially about its performance aspect. Consider contributing to the +repository when adding a new parser to Universal Ctags.</p> +</section> +</section> +<section id="writing-documents"> +<h2><a class="toc-backref" href="#id21">Writing Documents</a><a class="headerlink" href="#writing-documents" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">man/*.rst</span></code> files are the source files of our man pages. +The man pages are for users. See “<a class="reference internal" href="#how-to-add-a-new-man-page-for-your-parser">How to add a new man page for your parser</a>”.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">docs/*.rst</span></code> files explain experimental +new features. The files are for developers. The parts of contents +of <code class="docutils literal notranslate"><span class="pre">docs/*.rst</span></code> should be moved to <code class="docutils literal notranslate"><span class="pre">man/*.rst</span></code> in the future.</p></li> +<li><p>Update <code class="docutils literal notranslate"><span class="pre">docs/news.rst</span></code> especially if you add a new parser.</p></li> +<li><p>Write <code class="docutils literal notranslate"><span class="pre">docs/parser-<NAME-OF-YOUR-PARSER>.rst</span></code> as you want. +A FAQ and the design or your parser are common topics. +Consider the maintenance of your parser after you left the +project for some reason.</p></li> +</ul> +<section id="how-to-add-a-new-man-page-for-your-parser"> +<h3><a class="toc-backref" href="#id22">How to add a new man page for your parser</a><a class="headerlink" href="#how-to-add-a-new-man-page-for-your-parser" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li><p>write what the users of your parser may want to (or should) know to <code class="docutils literal notranslate"><span class="pre">man/ctags-lang-LANGUAGE.7.rst.in</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">man/ctags-lang-LANGUAGE.7.rst</span></code> to the list of <code class="docutils literal notranslate"><span class="pre">AC_CONFIG_FILES</span></code> in <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code>.</p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">man/ctags-lang-LANGUAGE.7</span></code> to <code class="docutils literal notranslate"><span class="pre">man_MANS</span></code> of <code class="docutils literal notranslate"><span class="pre">Makefile.am</span></code>.</p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">man/ctags-lang-LANGUAGE.7.rst.in</span></code> to <code class="docutils literal notranslate"><span class="pre">IN_SOURCE_FILES</span></code> of <code class="docutils literal notranslate"><span class="pre">man/Makefile</span></code>.</p></li> +<li><p>run <code class="docutils literal notranslate"><span class="pre">cd</span> <span class="pre">man;</span> <span class="pre">make</span> <span class="pre">QUICK=1</span> <span class="pre">update-docs</span></code>. This step generates the rst file at <code class="docutils literal notranslate"><span class="pre">docs/man/ctags-lang-LANGUAGE.7.rst</span></code>.</p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">ctags-lang-LANGUAGE(7)</span></code> to (toctree of) <code class="docutils literal notranslate"><span class="pre">docs/man-pages.rst</span></code>.</p></li> +<li><dl class="simple"> +<dt>do <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code> for</dt><dd><ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">man/ctags-lang-LANGUAGE.7.rst.in</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">configure.ac</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">Makefile.am</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">man/Makefile</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">docs/man/ctags-lang-LANGUAGE.7.rst</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">docs/man-pages.rst</span></code></p></li> +</ul> +</dd> +</dl> +</li> +<li><p>git commit with a log header: “<code class="docutils literal notranslate"><span class="pre">docs(man):</span> <span class="pre">add</span> <span class="pre">a</span> <span class="pre">man</span> <span class="pre">page</span> <span class="pre">for</span> <span class="pre">LANGUAGE</span></code>”.</p></li> +<li><p>make a pull request</p></li> +</ol> +</section> +</section> +<section id="committing-and-submitting-a-pull-request"> +<h2><a class="toc-backref" href="#id23">Committing and submitting a pull request</a><a class="headerlink" href="#committing-and-submitting-a-pull-request" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>Make a pull request even if the change is small enough.</p></li> +<li><p>Wait for one day till merging even if the change is small enough.</p></li> +<li><p>Wait for 3 days at least for non-small change to your parser.</p></li> +<li><p>Wait for 7 days at least and get an LGTM (Looks Good To Me) comment from a +member of the team if your commit changes the other parts than your parser and +the changes are not obvious.</p></li> +<li><p>Add a test case to your pull request. To make git-bisect happy, +don’t add a test case for a feature or a bugfix before adding the +code for the feature or the bugfix.</p></li> +<li><p>Even if a pull request includes multiple commits, each commit must +be semantically well separated. Sometimes you may want to adjust +whitespaces in the code. Adjusting whitespaces is o.k., but don’t +mix the other change with it. Make a commit just for the whitespaces +adjustment.</p></li> +</ul> +<section id="title-of-commit-log-and-pull-request"> +<h3><a class="toc-backref" href="#id24">Title of commit log and pull request</a><a class="headerlink" href="#title-of-commit-log-and-pull-request" title="Permalink to this headline">¶</a></h3> +<ul> +<li><p>“Misc Fixes” is allowed as far as each commit in a pull request is +semantically well separated. Sometimes, you may fix various minor +things randomly. Making pull requests for each of them is +boring. You may want to make “mix fixes” pull request especially if +your code is young.</p></li> +<li><p>Use [WIP] (Work In Progress) prefix as the title of your pull request, if you don’t +want people to take time for reviewing your code. Removing [WIP] +implies “ready to be reviewed.”</p></li> +<li><p>Use [FYI] (For Your Information) prefix as the title to show your idea or sketch represented +in C language.</p></li> +<li><p>Use the name of your parser as the prefix of a commit log.</p> +<div class="highlight-git notranslate"><div class="highlight"><pre><span></span>C++: record template type parameters to detect the end of template prefix + +If we know Foo is a name of type, it becomes easier to detect whether +">>" in "Foo>>" is a shift operator or the end marker of the template +prefix. +</pre></div> +</div> +<p>In the above example, “C++: ” is the prefix.</p> +</li> +<li><p>Use the name of your parser as the prefix of a pull request if your +change is about a parser.</p></li> +<li><p>Use following prefixes for the changes other than parsers.</p> +<dl class="simple"> +<dt>main:</dt><dd><p>Changes for files under <code class="docutils literal notranslate"><span class="pre">main/</span></code> directory</p> +</dd> +<dt>Units:</dt><dd><p>Changes for the test cases under <code class="docutils literal notranslate"><span class="pre">Units/</span></code> directory</p> +</dd> +<dt>Tmain</dt><dd><p>Changes for the test cases under <code class="docutils literal notranslate"><span class="pre">Tmain/</span></code> directory</p> +</dd> +<dt>docs(web)</dt><dd><p>Changes for the <code class="docutils literal notranslate"><span class="pre">docs/*.rst</span></code></p> +</dd> +<dt>docs(man)</dt><dd><p>Changes for the <code class="docutils literal notranslate"><span class="pre">man/*.rst</span></code></p> +</dd> +</dl> +<p>See also the output of <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code> command.</p> +</li> +<li><p>Combine prefixes with a comma if a change modifies multiple parts of our source tree</p> +<p>Here is an example.</p> +<div class="highlight-git notranslate"><div class="highlight"><pre><span></span>commit 64a05963c108af4b7832a2215006ff5cafcaaebb +Author: Masatake YAMATO <yamato@redhat.com> +Date: Tue Mar 19 12:19:37 2019 +0900 + +main,Flex,JavaScript,SQL,refactor: introduce a helper function to skip two character sequence + +... +</pre></div> +</div> +</li> +<li><p>Use following prefixes if the change as no run-time impact.</p> +<dl class="simple"> +<dt>cosmetic</dt><dd><ul class="simple"> +<li><p>Remove whitespaces at the end of lines</p></li> +<li><p>Adjust indentation</p></li> +<li><p>Remove an empty line</p></li> +<li><p>…</p></li> +</ul> +</dd> +<dt>style</dt><dd><ul class="simple"> +<li><p>Rename symbol names</p></li> +<li><p>…</p></li> +</ul> +</dd> +<dt>refactor</dt><dd><ul class="simple"> +<li><p>Code transformation that doesn’t intent changing run-time behavior</p></li> +</ul> +</dd> +</dl> +<p>These prefixes reduce the load of reviewers.</p> +</li> +<li><p>Use [INCOMPATIBLE] as a prefix for both pull request and commit log +if the change breaks the compatibility with Exuberant Ctags. Write +an explanation in <code class="docutils literal notranslate"><span class="pre">man/ctags-incompatibilities.7.rst.in</span></code> about the +detail of breakage.</p></li> +<li><p>Use [SELF-INCOMPATIBLE] as a prefix for both pull request and commit +log if the change breaks the compatibility with Universal Ctags +itself.</p></li> +</ul> +</section> +<section id="commit-log"> +<h3><a class="toc-backref" href="#id25">Commit log</a><a class="headerlink" href="#commit-log" title="Permalink to this headline">¶</a></h3> +<p>(For new parsers the following criteria is not applicable.)</p> +<p>Make clear the original motivation for the change and/or the impact +on the tags file.</p> +<p>If you fix a bug reported somewhere on the web, its URL should be +logged, too.</p> +<p>If the bug is reported in the Exuberant Ctags tracker on the +SourceForge web site, log it as <code class="docutils literal notranslate"><span class="pre">sf-bugs:N</span></code>, <code class="docutils literal notranslate"><span class="pre">sf-patches:N</span></code>, +<code class="docutils literal notranslate"><span class="pre">sf-support-requests:N</span></code>, or <code class="docutils literal notranslate"><span class="pre">sf-feature-requests:N</span></code>. +<code class="docutils literal notranslate"><span class="pre">docs/tracking.rst</span></code> also should be updated.</p> +</section> +<section id="squashing-commits"> +<h3><a class="toc-backref" href="#id26">Squashing commits</a><a class="headerlink" href="#squashing-commits" title="Permalink to this headline">¶</a></h3> +<p>When you submit a pull request you might receive some comments from a +reviewer and, in response, update your patches. After updating, we +would like you to squash your patches into logical units of work +before we merge them to keep the repository history as simple as +possible.</p> +<ul class="simple"> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rebase</span> <span class="pre">-i</span></code> and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">--force</span></code> to refine your change in +the meaning of “semantically well separated.” “semantically well +separated” is important than “recording the history of your try and +error.”</p></li> +</ul> +<p>Quoted from @steveno in <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/393">#393</a> :</p> +<blockquote> +<div><p>You can check out this page for a good example of how to squash +commits +<a class="reference external" href="http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html">http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html</a></p> +<p>Once you’ve squashed all your commits, simply do a git push -f to +your fork, and GitHub will update the pull request for you +automatically.</p> +</div></blockquote> +</section> +</section> +<section id="rules-for-reviewing-a-pull-request"> +<h2><a class="toc-backref" href="#id27">Rules for reviewing a pull request</a><a class="headerlink" href="#rules-for-reviewing-a-pull-request" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>Put your rough schedule as a comment if you don’t have time, but you +want to review.</p></li> +</ul> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Contributions</a><ul> +<li><a class="reference internal" href="#basic-rules">Basic rules</a></li> +<li><a class="reference internal" href="#before-you-start">Before You Start</a><ul> +<li><a class="reference internal" href="#what-should-be-tagged">What should be tagged?</a></li> +<li><a class="reference internal" href="#defining-kinds-and-roles">Defining kinds and roles</a></li> +<li><a class="reference internal" href="#scope-information-and-full-qualified-tags">Scope information and full qualified tags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#developing-a-parser">Developing a parser</a><ul> +<li><a class="reference internal" href="#origin-of-changes-and-license">Origin of changes and license</a></li> +<li><a class="reference internal" href="#reference">Reference</a></li> +<li><a class="reference internal" href="#c-language">C language</a><ul> +<li><a class="reference internal" href="#notes-for-gnu-emacs-users">Notes for GNU emacs users</a></li> +</ul> +</li> +<li><a class="reference internal" href="#compatibility">Compatibility</a></li> +<li><a class="reference internal" href="#command-line-options">Command line options</a></li> +<li><a class="reference internal" href="#writing-parser">Writing parser</a></li> +<li><a class="reference internal" href="#build-script">Build script</a></li> +</ul> +</li> +<li><a class="reference internal" href="#testing">Testing</a><ul> +<li><a class="reference internal" href="#test-cases">Test cases</a></li> +<li><a class="reference internal" href="#testing-your-parser">Testing your parser</a></li> +<li><a class="reference internal" href="#add-realistic-examples-for-you-parser-to-codebase">Add realistic examples for you parser to <em>codebase</em></a></li> +</ul> +</li> +<li><a class="reference internal" href="#writing-documents">Writing Documents</a><ul> +<li><a class="reference internal" href="#how-to-add-a-new-man-page-for-your-parser">How to add a new man page for your parser</a></li> +</ul> +</li> +<li><a class="reference internal" href="#committing-and-submitting-a-pull-request">Committing and submitting a pull request</a><ul> +<li><a class="reference internal" href="#title-of-commit-log-and-pull-request">Title of commit log and pull request</a></li> +<li><a class="reference internal" href="#commit-log">Commit log</a></li> +<li><a class="reference internal" href="#squashing-commits">Squashing commits</a></li> +</ul> +</li> +<li><a class="reference internal" href="#rules-for-reviewing-a-pull-request">Rules for reviewing a pull request</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="reporting.html" + title="previous chapter">Request for extending a parser (or Reporting a bug of parser)</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="other-projects.html" + title="next chapter">Relationship between other projects</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="other-projects.html" title="Relationship between other projects" + >next</a> |</li> + <li class="right" > + <a href="reporting.html" title="Request for extending a parser (or Reporting a bug of parser)" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Contributions</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/developers.html b/ctags/docs/developers.html new file mode 100644 index 0000000..6d6f3b1 --- /dev/null +++ b/ctags/docs/developers.html @@ -0,0 +1,167 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Who we are — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="prev" title="Relationship between other projects" href="other-projects.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="other-projects.html" title="Relationship between other projects" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Who we are</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="who-we-are"> +<h1>Who we are<a class="headerlink" href="#who-we-are" title="Permalink to this headline">¶</a></h1> +<p>Please, add your name, background and interests here If you are +interested in contributing to Universal Ctags steadily. So we can +dispatch a task and/or an issue to the right person!</p> +<p>(Keep the list in alphabetical order.)</p> +<p>Cameron Eagans <<a class="reference external" href="mailto:me%40cweagans.net">me<span>@</span>cweagans<span>.</span>net</a>></p> +<blockquote> +<div><p>I’ve been a PHP developer for almost 10 years, and have been using Vim +almost as long. My goal is to help guide the direction of the PHP +parser, as well as maintain the ctags website and help guide new +contributors to tasks that they may be able to help with. With time, +I may end up contributing directly to ctags development, but my C skills +are not so great at the moment.</p> +</div></blockquote> +<p>Colomban Wendling <<a class="reference external" href="mailto:colomban%40geany.org">colomban<span>@</span>geany<span>.</span>org</a>></p> +<blockquote> +<div><p>I am a developer of Geany, a lightweight IDE/editor that uses CTags +parsers to provide various code insights for a large variety of +languages. I don’t use CTags directly but through a (currently) +internal library. Hence, my fields of interest are the quality of the +parsers (good and comprehensive results) and their code (speed, proof +against any inputs, absence of memory leaks, regression tests), and a +CTags library applications could use more readily. I am mostly a C +developer, but as the maintainer of the CTags parsers in Geany I work +on all parsers.</p> +</div></blockquote> +<p>Frank Fesevur <<a class="reference external" href="mailto:ffes%40users.sourceforge.net">ffes<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>></p> +<blockquote> +<div><p>My current use of ctags is for a Notepad++ plug-in I’m writing. +The plug-in is not yet released because of problems with the +Windows version of ctags. Those problems are fixed by now. +I am a Windows developer, but also an occasional Ubuntu and +Raspbian user at home. I wrote the windres parser.</p> +</div></blockquote> +<p>Karol Samborski <<a class="reference external" href="mailto:edv.karol%40gmail.com">edv<span>.</span>karol<span>@</span>gmail<span>.</span>com</a>></p> +<blockquote> +<div><p>I like programming in multiple languages such as Haskell, C/C++, +TypeScript, PHP to name a few. Ctags are useful for me as I code mostly in +Vim. My goal here is to take care of the TypeScript parser.</p> +</div></blockquote> +<p>Ken Takata <<a class="reference external" href="mailto:kentkt%40csc.jp">kentkt<span>@</span>csc<span>.</span>jp</a>></p> +<blockquote> +<div><p>I use ctags with Vim mainly on Windows and Cygwin. +I’m the one of the heaviest contributors of Vim. +I set up the AppVeyor environment and I’m also maintaining the +<a class="reference external" href="https://github.com/universal-ctags/ctags-win32">ctags-win32</a> project.</p> +</div></blockquote> +<p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +<blockquote> +<div><p>I’m using ctags in batch jobs running on my source code base +where most of all source code in Fedora are deployed. I’m an +Emacs user, so generally I don’t use ctags interactively +except when hacking Universal Ctags. Therefore my primary goal +is to improve the robustness of parsers: I introduced Units +test facility and badinput command for achieving the goal. +The secondary goal is to support more languages and formats: I +introduced optlib. I’m working on Fedora. I don’t +have access to the other platforms.</p> +</div></blockquote> +<p>Qingming He <<a class="reference external" href="mailto:906459647%40qq.com">906459647<span>@</span>qq<span>.</span>com</a>></p> +<blockquote> +<div><p>I’m mainly a Fortran developer and I use ctags combined with Emacs to +handle my projects. My goal is to improve the Fortran parser to make +it support Fortran standards from 77 to 2008 and maybe 2015 to be +released in the near future. I’m also interested in improving the lisp +parsers (elisp and scheme).</p> +</div></blockquote> +<p>Szymon Tomasz Stefanek <<a class="reference external" href="mailto:s.stefanek%40gmail.com">s<span>.</span>stefanek<span>@</span>gmail<span>.</span>com</a>></p> +<blockquote> +<div><p>I’m a multilanguage developer and I use ctags with my own text editor +which has some IDE capabilities. I’m the maintainer of the new C/C++ parser.</p> +</div></blockquote> +<p>Vitor Antunes <<a class="reference external" href="mailto:vitor.hda%40gmail.com">vitor<span>.</span>hda<span>@</span>gmail<span>.</span>com</a>></p> +<blockquote> +<div><p>I’ve been working with Verilog for most of the last 10 +years and am an avid Vim user. My goal is to improve the +Verilog parser such that Vim can get the most out of it +in plugins like Tagbar and to support the Omni +completion plugin I am writing.</p> +</div></blockquote> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="other-projects.html" + title="previous chapter">Relationship between other projects</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="other-projects.html" title="Relationship between other projects" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Who we are</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/extending.html b/ctags/docs/extending.html new file mode 100644 index 0000000..c334e39 --- /dev/null +++ b/ctags/docs/extending.html @@ -0,0 +1,157 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Extending ctags with a parser written in C — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Writing a parser in C" href="parser-in-c.html" /> + <link rel="prev" title="Optscript, a programming language for extending optlib parsers" href="optscript.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-in-c.html" title="Writing a parser in C" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="optscript.html" title="Optscript, a programming language for extending optlib parsers" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Extending ctags with a parser written in C</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="extending-ctags-with-a-parser-written-in-c"> +<span id="extending-ctags-in-c"></span><h1>Extending ctags with a parser written in C<a class="headerlink" href="#extending-ctags-with-a-parser-written-in-c" title="Permalink to this headline">¶</a></h1> +<p>This chapter describes how to add a parser in C and the internal API of +Universal Ctags.</p> +<p>Before you start writing a parser in C, consider using <em>optlib parser</em>. +Universal Ctags extends the functionality so extensively that it can implement +most of functionality for the parser. +See <a class="reference internal" href="man/ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> and <a class="reference internal" href="optlib.html#optlib"><span class="std std-ref">Extending ctags with Regex parser (optlib)</span></a> for details.</p> +<p><em>optlib parser</em> is also suitable for prototyping of a parser in C.</p> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="parser-in-c.html">Writing a parser in C</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-in-c.html#registering-a-parser">Registering a parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-in-c.html#reading-input-file-stream">Reading input file stream</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-in-c.html#parsing">Parsing</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-in-c.html#adding-a-tag-to-the-tag-file">Adding a tag to the tag file</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-in-c.html#adding-the-parser-to-ctags">Adding the parser to <code class="docutils literal notranslate"><span class="pre">ctags</span></code></a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-in-c.html#misc">Misc.</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="internal.html">Input text stream</a><ul> +<li class="toctree-l2"><a class="reference internal" href="internal.html#inputfile-type-and-the-functions-of-input-group"><cite>inputFile</cite> type and the functions of input group</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#the-functions-of-bypass-group">The functions of bypass group</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#the-functions-of-raw-group">The functions of raw group</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="internal.html#output-tag-stream">Output tag stream</a><ul> +<li class="toctree-l2"><a class="reference internal" href="internal.html#cork-api">cork API</a><ul> +<li class="toctree-l3"><a class="reference internal" href="internal.html#background-and-idea">Background and Idea</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#how-to-use">How to use</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#automatic-full-qualified-tag-generation">Automatic full qualified tag generation</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="internal.html#tokeninfo-api">tokenInfo API</a></li> +<li class="toctree-l1"><a class="reference internal" href="internal.html#multiple-parsers">Multiple parsers</a><ul> +<li class="toctree-l2"><a class="reference internal" href="internal.html#guest-parser-promise-api">Guest parser (promise API)</a><ul> +<li class="toctree-l3"><a class="reference internal" href="internal.html#id3">Background and Idea</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#usage">Usage</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#internal-design">Internal design</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#api-for-subparser">API for subparser</a><ul> +<li class="toctree-l3"><a class="reference internal" href="internal.html#outline">Outline</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#fields-of-subparser-type">Fields of <code class="docutils literal notranslate"><span class="pre">subparser</span></code> type</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#extending-subparser-type">Extending <code class="docutils literal notranslate"><span class="pre">subparser</span></code> type</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#making-a-tag-in-a-subparser">Making a tag in a subparser</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#calling-methods-of-subparsers-from-a-base-parser">Calling methods of subparsers from a base parser</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#registering-a-subparser-to-its-base-parser">Registering a subparser to its base parser</a></li> +<li class="toctree-l3"><a class="reference internal" href="internal.html#scheduling-running-the-base-parser">Scheduling running the base parser</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="internal.html#packcc-compiler-compiler">PackCC compiler-compiler</a></li> +<li class="toctree-l1"><a class="reference internal" href="internal.html#automatic-parser-guessing-tbw">Automatic parser guessing (TBW)</a></li> +<li class="toctree-l1"><a class="reference internal" href="internal.html#managing-regular-expression-parsers-tbw">Managing regular expression parsers (TBW)</a></li> +<li class="toctree-l1"><a class="reference internal" href="internal.html#ghost-kind-in-regex-parser-tbw">Ghost kind in regex parser (TBW)</a></li> +</ul> +</div> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="optscript.html" + title="previous chapter">Optscript, a programming language for extending optlib parsers</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-in-c.html" + title="next chapter">Writing a parser in C</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-in-c.html" title="Writing a parser in C" + >next</a> |</li> + <li class="right" > + <a href="optscript.html" title="Optscript, a programming language for extending optlib parsers" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Extending ctags with a parser written in C</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/genindex.html b/ctags/docs/genindex.html new file mode 100644 index 0000000..c9695da --- /dev/null +++ b/ctags/docs/genindex.html @@ -0,0 +1,80 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Index — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="#" /> + <link rel="search" title="Search" href="search.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="#" title="General Index" + accesskey="I">index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Index</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + +<h1 id="index">Index</h1> + +<div class="genindex-jumpbox"> + +</div> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="#" title="General Index" + >index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Index</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/index.html b/ctags/docs/index.html new file mode 100644 index 0000000..d849c9c --- /dev/null +++ b/ctags/docs/index.html @@ -0,0 +1,285 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Universal Ctags Hacking Guide — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Building ctags" href="building.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="building.html" title="Building ctags" + accesskey="N">next</a> |</li> + <li class="nav-item nav-item-0"><a href="#">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Universal Ctags Hacking Guide</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="universal-ctags-hacking-guide"> +<h1>Universal Ctags Hacking Guide<a class="headerlink" href="#universal-ctags-hacking-guide" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>Draft</p> +</dd> +<dt class="field-even">Authors</dt> +<dd class="field-even"><p>Universal Ctags developers</p> +</dd> +<dt class="field-odd">Web Page</dt> +<dd class="field-odd"><p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +</dd> +</dl> +<p><a class="reference external" href="https://ctags.io/">Universal Ctags</a> (abbreviated as u-ctags) is a <em>maintained</em> implementation of +<code class="docutils literal notranslate"><span class="pre">ctags</span></code>. +<code class="docutils literal notranslate"><span class="pre">ctags</span></code> generates an index (or tag) file of language objects found in source +files for programming languages. +This index makes it easy for text editors and other tools to locate the indexed +items.</p> +<p><a class="reference external" href="http://ctags.sourceforge.net/">Exuberant Ctags</a> (e-ctags) maintained by Darren Hiebert, the ancestor of +<a class="reference external" href="https://ctags.io/">Universal Ctags</a>, improved traditional ctags with multi-language support, the +ability for the user to define new languages searched by regular expressions +(called optlib in Universal Ctags), and the ability to generate emacs-style TAGS +files. +But the activity of the project unfortunately stalled.</p> +<p><a class="reference external" href="https://ctags.io/">Universal Ctags</a> has the objective of continuing the development of <a class="reference external" href="http://ctags.sourceforge.net/">Exuberant +Ctags</a>. +Reza Jelveh <<a class="reference external" href="mailto:reza.jelveh%40gmail.com">reza<span>.</span>jelveh<span>@</span>gmail<span>.</span>com</a>> initially created a personal fork of +<a class="reference external" href="http://ctags.sourceforge.net/">Exuberant Ctags</a> on GitHub. +As interest and participation grew, it was decided to move development to a +dedicated project as <a class="reference external" href="https://ctags.io/">Universal Ctags</a>. +The goal of this project is to maintain a common/unified working space where +people interested in making ctags better can work together.</p> +<p>Some of major features of <a class="reference external" href="https://ctags.io/">Universal Ctags</a> are;</p> +<ul class="simple"> +<li><dl class="simple"> +<dt>more numbers of improved language support</dt><dd><ul> +<li><p>new extended C/C++ language parser, etc.</p></li> +</ul> +</dd> +</dl> +</li> +<li><p>fully extended optlib (a feature to define a new language parser from a +command line)</p></li> +<li><p>interactive mode (experimental)</p></li> +</ul> +<p>The primary documents of <a class="reference external" href="https://ctags.io/">Universal Ctags</a> are man pages. Users should first +consult the <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, and <a class="reference internal" href="man-pages.html#man-pages"><span class="std std-ref">other man pages</span></a> if +necessary.</p> +<p>This guide, which also includes the man pages, is primarily for developers and +provides additional information to the man pages, including experimental +features.</p> +<p>This is a draft document. Proofreading and pull-requests are welcome!</p> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="building.html">Building ctags</a><ul> +<li class="toctree-l2"><a class="reference internal" href="autotools.html">Building with configure (*nix including GNU/Linux)</a></li> +<li class="toctree-l2"><a class="reference internal" href="windows.html">Building/hacking/using on MS-Windows</a></li> +<li class="toctree-l2"><a class="reference internal" href="osx.html">Building on Mac OS</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man-pages.html">Man pages</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html">ctags(1)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/tags.5.html">tags(5)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-optlib.7.html">ctags-optlib(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html">ctags-client-tools(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-faq.7.html">ctags-faq(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html">ctags-lang-iPythonCell(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-julia.7.html">ctags-lang-julia(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-python.7.html">ctags-lang-python(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-verilog.7.html">ctags-lang-verilog(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-inko.7.html">ctags-lang-inko(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-r.7.html">ctags-lang-r(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-sql.7.html">ctags-lang-sql(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-incompatibilities.7.html">ctags-incompatibilities(7)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html">readtags(1)</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="parsers.html">Parsers</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-asm.html">Asm parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-cmake.html">CMake parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-cxx.html">The new C/C++ parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-html.html">The new HTML parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-puppetManifest.html">puppetManifest parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-python.html">The new Python parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-tcl.html">The new Tcl parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-vim.html">The Vim parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-xslt.html">XSLT parser</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="option-file.html">Option files</a><ul> +<li class="toctree-l2"><a class="reference internal" href="option-file.html#order-of-loading-option-files">Order of loading option files</a></li> +<li class="toctree-l2"><a class="reference internal" href="option-file.html#options-pathname-option"><code class="docutils literal notranslate"><span class="pre">--options=PATHNAME</span></code> option</a></li> +<li class="toctree-l2"><a class="reference internal" href="option-file.html#tips-for-writing-an-option-file">Tips for writing an option file</a></li> +<li class="toctree-l2"><a class="reference internal" href="option-file.html#difference-from-exuberant-ctags">Difference from Exuberant Ctags</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="output-format.html">Output formats</a><ul> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html">Changes to the tags file format</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-xref.html">Xref output</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-json.html">JSON output</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="running-multi-parsers.html">Running multiple parsers on an input file</a><ul> +<li class="toctree-l2"><a class="reference internal" href="running-multi-parsers.html#guest-parser-applying-a-parser-to-specified-areas-of-input-file">Guest parser: Applying a parser to specified areas of input file</a></li> +<li class="toctree-l2"><a class="reference internal" href="running-multi-parsers.html#subparser-tagging-definitions-of-higher-upper-level-language">Subparser: Tagging definitions of higher (upper) level language</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="interactive-mode.html">Interactive mode</a><ul> +<li class="toctree-l2"><a class="reference internal" href="interactive-mode.html#generate-tags">generate-tags</a></li> +<li class="toctree-l2"><a class="reference internal" href="interactive-mode.html#sandbox-submode">sandbox submode</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="news.html">Other changes</a><ul> +<li class="toctree-l2"><a class="reference internal" href="news.html#new-and-extended-options">New and extended options</a></li> +<li class="toctree-l2"><a class="reference internal" href="news.html#incompatible-changes-in-command-line">Incompatible changes in command line</a></li> +<li class="toctree-l2"><a class="reference internal" href="news.html#changes-imported-from-exuberant-ctags">Changes imported from Exuberant Ctags</a></li> +<li class="toctree-l2"><a class="reference internal" href="news.html#parser-related-changes">Parser related changes</a></li> +<li class="toctree-l2"><a class="reference internal" href="news.html#readtags">Readtags</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="optlib.html">Extending ctags with Regex parser (<em>optlib</em>)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#regular-expression-regex-engine">Regular expression (regex) engine</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#regex-option-argument-flags">Regex option argument flags</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#overriding-the-letter-for-file-kind">Overriding the letter for file kind</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#generating-fully-qualified-tags-automatically-from-scope-information">Generating fully qualified tags automatically from scope information</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#multi-line-pattern-match">Multi-line pattern match</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#advanced-pattern-matching-with-multiple-regex-tables">Advanced pattern matching with multiple regex tables</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#scheduling-a-guest-parser-with-guest-regex-flag">Scheduling a guest parser with <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#defining-a-subparser">Defining a subparser</a></li> +<li class="toctree-l2"><a class="reference internal" href="optlib.html#translating-an-option-file-into-c-source-code-optlib2c">Translating an option file into C source code (optlib2c)</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="optscript.html">Optscript, a programming language for extending optlib parsers</a><ul> +<li class="toctree-l2"><a class="reference internal" href="optscript.html#preparation-for-learning">Preparation for learning</a></li> +<li class="toctree-l2"><a class="reference internal" href="optscript.html#syntax-extension">Syntax extension</a></li> +<li class="toctree-l2"><a class="reference internal" href="optscript.html#the-optscript-command">The <code class="docutils literal notranslate"><span class="pre">optscript</span></code> command</a></li> +<li class="toctree-l2"><a class="reference internal" href="optscript.html#optscript-in-ctags">Optscript in ctags</a></li> +<li class="toctree-l2"><a class="reference internal" href="optscript.html#recipes">Recipes</a></li> +<li class="toctree-l2"><a class="reference internal" href="optscript.html#difference-between-optscript-and-postscript">Difference between Optscript and PostScript</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="extending.html">Extending ctags with a parser written in C</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-in-c.html">Writing a parser in C</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html">Input text stream</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#output-tag-stream">Output tag stream</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#tokeninfo-api">tokenInfo API</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#multiple-parsers">Multiple parsers</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#packcc-compiler-compiler">PackCC compiler-compiler</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#automatic-parser-guessing-tbw">Automatic parser guessing (TBW)</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#managing-regular-expression-parsers-tbw">Managing regular expression parsers (TBW)</a></li> +<li class="toctree-l2"><a class="reference internal" href="internal.html#ghost-kind-in-regex-parser-tbw">Ghost kind in regex parser (TBW)</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="tips.html">Testing ctags</a><ul> +<li class="toctree-l2"><a class="reference internal" href="tips.html#tmain-a-facility-for-testing-main-part"><em>Tmain</em>: a facility for testing main part</a></li> +<li class="toctree-l2"><a class="reference internal" href="tips.html#tinst-installation-test"><em>Tinst</em>: installation test</a></li> +<li class="toctree-l2"><a class="reference internal" href="tips.html#fussy-syntax-checking">Fussy syntax checking</a></li> +<li class="toctree-l2"><a class="reference internal" href="tips.html#finding-performance-bottleneck">Finding performance bottleneck</a></li> +<li class="toctree-l2"><a class="reference internal" href="tips.html#checking-coverage">Checking coverage</a></li> +<li class="toctree-l2"><a class="reference internal" href="tips.html#running-cppcheck">Running cppcheck</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing a parser</a><ul> +<li class="toctree-l2"><a class="reference internal" href="testing.html#units-test-facility"><em>Units</em> test facility</a></li> +<li class="toctree-l2"><a class="reference internal" href="testing.html#reviewing-the-result-of-units-test">Reviewing the result of Units test</a></li> +<li class="toctree-l2"><a class="reference internal" href="testing.html#semi-fuzz-fuzz-testing">Semi-fuzz(<em>Fuzz</em>) testing</a></li> +<li class="toctree-l2"><a class="reference internal" href="testing.html#noise-testing"><em>Noise</em> testing</a></li> +<li class="toctree-l2"><a class="reference internal" href="testing.html#chop-and-slap-testing"><em>Chop</em> and <em>slap</em> testing</a></li> +<li class="toctree-l2"><a class="reference internal" href="testing.html#input-validation-for-units">Input validation for <em>Units</em></a></li> +<li class="toctree-l2"><a class="reference internal" href="testing.html#testing-examples-in-language-specific-man-pages">Testing examples in language specific man pages</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="reporting.html">Request for extending a parser (or Reporting a bug of parser)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="reporting.html#before-reporting">Before reporting</a></li> +<li class="toctree-l2"><a class="reference internal" href="reporting.html#the-content-of-report">The content of report</a></li> +<li class="toctree-l2"><a class="reference internal" href="reporting.html#an-example-of-good-report">An example of good report</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="contributions.html">Contributions</a><ul> +<li class="toctree-l2"><a class="reference internal" href="contributions.html#basic-rules">Basic rules</a></li> +<li class="toctree-l2"><a class="reference internal" href="contributions.html#before-you-start">Before You Start</a></li> +<li class="toctree-l2"><a class="reference internal" href="contributions.html#developing-a-parser">Developing a parser</a></li> +<li class="toctree-l2"><a class="reference internal" href="contributions.html#testing">Testing</a></li> +<li class="toctree-l2"><a class="reference internal" href="contributions.html#writing-documents">Writing Documents</a></li> +<li class="toctree-l2"><a class="reference internal" href="contributions.html#committing-and-submitting-a-pull-request">Committing and submitting a pull request</a></li> +<li class="toctree-l2"><a class="reference internal" href="contributions.html#rules-for-reviewing-a-pull-request">Rules for reviewing a pull request</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="other-projects.html">Relationship between other projects</a><ul> +<li class="toctree-l2"><a class="reference internal" href="other-projects.html#other-tagging-engines">Other tagging engines</a></li> +<li class="toctree-l2"><a class="reference internal" href="other-projects.html#software-using-ctags">Software using ctags</a></li> +<li class="toctree-l2"><a class="reference internal" href="other-projects.html#other-interesting-ctags-repositories">Other interesting ctags repositories</a></li> +<li class="toctree-l2"><a class="reference internal" href="other-projects.html#tracking-other-projects">Tracking other projects</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="developers.html">Who we are</a></li> +</ul> +</div> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Next topic</h4> + <p class="topless"><a href="building.html" + title="next chapter">Building ctags</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="building.html" title="Building ctags" + >next</a> |</li> + <li class="nav-item nav-item-0"><a href="#">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Universal Ctags Hacking Guide</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/interactive-mode.html b/ctags/docs/interactive-mode.html new file mode 100644 index 0000000..c580295 --- /dev/null +++ b/ctags/docs/interactive-mode.html @@ -0,0 +1,185 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Interactive mode — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Other changes" href="news.html" /> + <link rel="prev" title="Running multiple parsers on an input file" href="running-multi-parsers.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="news.html" title="Other changes" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="running-multi-parsers.html" title="Running multiple parsers on an input file" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Interactive mode</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="interactive-mode"> +<span id="id1"></span><h1>Interactive mode<a class="headerlink" href="#interactive-mode" title="Permalink to this headline">¶</a></h1> +<p>Universal Ctags can be run with <code class="docutils literal notranslate"><span class="pre">--_interactive</span></code>, which enters a REPL that +can be used programmatically to control ctags generation. In this mode, json +commands are received over stdin, and corresponding responses are emitted over +stdout.</p> +<p>This feature needs ctags to be built with json support and this requires libjansson to be installed +at build-time. If it’s supported it will be listed in the output of <code class="docutils literal notranslate"><span class="pre">--list-features</span></code>:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-features <span class="p">|</span> grep json +<span class="go">json</span> +</pre></div> +</div> +<p>Communication with Universal Ctags over stdio uses the <a class="reference external" href="http://jsonlines.org/">json lines</a> format, where each +json object appears on a single line and is terminated with a newline.</p> +<p>When <code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--_interactive</span></code> is invoked, it will emit a single json object to stdout announcing +its name and version. This signals the start of the interactive loop, and the user can begin sending +commands over stdin.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --_interactive +<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span> +</pre></div> +</div> +<p>The following commands are currently supported in interactive mode:</p> +<ul class="simple"> +<li><p><a class="reference internal" href="#generate-tags">generate-tags</a></p></li> +</ul> +<section id="generate-tags"> +<h2>generate-tags<a class="headerlink" href="#generate-tags" title="Permalink to this headline">¶</a></h2> +<p>The <code class="docutils literal notranslate"><span class="pre">generate-tags</span></code> command takes two arguments:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">filename</span></code>: name of the file to generate tags for (required)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">size</span></code>: size in bytes of the file, if the contents will be received over stdin (optional)</p></li> +</ul> +<p>The simplest way to generate tags for a file is by passing its path on filesystem(<code class="docutils literal notranslate"><span class="pre">file</span> <span class="pre">request</span></code>). The response will include +one json object per line representing each tag, followed by a single json object with the <code class="docutils literal notranslate"><span class="pre">completed</span></code> +field emitted once the file has been fully processed.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">echo</span> <span class="s1">'{"command":"generate-tags", "filename":"test.rb"}'</span> <span class="p">|</span> ctags --_interactive +<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span> +<span class="go">{"_type": "tag", "name": "foobar", "path": "test.rb", "pattern": "/^ def foobar$/", "kind": "method", "scope": "Test", "scopeKind": "class"}</span> +<span class="go">{"_type":"completed", "command": "generate-tags"}</span> +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">generate-tags</span></code> command can also be used to generate tags for code which is not present on filesystem(<code class="docutils literal notranslate"><span class="pre">inline</span> <span class="pre">request</span></code>). For example, +an IDE might want to generate ctags for an unsaved buffer while the user is editing code. When <code class="docutils literal notranslate"><span class="pre">size</span></code> is specified, +the corresponding number of bytes are read over stdin after the json object and newline.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="o">(</span> +<span class="go"> echo '{"command":"generate-tags", "filename":"test.rb", "size": 17}'</span> +<span class="go"> echo 'def foobaz() end'</span> +<span class="go">) | ctags --_interactive</span> +<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span> +<span class="go">{"_type": "tag", "name": "foobaz", "path": "test.rb", "pattern": "/^def foobaz() end$/", "kind": "method"}</span> +<span class="go">{"_type": "completed", "command": "generate-tags"}</span> +</pre></div> +</div> +</section> +<section id="sandbox-submode"> +<span id="id2"></span><h2>sandbox submode<a class="headerlink" href="#sandbox-submode" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">sandbox</span></code> submode can be used with <code class="docutils literal notranslate"><span class="pre">--_interactive=sandbox</span></code>. This +submode will activate a sandbox, to this limits the damage that the +can be achieved when exploiting a buffer overflow in Universal Ctags.</p> +<p>In the sandbox submode ctags can generate tags only for inline +requests because ctags has to use open system call to handle file +requests. The open system call is not allowed in the sandbox.</p> +<p>This feature uses <a class="reference external" href="https://www.kernel.org/doc/html/latest/userspace-api/seccomp_filter.html">Seccomp BPF (SECure COMPuting with filters)</a>, +and is only supported on Linux. To use the sandbox submode <a class="reference external" href="https://github.com/seccomp/libseccomp">libseccomp</a> is needed at build-time. If ctags was +built with seccomp support, <code class="docutils literal notranslate"><span class="pre">sandbox</span></code> is listed in the output of +<code class="docutils literal notranslate"><span class="pre">--list-features</span></code> option.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-features <span class="p">|</span> grep sandbox +<span class="go">sandbox</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="o">(</span> +<span class="go"> echo '{"command":"generate-tags", "filename":"test.rb", "size": 17}'</span> +<span class="go"> echo 'def foobaz() end'</span> +<span class="go">) | ctags --_interactive=sandbox</span> +<span class="go">{"_type": "program", "name": "Universal Ctags", "version": "0.0.0"}</span> +<span class="go">{"_type": "tag", "name": "foobaz", "path": "test.rb", "pattern": "/^def foobaz() end$/", "kind": "method"}</span> +<span class="go">{"_type": "completed", "command": "generate-tags"}</span> +</pre></div> +</div> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Interactive mode</a><ul> +<li><a class="reference internal" href="#generate-tags">generate-tags</a></li> +<li><a class="reference internal" href="#sandbox-submode">sandbox submode</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="running-multi-parsers.html" + title="previous chapter">Running multiple parsers on an input file</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="news.html" + title="next chapter">Other changes</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="news.html" title="Other changes" + >next</a> |</li> + <li class="right" > + <a href="running-multi-parsers.html" title="Running multiple parsers on an input file" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Interactive mode</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/internal.html b/ctags/docs/internal.html new file mode 100644 index 0000000..6767bc7 --- /dev/null +++ b/ctags/docs/internal.html @@ -0,0 +1,854 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Input text stream — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Testing ctags" href="tips.html" /> + <link rel="prev" title="Writing a parser in C" href="parser-in-c.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="tips.html" title="Testing ctags" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-in-c.html" title="Writing a parser in C" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="extending.html" accesskey="U">Extending ctags with a parser written in C</a> »</li> + <li class="nav-item nav-item-this"><a href="">Input text stream</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="input-text-stream"> +<span id="id1"></span><h1>Input text stream<a class="headerlink" href="#input-text-stream" title="Permalink to this headline">¶</a></h1> +<figure class="align-default"> +<a class="reference internal image-reference" href="_images/input-text-stream.svg"><img alt="_images/input-text-stream.svg" src="_images/input-text-stream.svg" /></a> +</figure> +<p>Function prototypes for handling input text stream are declared in +<code class="docutils literal notranslate"><span class="pre">main/read.h</span></code>. The file exists in Exuberant Ctags, too. However, the +names functions are changed when overhauling <code class="docutils literal notranslate"><span class="pre">--line-directive</span></code> +option. (In addition macros were converted to functions for making +data structures for the input text stream opaque.)</p> +<p>Ctags has 3 groups of functions for handling input: <em>input</em>, <em>bypass</em>, and +<em>raw</em>. Parser developers should use input group. The rest of two +are for ctags main part.</p> +<section id="inputfile-type-and-the-functions-of-input-group"> +<span id="inputfile"></span><h2><cite>inputFile</cite> type and the functions of input group<a class="headerlink" href="#inputfile-type-and-the-functions-of-input-group" title="Permalink to this headline">¶</a></h2> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>The original version of this section was written +before <code class="docutils literal notranslate"><span class="pre">inputFile</span></code> type and <code class="docutils literal notranslate"><span class="pre">File</span></code> variable are made private.</p> +</div> +<p><code class="docutils literal notranslate"><span class="pre">inputFile</span></code> is the type for representing the input file and stream for +a parser. It was declared in <code class="docutils literal notranslate"><span class="pre">main/read.h</span></code> but now it is defined in +<code class="docutils literal notranslate"><span class="pre">main/read.c</span></code>.</p> +<p>Ctags uses a file static variable <code class="docutils literal notranslate"><span class="pre">File</span></code> having type <code class="docutils literal notranslate"><span class="pre">inputFile</span></code> for +maintaining the input file and stream. <code class="docutils literal notranslate"><span class="pre">File</span></code> is also defined in +main/read.c as <code class="docutils literal notranslate"><span class="pre">inputFile</span></code> is.</p> +<p><code class="docutils literal notranslate"><span class="pre">fp</span></code> and <code class="docutils literal notranslate"><span class="pre">line</span></code> are the essential fields of <code class="docutils literal notranslate"><span class="pre">File</span></code>. <code class="docutils literal notranslate"><span class="pre">fp</span></code> having type +well known <code class="docutils literal notranslate"><span class="pre">MIO</span></code> declared in <code class="docutils literal notranslate"><span class="pre">main/mio.h</span></code>. By calling functions of input group +(<code class="docutils literal notranslate"><span class="pre">getcFromInputFile</span></code> and <code class="docutils literal notranslate"><span class="pre">readLineFromInputFile</span></code>), a parser gets input +text from <code class="docutils literal notranslate"><span class="pre">fp</span></code>.</p> +<p>The functions of input group updates fields <code class="docutils literal notranslate"><span class="pre">input</span></code> and <code class="docutils literal notranslate"><span class="pre">source</span></code> of <code class="docutils literal notranslate"><span class="pre">File</span></code> variable. +These two fields has type <code class="docutils literal notranslate"><span class="pre">inputFileInfo</span></code>. These two fields are for mainly +tracking the name of file and the current line number. Usually ctags uses +only <code class="docutils literal notranslate"><span class="pre">input</span></code> field. <code class="docutils literal notranslate"><span class="pre">source</span></code> field is used only when <code class="docutils literal notranslate"><span class="pre">#line</span></code> directive is found +in the current input text stream.</p> +<p>A case when a tool generates the input file from another file, a tool +can record the original source file to the generated file with using +the <code class="docutils literal notranslate"><span class="pre">#line</span></code> directive. <code class="docutils literal notranslate"><span class="pre">source</span></code> field is used for tracking/recording the +information appeared on <code class="docutils literal notranslate"><span class="pre">#line</span></code> directives.</p> +<p>Regex pattern matching are also done behind calling the functions of +this group.</p> +</section> +<section id="the-functions-of-bypass-group"> +<h2>The functions of bypass group<a class="headerlink" href="#the-functions-of-bypass-group" title="Permalink to this headline">¶</a></h2> +<p>The functions of bypass group (<code class="docutils literal notranslate"><span class="pre">readLineFromBypass</span></code> and +<code class="docutils literal notranslate"><span class="pre">readLineFromBypassSlow</span></code>) are used for reading text from <code class="docutils literal notranslate"><span class="pre">fp</span></code> field of +<code class="docutils literal notranslate"><span class="pre">File</span></code> static variable without updating <code class="docutils literal notranslate"><span class="pre">input</span></code> and <code class="docutils literal notranslate"><span class="pre">source</span></code> fields of +<code class="docutils literal notranslate"><span class="pre">File</span></code> variable.</p> +<p>Parsers may not need the functions of this group. The functions are +used in ctags main part. The functions are used to make pattern +fields of tags file, for example.</p> +</section> +<section id="the-functions-of-raw-group"> +<h2>The functions of raw group<a class="headerlink" href="#the-functions-of-raw-group" title="Permalink to this headline">¶</a></h2> +<p>The functions of this group (<code class="docutils literal notranslate"><span class="pre">readLineRaw</span></code> and <code class="docutils literal notranslate"><span class="pre">readLineRawWithNoSeek</span></code>) +take a parameter having type <code class="docutils literal notranslate"><span class="pre">MIO</span></code>; and don’t touch <code class="docutils literal notranslate"><span class="pre">File</span></code> static +variable.</p> +<p>Parsers may not need the functions of this group. The functions are +used in ctags main part. The functions are used to load option files, +for example.</p> +</section> +</section> +<section id="output-tag-stream"> +<span id="id2"></span><h1>Output tag stream<a class="headerlink" href="#output-tag-stream" title="Permalink to this headline">¶</a></h1> +<figure class="align-default"> +<a class="reference internal image-reference" href="_images/output-tag-stream.svg"><img alt="_images/output-tag-stream.svg" src="_images/output-tag-stream.svg" /></a> +</figure> +<p>Ctags provides <code class="docutils literal notranslate"><span class="pre">makeTagEntry</span></code> to parsers as an entry point for writing +tag information to MIO. <code class="docutils literal notranslate"><span class="pre">makeTagEntry</span></code> calls <code class="docutils literal notranslate"><span class="pre">writeTagEntry</span></code> if the +parser does not set <code class="docutils literal notranslate"><span class="pre">useCork</span></code> field. <code class="docutils literal notranslate"><span class="pre">writeTagEntry</span></code> calls <code class="docutils literal notranslate"><span class="pre">writerWriteTag</span></code>. +<code class="docutils literal notranslate"><span class="pre">writerWriteTag</span></code> just calls <code class="docutils literal notranslate"><span class="pre">writeEntry</span></code> of writer backends. +<code class="docutils literal notranslate"><span class="pre">writerTable</span></code> variable holds the four backends: ctagsWriter, etagsWriter, +xrefWriter, and jsonWriter. +One of them is chosen depending on the arguments passed to ctags.</p> +<p>If <code class="docutils literal notranslate"><span class="pre">useCork</span></code> is set, the tag information goes to a queue on memory. +The queue is flushed when <code class="docutils literal notranslate"><span class="pre">useCork</span></code> in unset. See “<a class="reference internal" href="#cork-api">cork API</a>” for more +details.</p> +<section id="cork-api"> +<h2>cork API<a class="headerlink" href="#cork-api" title="Permalink to this headline">¶</a></h2> +<section id="background-and-idea"> +<h3>Background and Idea<a class="headerlink" href="#background-and-idea" title="Permalink to this headline">¶</a></h3> +<p><em>cork API</em> is introduced for recording scope information easier.</p> +<p>Before introducing cork API, a scope information must be recorded as +strings. It is flexible but memory management is required. +Following code is taken from <code class="docutils literal notranslate"><span class="pre">clojure.c</span></code> (with some modifications).</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">vStringLength</span> <span class="p">(</span><span class="n">parent</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">current</span><span class="p">.</span><span class="n">extensionFields</span><span class="p">.</span><span class="n">scope</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">ClojureKinds</span><span class="p">[</span><span class="n">K_NAMESPACE</span><span class="p">].</span><span class="n">name</span><span class="p">;</span> + <span class="n">current</span><span class="p">.</span><span class="n">extensionFields</span><span class="p">.</span><span class="n">scope</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">vStringValue</span> <span class="p">(</span><span class="n">parent</span><span class="p">);</span> +<span class="p">}</span> + +<span class="n">makeTagEntry</span> <span class="p">(</span><span class="o">&</span><span class="n">current</span><span class="p">);</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">parent</span></code>, <code class="docutils literal notranslate"><span class="pre">scope</span> <span class="pre">[0]</span></code> and <code class="docutils literal notranslate"><span class="pre">scope</span> <span class="pre">[1]</span></code> are vStrings. The parser must manage +their life cycles; the parser cannot free them till the tag referring them via +its scope fields are emitted, and must free them after emitting.</p> +<p>cork API provides more solid way to hold scope information. cork API +expects <code class="docutils literal notranslate"><span class="pre">parent</span></code>, which represents scope of a tag(<code class="docutils literal notranslate"><span class="pre">current</span></code>) +currently parser dealing, is recorded to a <em>tags</em> file before recording +the <code class="docutils literal notranslate"><span class="pre">current</span></code> tag via <code class="docutils literal notranslate"><span class="pre">makeTagEntry</span></code> function.</p> +<p>For passing the information about <code class="docutils literal notranslate"><span class="pre">parent</span></code> to <code class="docutils literal notranslate"><span class="pre">makeTagEntry</span></code>, +<code class="docutils literal notranslate"><span class="pre">tagEntryInfo</span></code> object was created. It was used just for recording; and +freed after recording. In cork API, it is not freed after recording; +a parser can reused it as scope information.</p> +</section> +<section id="how-to-use"> +<h3>How to use<a class="headerlink" href="#how-to-use" title="Permalink to this headline">¶</a></h3> +<p>See a commit titled with “<a class="reference external" href="https://github.com/universal-ctags/ctags/commit/ef181e6">clojure: use cork</a>”. +I applied cork API to the clojure parser.</p> +<p>Cork API can be enabled and disabled per parser, +and is disabled by default. So there is no impact till you +enables it in your parser.</p> +<p><code class="docutils literal notranslate"><span class="pre">useCork</span></code> field is introduced in <code class="docutils literal notranslate"><span class="pre">parserDefinition</span></code> type:</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span> +<span class="p">...</span> + <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">useCork</span><span class="p">;</span> +<span class="p">...</span> +<span class="p">}</span> <span class="n">parserDefinition</span><span class="p">;</span> +</pre></div> +</div> +<p>Set <code class="docutils literal notranslate"><span class="pre">CORK_QUEUE</span></code> to <code class="docutils literal notranslate"><span class="pre">useCork</span></code> like:</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="n">parserDefinition</span> <span class="o">*</span><span class="nf">ClojureParser</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> +<span class="p">{</span> + <span class="p">...</span> + <span class="n">parserDefinition</span> <span class="o">*</span><span class="n">def</span> <span class="o">=</span> <span class="n">parserNew</span> <span class="p">(</span><span class="s">"Clojure"</span><span class="p">);</span> + <span class="p">...</span> + <span class="n">def</span><span class="o">-></span><span class="n">useCork</span> <span class="o">=</span> <span class="n">CORK_QUEUE</span><span class="p">;</span> + <span class="k">return</span> <span class="n">def</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>When ctags running a parser with <code class="docutils literal notranslate"><span class="pre">useCork</span></code> being <code class="docutils literal notranslate"><span class="pre">CORK_QUEUE</span></code>, all output +requested via <code class="docutils literal notranslate"><span class="pre">makeTagEntry</span></code> function calling is stored to an internal +queue, not to <code class="docutils literal notranslate"><span class="pre">tags</span></code> file. When parsing an input file is done, the +tag information stored automatically to the queue are flushed to +<code class="docutils literal notranslate"><span class="pre">tags</span></code> file in batch.</p> +<p>When calling <code class="docutils literal notranslate"><span class="pre">makeTagEntry</span></code> with a <code class="docutils literal notranslate"><span class="pre">tagEntryInfo</span></code> object (<code class="docutils literal notranslate"><span class="pre">parent</span></code>), +it returns an integer. The integer can be used as handle for referring +the object after calling.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span> <span class="n">parent</span> <span class="o">=</span> <span class="n">CORK_NIL</span><span class="p">;</span> +<span class="p">...</span> +<span class="n">parent</span> <span class="o">=</span> <span class="n">makeTagEntry</span> <span class="p">(</span><span class="o">&</span><span class="n">e</span><span class="p">);</span> +</pre></div> +</div> +<p>The handle can be used by setting to a <code class="docutils literal notranslate"><span class="pre">scopeIndex</span></code> +field of <code class="docutils literal notranslate"><span class="pre">current</span></code> tag, which is in the scope of <code class="docutils literal notranslate"><span class="pre">parent</span></code>.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">current</span><span class="p">.</span><span class="n">extensionFields</span><span class="p">.</span><span class="n">scopeIndex</span> <span class="o">=</span> <span class="n">parent</span><span class="p">;</span> +</pre></div> +</div> +<p>When passing <code class="docutils literal notranslate"><span class="pre">current</span></code> to <code class="docutils literal notranslate"><span class="pre">makeTagEntry</span></code>, the <code class="docutils literal notranslate"><span class="pre">scopeIndex</span></code> is +referred for emitting the scope information of <code class="docutils literal notranslate"><span class="pre">current</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">scopeIndex</span></code> must be set to <code class="docutils literal notranslate"><span class="pre">CORK_NIL</span></code> if a tag is not in any scope. +When using <code class="docutils literal notranslate"><span class="pre">scopeIndex</span></code> of <code class="docutils literal notranslate"><span class="pre">current</span></code>, <code class="docutils literal notranslate"><span class="pre">NULL</span></code> must be assigned to both +<code class="docutils literal notranslate"><span class="pre">current.extensionFields.scope[0]</span></code> and +<code class="docutils literal notranslate"><span class="pre">current.extensionFields.scope[1]</span></code>. <code class="docutils literal notranslate"><span class="pre">initTagEntry</span></code> function does this +initialization internally, so you generally you don’t have to write +the initialization explicitly.</p> +</section> +<section id="automatic-full-qualified-tag-generation"> +<h3>Automatic full qualified tag generation<a class="headerlink" href="#automatic-full-qualified-tag-generation" title="Permalink to this headline">¶</a></h3> +<p>If a parser uses the cork API for recording and emitting scope +information, ctags can reuse it for generating <em>full qualified (FQ) +tags</em>. Set <code class="docutils literal notranslate"><span class="pre">requestAutomaticFQTag</span></code> field of <code class="docutils literal notranslate"><span class="pre">parserDefinition</span></code> to +<code class="docutils literal notranslate"><span class="pre">TRUE</span></code> then the main part of ctags emits FQ tags on behalf of the parser +if <code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code> is given.</p> +<p>An example can be found in DTS parser:</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="n">parserDefinition</span><span class="o">*</span> <span class="nf">DTSParser</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">static</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="n">extensions</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="s">"dts"</span><span class="p">,</span> <span class="s">"dtsi"</span><span class="p">,</span> <span class="nb">NULL</span> <span class="p">};</span> + <span class="n">parserDefinition</span><span class="o">*</span> <span class="k">const</span> <span class="n">def</span> <span class="o">=</span> <span class="n">parserNew</span> <span class="p">(</span><span class="s">"DTS"</span><span class="p">);</span> + <span class="p">...</span> + <span class="n">def</span><span class="o">-></span><span class="n">requestAutomaticFQTag</span> <span class="o">=</span> <span class="n">TRUE</span><span class="p">;</span> + <span class="k">return</span> <span class="n">def</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Setting <code class="docutils literal notranslate"><span class="pre">requestAutomaticFQTag</span></code> to <code class="docutils literal notranslate"><span class="pre">TRUE</span></code> implies setting +<code class="docutils literal notranslate"><span class="pre">useCork</span></code> to <code class="docutils literal notranslate"><span class="pre">CORK_QUEUE</span></code>.</p> +</section> +</section> +</section> +<section id="tokeninfo-api"> +<span id="tokeninfo"></span><h1>tokenInfo API<a class="headerlink" href="#tokeninfo-api" title="Permalink to this headline">¶</a></h1> +<p>In Exuberant Ctags, a developer can write a parser anyway; only input +stream and tagEntryInfo data structure is given.</p> +<p>However, while maintaining Universal Ctags I (Masatake YAMATO) think +we should have a framework for writing parser. Of course the framework +is optional; you can still write a parser without the framework.</p> +<p>To design a framework, I have studied how @b4n (Colomban Wendling) +writes parsers. tokenInfo API is the first fruit of my study.</p> +<p>TBW</p> +</section> +<section id="multiple-parsers"> +<h1>Multiple parsers<a class="headerlink" href="#multiple-parsers" title="Permalink to this headline">¶</a></h1> +<section id="guest-parser-promise-api"> +<span id="promiseapi"></span><h2>Guest parser (promise API)<a class="headerlink" href="#guest-parser-promise-api" title="Permalink to this headline">¶</a></h2> +<p>See “<a class="reference internal" href="running-multi-parsers.html#host-guest-parsers"><span class="std std-ref">Guest parser: Applying a parser to specified areas of input file</span></a>” about the concept of guest parsers.</p> +<section id="id3"> +<h3>Background and Idea<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3> +<p>More than one programming languages can be used in one input text stream. +<em>promise API</em> allows a host parser running a <a class="reference internal" href="running-multi-parsers.html#host-guest-parsers"><span class="std std-ref">guest parser</span></a> in the specified area of input text stream.</p> +<p>e.g. Code written in c language (C code) is embedded +in code written in Yacc language (Yacc code). Let’s think about this +input stream.</p> +<div class="highlight-yacc notranslate"><div class="highlight"><pre><span></span>/* foo.y */ + %token + END_OF_FILE 0 + ERROR 255 + BELL 1 + + %{ + /* C language */ + int counter; + %} + %right EQUALS + %left PLUS MINUS + ... + %% + CfgFile : CfgEntryList + { InterpretConfigs($1); } + ; + + ... + %% + int + yyerror(char *s) + { + (void)fprintf(stderr,"%s: line %d of %s\n",s,lineNum, + (scanFile?scanFile:"(unknown)")); + if (scanStr) + (void)fprintf(stderr,"last scanned symbol is: %s\n",scanStr); + return 1; + } +</pre></div> +</div> +<p>In the input the area started from <code class="docutils literal notranslate"><span class="pre">%{</span></code> to <code class="docutils literal notranslate"><span class="pre">%}</span></code> and the area started from +the second <code class="docutils literal notranslate"><span class="pre">%%</span></code> to the end of file are written in C. Yacc can be called +<em>host language</em>, and C can be called <em>guest language</em>.</p> +<p>Ctags may choose the Yacc parser for the input. However, the parser +doesn’t know about C syntax. Implementing C parser in the Yacc parser +is one of approach. However, ctags has already C parser. The Yacc +parser should utilize the existing C parser. The promise API allows this.</p> +<p>See also “<a class="reference internal" href="running-multi-parsers.html#host-guest-parsers"><span class="std std-ref">Guest parser: Applying a parser to specified areas of input file</span></a>” about more concept and examples of the +guest parser.</p> +</section> +<section id="usage"> +<h3>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3> +<p>See a commit titled with “<a class="reference external" href="https://github.com/universal-ctags/ctags/commit/757673f">Yacc: run C parser in the areas where code +is written in C</a>”. +I applied promise API to the Yacc parser.</p> +<p>The parser for host language must track and record the <code class="docutils literal notranslate"><span class="pre">start</span></code> and the +<code class="docutils literal notranslate"><span class="pre">end</span></code> of a guest language. Pairs of <code class="docutils literal notranslate"><span class="pre">line</span> <span class="pre">number</span></code> and <code class="docutils literal notranslate"><span class="pre">byte</span> <span class="pre">offset</span></code> +represents the <code class="docutils literal notranslate"><span class="pre">start</span></code> and <code class="docutils literal notranslate"><span class="pre">end</span></code>. When the <code class="docutils literal notranslate"><span class="pre">start</span></code> and <code class="docutils literal notranslate"><span class="pre">end</span></code> are +fixed, call <code class="docutils literal notranslate"><span class="pre">makePromise</span></code> with (1) the guest parser name, (2) <code class="docutils literal notranslate"><span class="pre">start</span></code>, +and (3) <code class="docutils literal notranslate"><span class="pre">end</span></code>. (This description is a bit simplified the real usage.)</p> +<p>Let’s see the actual code from “<a class="reference external" href="https://github.com/universal-ctags/ctags/blob/master/parsers/yacc.c">parsers/yacc.c</a>”.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nc">cStart</span> <span class="p">{</span> + <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">input</span><span class="p">;</span> + <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">source</span><span class="p">;</span> +<span class="p">};</span> +</pre></div> +</div> +<p>Both fields are for recording <code class="docutils literal notranslate"><span class="pre">start</span></code>. <code class="docutils literal notranslate"><span class="pre">input</span></code> field +is for recording the value returned from <code class="docutils literal notranslate"><span class="pre">getInputLineNumber</span></code>. +<code class="docutils literal notranslate"><span class="pre">source</span></code> is for <code class="docutils literal notranslate"><span class="pre">getSourceLineNumber</span></code>. See “<a class="reference internal" href="#inputfile">inputFile</a>” for the +difference of the two.</p> +<p><code class="docutils literal notranslate"><span class="pre">enter_c_prologue</span></code> shown in the next is a function called when <code class="docutils literal notranslate"><span class="pre">%{</span></code> is +found in the current input text stream. Remember, in yacc syntax, <code class="docutils literal notranslate"><span class="pre">%{</span></code> +is a marker of C code area.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">void</span> <span class="nf">enter_c_prologue</span> <span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">line</span> <span class="n">CTAGS_ATTR_UNUSED</span><span class="p">,</span> + <span class="k">const</span> <span class="n">regexMatch</span> <span class="o">*</span><span class="n">matches</span> <span class="n">CTAGS_ATTR_UNUSED</span><span class="p">,</span> + <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">count</span> <span class="n">CTAGS_ATTR_UNUSED</span><span class="p">,</span> + <span class="kt">void</span> <span class="o">*</span><span class="n">data</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">struct</span> <span class="nc">cStart</span> <span class="o">*</span><span class="n">cstart</span> <span class="o">=</span> <span class="n">data</span><span class="p">;</span> + + + <span class="n">readLineFromInputFile</span> <span class="p">();</span> + <span class="n">cstart</span><span class="o">-></span><span class="n">input</span> <span class="o">=</span> <span class="n">getInputLineNumber</span> <span class="p">();</span> + <span class="n">cstart</span><span class="o">-></span><span class="n">source</span> <span class="o">=</span> <span class="n">getSourceLineNumber</span> <span class="p">();</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The function just records the start line. It calls +<code class="docutils literal notranslate"><span class="pre">readLineFromInputFile</span></code> because the C code may start the next line of +the line where the marker is.</p> +<p><code class="docutils literal notranslate"><span class="pre">leave_c_prologue</span></code> shown in the next is a function called when <code class="docutils literal notranslate"><span class="pre">%}</span></code>, +the end marker of C code area, is found in the current input text stream.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">void</span> <span class="nf">leave_c_prologue</span> <span class="p">(</span><span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">line</span> <span class="n">CTAGS_ATTR_UNUSED</span><span class="p">,</span> + <span class="k">const</span> <span class="n">regexMatch</span> <span class="o">*</span><span class="n">matches</span> <span class="n">CTAGS_ATTR_UNUSED</span><span class="p">,</span> + <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">count</span> <span class="n">CTAGS_ATTR_UNUSED</span><span class="p">,</span> + <span class="kt">void</span> <span class="o">*</span><span class="n">data</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">struct</span> <span class="nc">cStart</span> <span class="o">*</span><span class="n">cstart</span> <span class="o">=</span> <span class="n">data</span><span class="p">;</span> + <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">c_end</span><span class="p">;</span> + + <span class="n">c_end</span> <span class="o">=</span> <span class="n">getInputLineNumber</span> <span class="p">();</span> + <span class="n">makePromise</span> <span class="p">(</span><span class="s">"C"</span><span class="p">,</span> <span class="n">cstart</span><span class="o">-></span><span class="n">input</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">c_end</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">cstart</span><span class="o">-></span><span class="n">source</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>After recording the line number of the end of the C code area, +<code class="docutils literal notranslate"><span class="pre">leave_c_prologue</span></code> calls <code class="docutils literal notranslate"><span class="pre">makePromise</span></code>.</p> +<p>Of course <code class="docutils literal notranslate"><span class="pre">"C"</span></code> stands for C language, the name of guest parser. +Available parser names can be listed by running ctags with +<code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> option. In this example two <code class="docutils literal notranslate"><span class="pre">0</span></code> characters are provided as +the 3rd and 5th argument. They are byte offsets of the start and the end of the +C language area from the beginning of the line which is 0 in this case. In +general, the guest language’s section does not have to start at the beginning of +the line in which case the two offsets have to be provided. Compilers reading +the input character by character can obtain the current offset by calling +<code class="docutils literal notranslate"><span class="pre">getInputLineOffset()</span></code>.</p> +</section> +<section id="internal-design"> +<h3>Internal design<a class="headerlink" href="#internal-design" title="Permalink to this headline">¶</a></h3> +<figure class="align-default"> +<a class="reference internal image-reference" href="_images/promise.svg"><img alt="_images/promise.svg" src="_images/promise.svg" /></a> +</figure> +<p>A host parser cannot run a guest parser directly. What the host parser +can do is just asking the ctags main part scheduling of running the +guest parser for specified area which defined with the <code class="docutils literal notranslate"><span class="pre">start</span></code> and +<code class="docutils literal notranslate"><span class="pre">end</span></code>. These scheduling requests are called <em>promises</em>.</p> +<p>After running the host parser, before closing the input stream, the +ctags main part checks the existence of promise(s). If there is, the +main part makes a sub input stream and run the guest parser specified +in the promise. The sub input stream is made from the original input +stream by narrowing as requested in the promise. The main part +iterates the above process till there is no promise.</p> +<p>Theoretically a guest parser can be nested; it can make a promise. +The level 2 guest is also just scheduled. (However, I have never +tested such a nested guest parser).</p> +<p>Why not running the guest parser directly from the context of the host +parser? Remember many parsers have their own file static variables. If +a parser is called from the parser, the variables may be crashed.</p> +</section> +</section> +<section id="api-for-subparser"> +<h2>API for subparser<a class="headerlink" href="#api-for-subparser" title="Permalink to this headline">¶</a></h2> +<p>See “<a class="reference internal" href="running-multi-parsers.html#base-sub-parsers"><span class="std std-ref">Subparser: Tagging definitions of higher (upper) level language</span></a>” about the concept of subparser.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>Consider using optlib when implementing a subparser. It is much more +easy and simple. See “<a class="reference internal" href="optlib.html#defining-subparsers"><span class="std std-ref">Defining a subparser</span></a>” for details.</p> +</div> +<section id="outline"> +<h3>Outline<a class="headerlink" href="#outline" title="Permalink to this headline">¶</a></h3> +<p>You have to work on both sides: a base parser and subparsers.</p> +<p>A base parser must define a data structure type (<code class="docutils literal notranslate"><span class="pre">baseMethodTable</span></code>) for +its subparsers by extending <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">subparser</span></code> defined in +<code class="docutils literal notranslate"><span class="pre">main/subparser.h</span></code>. A subparser defines a variable (<code class="docutils literal notranslate"><span class="pre">subparser</span> <span class="pre">var</span></code>) +having type <code class="docutils literal notranslate"><span class="pre">baseMethodTable</span></code> by filling its fields and registers +<code class="docutils literal notranslate"><span class="pre">subparser</span> <span class="pre">var</span></code> to the base parser using dependency API.</p> +<p>The base parser calls functions pointed by <code class="docutils literal notranslate"><span class="pre">baseMethodTable</span></code> of +subparsers during parsing. A function for probing a higher level +language may be included in <code class="docutils literal notranslate"><span class="pre">baseMethodTable</span></code>. What kind of fields +should be included in <code class="docutils literal notranslate"><span class="pre">baseMethodTable</span></code> is up to the design of a base +parser and the requirements of its subparsers. A method for +probing is one of them.</p> +<p>Registering a <code class="docutils literal notranslate"><span class="pre">subparser</span> <span class="pre">var</span></code> to a base parser is enough for the +bottom up choice. For handling the top down choice (e.g. specifying +<code class="docutils literal notranslate"><span class="pre">--language-force=<subparser></span></code> in a command line), more code is needed.</p> +<p>In the top down choice, the subparser must call <code class="docutils literal notranslate"><span class="pre">scheduleRunningBasepaser</span></code>, +declared in <code class="docutils literal notranslate"><span class="pre">main/subparser.h</span></code>, in its <code class="docutils literal notranslate"><span class="pre">parser</span></code> method. +Here, <code class="docutils literal notranslate"><span class="pre">parser</span></code> method means a function assigned to the <code class="docutils literal notranslate"><span class="pre">parser</span></code> member of +the <code class="docutils literal notranslate"><span class="pre">parserDefinition</span></code> of the subparser. +<code class="docutils literal notranslate"><span class="pre">scheduleRunningBaseparser</span></code> takes an integer argument +that specifies the dependency used for registering the <code class="docutils literal notranslate"><span class="pre">subparser</span> <span class="pre">var</span></code>.</p> +<p>By extending <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">subparser</span></code> you can define a type for +your subparser. Then make a variable for the type and +declare a dependency on the base parser.</p> +</section> +<section id="fields-of-subparser-type"> +<h3>Fields of <code class="docutils literal notranslate"><span class="pre">subparser</span></code> type<a class="headerlink" href="#fields-of-subparser-type" title="Permalink to this headline">¶</a></h3> +<p>Here the source code of Autoconf/m4 parsers is referred as an example.</p> +<p><code class="docutils literal notranslate"><span class="pre">main/types.h</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nc">sSubparser</span><span class="p">;</span> +<span class="k">typedef</span> <span class="k">struct</span> <span class="nc">sSubparser</span> <span class="n">subparser</span><span class="p">;</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">main/subparser.h</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">enum</span> <span class="n">eSubparserRunDirection</span> <span class="p">{</span> + <span class="n">SUBPARSER_BASE_RUNS_SUB</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">,</span> + <span class="n">SUBPARSER_SUB_RUNS_BASE</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span><span class="p">,</span> + <span class="n">SUBPARSER_BI_DIRECTION</span> <span class="o">=</span> <span class="n">SUBPARSER_BASE_RUNS_SUB</span><span class="o">|</span><span class="n">SUBPARSER_SUB_RUNS_BASE</span><span class="p">,</span> +<span class="p">}</span> <span class="n">subparserRunDirection</span><span class="p">;</span> + +<span class="k">struct</span> <span class="nc">sSubparser</span> <span class="p">{</span> + <span class="p">...</span> + + <span class="cm">/* public to the parser */</span> + <span class="n">subparserRunDirection</span> <span class="n">direction</span><span class="p">;</span> + + <span class="kt">void</span> <span class="p">(</span><span class="o">*</span> <span class="n">inputStart</span><span class="p">)</span> <span class="p">(</span><span class="n">subparser</span> <span class="o">*</span><span class="n">s</span><span class="p">);</span> + <span class="kt">void</span> <span class="p">(</span><span class="o">*</span> <span class="n">inputEnd</span><span class="p">)</span> <span class="p">(</span><span class="n">subparser</span> <span class="o">*</span><span class="n">s</span><span class="p">);</span> + <span class="kt">void</span> <span class="p">(</span><span class="o">*</span> <span class="n">exclusiveSubparserChosenNotify</span><span class="p">)</span> <span class="p">(</span><span class="n">subparser</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">data</span><span class="p">);</span> +<span class="p">};</span> +</pre></div> +</div> +<p>A subparser must fill the fields of <code class="docutils literal notranslate"><span class="pre">subparser</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">direction</span></code> field specifies how the subparser is called. See +“<a class="reference internal" href="running-multi-parsers.html#multiple-parsers-directions"><span class="std std-ref">Direction flags</span></a>” in “<a class="reference internal" href="running-multi-parsers.html#multiple-parsers"><span class="std std-ref">Running multiple parsers on an input file</span></a>” about +<em>direction flags</em>, and see “<a class="reference internal" href="optlib.html#optlib-directions"><span class="std std-ref">Direction flags</span></a>” in “<a class="reference internal" href="optlib.html#optlib"><span class="std std-ref">Extending ctags with Regex parser (optlib)</span></a>” for +examples of using the direction flags.</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 55%" /> +<col style="width: 45%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p><code class="docutils literal notranslate"><span class="pre">direction</span></code> field</p></th> +<th class="head"><p>Direction Flag</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SUBPARSER_BASE_RUNS_SUB</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">shared</span></code> (default)</p></td> +</tr> +<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">SUBPARSER_SUB_RUNS_BASE</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">dedicated</span></code></p></td> +</tr> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">SUBPARSER_BI_DIRECTION</span></code></p></td> +<td><p><code class="docutils literal notranslate"><span class="pre">bidirectional</span></code></p></td> +</tr> +</tbody> +</table> +<p>If a subparser runs exclusively and is chosen in top down way, set +<code class="docutils literal notranslate"><span class="pre">SUBPARSER_SUB_RUNS_BASE</span></code> flag. If a subparser runs coexisting way and +is chosen in bottom up way, set <code class="docutils literal notranslate"><span class="pre">SUBPARSER_BASE_RUNS_SUB</span></code>. Use +<code class="docutils literal notranslate"><span class="pre">SUBPARSER_BI_DIRECTION</span></code> if both cases can be considered.</p> +<p>SystemdUnit parser runs as a subparser of iniconf base parser. +SystemdUnit parser specifies <code class="docutils literal notranslate"><span class="pre">SUBPARSER_SUB_RUNS_BASE</span></code> because +unit files of systemd have very specific file extensions though +they are written in iniconf syntax. Therefore we expect SystemdUnit +parser is chosen in top down way. The same logic is applicable to +YumRepo parser.</p> +<p>Autoconf parser specifies <code class="docutils literal notranslate"><span class="pre">SUBPARSER_BI_DIRECTION</span></code>. For input +file having name <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code>, by pattern matching, Autoconf parser +is chosen in top down way. In other hand, for file name <code class="docutils literal notranslate"><span class="pre">foo.m4</span></code>, +Autoconf parser can be chosen in bottom up way.</p> +<p><code class="docutils literal notranslate"><span class="pre">inputStart</span></code> is called before the base parser starting parsing a new input file. +<code class="docutils literal notranslate"><span class="pre">inputEnd</span></code> is called after the base parser finishing parsing the input file. +Universal Ctags main part calls these methods. Therefore, a base parser doesn’t +have to call them.</p> +<p><code class="docutils literal notranslate"><span class="pre">exclusiveSubparserChosenNotify</span></code> is called when a parser is chosen +as an exclusive parser. Calling this method is a job of a base parser.</p> +</section> +<section id="extending-subparser-type"> +<h3>Extending <code class="docutils literal notranslate"><span class="pre">subparser</span></code> type<a class="headerlink" href="#extending-subparser-type" title="Permalink to this headline">¶</a></h3> +<p>The m4 parser extends <code class="docutils literal notranslate"><span class="pre">subparser</span></code> type like following:</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/m4.h</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">struct</span> <span class="nc">sM4Subparser</span> <span class="n">m4Subparser</span><span class="p">;</span> +<span class="k">struct</span> <span class="nc">sM4Subparser</span> <span class="p">{</span> + <span class="n">subparser</span> <span class="n">subparser</span><span class="p">;</span> + + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span> <span class="n">probeLanguage</span><span class="p">)</span> <span class="p">(</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">token</span><span class="p">);</span> + + <span class="cm">/* return value: Cork index */</span> + <span class="kt">int</span> <span class="p">(</span><span class="o">*</span> <span class="n">newMacroNotify</span><span class="p">)</span> <span class="p">(</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">token</span><span class="p">);</span> + + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span> <span class="n">doesLineCommentStart</span><span class="p">)</span> <span class="p">(</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4</span><span class="p">,</span> <span class="kt">int</span> <span class="n">c</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">token</span><span class="p">);</span> + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span> <span class="n">doesStringLiteralStart</span><span class="p">)</span> <span class="p">(</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4</span><span class="p">,</span> <span class="kt">int</span> <span class="n">c</span><span class="p">);</span> +<span class="p">};</span> +</pre></div> +</div> +<p>Put <code class="docutils literal notranslate"><span class="pre">subparser</span></code> as the first member of the extended struct (here sM4Subparser). +In addition the first field, 4 methods are defined in the extended struct.</p> +<p>Till choosing a subparser for the current input file, the m4 parser calls +<code class="docutils literal notranslate"><span class="pre">probeLanguage</span></code> method of its subparsers each time when find a token +in the input file. A subparser returns <code class="docutils literal notranslate"><span class="pre">true</span></code> if it recognizes the +input file is for the itself by analyzing tokens passed from the +base parser.</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/autoconf.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="n">parserDefinition</span><span class="o">*</span> <span class="nf">AutoconfParser</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">static</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="n">patterns</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="s">"configure.in"</span><span class="p">,</span> <span class="nb">NULL</span> <span class="p">};</span> + <span class="k">static</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="n">extensions</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="s">"ac"</span><span class="p">,</span> <span class="nb">NULL</span> <span class="p">};</span> + <span class="n">parserDefinition</span><span class="o">*</span> <span class="k">const</span> <span class="n">def</span> <span class="o">=</span> <span class="n">parserNew</span><span class="p">(</span><span class="s">"Autoconf"</span><span class="p">);</span> + + <span class="k">static</span> <span class="n">m4Subparser</span> <span class="n">autoconfSubparser</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">.</span><span class="n">subparser</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">.</span><span class="n">direction</span> <span class="o">=</span> <span class="n">SUBPARSER_BI_DIRECTION</span><span class="p">,</span> + <span class="p">.</span><span class="n">exclusiveSubparserChosenNotify</span> <span class="o">=</span> <span class="n">exclusiveSubparserChosenCallback</span><span class="p">,</span> + <span class="p">},</span> + <span class="p">.</span><span class="n">probeLanguage</span> <span class="o">=</span> <span class="n">probeLanguage</span><span class="p">,</span> + <span class="p">.</span><span class="n">newMacroNotify</span> <span class="o">=</span> <span class="n">newMacroCallback</span><span class="p">,</span> + <span class="p">.</span><span class="n">doesLineCommentStart</span> <span class="o">=</span> <span class="n">doesLineCommentStart</span><span class="p">,</span> + <span class="p">.</span><span class="n">doesStringLiteralStart</span> <span class="o">=</span> <span class="n">doesStringLiteralStart</span><span class="p">,</span> + <span class="p">};</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">probeLanguage</span></code> function defined in <code class="docutils literal notranslate"><span class="pre">autoconf.c</span></code> is connected to +the <code class="docutils literal notranslate"><span class="pre">probeLanguage</span></code> member of <code class="docutils literal notranslate"><span class="pre">autoconfSubparser</span></code>. The <code class="docutils literal notranslate"><span class="pre">probeLanguage</span></code> function +of Autoconf is very simple:</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/autoconf.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">bool</span> <span class="nf">probeLanguage</span> <span class="p">(</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">token</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">return</span> <span class="n">strncmp</span> <span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="s">"m4_"</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> + <span class="o">||</span> <span class="n">strncmp</span> <span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="s">"AC_"</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> + <span class="o">||</span> <span class="n">strncmp</span> <span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="s">"AM_"</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> + <span class="o">||</span> <span class="n">strncmp</span> <span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="s">"AS_"</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> + <span class="o">||</span> <span class="n">strncmp</span> <span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="s">"AH_"</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span> + <span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>This function checks the prefix of passed tokens. If known +prefix is found, Autoconf assumes this is an Autoconf input +and returns <code class="docutils literal notranslate"><span class="pre">true</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/m4.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">m4tmp</span><span class="o">-></span><span class="n">probeLanguage</span> + <span class="o">&&</span> <span class="n">m4tmp</span><span class="o">-></span><span class="n">probeLanguage</span> <span class="p">(</span><span class="n">m4tmp</span><span class="p">,</span> <span class="n">token</span><span class="p">))</span> +<span class="p">{</span> + <span class="n">chooseExclusiveSubparser</span> <span class="p">((</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="p">)</span><span class="n">tmp</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> + <span class="n">m4found</span> <span class="o">=</span> <span class="n">m4tmp</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The m4 parsers calls <code class="docutils literal notranslate"><span class="pre">probeLanguage</span></code> function of a subparser. If <code class="docutils literal notranslate"><span class="pre">true</span></code> +is returned <code class="docutils literal notranslate"><span class="pre">chooseExclusiveSubparser</span></code> function which is defined +in the main part. <code class="docutils literal notranslate"><span class="pre">chooseExclusiveSubparser</span></code> calls +<code class="docutils literal notranslate"><span class="pre">exclusiveSubparserChosenNotify</span></code> method of the chosen subparser.</p> +<p>The method is implemented in Autoconf subparser like following:</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/autoconf.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">void</span> <span class="nf">exclusiveSubparserChosenCallback</span> <span class="p">(</span><span class="n">subparser</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">data</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">setM4Quotes</span> <span class="p">(</span><span class="sc">'['</span><span class="p">,</span> <span class="sc">']'</span><span class="p">);</span> +<span class="p">}</span> +</pre></div> +</div> +<p>It changes quote characters of the m4 parser.</p> +</section> +<section id="making-a-tag-in-a-subparser"> +<h3>Making a tag in a subparser<a class="headerlink" href="#making-a-tag-in-a-subparser" title="Permalink to this headline">¶</a></h3> +<p>Via calling callback functions defined in subparsers, their base parser +gives chance to them making tag entries.</p> +<p>The m4 parser calls <code class="docutils literal notranslate"><span class="pre">newMacroNotify</span></code> method when it finds an m4 macro is used. +The Autoconf parser connects <code class="docutils literal notranslate"><span class="pre">newMacroCallback</span></code> function defined in <code class="docutils literal notranslate"><span class="pre">parser/autoconf.c</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/autoconf.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span> <span class="nf">newMacroCallback</span> <span class="p">(</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">token</span><span class="p">)</span> +<span class="p">{</span> + <span class="kt">int</span> <span class="n">keyword</span><span class="p">;</span> + <span class="kt">int</span> <span class="n">index</span> <span class="o">=</span> <span class="n">CORK_NIL</span><span class="p">;</span> + + <span class="n">keyword</span> <span class="o">=</span> <span class="n">lookupKeyword</span> <span class="p">(</span><span class="n">token</span><span class="p">,</span> <span class="n">getInputLanguage</span> <span class="p">());</span> + + <span class="cm">/* TODO:</span> +<span class="cm"> AH_VERBATIM</span> +<span class="cm"> */</span> + <span class="k">switch</span> <span class="p">(</span><span class="n">keyword</span><span class="p">)</span> + <span class="p">{</span> + <span class="k">case</span> <span class="nl">KEYWORD_NONE</span><span class="p">:</span> + <span class="k">break</span><span class="p">;</span> + <span class="k">case</span> <span class="nl">KEYWORD_init</span><span class="p">:</span> + <span class="n">index</span> <span class="o">=</span> <span class="n">makeAutoconfTag</span> <span class="p">(</span><span class="n">PACKAGE_KIND</span><span class="p">);</span> + <span class="k">break</span><span class="p">;</span> + +<span class="p">...</span> + +<span class="k">extern</span> <span class="n">parserDefinition</span><span class="o">*</span> <span class="n">AutoconfParser</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> +<span class="p">{</span> + <span class="p">...</span> + <span class="k">static</span> <span class="n">m4Subparser</span> <span class="n">autoconfSubparser</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">.</span><span class="n">subparser</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">.</span><span class="n">direction</span> <span class="o">=</span> <span class="n">SUBPARSER_BI_DIRECTION</span><span class="p">,</span> + <span class="p">.</span><span class="n">exclusiveSubparserChosenNotify</span> <span class="o">=</span> <span class="n">exclusiveSubparserChosenCallback</span><span class="p">,</span> + <span class="p">},</span> + <span class="p">.</span><span class="n">probeLanguage</span> <span class="o">=</span> <span class="n">probeLanguage</span><span class="p">,</span> + <span class="p">.</span><span class="n">newMacroNotify</span> <span class="o">=</span> <span class="n">newMacroCallback</span><span class="p">,</span> +</pre></div> +</div> +<p>In <code class="docutils literal notranslate"><span class="pre">newMacroCallback</span></code> function, the Autoconf parser receives the name of macro +found by the base parser and analysis whether the macro is interesting +in the context of Autoconf language or not. If it is interesting name, +the Autoconf parser makes a tag for it.</p> +</section> +<section id="calling-methods-of-subparsers-from-a-base-parser"> +<h3>Calling methods of subparsers from a base parser<a class="headerlink" href="#calling-methods-of-subparsers-from-a-base-parser" title="Permalink to this headline">¶</a></h3> +<p>A base parser can use <code class="docutils literal notranslate"><span class="pre">foreachSubparser</span></code> macro for accessing its +subparsers. A base should call <code class="docutils literal notranslate"><span class="pre">enterSubparser</span></code> before calling a +method of a subparser, and call <code class="docutils literal notranslate"><span class="pre">leaveSubparser</span></code> after calling the +method. The macro and functions are declare in <code class="docutils literal notranslate"><span class="pre">main/subparser.h</span></code> .</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/m4.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="n">m4Subparser</span> <span class="o">*</span> <span class="nf">maySwitchLanguage</span> <span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span> <span class="n">token</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">subparser</span> <span class="o">*</span><span class="n">tmp</span><span class="p">;</span> + <span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4found</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span> + + <span class="n">foreachSubparser</span> <span class="p">(</span><span class="n">tmp</span><span class="p">,</span> <span class="nb">false</span><span class="p">)</span> + <span class="p">{</span> + <span class="n">m4Subparser</span> <span class="o">*</span><span class="n">m4tmp</span> <span class="o">=</span> <span class="p">(</span><span class="n">m4Subparser</span> <span class="o">*</span><span class="p">)</span><span class="n">tmp</span><span class="p">;</span> + + <span class="n">enterSubparser</span><span class="p">(</span><span class="n">tmp</span><span class="p">);</span> + <span class="k">if</span> <span class="p">(</span><span class="n">m4tmp</span><span class="o">-></span><span class="n">probeLanguage</span> + <span class="o">&&</span> <span class="n">m4tmp</span><span class="o">-></span><span class="n">probeLanguage</span> <span class="p">(</span><span class="n">m4tmp</span><span class="p">,</span> <span class="n">token</span><span class="p">))</span> + <span class="p">{</span> + <span class="n">chooseExclusiveSubparser</span> <span class="p">(</span><span class="n">tmp</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">);</span> + <span class="n">m4found</span> <span class="o">=</span> <span class="n">m4tmp</span><span class="p">;</span> + <span class="p">}</span> + <span class="n">leaveSubparser</span><span class="p">();</span> + + <span class="k">if</span> <span class="p">(</span><span class="n">m4found</span><span class="p">)</span> + <span class="k">break</span><span class="p">;</span> + <span class="p">}</span> + + <span class="k">return</span> <span class="n">m4found</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">foreachSubparser</span></code> takes a variable having type <code class="docutils literal notranslate"><span class="pre">subparser</span></code>. +For each iteration, the value for the variable is updated.</p> +<p><code class="docutils literal notranslate"><span class="pre">enterSubparser</span></code> takes a variable having type <code class="docutils literal notranslate"><span class="pre">subparser</span></code>. With the +calling <code class="docutils literal notranslate"><span class="pre">enterSubparser</span></code>, the current language (the value returned from +<code class="docutils literal notranslate"><span class="pre">getInputLanguage</span></code>) can be temporary switched to the language specified +with the variable. One of the effect of switching is that <code class="docutils literal notranslate"><span class="pre">language</span></code> +field of tags made in the callback function called between +<code class="docutils literal notranslate"><span class="pre">enterSubparser</span></code> and <code class="docutils literal notranslate"><span class="pre">leaveSubparser</span></code> is adjusted.</p> +</section> +<section id="registering-a-subparser-to-its-base-parser"> +<h3>Registering a subparser to its base parser<a class="headerlink" href="#registering-a-subparser-to-its-base-parser" title="Permalink to this headline">¶</a></h3> +<p>Use <code class="docutils literal notranslate"><span class="pre">DEPTYPE_SUBPARSER</span></code> dependency in a subparser for registration.</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/autoconf.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="n">parserDefinition</span><span class="o">*</span> <span class="nf">AutoconfParser</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">parserDefinition</span><span class="o">*</span> <span class="k">const</span> <span class="n">def</span> <span class="o">=</span> <span class="n">parserNew</span><span class="p">(</span><span class="s">"Autoconf"</span><span class="p">);</span> + + <span class="k">static</span> <span class="n">m4Subparser</span> <span class="n">autoconfSubparser</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">.</span><span class="n">subparser</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">.</span><span class="n">direction</span> <span class="o">=</span> <span class="n">SUBPARSER_BI_DIRECTION</span><span class="p">,</span> + <span class="p">.</span><span class="n">exclusiveSubparserChosenNotify</span> <span class="o">=</span> <span class="n">exclusiveSubparserChosenCallback</span><span class="p">,</span> + <span class="p">},</span> + <span class="p">.</span><span class="n">probeLanguage</span> <span class="o">=</span> <span class="n">probeLanguage</span><span class="p">,</span> + <span class="p">.</span><span class="n">newMacroNotify</span> <span class="o">=</span> <span class="n">newMacroCallback</span><span class="p">,</span> + <span class="p">.</span><span class="n">doesLineCommentStart</span> <span class="o">=</span> <span class="n">doesLineCommentStart</span><span class="p">,</span> + <span class="p">.</span><span class="n">doesStringLiteralStart</span> <span class="o">=</span> <span class="n">doesStringLiteralStart</span><span class="p">,</span> + <span class="p">};</span> + <span class="k">static</span> <span class="n">parserDependency</span> <span class="n">dependencies</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">DEPTYPE_SUBPARSER</span><span class="p">,</span> <span class="s">"M4"</span><span class="p">,</span> <span class="o">&</span><span class="n">autoconfSubparser</span> <span class="p">},</span> + <span class="p">};</span> + + <span class="n">def</span><span class="o">-></span><span class="n">dependencies</span> <span class="o">=</span> <span class="n">dependencies</span><span class="p">;</span> + <span class="n">def</span><span class="o">-></span><span class="n">dependencyCount</span> <span class="o">=</span> <span class="n">ARRAY_SIZE</span> <span class="p">(</span><span class="n">dependencies</span><span class="p">);</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">DEPTYPE_SUBPARSER</span></code> is specified in the 0th element of <code class="docutils literal notranslate"><span class="pre">dependencies</span></code> +function static variable. In the next a literal string “M4” is +specified and <code class="docutils literal notranslate"><span class="pre">autoconfSubparser</span></code> follows. The intent of the code is +registering <code class="docutils literal notranslate"><span class="pre">autoconfSubparser</span></code> subparser definition to a base parser +named “M4”.</p> +<p><code class="docutils literal notranslate"><span class="pre">dependencies</span></code> function static variable must be assigned to +<code class="docutils literal notranslate"><span class="pre">dependencies</span></code> fields of a variable of <code class="docutils literal notranslate"><span class="pre">parserDefinition</span></code>. +The main part of Universal Ctags refers the field when +initializing parsers.</p> +<p><code class="docutils literal notranslate"><span class="pre">[0]</span></code> emphasizes this is “the 0th element”. The subparser may refer +the index of the array when the subparser calls +<code class="docutils literal notranslate"><span class="pre">scheduleRunningBaseparser</span></code>.</p> +</section> +<section id="scheduling-running-the-base-parser"> +<h3>Scheduling running the base parser<a class="headerlink" href="#scheduling-running-the-base-parser" title="Permalink to this headline">¶</a></h3> +<p>For the case that a subparser is chosen in top down, the subparser +must call <code class="docutils literal notranslate"><span class="pre">scheduleRunningBaseparser</span></code> in the main <code class="docutils literal notranslate"><span class="pre">parser</span></code> method.</p> +<p><code class="docutils literal notranslate"><span class="pre">parsers/autoconf.c</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">void</span> <span class="nf">findAutoconfTags</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> +<span class="p">{</span> + <span class="n">scheduleRunningBaseparser</span> <span class="p">(</span><span class="mi">0</span><span class="p">);</span> +<span class="p">}</span> + +<span class="k">extern</span> <span class="n">parserDefinition</span><span class="o">*</span> <span class="nf">AutoconfParser</span> <span class="p">(</span><span class="kt">void</span><span class="p">)</span> +<span class="p">{</span> + <span class="p">...</span> + <span class="n">parserDefinition</span><span class="o">*</span> <span class="k">const</span> <span class="n">def</span> <span class="o">=</span> <span class="n">parserNew</span><span class="p">(</span><span class="s">"Autoconf"</span><span class="p">);</span> + <span class="p">...</span> + <span class="k">static</span> <span class="n">parserDependency</span> <span class="n">dependencies</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> + <span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">DEPTYPE_SUBPARSER</span><span class="p">,</span> <span class="s">"M4"</span><span class="p">,</span> <span class="o">&</span><span class="n">autoconfSubparser</span> <span class="p">},</span> + <span class="p">};</span> + + <span class="n">def</span><span class="o">-></span><span class="n">dependencies</span> <span class="o">=</span> <span class="n">dependencies</span><span class="p">;</span> + <span class="p">...</span> + <span class="n">def</span><span class="o">-></span><span class="n">parser</span> <span class="o">=</span> <span class="n">findAutoconfTags</span><span class="p">;</span> + <span class="p">...</span> + <span class="k">return</span> <span class="n">def</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>A subparser can do nothing actively. A base parser makes its subparser +work by calling methods of the subparser. Therefore a subparser must +run its base parser when the subparser is chosen in a top down way, +The main part prepares <code class="docutils literal notranslate"><span class="pre">scheduleRunningBaseparser</span></code> function for the purpose.</p> +<p>A subparser should call the function from <code class="docutils literal notranslate"><span class="pre">parser</span></code> method of <code class="docutils literal notranslate"><span class="pre">parserDefinition</span></code> +of the subparser. <code class="docutils literal notranslate"><span class="pre">scheduleRunningBaseparser</span></code> takes an integer. It specifies +an index of the dependency which is used for registering the subparser.</p> +</section> +</section> +</section> +<section id="packcc-compiler-compiler"> +<h1>PackCC compiler-compiler<a class="headerlink" href="#packcc-compiler-compiler" title="Permalink to this headline">¶</a></h1> +<p>PackCC is a compiler-compiler; it translates <code class="docutils literal notranslate"><span class="pre">.peg</span></code> grammar file to <code class="docutils literal notranslate"><span class="pre">.c</span></code> +file. PackCC was originally written by Arihiro Yoshida. Its source +repository is at <a class="reference external" href="https://github.com/arithy/packcc">https://github.com/arithy/packcc</a>.</p> +<p>The source tree of PackCC is grafted at <code class="docutils literal notranslate"><span class="pre">misc/packcc</span></code> directory. +Building PackCC and ctags are integrated in the build-scripts of +Universal Ctags.</p> +<p>Refer <a class="reference external" href="https://github.com/universal-ctags/ctags/blob/master/peg/varlink.peg">peg/valink.peg</a> as a +sample of a parser using PackCC.</p> +</section> +<section id="automatic-parser-guessing-tbw"> +<h1>Automatic parser guessing (TBW)<a class="headerlink" href="#automatic-parser-guessing-tbw" title="Permalink to this headline">¶</a></h1> +</section> +<section id="managing-regular-expression-parsers-tbw"> +<h1>Managing regular expression parsers (TBW)<a class="headerlink" href="#managing-regular-expression-parsers-tbw" title="Permalink to this headline">¶</a></h1> +</section> +<section id="ghost-kind-in-regex-parser-tbw"> +<h1>Ghost kind in regex parser (TBW)<a class="headerlink" href="#ghost-kind-in-regex-parser-tbw" title="Permalink to this headline">¶</a></h1> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Input text stream</a><ul> +<li><a class="reference internal" href="#inputfile-type-and-the-functions-of-input-group"><cite>inputFile</cite> type and the functions of input group</a></li> +<li><a class="reference internal" href="#the-functions-of-bypass-group">The functions of bypass group</a></li> +<li><a class="reference internal" href="#the-functions-of-raw-group">The functions of raw group</a></li> +</ul> +</li> +<li><a class="reference internal" href="#output-tag-stream">Output tag stream</a><ul> +<li><a class="reference internal" href="#cork-api">cork API</a><ul> +<li><a class="reference internal" href="#background-and-idea">Background and Idea</a></li> +<li><a class="reference internal" href="#how-to-use">How to use</a></li> +<li><a class="reference internal" href="#automatic-full-qualified-tag-generation">Automatic full qualified tag generation</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#tokeninfo-api">tokenInfo API</a></li> +<li><a class="reference internal" href="#multiple-parsers">Multiple parsers</a><ul> +<li><a class="reference internal" href="#guest-parser-promise-api">Guest parser (promise API)</a><ul> +<li><a class="reference internal" href="#id3">Background and Idea</a></li> +<li><a class="reference internal" href="#usage">Usage</a></li> +<li><a class="reference internal" href="#internal-design">Internal design</a></li> +</ul> +</li> +<li><a class="reference internal" href="#api-for-subparser">API for subparser</a><ul> +<li><a class="reference internal" href="#outline">Outline</a></li> +<li><a class="reference internal" href="#fields-of-subparser-type">Fields of <code class="docutils literal notranslate"><span class="pre">subparser</span></code> type</a></li> +<li><a class="reference internal" href="#extending-subparser-type">Extending <code class="docutils literal notranslate"><span class="pre">subparser</span></code> type</a></li> +<li><a class="reference internal" href="#making-a-tag-in-a-subparser">Making a tag in a subparser</a></li> +<li><a class="reference internal" href="#calling-methods-of-subparsers-from-a-base-parser">Calling methods of subparsers from a base parser</a></li> +<li><a class="reference internal" href="#registering-a-subparser-to-its-base-parser">Registering a subparser to its base parser</a></li> +<li><a class="reference internal" href="#scheduling-running-the-base-parser">Scheduling running the base parser</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#packcc-compiler-compiler">PackCC compiler-compiler</a></li> +<li><a class="reference internal" href="#automatic-parser-guessing-tbw">Automatic parser guessing (TBW)</a></li> +<li><a class="reference internal" href="#managing-regular-expression-parsers-tbw">Managing regular expression parsers (TBW)</a></li> +<li><a class="reference internal" href="#ghost-kind-in-regex-parser-tbw">Ghost kind in regex parser (TBW)</a></li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="parser-in-c.html" + title="previous chapter">Writing a parser in C</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="tips.html" + title="next chapter">Testing ctags</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="tips.html" title="Testing ctags" + >next</a> |</li> + <li class="right" > + <a href="parser-in-c.html" title="Writing a parser in C" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="extending.html" >Extending ctags with a parser written in C</a> »</li> + <li class="nav-item nav-item-this"><a href="">Input text stream</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man-pages.html b/ctags/docs/man-pages.html new file mode 100644 index 0000000..2dd1007 --- /dev/null +++ b/ctags/docs/man-pages.html @@ -0,0 +1,336 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Man pages — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="ctags" href="man/ctags.1.html" /> + <link rel="prev" title="Building on Mac OS" href="osx.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="man/ctags.1.html" title="ctags" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="osx.html" title="Building on Mac OS" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Man pages</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="man-pages"> +<span id="id1"></span><h1>Man pages<a class="headerlink" href="#man-pages" title="Permalink to this headline">¶</a></h1> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="man/ctags.1.html">ctags(1)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#command-line-interface">COMMAND LINE INTERFACE</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#letters-and-names">Letters and names</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#list-options">List options</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#options">OPTIONS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#input-output-file-options">Input/Output File Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#output-format-options">Output Format Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#language-selection-and-mapping-options">Language Selection and Mapping Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#tags-file-contents-options">Tags File Contents Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#option-file-options">Option File Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#optlib-options">optlib Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#language-specific-options">Language Specific Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#listing-options">Listing Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#miscellaneous-options">Miscellaneous Options</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#obsoleted-options">Obsoleted Options</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#operational-details">OPERATIONAL DETAILS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#notes-for-c-c-parser">Notes for C/C++ Parser</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#determining-file-language">Determining file language</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#tag-file-format">TAG FILE FORMAT</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#tag-entries">TAG ENTRIES</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#extension-fields">Extension fields</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#extras">Extras</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags.1.html#language-specific-fields-and-extras">Language-specific fields and extras</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#how-to-use-with-vi">HOW TO USE WITH VI</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#how-to-use-with-gnu-emacs">HOW TO USE WITH GNU EMACS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#how-to-use-with-nedit">HOW TO USE WITH NEDIT</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#caveats">CAVEATS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#bugs">BUGS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#environment-variables">ENVIRONMENT VARIABLES</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#files">FILES</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#see-also">SEE ALSO</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#author">AUTHOR</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#motivation">MOTIVATION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags.1.html#credits">CREDITS</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/tags.5.html">tags(5)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/tags.5.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/tags.5.html#proposal-for-extended-vi-tags-file-format">Proposal for extended Vi tags file format</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#introduction">Introduction</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#from-proposal-to-standard">From proposal to standard</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#backwards-compatibility">Backwards compatibility</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#security">Security</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#goals">Goals</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#proposal">Proposal</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/tags.5.html#exceptions-in-universal-ctags">Exceptions in Universal Ctags</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#exceptions">Exceptions</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/tags.5.html#compatible-output-and-weakness">Compatible output and weakness</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/tags.5.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-optlib.7.html">ctags-optlib(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-optlib.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-optlib.7.html#description">DESCRIPTION</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-optlib.7.html#storing-a-parser-definition-to-a-file">Storing a parser definition to a file</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-optlib.7.html#overview-for-defining-a-parser">Overview for defining a parser</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-optlib.7.html#options">OPTIONS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-optlib.7.html#flags-for-regex-lang-option">FLAGS FOR <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> OPTION</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-optlib.7.html#examples">EXAMPLES</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-optlib.7.html#perl-pod">Perl Pod</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-optlib.7.html#using-scope-regex-flags">Using scope regex flags</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-optlib.7.html#see-also">SEE ALSO</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-optlib.7.html#author">AUTHOR</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-client-tools.7.html">ctags-client-tools(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#pseudo-tags">PSEUDO-TAGS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#options-for-pseudo-tags">Options for Pseudo-tags</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#list-of-notable-pseudo-tags">List of notable pseudo-tags</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#redundant-kinds">REDUNDANT-KINDS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#multiple-languages-for-an-input-file">MULTIPLE-LANGUAGES FOR AN INPUT FILE</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#utilizing-readtags">UTILIZING READTAGS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#build-filter-sorter-expressions">Build Filter/Sorter Expressions</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#parse-readtags-output">Parse Readtags Output</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#make-use-of-the-pattern-field">Make Use of the Pattern Field</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#remark-about-a-previous-format-of-the-pattern-field">Remark: About a Previous Format of the Pattern Field</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#json-output">JSON OUTPUT</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#format">Format</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-client-tools.7.html#data-type-used-in-a-field">Data type used in a field</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-client-tools.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-faq.7.html">ctags-faq(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-faq.7.html#description">DESCRIPTION</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#what-is-the-difference-between-universal-ctags-and-exuberant-ctags">What is the difference between Universal Ctags and Exuberant Ctags?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#how-can-i-avoid-having-to-specify-my-favorite-option-every-time">How can I avoid having to specify my favorite option every time?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file">What are these strange bits of text beginning with <code class="docutils literal notranslate"><span class="pre">;"</span></code> which follow many of the lines in the tag file?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#why-can-t-i-jump-to-class-member">Why can’t I jump to <code class="docutils literal notranslate"><span class="pre">class::member</span></code>?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag">Why do I end up on the wrong line when I jump to a tag?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name">How do I jump to the tag I want instead of the wrong one by the same name?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#how-can-i-locate-all-references-to-a-specific-function-or-variable">How can I locate all references to a specific function or variable?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#why-does-appending-tags-to-a-tag-file-tag-so-long">Why does appending tags to a tag file tag so long?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy">How should I set up tag files for a multi-level directory hierarchy?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#does-universal-ctags-support-unicode-file-names">Does Universal Ctags support Unicode file names?</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-faq.7.html#why-does-zsh-cause-zsh-no-matches-found-error">Why does zsh cause “zsh: no matches found” error?</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-faq.7.html#see-also">SEE ALSO</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-faq.7.html#author">AUTHOR</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html">ctags-lang-iPythonCell(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html#kind-s">KIND(S)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html#extra-s">EXTRA(S)</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html#customizing">CUSTOMIZING</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-iPythonCell.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-lang-julia.7.html">ctags-lang-julia(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-julia.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-julia.7.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-julia.7.html#tagging-import-and-using-expressions">TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> AND <code class="docutils literal notranslate"><span class="pre">using</span></code> EXPRESSIONS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-julia.7.html#summary">Summary</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-julia.7.html#examples">Examples</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-julia.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-lang-python.7.html">ctags-lang-python(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-python.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-python.7.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-python.7.html#tagging-import-statements">TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> STATEMENTS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-python.7.html#summary">Summary</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-python.7.html#examples">Examples</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-python.7.html#lambda-expression-and-type-hint">LAMBDA EXPRESSION AND TYPE HINT</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-python.7.html#id1">Summary</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-python.7.html#id2">Examples</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-python.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-lang-verilog.7.html">ctags-lang-verilog(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-verilog.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-verilog.7.html#description">DESCRIPTION</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-verilog.7.html#supported-kinds">Supported Kinds</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-verilog.7.html#supported-language-specific-fields">Supported Language Specific Fields</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-lang-verilog.7.html#tips">TIPS</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-verilog.7.html#known-issues">KNOWN ISSUES</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-verilog.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-lang-inko.7.html">ctags-lang-inko(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-inko.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-inko.7.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-inko.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-lang-r.7.html">ctags-lang-r(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-r.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-r.7.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-r.7.html#kinds">Kinds</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-r.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-lang-sql.7.html">ctags-lang-sql(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-sql.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-sql.7.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-sql.7.html#examples">EXAMPLES</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-sql.7.html#known-bugs">KNOWN BUGS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-sql.7.html#see-also">SEE ALSO</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-lang-sql.7.html#references">REFERENCES</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/ctags-incompatibilities.7.html">ctags-incompatibilities(7)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-incompatibilities.7.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-incompatibilities.7.html#description">DESCRIPTION</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-incompatibilities.7.html#option-files-loading-at-starting-up-time-preload-files">Option files loading at starting up time (preload files)</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-incompatibilities.7.html#environment-variables-for-arranging-command-lines">Environment variables for arranging command lines</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-incompatibilities.7.html#incompatibilities-in-command-line-interface">Incompatibilities in command line interface</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-incompatibilities.7.html#incompatibilities-in-language-and-kind-definitions">Incompatibilities in language and kind definitions</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/ctags-incompatibilities.7.html#incompatibilities-in-tags-file-format">Incompatibilities in tags file format</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/ctags-incompatibilities.7.html#see-also">SEE ALSO</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="man/readtags.1.html">readtags(1)</a><ul> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html#synopsis">SYNOPSIS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html#description">DESCRIPTION</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html#actions">ACTIONS</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html#options">OPTIONS</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#controlling-the-tags-reading-behavior">Controlling the Tags Reading Behavior</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#controlling-the-name-action-behavior">Controlling the NAME Action Behavior</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#controlling-the-output">Controlling the Output</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#filtering-and-sorting">Filtering and Sorting</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#examples">Examples</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html#expression">EXPRESSION</a><ul> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#filtering">Filtering</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#sorting">Sorting</a></li> +<li class="toctree-l3"><a class="reference internal" href="man/readtags.1.html#inspecting-the-behavior-of-expressions">Inspecting the Behavior of Expressions</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html#see-also">SEE ALSO</a></li> +<li class="toctree-l2"><a class="reference internal" href="man/readtags.1.html#credits">CREDITS</a></li> +</ul> +</li> +</ul> +</div> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="osx.html" + title="previous chapter">Building on Mac OS</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="man/ctags.1.html" + title="next chapter">ctags</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="man/ctags.1.html" title="ctags" + >next</a> |</li> + <li class="right" > + <a href="osx.html" title="Building on Mac OS" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Man pages</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-client-tools.7.html b/ctags/docs/man/ctags-client-tools.7.html new file mode 100644 index 0000000..8acd0ef --- /dev/null +++ b/ctags/docs/man/ctags-client-tools.7.html @@ -0,0 +1,615 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-client-tools — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-faq" href="ctags-faq.7.html" /> + <link rel="prev" title="ctags-optlib" href="ctags-optlib.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-faq.7.html" title="ctags-faq" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-optlib.7.html" title="ctags-optlib" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-client-tools</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-client-tools"> +<span id="ctags-client-tools-7"></span><h1>ctags-client-tools<a class="headerlink" href="#ctags-client-tools" title="Permalink to this headline">¶</a></h1> +<p>Hints for developing a tool using ctags command and tags output</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [options] [file(s)]</div> +<div class="line"><strong>etags</strong> [options] [file(s)]</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p><strong>Client tool</strong> means a tool running the ctags command +and/or reading a tags file generated by ctags command. +This man page gathers hints for people who develop client tools.</p> +</section> +<section id="pseudo-tags"> +<h2>PSEUDO-TAGS<a class="headerlink" href="#pseudo-tags" title="Permalink to this headline">¶</a></h2> +<p><strong>Pseudo-tags</strong>, stored in a tag file, indicate how +ctags generated the tags file: whether the +tags file is sorted or not, which version of tags file format is used, +the name of tags generator, and so on. The opposite term for +pseudo-tags is <strong>regular-tags</strong>. A regular-tag is for a language +object in an input file. A pseudo-tag is for the tags file +itself. Client tools may use pseudo-tags as reference for processing +regular-tags.</p> +<p>A pseudo-tag is stored in a tags file in the same format as +regular-tags as described in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, except that pseudo-tag names +are prefixed with “!_”. For the general information about +pseudo-tags, see “TAG FILE INFORMATION” in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +<p>An example of a pseudo tag:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ +</pre></div> +</div> +<p>The value, “2”, associated with the pseudo tag “TAG_PROGRAM_NAME”, is +used in the field for input file. The description, “Derived from +Exuberant Ctags”, is used in the field for pattern.</p> +<p>Universal Ctags extends the naming scheme of the classical pseudo-tags +available in Exuberant Ctags for emitting language specific +information as pseudo tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_{pseudo-tag-name}!{language-name} {associated-value} /{description}/ +</pre></div> +</div> +<p>The language-name is appended to the pseudo-tag name with a separator, “!”.</p> +<p>An example of pseudo tag with a language suffix:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_DESCRIPTION!C f,function /function definitions/ +</pre></div> +</div> +<p>This pseudo-tag says “the function kind of C language is enabled +when generating this tags file.” <code class="docutils literal notranslate"><span class="pre">--pseudo-tags</span></code> is the option for +enabling/disabling individual pseudo-tags. When enabling/disabling a +pseudo tag with the option, specify the tag name only +“TAG_KIND_DESCRIPTION”, without the prefix (“!_”) or the suffix (“!C”).</p> +<section id="options-for-pseudo-tags"> +<h3>Options for Pseudo-tags<a class="headerlink" href="#options-for-pseudo-tags" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--extras=+p</span></code> (or <code class="docutils literal notranslate"><span class="pre">--extras=+{pseudo}</span></code>)</dt><dd><p>Forces writing pseudo-tags.</p> +<p>ctags emits pseudo-tags by default when writing tags +to a regular file (e.g. “tags’.) However, when specifying <code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">-</span></code> +or <code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">-</span></code> for writing tags to standard output, +ctags doesn’t emit pseudo-tags. <code class="docutils literal notranslate"><span class="pre">--extras=+p</span></code> or +<code class="docutils literal notranslate"><span class="pre">--extras=+{pseudo}</span></code> will force pseudo-tags to be written.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code></dt><dd><p>Lists available types of pseudo-tags and shows whether they are enabled or disabled.</p> +<p>Running ctags with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code> option +lists available pseudo-tags. Some of pseudo-tags newly introduced +in Universal Ctags project are disabled by default. Use +<code class="docutils literal notranslate"><span class="pre">--pseudo-tags=...</span></code> to enable them.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--pseudo-tags=[+|-]names|*</span></code></dt><dd><p>Specifies a list of pseudo-tag types to include in the output.</p> +<p>The parameters are a set of pseudo tag names. Valid pseudo tag names +can be listed with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code>. Surround each name in the set +with braces, like “{TAG_PROGRAM_AUTHOR}”. You don’t have to include the “!_” +pseudo tag prefix when specifying a name in the option argument for <code class="docutils literal notranslate"><span class="pre">--pseudo-tags=</span></code> +option.</p> +<p>pseudo-tags don’t have a notation using one-letter flags.</p> +<p>If a name is preceded by either the ‘+’ or ‘-’ characters, that +tags’s effect has been added or removed. Otherwise the names replace +any current settings. All entries are included if ‘*’ is given.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--fields=+E</span></code> (or <code class="docutils literal notranslate"><span class="pre">--fields=+{extras}</span></code>)</dt><dd><p>Attach “extras:pseudo” field to pseudo-tags.</p> +<p>An example of pseudo tags with the field:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ extras:pseudo +</pre></div> +</div> +<p>If the name of a normal tag in a tag file starts with “!_”, a +client tool cannot distinguish whether the tag is a regular-tag or +pseudo-tag. The fields attached with this option help the tool +distinguish them.</p> +</dd> +</dl> +</section> +<section id="list-of-notable-pseudo-tags"> +<h3>List of notable pseudo-tags<a class="headerlink" href="#list-of-notable-pseudo-tags" title="Permalink to this headline">¶</a></h3> +<p>Running ctags with <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code> option lists available types +of pseudo-tags with short descriptions. This subsection shows hints +for using notable ones.</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_EXTRA_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled extras:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_EXTRA_DESCRIPTION {extra-name} /description/ +!_TAG_EXTRA_DESCRIPTION!{language-name} {extra-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some extra tags (extras), refer to +the pseudo-tags of this type. A tool can reject the tags file that +doesn’t include expected extras, and raise an error in an early +stage of processing.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --extras=+p --pseudo-tags='{TAG_EXTRA_DESCRIPTION}' -o - input.c +!_TAG_EXTRA_DESCRIPTION anonymous /Include tags for non-named objects like lambda/ +!_TAG_EXTRA_DESCRIPTION fileScope /Include tags of file scope/ +!_TAG_EXTRA_DESCRIPTION pseudo /Include pseudo tags/ +!_TAG_EXTRA_DESCRIPTION subparser /Include tags generated by subparsers/ +... +</pre></div> +</div> +<p>A client tool can know “{anonymous}”, “{fileScope}”, “{pseudo}”, +and “{subparser}” extras are enabled from the output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FIELD_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled fields:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_FIELD_DESCRIPTION {field-name} /description/ +!_TAG_FIELD_DESCRIPTION!{language-name} {field-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some fields, refer to the pseudo-tags of +this type. A tool can reject a tags file that doesn’t include +expected fields, and raise an error in an early stage of +processing.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --fields-C=+'{macrodef}' --extras=+p --pseudo-tags='{TAG_FIELD_DESCRIPTION}' -o - input.c +!_TAG_FIELD_DESCRIPTION file /File-restricted scoping/ +!_TAG_FIELD_DESCRIPTION input /input file/ +!_TAG_FIELD_DESCRIPTION name /tag name/ +!_TAG_FIELD_DESCRIPTION pattern /pattern/ +!_TAG_FIELD_DESCRIPTION typeref /Type and name of a variable or typedef/ +!_TAG_FIELD_DESCRIPTION!C macrodef /macro definition/ +... +</pre></div> +</div> +<p>A client tool can know “{file}”, “{input}”, “{name}”, “{pattern}”, +and “{typeref}” fields are enabled from the output. +The fields are common in languages. In addition to the common fields, +the tool can known “{macrodef}” field of C language is also enabled.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_ENCODING</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_FORMAT</span></code></dt><dd><p>See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_FILE_SORTED</span></code></dt><dd><p>See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled kinds:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_DESCRIPTION!{language-name} {kind-letter},{kind-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some kinds, refer to the pseudo-tags of +this type. A tool can reject the tags file that doesn’t include +expected kinds, and raise an error in an early stage of +processing.</p> +<p>Kinds are language specific, so a language name is always +appended to the tag name as suffix.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --extras=+p --kinds-C=vfm --pseudo-tags='{TAG_KIND_DESCRIPTION}' -o - input.c +!_TAG_KIND_DESCRIPTION!C f,function /function definitions/ +!_TAG_KIND_DESCRIPTION!C m,member /struct, and union members/ +!_TAG_KIND_DESCRIPTION!C v,variable /variable definitions/ +... +</pre></div> +</div> +<p>A client tool can know “{function}”, “{member}”, and “{variable}” +kinds of C language are enabled from the output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_EXCMD</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the specified type of EX command with <code class="docutils literal notranslate"><span class="pre">--excmd</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_FILESEP</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_PATTERN_LENGTH_LIMIT</span></code> (new in Universal Ctags)</dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_PROC_CWD</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the working directory of ctags during processing.</p> +<p>This pseudo-tag helps a client tool solve the absolute paths for +the input files for tag entries even when they are tagged with +relative paths.</p> +<p>An example of the pseudo-tags:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cat tags +!_TAG_PROC_CWD /tmp/ // +main input.c /^int main (void) { return 0; }$/;" f typeref:typename:int +... +</pre></div> +</div> +<p>From the regular tag for “main”, the client tool can know the +“main” is at “input.c”. However, it is a relative path. So if the +directory where ctags run and the directory +where the client tool runs are different, the client tool cannot +find “input.c” from the file system. In that case, +<code class="docutils literal notranslate"><span class="pre">TAG_PROC_CWD</span></code> gives the tool a hint; “input.c” may be at “/tmp”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_PROGRAM_NAME</span></code></dt><dd><p>TBW</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAG_ROLE_DESCRIPTION</span></code> (new in Universal Ctags)</dt><dd><p>Indicates the names and descriptions of enabled roles:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_ROLE_DESCRIPTION!{language-name}!{kind-name} {role-name} /description/ +</pre></div> +</div> +<p>If your tool relies on some roles, refer to the pseudo-tags of +this type. Note that a role owned by a disabled kind is not listed +even if the role itself is enabled.</p> +</dd> +</dl> +</section> +</section> +<section id="redundant-kinds"> +<h2>REDUNDANT-KINDS<a class="headerlink" href="#redundant-kinds" title="Permalink to this headline">¶</a></h2> +<p>TBW</p> +</section> +<section id="multiple-languages-for-an-input-file"> +<h2>MULTIPLE-LANGUAGES FOR AN INPUT FILE<a class="headerlink" href="#multiple-languages-for-an-input-file" title="Permalink to this headline">¶</a></h2> +<p>Universal ctags can run multiple parsers. +That means a parser, which supports multiple parsers, may output tags for +different languages. <code class="docutils literal notranslate"><span class="pre">language</span></code>/<code class="docutils literal notranslate"><span class="pre">l</span></code> field can be used to show the language +for each tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat /tmp/foo.html +<span class="go"><html></span> +<span class="go"><script>var x = 1</script></span> +<span class="go"><h1>title</h1></span> +<span class="go"></html></span> +<span class="gp">$ </span>./ctags -o - --extras<span class="o">=</span>+g /tmp/foo.html +<span class="go">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h</span> +<span class="go">x /tmp/foo.html /var x = 1/;" v</span> +<span class="gp">$ </span>./ctags -o - --extras<span class="o">=</span>+g --fields<span class="o">=</span>+l /tmp/foo.html +<span class="go">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h language:HTML</span> +<span class="go">x /tmp/foo.html /var x = 1/;" v language:JavaScript</span> +</pre></div> +</div> +</section> +<section id="utilizing-readtags"> +<h2>UTILIZING READTAGS<a class="headerlink" href="#utilizing-readtags" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> to know how to use readtags. This section is for discussing +some notable topics for client tools.</p> +<section id="build-filter-sorter-expressions"> +<h3>Build Filter/Sorter Expressions<a class="headerlink" href="#build-filter-sorter-expressions" title="Permalink to this headline">¶</a></h3> +<p>Certain escape sequences in expressions are recognized by readtags. For +example, when searching for a tag that matches <code class="docutils literal notranslate"><span class="pre">a\?b</span></code>, if using a filter +expression like <code class="docutils literal notranslate"><span class="pre">'(eq?</span> <span class="pre">$name</span> <span class="pre">"a\?b")'</span></code>, since <code class="docutils literal notranslate"><span class="pre">\?</span></code> is translated into a +single <code class="docutils literal notranslate"><span class="pre">?</span></code> by readtags, it actually searches for <code class="docutils literal notranslate"><span class="pre">a?b</span></code>.</p> +<p>Another problem is if a single quote appear in filter expressions (which is +also wrapped by single quotes), it terminates the expression, producing broken +expressions, and may even cause unintended shell injection. Single quotes can +be escaped using <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code>.</p> +<p>So, client tools need to:</p> +<ul class="simple"> +<li><p>Replace <code class="docutils literal notranslate"><span class="pre">\</span></code> by <code class="docutils literal notranslate"><span class="pre">\\</span></code></p></li> +<li><p>Replace <code class="docutils literal notranslate"><span class="pre">'</span></code> by <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code></p></li> +</ul> +<p>inside the expressions. If the expression also contains strings, <code class="docutils literal notranslate"><span class="pre">"</span></code> in the +strings needs to be replaced by <code class="docutils literal notranslate"><span class="pre">\"</span></code>.</p> +<p>Client tools written in Lisp could build the expression using lists. <code class="docutils literal notranslate"><span class="pre">prin1</span></code> +(in Common Lisp style Lisps) and <code class="docutils literal notranslate"><span class="pre">write</span></code> (in Scheme style Lisps) can +translate the list into a string that can be directly used. For example, in +EmacsLisp:</p> +<div class="highlight-EmacsLisp notranslate"><div class="highlight"><pre><span></span>(let ((name "hi")) + (prin1 `(eq? $name ,name))) +=> "(eq\\? $name "hi")" +</pre></div> +</div> +<p>The “?” is escaped, and readtags can handle it. Scheme style Lisps should do +proper escaping so the expression readtags gets is just the expression passed +into <code class="docutils literal notranslate"><span class="pre">write</span></code>. Common Lisp style Lisps may produce unrecognized escape +sequences by readtags, like <code class="docutils literal notranslate"><span class="pre">\#</span></code>. Readtags provides some aliases for these +Lisps:</p> +<ul class="simple"> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">true</span></code> for <code class="docutils literal notranslate"><span class="pre">#t</span></code>.</p></li> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">false</span></code> for <code class="docutils literal notranslate"><span class="pre">#f</span></code>.</p></li> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">nil</span></code> or <code class="docutils literal notranslate"><span class="pre">()</span></code> for <code class="docutils literal notranslate"><span class="pre">()</span></code>.</p></li> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN")</span></code> for <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code>. Use +<code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN"</span> <span class="pre">:case-fold</span> <span class="pre">true)</span></code> for <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code>. Notice +that <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code> doesn’t require escaping “/” in the pattern.</p></li> +</ul> +<p>Notice that even when the client tool uses this method, <code class="docutils literal notranslate"><span class="pre">'</span></code> still needs to be +replaced by <code class="docutils literal notranslate"><span class="pre">'"'"'</span></code> to prevent broken expressions and shell injection.</p> +<p>Another thing to notice is that missing fields are represented by <code class="docutils literal notranslate"><span class="pre">#f</span></code>, and +applying string operators to them will produce an error. You should always +check if a field is missing before applying string operators. See the +“Filtering” section in <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> to know how to do this. Run “readtags -H +filter” to see which operators take string arguments.</p> +</section> +<section id="parse-readtags-output"> +<h3>Parse Readtags Output<a class="headerlink" href="#parse-readtags-output" title="Permalink to this headline">¶</a></h3> +<p>In the output of readtags, tabs can appear in all field values (e.g., the tag +name itself could contain tabs), which makes it hard to split the line into +fields. Client tools should use the <code class="docutils literal notranslate"><span class="pre">-E</span></code> option, which keeps the escape +sequences in the tags file, so the only field that could contain tabs is the +pattern field.</p> +<p>The pattern field could:</p> +<ul class="simple"> +<li><p>Use a line number. It will look like <code class="docutils literal notranslate"><span class="pre">number;"</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">10;"</span></code>).</p></li> +<li><p>Use a search pattern. It will look like <code class="docutils literal notranslate"><span class="pre">/pattern/;"</span></code> or <code class="docutils literal notranslate"><span class="pre">?pattern?;"</span></code>. +Notice that the search pattern could contain tabs.</p></li> +<li><p>Combine these two, like <code class="docutils literal notranslate"><span class="pre">number;/pattern/;"</span></code> or <code class="docutils literal notranslate"><span class="pre">number;?pattern?;"</span></code>.</p></li> +</ul> +<p>These are true for tags files using extended format, which is the default one. +The legacy format (i.e. <code class="docutils literal notranslate"><span class="pre">--format=1</span></code>) doesn’t include the semicolons. It’s +old and barely used, so we won’t discuss it here.</p> +<p>Client tools could split the line using the following steps:</p> +<ul class="simple"> +<li><p>Find the first 2 tabs in the line, so we get the name and input field.</p></li> +<li><p>From the 2nd tab:</p> +<ul> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">/</span></code> follows, then the pattern delimiter is <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">?</span></code> follows, then the pattern delimiter is <code class="docutils literal notranslate"><span class="pre">?</span></code>.</p></li> +<li><p>If a number follows, then:</p> +<ul> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">;/</span></code> follows the number, then the delimiter is <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">;?</span></code> follows the number, then the delimiter is <code class="docutils literal notranslate"><span class="pre">?</span></code>.</p></li> +<li><p>If a <code class="docutils literal notranslate"><span class="pre">;"</span></code> follows the number, then the field uses only line number, and +there’s no pattern delimiter (since there’s no regex pattern). In this +case the pattern field ends at the 3rd tab.</p></li> +</ul> +</li> +</ul> +</li> +<li><p>After the opening delimiter, find the next unescaped pattern delimiter, and +that’s the closing delimiter. It will be followed by <code class="docutils literal notranslate"><span class="pre">;"</span></code> and then a tab. +That’s the end of the pattern field. By “unescaped pattern delimiter”, we +mean there’s an even number (including 0) of backslashes before it.</p></li> +<li><p>From here, split the rest of the line into fields by tabs.</p></li> +</ul> +<p>Then, the escape sequences in fields other than the pattern field should be +translated. See “Proposal” in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> to know about all the escape sequences.</p> +</section> +<section id="make-use-of-the-pattern-field"> +<h3>Make Use of the Pattern Field<a class="headerlink" href="#make-use-of-the-pattern-field" title="Permalink to this headline">¶</a></h3> +<p>The pattern field specifies how to find a tag in its source file. The code +generating this field seems to have a long history, so there are some pitfalls +and it’s a bit hard to handle. A client tool could simply require the <code class="docutils literal notranslate"><span class="pre">line:</span></code> +field and jump to the line it specifies, to avoid using the pattern field. But +anyway, we’ll discuss how to make the best use of it here.</p> +<p>You should take the words here merely as suggestions, and not standards. A +client tool could definitely develop better (or simpler) ways to use the +pattern field.</p> +<p>From the last section, we know the pattern field could contain a line number +and a search pattern. When it only contains the line number, handling it is +easy: you simply go to that line.</p> +<p>The search pattern resembles an EX command, but as we’ll see later, it’s +actually not a valid one, so some manual work are required to process it.</p> +<p>The search pattern could look like <code class="docutils literal notranslate"><span class="pre">/pat/</span></code>, called “forward search pattern”, +or <code class="docutils literal notranslate"><span class="pre">?pat?</span></code>, called “backward search pattern”. Using a search pattern means +even if the source file is updated, as long as the part containing the tag +doesn’t change, we could still locate the tag correctly by searching.</p> +<p>When the pattern field only contains the search pattern, you just search for +it. The search direction (forward/backward) doesn’t matter, as it’s decided +solely by whether the <code class="docutils literal notranslate"><span class="pre">-B</span></code> option is enabled, and not the actual context. You +could always start the search from say the beginning of the file.</p> +<p>When both the search pattern and the line number are presented, you could make +good use of the line number, by going to the line first, then searching for the +nearest occurence of the pattern. A way to do this is to search both forward +and backward for the pattern, and when there is a occurence on both sides, go +to the nearer one.</p> +<p>What’s good about this is when there are multiple identical lines in the source +file (e.g. the COMMON block in Fortran), this could help us find the correct +one, even after the source file is updated and the tag position is shifted by a +few lines.</p> +<p>Now let’s discuss how to search for the pattern. After you trim the <code class="docutils literal notranslate"><span class="pre">/</span></code> or +<code class="docutils literal notranslate"><span class="pre">?</span></code> around it, the pattern resembles a regex pattern. It should be a regex +pattern, as required by being a valid EX command, but it’s actually not, as +you’ll see below.</p> +<p>It could begin with a <code class="docutils literal notranslate"><span class="pre">^</span></code>, which means the pattern starts from the beginning +of a line. It could also end with an <em>unescaped</em> <code class="docutils literal notranslate"><span class="pre">$</span></code> which means the pattern +ends at the end of a line. Let’s keep this information, and trim them too.</p> +<p>Now the remaining part is the actual string containing the tag. Some characters +are escaped:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">\</span></code>.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">$</span></code>, but only at the end of the string.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">/</span></code>, but only in forward search patterns.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">?</span></code>, but only in backward search patterns.</p></li> +</ul> +<p>You need to unescape these to get the literal string. Now you could convert +this literal string to a regexp that matches it (by escaping, like +<code class="docutils literal notranslate"><span class="pre">re.escape</span></code> in Python or <code class="docutils literal notranslate"><span class="pre">regexp-quote</span></code> in Elisp), and assemble it with +<code class="docutils literal notranslate"><span class="pre">^</span></code> or <code class="docutils literal notranslate"><span class="pre">$</span></code> if the pattern originally has it, and finally search for the tag +using this regexp.</p> +</section> +<section id="remark-about-a-previous-format-of-the-pattern-field"> +<h3>Remark: About a Previous Format of the Pattern Field<a class="headerlink" href="#remark-about-a-previous-format-of-the-pattern-field" title="Permalink to this headline">¶</a></h3> +<p>In some earlier versions of Universal Ctags, the line number in the pattern +field is the actual line number minus one, for forward search patterns; or plus +one, for backward search patterns. The idea is to resemble an EX command: you +go to the line, then search forward/backward for the pattern, and you can +always find the correct one. But this denies the purpose of using a search +pattern: to tolerate file updates. For example, the tag is at line 50, +according to this scheme, the pattern field should be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">49</span><span class="p">;</span><span class="o">/</span><span class="n">pat</span><span class="o">/</span><span class="p">;</span><span class="s2">"</span> +</pre></div> +</div> +<p>Then let’s assume that some code above are removed, and the tag is now at +line 45. Now you can’t find it if you search forward from line 49.</p> +<p>Due to this reason, Universal Ctags turns to use the actual line number. A +client tool could distinguish them by the <code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_EXCMD</span></code> pseudo tag, it’s +“combine” for the old scheme, and “combineV2” for the present scheme. But +probably there’s no need to treat them differently, since “search for the +nearest occurence from the line” gives good result on both schemes.</p> +</section> +</section> +<section id="json-output"> +<h2>JSON OUTPUT<a class="headerlink" href="#json-output" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags supports <a class="reference external" href="https://www.json.org/">JSON</a> (strictly +speaking <a class="reference external" href="https://jsonlines.org/">JSON Lines</a>) output format if the +ctags executable is built with <code class="docutils literal notranslate"><span class="pre">libjansson</span></code>. JSON output goes to +standard output by default.</p> +<section id="format"> +<h3>Format<a class="headerlink" href="#format" title="Permalink to this headline">¶</a></h3> +<p>Each JSON line represents a tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --extras<span class="o">=</span>+p --output-format<span class="o">=</span>json --fields<span class="o">=</span>-s input.py +<span class="go">{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "0.0", "pattern": "in development"}</span> +<span class="go">{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"}</span> +<span class="go">...</span> +<span class="go">{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"}</span> +<span class="go">{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"}</span> +<span class="go">...</span> +</pre></div> +</div> +<p>A key not starting with <code class="docutils literal notranslate"><span class="pre">_</span></code> is mapped to a field of ctags. +“<code class="docutils literal notranslate"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></code>” options list the fields.</p> +<p>A key starting with <code class="docutils literal notranslate"><span class="pre">_</span></code> represents meta information of the JSON +line. Currently only <code class="docutils literal notranslate"><span class="pre">_type</span></code> key is used. If the value for the key +is <code class="docutils literal notranslate"><span class="pre">tag</span></code>, the JSON line represents a normal tag. If the value is +<code class="docutils literal notranslate"><span class="pre">ptag</span></code>, the line represents a pseudo-tag.</p> +<p>The output format can be changed in the +future. <code class="docutils literal notranslate"><span class="pre">JSON_OUTPUT_VERSION</span></code> pseudo-tag provides a change +client-tools to handle the changes. Current version is “0.0”. A +client-tool can extract the version with <code class="docutils literal notranslate"><span class="pre">path</span></code> key from the +pseudo-tag.</p> +<p>The JSON output format is newly designed and has no limitation found +in the default tags file format.</p> +<ul class="simple"> +<li><p>The values for <code class="docutils literal notranslate"><span class="pre">kind</span></code> key are represented in long-name flags. +No one-letter is here.</p></li> +<li><p>Scope names and scope kinds have distinguished keys: <code class="docutils literal notranslate"><span class="pre">scope</span></code> and <code class="docutils literal notranslate"><span class="pre">scopeKind</span></code>. +They are combined in the default tags file format.</p></li> +</ul> +</section> +<section id="data-type-used-in-a-field"> +<h3>Data type used in a field<a class="headerlink" href="#data-type-used-in-a-field" title="Permalink to this headline">¶</a></h3> +<p>Values for the most of all keys are represented in JSON string type. +However, some of them are represented in string, integer, and/or boolean type.</p> +<p>“<code class="docutils literal notranslate"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></code>” options show What kind of data type +used in a field of JSON.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --output-format<span class="o">=</span>json --list-fields +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="go">F input yes NONE s-- no input file</span> +<span class="go">...</span> +<span class="go">P pattern yes NONE s-b no pattern</span> +<span class="go">...</span> +<span class="go">f file yes NONE --b no File-restricted scoping</span> +<span class="go">...</span> +<span class="go">e end no NONE -i- no end lines of various items</span> +<span class="go">...</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">JSTYPE</span></code> column shows the data types.</p> +<dl class="simple"> +<dt>‘<code class="docutils literal notranslate"><span class="pre">s</span></code>’</dt><dd><p>string</p> +</dd> +<dt>‘<code class="docutils literal notranslate"><span class="pre">i</span></code>’</dt><dd><p>integer</p> +</dd> +<dt>‘<code class="docutils literal notranslate"><span class="pre">b</span></code>’</dt><dd><p>boolean (true or false)</p> +</dd> +</dl> +<p>For an example, the value for <code class="docutils literal notranslate"><span class="pre">pattern</span></code> field of ctags takes a string or a boolean value.</p> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-lang-python.7.html#ctags-lang-python-7"><span class="std std-ref">ctags-lang-python(7)</span></a>, <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>, <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-client-tools</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#pseudo-tags">PSEUDO-TAGS</a><ul> +<li><a class="reference internal" href="#options-for-pseudo-tags">Options for Pseudo-tags</a></li> +<li><a class="reference internal" href="#list-of-notable-pseudo-tags">List of notable pseudo-tags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#redundant-kinds">REDUNDANT-KINDS</a></li> +<li><a class="reference internal" href="#multiple-languages-for-an-input-file">MULTIPLE-LANGUAGES FOR AN INPUT FILE</a></li> +<li><a class="reference internal" href="#utilizing-readtags">UTILIZING READTAGS</a><ul> +<li><a class="reference internal" href="#build-filter-sorter-expressions">Build Filter/Sorter Expressions</a></li> +<li><a class="reference internal" href="#parse-readtags-output">Parse Readtags Output</a></li> +<li><a class="reference internal" href="#make-use-of-the-pattern-field">Make Use of the Pattern Field</a></li> +<li><a class="reference internal" href="#remark-about-a-previous-format-of-the-pattern-field">Remark: About a Previous Format of the Pattern Field</a></li> +</ul> +</li> +<li><a class="reference internal" href="#json-output">JSON OUTPUT</a><ul> +<li><a class="reference internal" href="#format">Format</a></li> +<li><a class="reference internal" href="#data-type-used-in-a-field">Data type used in a field</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-optlib.7.html" + title="previous chapter">ctags-optlib</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-faq.7.html" + title="next chapter">ctags-faq</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-faq.7.html" title="ctags-faq" + >next</a> |</li> + <li class="right" > + <a href="ctags-optlib.7.html" title="ctags-optlib" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-client-tools</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-faq.7.html b/ctags/docs/man/ctags-faq.7.html new file mode 100644 index 0000000..433e5e7 --- /dev/null +++ b/ctags/docs/man/ctags-faq.7.html @@ -0,0 +1,510 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-faq — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-lang-iPythonCell" href="ctags-lang-iPythonCell.7.html" /> + <link rel="prev" title="ctags-client-tools" href="ctags-client-tools.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-client-tools.7.html" title="ctags-client-tools" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-faq</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-faq"> +<span id="ctags-faq-7"></span><h1><a class="toc-backref" href="#id2">ctags-faq</a><a class="headerlink" href="#ctags-faq" title="Permalink to this headline">¶</a></h1> +<p>Universal Ctags FAQ</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<p>This is the Universal Ctags FAQ (Frequently-Asked Questions). +It is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a></p> +<div class="contents topic" id="contents"> +<p class="topic-title">Contents</p> +<ul class="simple"> +<li><p><a class="reference internal" href="#ctags-faq" id="id2">ctags-faq</a></p> +<ul> +<li><p><a class="reference internal" href="#description" id="id3">DESCRIPTION</a></p> +<ul> +<li><p><a class="reference internal" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags" id="id4">What is the difference between Universal Ctags and Exuberant Ctags?</a></p></li> +<li><p><a class="reference internal" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time" id="id5">How can I avoid having to specify my favorite option every time?</a></p></li> +<li><p><a class="reference internal" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file" id="id6">What are these strange bits of text beginning with <code class="docutils literal notranslate"><span class="pre">;"</span></code> which follow many of the lines in the tag file?</a></p></li> +<li><p><a class="reference internal" href="#why-can-t-i-jump-to-class-member" id="id7">Why can’t I jump to <code class="docutils literal notranslate"><span class="pre">class::member</span></code>?</a></p></li> +<li><p><a class="reference internal" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag" id="id8">Why do I end up on the wrong line when I jump to a tag?</a></p></li> +<li><p><a class="reference internal" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name" id="id9">How do I jump to the tag I want instead of the wrong one by the same name?</a></p></li> +<li><p><a class="reference internal" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable" id="id10">How can I locate all references to a specific function or variable?</a></p></li> +<li><p><a class="reference internal" href="#why-does-appending-tags-to-a-tag-file-tag-so-long" id="id11">Why does appending tags to a tag file tag so long?</a></p></li> +<li><p><a class="reference internal" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy" id="id12">How should I set up tag files for a multi-level directory hierarchy?</a></p></li> +<li><p><a class="reference internal" href="#does-universal-ctags-support-unicode-file-names" id="id13">Does Universal Ctags support Unicode file names?</a></p></li> +<li><p><a class="reference internal" href="#why-does-zsh-cause-zsh-no-matches-found-error" id="id14">Why does zsh cause “zsh: no matches found” error?</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#see-also" id="id15">SEE ALSO</a></p></li> +<li><p><a class="reference internal" href="#author" id="id16">AUTHOR</a></p></li> +</ul> +</li> +</ul> +</div> +<section id="description"> +<h2><a class="toc-backref" href="#id3">DESCRIPTION</a><a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<section id="what-is-the-difference-between-universal-ctags-and-exuberant-ctags"> +<h3><a class="toc-backref" href="#id4">What is the difference between Universal Ctags and Exuberant Ctags?</a><a class="headerlink" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags is an unofficial fork of Exuberant Ctags. +The differences are summarized in <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a> man page.</p> +<p>The most notable one is that Universal Ctags doesn’t read <code class="docutils literal notranslate"><span class="pre">~/.ctags</span></code> file. +Instead, it reads <code class="docutils literal notranslate"><span class="pre">*.ctags</span></code> under <code class="docutils literal notranslate"><span class="pre">~/.ctags.d</span></code> directory.</p> +</section> +<section id="how-can-i-avoid-having-to-specify-my-favorite-option-every-time"> +<h3><a class="toc-backref" href="#id5">How can I avoid having to specify my favorite option every time?</a><a class="headerlink" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time" title="Permalink to this headline">¶</a></h3> +<p>Either by setting the environment variable <code class="docutils literal notranslate"><span class="pre">CTAGS</span></code> to your custom +options, or putting them into a <code class="docutils literal notranslate"><span class="pre">~/.ctags.d/anyname.ctags</span></code> file in your home +directory.</p> +</section> +<section id="what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file"> +<h3><a class="toc-backref" href="#id6">What are these strange bits of text beginning with <code class="docutils literal notranslate"><span class="pre">;"</span></code> which follow many of the lines in the tag file?</a><a class="headerlink" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file" title="Permalink to this headline">¶</a></h3> +<p>These are <em>extension flags</em>. They are added in order to provide extra +information about the tag that may be utilized by the editor in order to +more intelligently handle tags. They are appended to the EX command part of +the tag line in a manner that provides backwards compatibility with existing +implementations of the Vi editor. The semicolon is an EX command separator +and the double quote begins an EX comment. Thus, the extension flags appear +as an EX comment and should be ignored by the editor when it processes the +EX command.</p> +<p>Some non-vi editors, however, implement only the bare minimum of EX commands +in order to process the search command or line number in the third field of +the tag file. If you encounter this problem, use the option <code class="docutils literal notranslate"><span class="pre">--format=1</span></code> to +generate a tag file without these extensions (remember that you can set the +CTAGS environment variable to any default arguments you wish to supply). Then +ask the supplier of your editor to implement handling of this feature of EX +commands.</p> +</section> +<section id="why-can-t-i-jump-to-class-member"> +<h3><a class="toc-backref" href="#id7">Why can’t I jump to <code class="docutils literal notranslate"><span class="pre">class::member</span></code>?</a><a class="headerlink" href="#why-can-t-i-jump-to-class-member" title="Permalink to this headline">¶</a></h3> +<p>Because, by default, ctags only generates tags for the separate identifiers +found in the source files. If you specify the <code class="docutils literal notranslate"><span class="pre">--extra=+q</span></code> option, then +ctags will also generate a second, class-qualified tag for each class member +(data and function/method) in the form <code class="docutils literal notranslate"><span class="pre">class::member</span></code> for C++, and in the form +<code class="docutils literal notranslate"><span class="pre">class.method</span></code> for Eiffel and Java.</p> +</section> +<section id="why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag"> +<h3><a class="toc-backref" href="#id8">Why do I end up on the wrong line when I jump to a tag?</a><a class="headerlink" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag" title="Permalink to this headline">¶</a></h3> +<p>By default, ctags encodes the line number in the file where macro (<code class="docutils literal notranslate"><span class="pre">#define</span></code>) +tags are found. This was done to remain compatible with the original UNIX +version of ctags. If you change the file containing the tag without +rebuilding the tag file, the location of tag in the tag file may no longer +match the current location.</p> +<p>In order to avoid this problem, you can specify the option <code class="docutils literal notranslate"><span class="pre">--excmd=p</span></code>, +which causes ctags to use a search pattern to locate macro tags. I have +never uncovered the reason why the original UNIX ctags used line numbers +exclusively for macro tags, but have so far resisted changing the default +behavior of Exuberant (and Universal) Ctags to behave differently.</p> +</section> +<section id="how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name"> +<h3><a class="toc-backref" href="#id9">How do I jump to the tag I want instead of the wrong one by the same name?</a><a class="headerlink" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name" title="Permalink to this headline">¶</a></h3> +<p>A tag file is simple a list of tag names and where to find them. If there +are duplicate entries, you often end up going to the wrong one because the +tag file is sorted and your editor locates the first one in the tag file.</p> +<p>Standard Vi provides no facilities to alter this behavior. However, Vim +has some nice features to minimize this problem, primarily by examining all +matches and choosing the best one under the circumstances. Vim also provides +commands which allow for selection of the desired matching tag.</p> +</section> +<section id="how-can-i-locate-all-references-to-a-specific-function-or-variable"> +<h3><a class="toc-backref" href="#id10">How can I locate all references to a specific function or variable?</a><a class="headerlink" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable" title="Permalink to this headline">¶</a></h3> +<p>There are several packages already available which provide this capability. +Namely, these are: GLOBAL source code tag system, GNU id-utils, cscope, +and cflow. As of this writing, they can be found in the following locations:</p> +<ul class="simple"> +<li><p>GLOBAL: <a class="reference external" href="http://www.gnu.org/software/global">http://www.gnu.org/software/global</a></p></li> +<li><p>id-utils: <a class="reference external" href="http://www.gnu.org/software/idutils/idutils.html">http://www.gnu.org/software/idutils/idutils.html</a></p></li> +<li><p>cscope: <a class="reference external" href="http://cscope.sourceforge.net">http://cscope.sourceforge.net</a></p></li> +<li><p>cflow: <a class="reference external" href="ftp://www.ibiblio.org/pub/Linux/devel/lang/c">ftp://www.ibiblio.org/pub/Linux/devel/lang/c</a></p></li> +</ul> +</section> +<section id="why-does-appending-tags-to-a-tag-file-tag-so-long"> +<h3><a class="toc-backref" href="#id11">Why does appending tags to a tag file tag so long?</a><a class="headerlink" href="#why-does-appending-tags-to-a-tag-file-tag-so-long" title="Permalink to this headline">¶</a></h3> +<p>Sometimes, in an attempt to build a global tag file for all source files in +a large source tree of many directories, someone will make an attempt to run +ctags in append (<code class="docutils literal notranslate"><span class="pre">-a</span></code>) mode on every directory in the hierarchy. Each time +ctags is invoked, its default behavior is to sort the tag file once the tags +for that execution have been added. As the cumulative tag file grows, the sort +time increases arithmetically.</p> +<p>The best way to avoid this problem (and the most efficient) is to make +use of the <code class="docutils literal notranslate"><span class="pre">--recurse</span></code> (or <code class="docutils literal notranslate"><span class="pre">-R</span></code>) option of ctags by executing the following +command in the root of the directory hierarchy (thus running ctags only once):</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags -R +</pre></div> +</div> +</div></blockquote> +<p>If you really insist on running ctags separately on each directory, you can +avoid the sort pass each time by specifying the option <code class="docutils literal notranslate"><span class="pre">--sort=no</span></code>. Once the +tag file is completely built, use the sort command to manually sort the +final tag file, or let the final invocation of ctags sort the file.</p> +</section> +<section id="how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy"> +<h3><a class="toc-backref" href="#id12">How should I set up tag files for a multi-level directory hierarchy?</a><a class="headerlink" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy" title="Permalink to this headline">¶</a></h3> +<p>There are a few ways of approaching this:</p> +<ol class="arabic simple"> +<li><p>A local tag file in each directory containing only the tags for source +files in that directory.</p></li> +<li><p>One single big, global tag file present in the root directory of your +hierarchy, containing all tags present in all source files in the +hierarchy.</p></li> +<li><p>A local tag file in each directory containing only the tags for source +files in that directory, in addition to one single global tag file +present in the root directory of your hierarchy, containing all +non-static tags present in all source files in the hierarchy.</p></li> +<li><p>A local tag file in each directory of the hierarchy, each one +containing all tags present in source files in that directory and all +non-static tags in every directory below it (note that this implies +also having one big tag file in the root directory of the hierarchy).</p></li> +</ol> +<p>Each of these approaches has its own set of advantages and disadvantages, +depending upon your particular conditions. Which approach is deemed best +depends upon the following factors:</p> +<ol class="upperalpha"> +<li><p>The ability of your editor to use multiple tag files.</p> +<p>If your editor cannot make use of multiple tag files (original vi +implementations could not), then one large tag file is the only way to +go if you ever desire to jump to tags located in other directories. If +you never need to jump to tags in another directory (i.e. the source +in each directory is entirely self-contained), then a local tag file +in each directory will fit your needs.</p> +</li> +<li><p>The time is takes for your editor to look up a tag in the tag file.</p> +<p>The significance of this factor depends upon the size of your source +tree and on whether the source files are located on a local or remote +file system. For source and tag files located on a local file system, +looking up a tag is not as big a hit as one might first imagine, since +vi implementations typically perform a binary search on a sorted tag +file. This may or may not be true for the editor you use. For files +located on a remote file system, reading a large file is an expensive +operation.</p> +</li> +<li><p>Whether or not you expect the source code to change and the time it +takes to rebuild a tag file to account for changes to the source code.</p> +<p>While Universal Ctags is particularly fast in scanning source code +(around 1-2 MB/sec), a large project may still result in objectionable +delays if one wishes to keep their tag file(s) up to date on a +frequent basis, or if the files are located on a remote file system.</p> +</li> +<li><p>The presence of duplicate tags in the source code and the ability to +handle them.</p> +<p>The impact of this factor is influenced by the following three issues:</p> +<ol class="arabic"> +<li><p>How common are duplicate tags in your project?</p></li> +<li><p>Does your editor provide any facilities for dealing with duplicate +tags?</p> +<p>While standard vi does not, many modern vi implementations, such +as Vim have good facilities for selecting the desired match from +the list of duplicates. If your editor does not support duplicate +tags, then it will typically send you to only one of them, whether +or not that is the one you wanted (and not even notifying you that +there are other potential matches).</p> +</li> +<li><p>What is the significance of duplicate tags?</p> +<p>For example, if you have two tags of the same name from entirely +isolated software components, jumping first to the match found +in component B while working in component A may be entirely +misleading, distracting or inconvenient (to keep having to choose +which one if your editor provides you with a list of matches). +However, if you have two tags of the same name for parallel builds +(say two initialization routines for different hosts), you may +always want to specify which one you want.</p> +</li> +</ol> +</li> +</ol> +<p>Of the approaches listed above, I tend to favor Approach 3. My editor of +choice is Vim, which provides a rich set of features for handling multiple +tag files, which partly influences my choice. If you are working with +source files on a remote file system, then I would recommend either +Approach 3 or Approach 4, depending upon the hit when reading the global +tag file.</p> +<p>The advantages of Approach 3 are many (assuming that your editor has +the ability to support both multiple tag files and duplicate tags). All +lookups of tag located in the current directory are fast and the local +tag file can be quickly and easily regenerated in one second or less +(I have even mapped a keystroke to do this easily). A lookup of a +(necessarily non-static) tag found in another directory fails a lookup in +the local tag file, but is found in the global tag file, which satisfies +all cross-directory lookups. The global tag file can be automatically +regenerated periodically with a cron job (and perhaps the local tag files +also).</p> +<p>Now I give an example of how you would implement Approach 3. Means of +implementing the other approaches can be performed in a similar manner.</p> +<p>Here is a visual representation of an example directory hierarchy:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>project +`-----misccomp +| `... +`-----sysint + `-----client + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----common + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----server + `-----hdrs + `-----lib + `-----src + `-----test +</pre></div> +</div> +<p>Here is a recommended solution (conceptually) to build the tag files:</p> +<ol class="arabic"> +<li><p>Within each of the leaf nodes (i.e. <code class="docutils literal notranslate"><span class="pre">hdrs</span></code>, <code class="docutils literal notranslate"><span class="pre">lib</span></code>, <code class="docutils literal notranslate"><span class="pre">src</span></code>, <code class="docutils literal notranslate"><span class="pre">test</span></code>) build a tag +file using “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">*.[ch]</span></code>”. This can be easily be done for the whole +hierarchy by making a shell script, call it <code class="docutils literal notranslate"><span class="pre">dirtags</span></code>, containing the +following lines:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span> +<span class="nb">cd</span> <span class="nv">$1</span> +ctags * +</pre></div> +</div> +</div></blockquote> +<p>Now execute the following command:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>find * -type d -exec dirtags <span class="o">{}</span> <span class="se">\;</span> +</pre></div> +</div> +</div></blockquote> +<p>These tag files are trivial (and extremely quick) to rebuild while +making changes within a directory. The following Vim key mapping is +quite useful to rebuild the tag file in the directory of the current +source file:</p> +<blockquote> +<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>:nmap ,t :!(cd %:p:h;ctags *.[ch])&<CR><CR> +</pre></div> +</div> +</div></blockquote> +</li> +<li><p>Build the global tag file:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> ~/project +ctags --file-scope<span class="o">=</span>no -R +</pre></div> +</div> +</div></blockquote> +<p>thus constructing a tag file containing only non-static tags for all +source files in all descendent directories.</p> +</li> +<li><p>Configure your editor to read the local tag file first, then consult +the global tag file when not found in the local tag file. In Vim, +this is done as follows:</p> +<blockquote> +<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>:set tags=./tags,tags,~/project/tags +</pre></div> +</div> +</div></blockquote> +</li> +</ol> +<p>If you wish to implement Approach 4, you would need to replace the +<code class="docutils literal notranslate"><span class="pre">dirtags</span></code> script of step 1 with the following:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/sh</span> +<span class="nb">cd</span> <span class="nv">$1</span> +ctags * +<span class="c1"># Now append the non-static tags from descendent directories</span> +find * -type d -prune -print <span class="p">|</span> ctags -aR --file-scope<span class="o">=</span>no -L- +</pre></div> +</div> +</div></blockquote> +<p>And replace the configuration of step 3 with this:</p> +<blockquote> +<div><div class="highlight-text notranslate"><div class="highlight"><pre><span></span>:set tags=./tags;$HOME,tags +</pre></div> +</div> +</div></blockquote> +<p>As a caveat, it should be noted that step 2 builds a global tag file whose +file names will be relative to the directory in which the global tag file +is being built. This takes advantage of the Vim <code class="docutils literal notranslate"><span class="pre">tagrelative</span></code> option, +which causes the path to be interpreted a relative to the location of the +tag file instead of the current directory. For standard vi, which always +interprets the paths as relative to the current directory, we need to +build the global tag file with absolute path names. This can be +accomplished by replacing step 2 with the following:</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> ~/project +ctags --file-scope<span class="o">=</span>no -R <span class="sb">`</span><span class="nb">pwd</span><span class="sb">`</span> +</pre></div> +</div> +</div></blockquote> +</section> +<section id="does-universal-ctags-support-unicode-file-names"> +<h3><a class="toc-backref" href="#id13">Does Universal Ctags support Unicode file names?</a><a class="headerlink" href="#does-universal-ctags-support-unicode-file-names" title="Permalink to this headline">¶</a></h3> +<p>Yes, Unicode file names are supported on unix-like platforms (Linux, macOS, +Cygwin, etc.).</p> +<p>However, on Windows, you need to use Windows 10 version 1903 or later to use +Unicode file names. (This is an experimental feature, though.) On older versions +on Windows, Universal Ctags only support file names represented in the current +code page. If you still want to use Unicode file names on them, use Cygwin or +MSYS2 version of Universal Ctags as a workaround.</p> +</section> +<section id="why-does-zsh-cause-zsh-no-matches-found-error"> +<h3><a class="toc-backref" href="#id14">Why does zsh cause “zsh: no matches found” error?</a><a class="headerlink" href="#why-does-zsh-cause-zsh-no-matches-found-error" title="Permalink to this headline">¶</a></h3> +<p>zsh causes error on the following cases;</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags --extra<span class="o">=</span>+* ... +ctags --exclude<span class="o">=</span>foo/* ... +</pre></div> +</div> +</div></blockquote> +<p>This is the 2nd most significant incompatibility <em>feature</em> of zsh.</p> +<p>Cited from “Z-Shell Frequently-Asked Questions”, “<a class="reference external" href="http://zsh.sourceforge.net/FAQ/zshfaq02.html">2.1: Differences from sh and +ksh</a>”;</p> +<blockquote> +<div><p>… The next most classic difference is that unmatched glob patterns cause +the command to abort; set <code class="docutils literal notranslate"><span class="pre">NO_NOMATCH</span></code> for those.</p> +</div></blockquote> +<p>You may add “<code class="docutils literal notranslate"><span class="pre">setopt</span> <span class="pre">nonomatch</span></code>” on your <code class="docutils literal notranslate"><span class="pre">~/.zshrc</span></code>. Or you can escape glob +patterns with backslash;</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags --extra<span class="o">=</span>+<span class="se">\*</span> ... +ctags --exclude<span class="o">=</span>foo/<span class="se">\*</span> ... +</pre></div> +</div> +</div></blockquote> +<p>Or quote them;</p> +<blockquote> +<div><div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags <span class="s1">'--extra=+*'</span> ... +ctags <span class="s1">'--exclude=foo/*'</span> ... +</pre></div> +</div> +</div></blockquote> +</section> +</section> +<section id="see-also"> +<h2><a class="toc-backref" href="#id15">SEE ALSO</a><a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a></p> +</section> +<section id="author"> +<h2><a class="toc-backref" href="#id16">AUTHOR</a><a class="headerlink" href="#author" title="Permalink to this headline">¶</a></h2> +<p>This FAQ is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a> by +Darren Hiebert and <a class="reference external" href="mailto:vberthoux%40users.sourceforge.net">vberthoux<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a></p> +<p>Universal Ctags project: <a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-faq</a><ul> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags">What is the difference between Universal Ctags and Exuberant Ctags?</a></li> +<li><a class="reference internal" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time">How can I avoid having to specify my favorite option every time?</a></li> +<li><a class="reference internal" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file">What are these strange bits of text beginning with <code class="docutils literal notranslate"><span class="pre">;"</span></code> which follow many of the lines in the tag file?</a></li> +<li><a class="reference internal" href="#why-can-t-i-jump-to-class-member">Why can’t I jump to <code class="docutils literal notranslate"><span class="pre">class::member</span></code>?</a></li> +<li><a class="reference internal" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag">Why do I end up on the wrong line when I jump to a tag?</a></li> +<li><a class="reference internal" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name">How do I jump to the tag I want instead of the wrong one by the same name?</a></li> +<li><a class="reference internal" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable">How can I locate all references to a specific function or variable?</a></li> +<li><a class="reference internal" href="#why-does-appending-tags-to-a-tag-file-tag-so-long">Why does appending tags to a tag file tag so long?</a></li> +<li><a class="reference internal" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy">How should I set up tag files for a multi-level directory hierarchy?</a></li> +<li><a class="reference internal" href="#does-universal-ctags-support-unicode-file-names">Does Universal Ctags support Unicode file names?</a></li> +<li><a class="reference internal" href="#why-does-zsh-cause-zsh-no-matches-found-error">Why does zsh cause “zsh: no matches found” error?</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#author">AUTHOR</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-client-tools.7.html" + title="previous chapter">ctags-client-tools</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-iPythonCell.7.html" + title="next chapter">ctags-lang-iPythonCell</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + >next</a> |</li> + <li class="right" > + <a href="ctags-client-tools.7.html" title="ctags-client-tools" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-faq</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-incompatibilities.7.html b/ctags/docs/man/ctags-incompatibilities.7.html new file mode 100644 index 0000000..4e15f59 --- /dev/null +++ b/ctags/docs/man/ctags-incompatibilities.7.html @@ -0,0 +1,337 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-incompatibilities — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="readtags" href="readtags.1.html" /> + <link rel="prev" title="ctags-lang-sql" href="ctags-lang-sql.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="readtags.1.html" title="readtags" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-sql.7.html" title="ctags-lang-sql" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-incompatibilities</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-incompatibilities"> +<span id="ctags-incompatibilities-7"></span><h1>ctags-incompatibilities<a class="headerlink" href="#ctags-incompatibilities" title="Permalink to this headline">¶</a></h1> +<p>Incompatibilities between Universal Ctags and Exuberant Ctags</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [options] [file(s)]</div> +<div class="line"><strong>etags</strong> [options] [file(s)]</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This page describes major incompatible changes introduced to +Universal Ctags forked from Exuberant Ctags.</p> +<section id="option-files-loading-at-starting-up-time-preload-files"> +<h3>Option files loading at starting up time (preload files)<a class="headerlink" href="#option-files-loading-at-starting-up-time-preload-files" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags doesn’t load <code class="docutils literal notranslate"><span class="pre">~/.ctags</span></code> at starting up time. +File paths for preload files are changed. +See “FILES” section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="environment-variables-for-arranging-command-lines"> +<h3>Environment variables for arranging command lines<a class="headerlink" href="#environment-variables-for-arranging-command-lines" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags doesn’t read <code class="docutils literal notranslate"><span class="pre">CTAGS</span></code> and/or <code class="docutils literal notranslate"><span class="pre">ETAGS</span></code> environment +variables.</p> +</section> +<section id="incompatibilities-in-command-line-interface"> +<h3>Incompatibilities in command line interface<a class="headerlink" href="#incompatibilities-in-command-line-interface" title="Permalink to this headline">¶</a></h3> +<section id="ordering-in-a-command-line"> +<h4>Ordering in a command line<a class="headerlink" href="#ordering-in-a-command-line" title="Permalink to this headline">¶</a></h4> +<p>The command line format of Universal Ctags is “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">[options]</span> +<span class="pre">[source_file(s)]</span></code>” following the standard POSIX convention.</p> +<p>Exuberant Ctags accepts a option following a source file.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - foo.c --list-kinds<span class="o">=</span>Sh +<span class="go">f functions</span> +</pre></div> +</div> +<p>Universal Ctags warns and ignores the option <code class="docutils literal notranslate"><span class="pre">--list-kinds=Sh</span></code> as follows.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - foo.c --list-kinds<span class="o">=</span>Sh +<span class="go">ctags: Warning: cannot open input file "--list-kinds=Sh" : No such file or directory</span> +<span class="go">a foo.c /^void a () {}$/;" f typeref:typename:void</span> +<span class="go">b foo.c /^void b () {}$/;" f typeref:typename:void</span> +</pre></div> +</div> +</section> +<section id="the-order-of-application-of-patterns-and-extensions-in-langmap"> +<h4>The order of application of patterns and extensions in <code class="docutils literal notranslate"><span class="pre">--langmap</span></code><a class="headerlink" href="#the-order-of-application-of-patterns-and-extensions-in-langmap" title="Permalink to this headline">¶</a></h4> +<p>When applying mappings for a name of given source file, +Exuberant Ctags tests file name patterns <em>AFTER</em> file extensions +(<em>e-map-order</em>). Universal Ctags does this differently; it tests file +name patterns <em>BEFORE</em> file extensions (<em>u-map-order</em>).</p> +<p>This incompatible change is introduced to deal with the following +situation:</p> +<blockquote> +<div><ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">build.xml</span></code> as a source file,</p></li> +<li><p>The Ant parser declares it handles a file name pattern <code class="docutils literal notranslate"><span class="pre">build.xml</span></code>, and</p></li> +<li><p>The XML parser declares it handles a file extension <code class="docutils literal notranslate"><span class="pre">.xml</span></code>.</p></li> +</ul> +</div></blockquote> +<p>Which parser should be used for parsing <code class="docutils literal notranslate"><span class="pre">build.xml</span></code>? The assumption +of Universal Ctags is the user may want to use the Ant parser; the +file name pattern it declares is more specific than the file extension +that the XML parser declares. However, e-map-order chooses the XML +parser.</p> +<p>So Universal Ctags uses the u-map-order even though it introduces an +incompatibility.</p> +<p><code class="docutils literal notranslate"><span class="pre">--list-map-extensions=<language></span></code> and <code class="docutils literal notranslate"><span class="pre">--list-map-patterns=<language></span></code> +options are helpful to verify and the file extensions and the file +name patterns of given <em><language></em>.</p> +</section> +<section id="remove-file-tags-and-file-scope-options"> +<h4>Remove <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> and <code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> options<a class="headerlink" href="#remove-file-tags-and-file-scope-options" title="Permalink to this headline">¶</a></h4> +<p>Even in Exuberant Ctags, <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> is not documented in its man page. +Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> or <code class="docutils literal notranslate"><span class="pre">--file-tags=yes</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=+f</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=+{inputFile}</span></code>.</p> +<p>Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags=no</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=-{inputFile}</span></code>.</p> +<p>Universal Ctags introduces <code class="docutils literal notranslate"><span class="pre">F/fileScope</span></code> extra as the replacement for +<code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> option.</p> +<p>Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> or <code class="docutils literal notranslate"><span class="pre">--file-tags=yes</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=+F</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=+{fileScope}</span></code>.</p> +<p>Instead of specifying <code class="docutils literal notranslate"><span class="pre">--file-tags=no</span></code>, use +<code class="docutils literal notranslate"><span class="pre">--extras=-F</span></code> or <code class="docutils literal notranslate"><span class="pre">--extras=-{fileScope}</span></code>.</p> +</section> +</section> +<section id="incompatibilities-in-language-and-kind-definitions"> +<h3>Incompatibilities in language and kind definitions<a class="headerlink" href="#incompatibilities-in-language-and-kind-definitions" title="Permalink to this headline">¶</a></h3> +<section id="language-name-defined-with-langdef-name-option"> +<h4>Language name defined with <code class="docutils literal notranslate"><span class="pre">--langdef=name</span></code> option<a class="headerlink" href="#language-name-defined-with-langdef-name-option" title="Permalink to this headline">¶</a></h4> +<p>The characters you can use are more restricted than Exuberant Ctags. +For more details, see the description of <code class="docutils literal notranslate"><span class="pre">--langdef=name</span></code> in <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +</section> +<section id="obsoleting-lang-kinds-option"> +<h4>Obsoleting <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> option<a class="headerlink" href="#obsoleting-lang-kinds-option" title="Permalink to this headline">¶</a></h4> +<p>Some options have <em><LANG></em> as parameterized parts in their name like +<code class="docutils literal notranslate"><span class="pre">--foo-<LANG>=...</span></code> or <code class="docutils literal notranslate"><span class="pre">--<LANG>-foo=...</span></code>. The most of all such +options in Exuberant Ctags have the former form, <code class="docutils literal notranslate"><span class="pre">--foo-<LANG>=...</span></code>. +The exception is <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code>.</p> +<p>Universal Ctags uses the former form for all <em><LANG></em> parameterized +option. Use <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> instead of <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> in +Universal Ctags. <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> still works but it will be +removed in the future.</p> +<p>The former form may be friendly to shell completion engines.</p> +</section> +<section id="disallowing-to-define-a-kind-with-file-as-name"> +<h4>Disallowing to define a kind with <code class="docutils literal notranslate"><span class="pre">file</span></code> as name<a class="headerlink" href="#disallowing-to-define-a-kind-with-file-as-name" title="Permalink to this headline">¶</a></h4> +<p>The kind name <code class="docutils literal notranslate"><span class="pre">file</span></code> is reserved. Using it as part of kind spec in +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option is now disallowed.</p> +</section> +<section id="disallowing-to-define-a-kind-with-f-as-letter"> +<h4>Disallowing to define a kind with ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ as letter<a class="headerlink" href="#disallowing-to-define-a-kind-with-f-as-letter" title="Permalink to this headline">¶</a></h4> +<p>The kind letter ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ is reserved. Using it as part of a kind spec in +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option is now disallowed.</p> +</section> +<section id="disallowing-to-use-other-than-alphabetical-character-as-kind-letter"> +<h4>Disallowing to use other than alphabetical character as kind letter<a class="headerlink" href="#disallowing-to-use-other-than-alphabetical-character-as-kind-letter" title="Permalink to this headline">¶</a></h4> +<p>Exuberant Ctags accepts a character other than alphabetical character +as kind letter in <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=...</span></code> option. Universal Ctags +accepts only an alphabetical character.</p> +</section> +<section id="acceptable-characters-as-parts-of-a-kind-name"> +<h4>Acceptable characters as parts of a kind name<a class="headerlink" href="#acceptable-characters-as-parts-of-a-kind-name" title="Permalink to this headline">¶</a></h4> +<p>Exuberant Ctags accepts any character as a part of a kind name +defined with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/regex/replacement/kind-spec/</span></code>.</p> +<p>Universal Ctags accepts only an alphabetical character as +the initial letter of a kind name. +Universal Ctags accepts only an alphabetical character or +numerical character as the rest letters.</p> +<p>An example:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i +</pre></div> +</div> +<p>Universal Ctags rejects this because the kind name, <code class="docutils literal notranslate"><span class="pre">abstract</span> <span class="pre">class</span></code>, +includes a whitespace character.</p> +<p>This requirement is for making the output of Universal Ctags follow +the tags file format.</p> +</section> +<section id="a-combination-of-a-kind-letter-and-a-kind-name"> +<h4>A combination of a kind letter and a kind name<a class="headerlink" href="#a-combination-of-a-kind-letter-and-a-kind-name" title="Permalink to this headline">¶</a></h4> +<p>In Universal Ctags, the combination of +a kind letter and a kind name must be unique in a language.</p> +<p>You cannot define more than one kind reusing a kind letter with +different kind names. You cannot define more than one kind reusing a +kind name with different kind letters.</p> +<p>An example:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i +--regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i +</pre></div> +</div> +<p>Universal Ctags rejects this because the kind letter, ‘<code class="docutils literal notranslate"><span class="pre">a</span></code>’, used twice +for defining a kind <code class="docutils literal notranslate"><span class="pre">abstractClass</span></code> and <code class="docutils literal notranslate"><span class="pre">attribute</span></code>.</p> +</section> +</section> +<section id="incompatibilities-in-tags-file-format"> +<h3>Incompatibilities in tags file format<a class="headerlink" href="#incompatibilities-in-tags-file-format" title="Permalink to this headline">¶</a></h3> +<section id="using-numerical-character-in-the-name-part-of-tag-tagfield"> +<h4>Using numerical character in the name part of tag tagfield<a class="headerlink" href="#using-numerical-character-in-the-name-part-of-tag-tagfield" title="Permalink to this headline">¶</a></h4> +<p>The version 2 tags file format, the default output format of +Exuberant Ctags, accepts only alphabetical characters in the name part +of tag tagfield.</p> +<p>Universal Ctags introduces an exception to this specification; it may +use numerical characters in addition to alphabetical characters as the +letters other than initial letter of the name part.</p> +<p>The kinds <code class="docutils literal notranslate"><span class="pre">heading1</span></code>, <code class="docutils literal notranslate"><span class="pre">heading2</span></code>, and <code class="docutils literal notranslate"><span class="pre">heading3</span></code> in the HTML parser +are the examples.</p> +</section> +<section id="truncating-the-pattern-for-long-input-lines"> +<h4>Truncating the pattern for long input lines<a class="headerlink" href="#truncating-the-pattern-for-long-input-lines" title="Permalink to this headline">¶</a></h4> +<p>To prevent generating overly large tags files, a pattern field is +truncated, by default, when its size exceeds 96 bytes. A different +limit can be specified with <code class="docutils literal notranslate"><span class="pre">--pattern-length-limit=N</span></code>. Specifying +0 as <em>N</em> results no truncation as Exuberant Ctags does not.</p> +</section> +<section id="kind-letters-and-names"> +<h4>Kind letters and names<a class="headerlink" href="#kind-letters-and-names" title="Permalink to this headline">¶</a></h4> +<p>A kind letter ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ and a kind name <code class="docutils literal notranslate"><span class="pre">file</span></code> are reserved in the +main part. A parser cannot have a kind conflicting with +these reserved ones. Some incompatible changes are introduced +to follow the above rule.</p> +<ul class="simple"> +<li><p>Cobol’s <code class="docutils literal notranslate"><span class="pre">file</span></code> kind is renamed to <code class="docutils literal notranslate"><span class="pre">fileDesc</span></code> because the +kind name <code class="docutils literal notranslate"><span class="pre">file</span></code> is reserved.</p></li> +<li><p>Ruby’s ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ (singletonMethod) is changed to ‘<code class="docutils literal notranslate"><span class="pre">S</span></code>’.</p></li> +<li><p>SQL’s ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ (field) is changed to ‘<code class="docutils literal notranslate"><span class="pre">E</span></code>’.</p></li> +</ul> +</section> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>, and <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-incompatibilities</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#option-files-loading-at-starting-up-time-preload-files">Option files loading at starting up time (preload files)</a></li> +<li><a class="reference internal" href="#environment-variables-for-arranging-command-lines">Environment variables for arranging command lines</a></li> +<li><a class="reference internal" href="#incompatibilities-in-command-line-interface">Incompatibilities in command line interface</a><ul> +<li><a class="reference internal" href="#ordering-in-a-command-line">Ordering in a command line</a></li> +<li><a class="reference internal" href="#the-order-of-application-of-patterns-and-extensions-in-langmap">The order of application of patterns and extensions in <code class="docutils literal notranslate"><span class="pre">--langmap</span></code></a></li> +<li><a class="reference internal" href="#remove-file-tags-and-file-scope-options">Remove <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> and <code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> options</a></li> +</ul> +</li> +<li><a class="reference internal" href="#incompatibilities-in-language-and-kind-definitions">Incompatibilities in language and kind definitions</a><ul> +<li><a class="reference internal" href="#language-name-defined-with-langdef-name-option">Language name defined with <code class="docutils literal notranslate"><span class="pre">--langdef=name</span></code> option</a></li> +<li><a class="reference internal" href="#obsoleting-lang-kinds-option">Obsoleting <code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds</span></code> option</a></li> +<li><a class="reference internal" href="#disallowing-to-define-a-kind-with-file-as-name">Disallowing to define a kind with <code class="docutils literal notranslate"><span class="pre">file</span></code> as name</a></li> +<li><a class="reference internal" href="#disallowing-to-define-a-kind-with-f-as-letter">Disallowing to define a kind with ‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ as letter</a></li> +<li><a class="reference internal" href="#disallowing-to-use-other-than-alphabetical-character-as-kind-letter">Disallowing to use other than alphabetical character as kind letter</a></li> +<li><a class="reference internal" href="#acceptable-characters-as-parts-of-a-kind-name">Acceptable characters as parts of a kind name</a></li> +<li><a class="reference internal" href="#a-combination-of-a-kind-letter-and-a-kind-name">A combination of a kind letter and a kind name</a></li> +</ul> +</li> +<li><a class="reference internal" href="#incompatibilities-in-tags-file-format">Incompatibilities in tags file format</a><ul> +<li><a class="reference internal" href="#using-numerical-character-in-the-name-part-of-tag-tagfield">Using numerical character in the name part of tag tagfield</a></li> +<li><a class="reference internal" href="#truncating-the-pattern-for-long-input-lines">Truncating the pattern for long input lines</a></li> +<li><a class="reference internal" href="#kind-letters-and-names">Kind letters and names</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-sql.7.html" + title="previous chapter">ctags-lang-sql</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="readtags.1.html" + title="next chapter">readtags</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="readtags.1.html" title="readtags" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-sql.7.html" title="ctags-lang-sql" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-incompatibilities</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-lang-iPythonCell.7.html b/ctags/docs/man/ctags-lang-iPythonCell.7.html new file mode 100644 index 0000000..84be1b1 --- /dev/null +++ b/ctags/docs/man/ctags-lang-iPythonCell.7.html @@ -0,0 +1,186 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-lang-iPythonCell — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-lang-julia" href="ctags-lang-julia.7.html" /> + <link rel="prev" title="ctags-faq" href="ctags-faq.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-lang-julia.7.html" title="ctags-lang-julia" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-faq.7.html" title="ctags-faq" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-iPythonCell</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-ipythoncell"> +<span id="ctags-lang-ipythoncell-7"></span><h1>ctags-lang-iPythonCell<a class="headerlink" href="#ctags-lang-ipythoncell" title="Permalink to this headline">¶</a></h1> +<p>The man page of the iPythonCell parser for Universal Ctags</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> … --extras={subparser} --languages=+iPythonCell,Python \</div> +<div class="line-block"> +<div class="line">[--extras-IPythonCell=+{doubleSharps}] \</div> +<div class="line">[--regex-IPythonCell=/<PATTERN>/\n/c/] …</div> +</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>iPythonCell is a subparser stacked on top of the Python parser. +It works when:</p> +<ul class="simple"> +<li><p>The Python parser is enabled,</p></li> +<li><p>the <code class="docutils literal notranslate"><span class="pre">subparser</span></code> extra is enabeld, and</p></li> +<li><p>the iPythonCell parser itself is enabled.</p></li> +</ul> +<p>iPythonCell extracts cells explained as in vim-ipython-cell +(<a class="reference external" href="https://github.com/hanschen/vim-ipython-cell/blob/master/README.md">https://github.com/hanschen/vim-ipython-cell/blob/master/README.md</a>).</p> +</section> +<section id="kind-s"> +<h2>KIND(S)<a class="headerlink" href="#kind-s" title="Permalink to this headline">¶</a></h2> +<p>The iPythonCell parser defines only a <code class="docutils literal notranslate"><span class="pre">cell</span></code> kind.</p> +</section> +<section id="extra-s"> +<h2>EXTRA(S)<a class="headerlink" href="#extra-s" title="Permalink to this headline">¶</a></h2> +<p>Tagging cells staring with <code class="docutils literal notranslate"><span class="pre">##...</span></code> is disabled by default because +the pattern is too generic; with that pattern unwanted tags can be extracted.</p> +<p>Enable <code class="docutils literal notranslate"><span class="pre">doubleSharps</span></code> language specific extra for tagging cells +staring with <code class="docutils literal notranslate"><span class="pre">##...</span></code>.</p> +</section> +<section id="customizing"> +<h2>CUSTOMIZING<a class="headerlink" href="#customizing" title="Permalink to this headline">¶</a></h2> +<p>If your favorite cell pattern is not supported in the parser, you can +define the pattern in your <code class="docutils literal notranslate"><span class="pre">.ctagd.d/your.ctags</span></code> or command lines. +Here is an example how to support “<code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">CTAGS:</span> <span class="pre">...</span></code>”:</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="n">x</span><span class="o">=</span><span class="mi">1</span> +<span class="c1"># CTAGS: DEFINE F</span> +<span class="k">def</span> <span class="nf">F</span><span class="p">():</span> + <span class="c1"># CTAGS: DO NOTING</span> + <span class="k">pass</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE --sort=no --extras=+{subparser} --regex-IPythonCell=/[ t]*# CTAGS:[ ]?(.*)$/1/c/ -o - input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>x input.py /^x=1$/;" v +DEFINE F input.py /^# CTAGS: DEFINE F$/;" c +F input.py /^def F():$/;" f +DO NOTING input.py /^ # CTAGS: DO NOTING$/;" c +</pre></div> +</div> +<p>You can put “<code class="docutils literal notranslate"><span class="pre">--regex-IPythonCell=/[</span> <span class="pre">\t]*#</span> <span class="pre">CTAGS:[</span> <span class="pre">]?(.*)$/\1/c/</span></code>” in <code class="docutils literal notranslate"><span class="pre">your.ctags</span></code> +to avoid specifying the pattern repeatedly.</p> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a>, <a class="reference internal" href="ctags-lang-python.7.html#ctags-lang-python-7"><span class="std std-ref">ctags-lang-python(7)</span></a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-lang-iPythonCell</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#kind-s">KIND(S)</a></li> +<li><a class="reference internal" href="#extra-s">EXTRA(S)</a></li> +<li><a class="reference internal" href="#customizing">CUSTOMIZING</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-faq.7.html" + title="previous chapter">ctags-faq</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-julia.7.html" + title="next chapter">ctags-lang-julia</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-lang-julia.7.html" title="ctags-lang-julia" + >next</a> |</li> + <li class="right" > + <a href="ctags-faq.7.html" title="ctags-faq" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-iPythonCell</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-lang-inko.7.html b/ctags/docs/man/ctags-lang-inko.7.html new file mode 100644 index 0000000..78d9968 --- /dev/null +++ b/ctags/docs/man/ctags-lang-inko.7.html @@ -0,0 +1,141 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-lang-inko — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-lang-r" href="ctags-lang-r.7.html" /> + <link rel="prev" title="ctags-lang-verilog" href="ctags-lang-verilog.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-lang-r.7.html" title="ctags-lang-r" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-verilog.7.html" title="ctags-lang-verilog" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-inko</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-inko"> +<span id="ctags-lang-inko-7"></span><h1>ctags-lang-inko<a class="headerlink" href="#ctags-lang-inko" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> … --languages=+Inko …</div> +<div class="line"><strong>ctags</strong> … --language-force=Inko …</div> +<div class="line"><strong>ctags</strong> … --map-Inko=+.inko …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page describes the Inko parser for Universal Ctags.</p> +<p>The input file is expected to be valid Inko source code, otherwise the output of +ctags is undefined.</p> +<p>Tags are generated for objects, traits, methods, attributes, and constants. +String literals are ignored.</p> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-lang-inko</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-verilog.7.html" + title="previous chapter">ctags-lang-verilog</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-r.7.html" + title="next chapter">ctags-lang-r</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-lang-r.7.html" title="ctags-lang-r" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-verilog.7.html" title="ctags-lang-verilog" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-inko</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-lang-julia.7.html b/ctags/docs/man/ctags-lang-julia.7.html new file mode 100644 index 0000000..a420c5e --- /dev/null +++ b/ctags/docs/man/ctags-lang-julia.7.html @@ -0,0 +1,332 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-lang-julia — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-lang-python" href="ctags-lang-python.7.html" /> + <link rel="prev" title="ctags-lang-iPythonCell" href="ctags-lang-iPythonCell.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-lang-python.7.html" title="ctags-lang-python" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-julia</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-julia"> +<span id="ctags-lang-julia-7"></span><h1>ctags-lang-julia<a class="headerlink" href="#ctags-lang-julia" title="Permalink to this headline">¶</a></h1> +<p>Random notes about tagging Julia source code with Universal-ctags</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal-ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> … --languages=+Julia …</div> +<div class="line"><strong>ctags</strong> … --language-force=Julia …</div> +<div class="line"><strong>ctags</strong> … --map-Julia=+.jl …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page gathers random notes about tagging Julia source code.</p> +</section> +<section id="tagging-import-and-using-expressions"> +<h2>TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> AND <code class="docutils literal notranslate"><span class="pre">using</span></code> EXPRESSIONS<a class="headerlink" href="#tagging-import-and-using-expressions" title="Permalink to this headline">¶</a></h2> +<section id="summary"> +<h3>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h3> +<p><cite>using X</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>used</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>using X: a, b</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>a, b</p></td> +<td><p>unknown</p></td> +<td><p>used</p></td> +<td><p>scope:module:X</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>imported</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X.a, Y.b</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X, Y</p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>a</p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:X</p></td> +</tr> +<tr class="row-even"><td><p>b</p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:Y</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X: a, b</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>a,b</p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:X</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="examples"> +<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3> +<p>“input.jl”</p> +<div class="highlight-Julia notranslate"><div class="highlight"><pre><span></span><span class="k">using</span> <span class="n">X0</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK input.jl”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X0 input.jl /^using X0$/;" kind:module roles:used +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--extras=+r</span></code> (or <code class="docutils literal notranslate"><span class="pre">--extras=+{reference}</span></code>) option is needed for this tag, +since it’s a reference tag. This is because module <code class="docutils literal notranslate"><span class="pre">X</span></code> is not defined here. +It is defined in another file. Enable <code class="docutils literal notranslate"><span class="pre">roles:</span></code> field with <code class="docutils literal notranslate"><span class="pre">--fields=+r</span></code> is +for recording that the module is “used”, i.e., loaded by <code class="docutils literal notranslate"><span class="pre">using</span></code>.</p> +<p>“input.jl”</p> +<div class="highlight-Julia notranslate"><div class="highlight"><pre><span></span><span class="k">import</span> <span class="n">X1</span><span class="o">.</span><span class="n">a</span><span class="p">,</span> <span class="n">X2</span><span class="o">.</span><span class="n">b</span><span class="p">,</span> <span class="n">X3</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzKZ input.jl”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X1 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace +X2 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace +X3 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:imported +a input.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X1 roles:imported +b input.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X2 roles:imported +</pre></div> +</div> +<p>Why <code class="docutils literal notranslate"><span class="pre">X1</span></code> and <code class="docutils literal notranslate"><span class="pre">X2</span></code> have role “namespace”, while <code class="docutils literal notranslate"><span class="pre">X3</span></code> have role “imported”? +It’s because the symbol <code class="docutils literal notranslate"><span class="pre">a</span></code> in module <code class="docutils literal notranslate"><span class="pre">X1</span></code>, and <code class="docutils literal notranslate"><span class="pre">b</span></code> in module <code class="docutils literal notranslate"><span class="pre">X2</span></code> are +brought to the current scope, but <code class="docutils literal notranslate"><span class="pre">X1</span></code> and <code class="docutils literal notranslate"><span class="pre">X2</span></code> themselves are not. We use +“namespace” role for such modules.</p> +<p><code class="docutils literal notranslate"><span class="pre">X3</span></code> is different. The symbol <code class="docutils literal notranslate"><span class="pre">X3</span></code>, together with all exported symbols in +<code class="docutils literal notranslate"><span class="pre">X3</span></code>, is brought to current scope. For such modules, we use “imported” or +“used” role depending whether they are loaded by <code class="docutils literal notranslate"><span class="pre">import</span></code> or <code class="docutils literal notranslate"><span class="pre">using</span></code>.</p> +<p>Also, notice that <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> have the “unknown” kind. This is because we +cannot know whether it’s a function, constant, or macro, etc.</p> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-lang-julia</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#tagging-import-and-using-expressions">TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> AND <code class="docutils literal notranslate"><span class="pre">using</span></code> EXPRESSIONS</a><ul> +<li><a class="reference internal" href="#summary">Summary</a></li> +<li><a class="reference internal" href="#examples">Examples</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-iPythonCell.7.html" + title="previous chapter">ctags-lang-iPythonCell</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-python.7.html" + title="next chapter">ctags-lang-python</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-lang-python.7.html" title="ctags-lang-python" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-iPythonCell.7.html" title="ctags-lang-iPythonCell" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-julia</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-lang-python.7.html b/ctags/docs/man/ctags-lang-python.7.html new file mode 100644 index 0000000..fcd72c4 --- /dev/null +++ b/ctags/docs/man/ctags-lang-python.7.html @@ -0,0 +1,476 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-lang-python — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-lang-verilog" href="ctags-lang-verilog.7.html" /> + <link rel="prev" title="ctags-lang-julia" href="ctags-lang-julia.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-lang-verilog.7.html" title="ctags-lang-verilog" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-julia.7.html" title="ctags-lang-julia" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-python</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-python"> +<span id="ctags-lang-python-7"></span><h1>ctags-lang-python<a class="headerlink" href="#ctags-lang-python" title="Permalink to this headline">¶</a></h1> +<p>Random notes about tagging python source code with Universal Ctags</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> … --languages=+Python …</div> +<div class="line"><strong>ctags</strong> … --language-force=Python …</div> +<div class="line"><strong>ctags</strong> … --map-Python=+.py …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page gathers random notes about tagging python source code.</p> +</section> +<section id="tagging-import-statements"> +<h2>TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> STATEMENTS<a class="headerlink" href="#tagging-import-statements" title="Permalink to this headline">¶</a></h2> +<section id="summary"> +<h3>Summary<a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h3> +<p><cite>import X</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>imported</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>import X as Y</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>X</p></td> +<td><p>module</p></td> +<td><p>indirectlyImported</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p>Y</p></td> +<td><p>namespace</p></td> +<td><p>definition</p></td> +<td><p>nameref:module:X</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>from X import *</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>X</cite></p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>from X import Y</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>X</cite></p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p><cite>Y</cite></p></td> +<td><p>unknown</p></td> +<td><p>imported</p></td> +<td><p>scope:module:<cite>X</cite></p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>from X import Y as Z</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 7%" /> +<col style="width: 18%" /> +<col style="width: 33%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>X</cite></p></td> +<td><p>module</p></td> +<td><p>namespace</p></td> +<td><p>N/A</p></td> +</tr> +<tr class="row-odd"><td><p><cite>Y</cite></p></td> +<td><p>unknown</p></td> +<td><p>indirectlyImported</p></td> +<td><p>scope:module:<cite>X</cite></p></td> +</tr> +<tr class="row-even"><td><p><cite>Z</cite></p></td> +<td><p>unknown</p></td> +<td><p>definition</p></td> +<td><p>nameref:unknown:<cite>X</cite></p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="examples"> +<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">X0</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X0 input.py /^import X0$/;" kind:module roles:imported +</pre></div> +</div> +<p>A tag for an imported module has <code class="docutils literal notranslate"><span class="pre">module</span></code> kind with <code class="docutils literal notranslate"><span class="pre">imported</span></code> role. The +module is not defined here; it is defined in another file. So the tag for the +imported module is a reference tag; specify <code class="docutils literal notranslate"><span class="pre">--extras=+r</span></code> (or +<code class="docutils literal notranslate"><span class="pre">--extras=+{reference}</span></code>) option for tagging it. “roles:” field enabled with +<code class="docutils literal notranslate"><span class="pre">--fields=+r</span></code> is for recording the module is “imported” to the tag file.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">X1</span> <span class="k">as</span> <span class="nn">Y1</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK --fields-Python=+{nameref} input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X1 input.py /^import X1 as Y1$/;" kind:module roles:indirectlyImported +Y1 input.py /^import X1 as Y1$/;" kind:namespace roles:def nameref:module:X1 +</pre></div> +</div> +<p>“Y1” introduces a new name and is defined here. So “Y1” is tagged as a +definition tag. “X1” is imported in a way that its name cannot be used +in this source file. For letting client tools know that the name cannot be used, +<code class="docutils literal notranslate"><span class="pre">indirectlyImported</span></code> role is assigned for “X1”. “Y1” is the name for +accessing objects defined in the module imported via “X1”. For recording this +relationship, <code class="docutils literal notranslate"><span class="pre">nameref:</span></code> field is attached to the tag of “Y1”. Instead of +<code class="docutils literal notranslate"><span class="pre">module</span></code> kind, <code class="docutils literal notranslate"><span class="pre">namespace</span></code> kind is assigned to “Y1” because “Y1” itself +isn’t a module.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">X2</span> <span class="kn">import</span> <span class="o">*</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzK input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X2 input.py /^from X2 import *$/;" kind:module roles:namespace +</pre></div> +</div> +<p>The module is not defined here; it is defined in another file. So the tag for +the imported module is a reference tag. Unlike “X0” in “import X0”, “X2” may not +be used because the names defined in “X2” can be used in this source file. To represent +the difference <code class="docutils literal notranslate"><span class="pre">namespace</span></code> role is attached to “X2” instead of <code class="docutils literal notranslate"><span class="pre">imported</span></code>.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">X3</span> <span class="kn">import</span> <span class="n">Y3</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzKZ input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X3 input.py /^from X3 import Y3$/;" kind:module roles:namespace +Y3 input.py /^from X3 import Y3$/;" kind:unknown scope:module:X3 roles:imported +</pre></div> +</div> +<p>“Y3” is a name for a language object defined in “X3” module. “scope:module:X3” +attached to “Y3” represents this relation between “Y3” and “X3”. ctags +assigns <code class="docutils literal notranslate"><span class="pre">unknown</span></code> kind to “Y3” because ctags cannot know whether “Y3” is a +class, a variable, or a function from the input file.</p> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">X4</span> <span class="kn">import</span> <span class="n">Y4</span> <span class="k">as</span> <span class="n">Z4</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --extras=+r --fields=+rzKZ input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>X4 input.py /^from X4 import Y4 as Z4$/;" kind:module roles:namespace +Y4 input.py /^from X4 import Y4 as Z4$/;" kind:unknown scope:module:X4 roles:indirectlyImported +Z4 input.py /^from X4 import Y4 as Z4$/;" kind:unknown roles:def nameref:unknown:Y4 +</pre></div> +</div> +<p>“Y4” is similar to “Y3” of “from X3 import Y3” but the name cannot be used here. +<code class="docutils literal notranslate"><span class="pre">indirectlyImported</span></code> role assigned to “Y4” representing this. “Z4” is the name for +accessing the language object named in “Y4” in “X4” module. “nameref:unknown:Y4” +attached to “Z4” and “scope:module:X4” attached to “Y4” represent the relations.</p> +</section> +</section> +<section id="lambda-expression-and-type-hint"> +<h2>LAMBDA EXPRESSION AND TYPE HINT<a class="headerlink" href="#lambda-expression-and-type-hint" title="Permalink to this headline">¶</a></h2> +<section id="id1"> +<h3>Summary<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p><cite>id = lambda var0: var0</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 18%" /> +<col style="width: 16%" /> +<col style="width: 29%" /> +<col style="width: 37%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>id</cite></p></td> +<td><p>function</p></td> +<td><p>definition</p></td> +<td><p>signature:(<cite>var0</cite>)</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p><cite>id_t: Callable[[int], int] = lambda var1: var1</cite></p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 10%" /> +<col style="width: 10%" /> +<col style="width: 17%" /> +<col style="width: 63%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>name</p></th> +<th class="head"><p>kind</p></th> +<th class="head"><p>role</p></th> +<th class="head"><p>other noticeable fields</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><cite>id_t</cite></p></td> +<td><p>variable</p></td> +<td><p>definition</p></td> +<td><p>typeref:typename:<cite>Callable[[int], int]</cite> nameref:function:anonFuncN</p></td> +</tr> +<tr class="row-odd"><td><p>anonFuncN</p></td> +<td><p>function</p></td> +<td><p>definition</p></td> +<td><p>signature:(<cite>var1</cite>)</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="id2"> +<h3>Examples<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p>“input.py”</p> +<div class="highlight-Python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Callable</span> +<span class="nb">id</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">var0</span><span class="p">:</span> <span class="n">var0</span> +<span class="n">id_t</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="nb">int</span><span class="p">],</span> <span class="nb">int</span><span class="p">]</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">var1</span><span class="p">:</span> <span class="n">var1</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --fields=+KS --fields-Python=+{nameref} --extras=+{anonymous} input.py”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>id input.py /^id = lambda var0: var0$/;" function signature:(var0) +id_t input.py /^id_t: Callable[[int], int] = lambda var1: var1$/;"\ + variable typeref:typename:Callable[[int], int] nameref:function:anonFunc84011d2c0101 +anonFunc84011d2c0101 input.py /^id_t: Callable[[int], int] = lambda var1: var1$/;"\ + function signature:(var1) +</pre></div> +</div> +<p>If a variable (“id”) with no type hint is initialized with a lambda expression, +ctags assigns <code class="docutils literal notranslate"><span class="pre">function</span></code> kind for the tag of “id”.</p> +<p>If a variable (“id_t”) with a type hint is initialized with a lambda expression, +ctags assigns <code class="docutils literal notranslate"><span class="pre">variable</span></code> kind for the tag of “id_t” with <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> and +<code class="docutils literal notranslate"><span class="pre">nameref:</span></code> fields. ctags fills <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field with the value of the type +hint. The way of filling <code class="docutils literal notranslate"><span class="pre">nameref:</span></code> is a bit complicated.</p> +<p>For the lambda expression used in initializing the type-hint’ed variable, ctags +creates <code class="docutils literal notranslate"><span class="pre">anonymous</span></code> extra tag (“anonFunc84011d2c0101”). ctags fills the +<code class="docutils literal notranslate"><span class="pre">nameref:</span></code> field of “id_t” with the name of <code class="docutils literal notranslate"><span class="pre">anonymous</span></code> extra tag: +“nameref:function:anonFunc84011d2c0101”.</p> +<p>You may think why ctags does so complicated, and why ctags doesn’t emit +following tags output for the input:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>id input.py /^id = \\$/;" function signature:(var0) +id_t input.py /^id_t: \\$/;" function typeref:typename:Callable[[int], int] signature:(var1) +</pre></div> +</div> +<p>There is a reason. The other languages of ctags obey the following rule: ctags fills +<code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field for a tag of a callable object (like function) with the type +of its return value. If we consider “id_t” is a function, its <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field +should have “typename:int”. However, for filling <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> with “typename:int”, +ctags has to analyze “Callable[[int], int]” deeper. We don’t want to do so.</p> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a>, <a class="reference internal" href="ctags-lang-iPythonCell.7.html#ctags-lang-ipythoncell-7"><span class="std std-ref">ctags-lang-iPythonCell(7)</span></a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-lang-python</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#tagging-import-statements">TAGGING <code class="docutils literal notranslate"><span class="pre">import</span></code> STATEMENTS</a><ul> +<li><a class="reference internal" href="#summary">Summary</a></li> +<li><a class="reference internal" href="#examples">Examples</a></li> +</ul> +</li> +<li><a class="reference internal" href="#lambda-expression-and-type-hint">LAMBDA EXPRESSION AND TYPE HINT</a><ul> +<li><a class="reference internal" href="#id1">Summary</a></li> +<li><a class="reference internal" href="#id2">Examples</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-julia.7.html" + title="previous chapter">ctags-lang-julia</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-verilog.7.html" + title="next chapter">ctags-lang-verilog</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-lang-verilog.7.html" title="ctags-lang-verilog" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-julia.7.html" title="ctags-lang-julia" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-python</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-lang-r.7.html b/ctags/docs/man/ctags-lang-r.7.html new file mode 100644 index 0000000..f7f93e7 --- /dev/null +++ b/ctags/docs/man/ctags-lang-r.7.html @@ -0,0 +1,210 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-lang-r — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-lang-sql" href="ctags-lang-sql.7.html" /> + <link rel="prev" title="ctags-lang-inko" href="ctags-lang-inko.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-lang-sql.7.html" title="ctags-lang-sql" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-inko.7.html" title="ctags-lang-inko" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-r</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-r"> +<span id="ctags-lang-r-7"></span><h1>ctags-lang-r<a class="headerlink" href="#ctags-lang-r" title="Permalink to this headline">¶</a></h1> +<p>Random notes about tagging R source code with Universal Ctags</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> … --languages=+R …</div> +<div class="line"><strong>ctags</strong> … --language-force=R …</div> +<div class="line"><strong>ctags</strong> … --map-Python=+.r …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page gathers random notes about tagging R source code +with Universal Ctags.</p> +</section> +<section id="kinds"> +<h2>Kinds<a class="headerlink" href="#kinds" title="Permalink to this headline">¶</a></h2> +<p>If a variable gets a value returned from a <em>well-known constructor</em> +and the variable appears for the first time in the current input file, +the R parser makes a tag for the variable and attaches a kind +associated with the constructor to the tag regardless of whether +the variable appears in the top-level context or a function.</p> +<p>Well-known constructor and kind mapping</p> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 40%" /> +<col style="width: 60%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Constructor</p></th> +<th class="head"><p>kind</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>function()</p></td> +<td><p>function</p></td> +</tr> +<tr class="row-odd"><td><p>c()</p></td> +<td><p>vector</p></td> +</tr> +<tr class="row-even"><td><p>list()</p></td> +<td><p>list</p></td> +</tr> +<tr class="row-odd"><td><p>data.frame()</p></td> +<td><p>dataframe</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +<p>If a variable doesn’t get a value returned from one of well-known +constructors, the R parser attaches <code class="docutils literal notranslate"><span class="pre">globalVar</span></code> or <code class="docutils literal notranslate"><span class="pre">functionVar</span></code> kind +to the tag for the variable depending on the context.</p> +<p>Here is an example demonstrating the usage of the kinds:</p> +<p>“input.r”</p> +<div class="highlight-R notranslate"><div class="highlight"><pre><span></span><span class="n">G</span> <span class="o"><-</span> <span class="m">1</span> +<span class="n">v</span> <span class="o"><-</span> <span class="nf">c</span><span class="p">(</span><span class="m">1</span><span class="p">,</span> <span class="m">2</span><span class="p">)</span> +<span class="n">l</span> <span class="o"><-</span> <span class="nf">list</span><span class="p">(</span><span class="m">3</span><span class="p">,</span> <span class="m">4</span><span class="p">)</span> +<span class="n">d</span> <span class="o"><-</span> <span class="nf">data.frame</span><span class="p">(</span><span class="n">n</span> <span class="o">=</span> <span class="n">v</span><span class="p">)</span> +<span class="n">f</span> <span class="o"><-</span> <span class="nf">function</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="p">{</span> + <span class="n">g</span> <span class="o"><-</span> <span class="nf">function </span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">a</span> <span class="o">+</span> <span class="n">b</span> + <span class="n">w</span> <span class="o"><-</span> <span class="nf">c</span><span class="p">(</span><span class="m">1</span><span class="p">,</span> <span class="m">2</span><span class="p">)</span> + <span class="n">m</span> <span class="o"><-</span> <span class="nf">list </span><span class="p">(</span><span class="m">3</span><span class="p">,</span> <span class="m">4</span><span class="p">)</span> + <span class="n">e</span> <span class="o"><-</span> <span class="nf">data.frame</span><span class="p">(</span><span class="n">n</span> <span class="o">=</span> <span class="n">w</span><span class="p">)</span> + <span class="n">L</span> <span class="o"><-</span> <span class="m">2</span> +<span class="p">}</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE --sort=no --fields=+KZ -o - input.r”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>G input.r /^G <- 1$/;" globalVar +v input.r /^v <- c(1, 2)$/;" vector +l input.r /^l <- list(3, 4)$/;" list +d input.r /^d <- data.frame(n = v)$/;" dataframe +n input.r /^d <- data.frame(n = v)$/;" nameattr scope:dataframe:d +f input.r /^f <- function(a) {$/;" function +g input.r /^ g <- function (b) a + b$/;" function scope:function:f +w input.r /^ w <- c(1, 2)$/;" vector scope:function:f +m input.r /^ m <- list (3, 4)$/;" list scope:function:f +e input.r /^ e <- data.frame(n = w)$/;" dataframe scope:function:f +n input.r /^ e <- data.frame(n = w)$/;" nameattr scope:dataframe:f.e +L input.r /^ L <- 2$/;" functionVar scope:function:f +</pre></div> +</div> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-lang-r</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#kinds">Kinds</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-inko.7.html" + title="previous chapter">ctags-lang-inko</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-sql.7.html" + title="next chapter">ctags-lang-sql</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-lang-sql.7.html" title="ctags-lang-sql" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-inko.7.html" title="ctags-lang-inko" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-r</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-lang-sql.7.html b/ctags/docs/man/ctags-lang-sql.7.html new file mode 100644 index 0000000..6046469 --- /dev/null +++ b/ctags/docs/man/ctags-lang-sql.7.html @@ -0,0 +1,237 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-lang-sql — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-incompatibilities" href="ctags-incompatibilities.7.html" /> + <link rel="prev" title="ctags-lang-r" href="ctags-lang-r.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-incompatibilities.7.html" title="ctags-incompatibilities" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-r.7.html" title="ctags-lang-r" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-sql</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-sql"> +<span id="ctags-lang-sql-7"></span><h1>ctags-lang-sql<a class="headerlink" href="#ctags-lang-sql" title="Permalink to this headline">¶</a></h1> +<p>The man page of the SQL parser for Universal Ctags</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> … [--extras={guest}] --languages=+SQL …</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The SQL parser supports various SQL dialects. PostgreSQL is one of them.</p> +<p>PostgreSQL allows user-defined functions to be written in other +languages (<em>procedural languages</em>) besides SQL and C <a class="reference internal" href="#pl" id="id1"><span>[PL]</span></a>.</p> +<p>The SQL parser makes tags for language objects in the user-defined +functions written in the procedural languages if the <code class="docutils literal notranslate"><span class="pre">guest</span></code> extra +is enabled.</p> +<p>The SQL parser looks for a token coming after <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> keyword in +the source code to choose a proper guest parser.</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span>... LANGUAGE plpythonu AS '... user-defined function ' ... +... AS $$ user-defined function $$ LANGUAGE plv8 ... +</pre></div> +</div> +<p>In the above examples, <code class="docutils literal notranslate"><span class="pre">plpythonu</span></code> and <code class="docutils literal notranslate"><span class="pre">plv8</span></code> are the names of +procedural languages. The SQL parser trims <cite>pl</cite> at the start and <cite>u</cite> +at the end of the name before finding a parser ctags having. For +<code class="docutils literal notranslate"><span class="pre">plpythonu</span></code> and <code class="docutils literal notranslate"><span class="pre">`plv8</span></code>, the SQL parser extracts <code class="docutils literal notranslate"><span class="pre">python</span></code> and +<code class="docutils literal notranslate"><span class="pre">v8</span></code> as the candidates of guest parsers.</p> +<p>For <code class="docutils literal notranslate"><span class="pre">plpythonu</span></code>, ctags can run its Python parser. ctags doesn’t +have a parser named <code class="docutils literal notranslate"><span class="pre">v8</span></code>. However, JavaScript parser of ctags has +<code class="docutils literal notranslate"><span class="pre">v8</span></code> as an alias. So ctags can run the JavaScript parser as the +guest parser for <code class="docutils literal notranslate"><span class="pre">plv8</span></code>.</p> +</section> +<section id="examples"> +<h2>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> +<p>tagging code including a user-defined function in a string literal <a class="reference internal" href="#gh3006" id="id2"><span>[GH3006]</span></a>:</p> +<p>“input.sql”</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">OR</span> <span class="k">REPLACE</span> <span class="k">FUNCTION</span> <span class="n">fun1</span><span class="p">()</span> <span class="k">RETURNS</span> <span class="nb">VARCHAR</span> <span class="k">AS</span> <span class="s1">'</span> +<span class="s1">DECLARE</span> +<span class="s1"> test1_var1 VARCHAR(64) := $$ABC$$;</span> +<span class="s1"> test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$;</span> +<span class="s1"> test1_var3 INTEGER := 1;</span> +<span class="s1">BEGIN</span> +<span class="s1"> RETURN TO_CHAR(test_var3, ''000'') || test1_var1 || test1_var2;</span> +<span class="s1">END;</span> +<span class="s1">'</span> <span class="k">LANGUAGE</span> <span class="n">plpgsql</span><span class="p">;</span> +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --extras=+{guest} input.sql”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>fun1 input.sql /^CREATE OR REPLACE FUNCTION fun1() RETURNS VARCHAR AS '$/;" f +test1_var1 input.sql /^ test1_var1 VARCHAR(64) := $$ABC$$;$/;" v +test1_var2 input.sql /^ test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$;$/;" v +test1_var3 input.sql /^ test1_var3 INTEGER := 1;$/;" v +</pre></div> +</div> +<p>tagging code including a user-defined function in a dollar quote <a class="reference internal" href="#gh3006" id="id3"><span>[GH3006]</span></a>:</p> +<p>“input.sql”</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span>CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $$ +DECLARE + test2_var1 VARCHAR(64) := 'ABC2'; + test2_var2 VARCHAR(64) := 'XYZ2'; + test2_var3 INTEGER := 2; +BEGIN + RETURN TO_CHAR(test2_var3, '000') || test2_var1 || test2_var2; +END; +$$; +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --extras=+{guest} input.sql”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>fun2 input.sql /^CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $\$$/;" f +test2_var1 input.sql /^ test2_var1 VARCHAR(64) := 'ABC2';$/;" v +test2_var2 input.sql /^ test2_var2 VARCHAR(64) := 'XYZ2';$/;" v +test2_var3 input.sql /^ test2_var3 INTEGER := 2;$/;" v +</pre></div> +</div> +<p>tagging code including a user-defined written in JavaScript:</p> +<div class="highlight-SQL notranslate"><div class="highlight"><pre><span></span>-- Derived from https://github.com/plv8/plv8/blob/r3.0alpha/sql/plv8.sql +CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS +$$ + var o = {}; + for (var i = 0; i < keys.length; i++) + o[keys[i]] = vals[i]; + return JSON.stringify(o); +$$ +LANGUAGE plv8 IMMUTABLE STRICT; +</pre></div> +</div> +<p>“output.tags” +with “--options=NONE -o - --sort=no --extras=+{guest} input.sql”</p> +<div class="highlight-tags notranslate"><div class="highlight"><pre><span></span>test input.sql /^CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS$/;" f +o input.sql /^ var o = {};$/;" v +</pre></div> +</div> +</section> +<section id="known-bugs"> +<h2>KNOWN BUGS<a class="headerlink" href="#known-bugs" title="Permalink to this headline">¶</a></h2> +<p>Escape sequences (<cite>‘’</cite>) in a string literal may make a guest parser confused.</p> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a></p> +</section> +<section id="references"> +<h2>REFERENCES<a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2> +<dl class="citation"> +<dt class="label" id="pl"><span class="brackets"><a class="fn-backref" href="#id1">PL</a></span></dt> +<dd><p>PostgreSQL 9.5.25 Documentation, “Chapter 39. Procedural Languages”, <a class="reference external" href="https://www.postgresql.org/docs/9.5/xplang.html">https://www.postgresql.org/docs/9.5/xplang.html</a></p> +</dd> +<dt class="label" id="gh3006"><span class="brackets">GH3006</span><span class="fn-backref">(<a href="#id2">1</a>,<a href="#id3">2</a>)</span></dt> +<dd><p>@bagl’s comment submitted to <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/3006">https://github.com/universal-ctags/ctags/issues/3006</a></p> +</dd> +</dl> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-lang-sql</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#examples">EXAMPLES</a></li> +<li><a class="reference internal" href="#known-bugs">KNOWN BUGS</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#references">REFERENCES</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-r.7.html" + title="previous chapter">ctags-lang-r</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-incompatibilities.7.html" + title="next chapter">ctags-incompatibilities</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-incompatibilities.7.html" title="ctags-incompatibilities" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-r.7.html" title="ctags-lang-r" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-sql</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-lang-verilog.7.html b/ctags/docs/man/ctags-lang-verilog.7.html new file mode 100644 index 0000000..2114fac --- /dev/null +++ b/ctags/docs/man/ctags-lang-verilog.7.html @@ -0,0 +1,318 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-lang-verilog — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-lang-inko" href="ctags-lang-inko.7.html" /> + <link rel="prev" title="ctags-lang-python" href="ctags-lang-python.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-lang-inko.7.html" title="ctags-lang-inko" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-lang-python.7.html" title="ctags-lang-python" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-verilog</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-lang-verilog"> +<span id="ctags-lang-verilog-7"></span><h1>ctags-lang-verilog<a class="headerlink" href="#ctags-lang-verilog" title="Permalink to this headline">¶</a></h1> +<p>The man page about SystemVerilog/Verilog parser for Universal Ctags</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> … [--kinds-systemverilog=+Q] [--fields-SystemVerilog=+{parameter}] …</div> +<div class="line"><strong>ctags</strong> … [--fields-Verilog=+{parameter}] …</div> +</div> +<blockquote> +<div><table class="docutils align-default"> +<colgroup> +<col style="width: 31%" /> +<col style="width: 31%" /> +<col style="width: 39%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>Language</p></th> +<th class="head"><p>Language ID</p></th> +<th class="head"><p>File Mapping</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>SystemVerilog</p></td> +<td><p>SystemVerilog</p></td> +<td><p>.sv, .svh, svi</p></td> +</tr> +<tr class="row-odd"><td><p>Verilog</p></td> +<td><p>Verilog</p></td> +<td><p>.v</p></td> +</tr> +</tbody> +</table> +</div></blockquote> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>This man page describes about the SystemVerilog/Verilog parser for Universal Ctags. +SystemVerilog parser supports IEEE Std 1800-2017 keywords. +Verilog parser supports IEEE Std 1364-2005 keywords.</p> +<section id="supported-kinds"> +<h3>Supported Kinds<a class="headerlink" href="#supported-kinds" title="Permalink to this headline">¶</a></h3> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-kinds-full<span class="o">=</span>SystemVerilog +<span class="gp">#</span>LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">A assert yes no 0 NONE assertions (assert, assume, cover, restrict)</span> +<span class="go">C class yes no 0 NONE classes</span> +<span class="go">E enum yes no 0 NONE enumerators</span> +<span class="go">H checker yes no 0 NONE checkers</span> +<span class="go">I interface yes no 0 NONE interfaces</span> +<span class="go">K package yes no 0 NONE packages</span> +<span class="go">L clocking yes no 0 NONE clocking</span> +<span class="go">M modport yes no 0 NONE modports</span> +<span class="go">N nettype yes no 0 NONE nettype declarations</span> +<span class="go">O constraint yes no 0 NONE constraints</span> +<span class="go">P program yes no 0 NONE programs</span> +<span class="go">Q prototype no no 0 NONE prototypes (extern, pure)</span> +<span class="go">R property yes no 0 NONE properties</span> +<span class="go">S struct yes no 0 NONE structs and unions</span> +<span class="go">T typedef yes no 0 NONE type declarations</span> +<span class="go">V covergroup yes no 0 NONE covergroups</span> +<span class="go">b block yes no 0 NONE blocks (begin, fork)</span> +<span class="go">c constant yes no 0 NONE constants (define, parameter, specparam, enum values)</span> +<span class="go">e event yes no 0 NONE events</span> +<span class="go">f function yes no 0 NONE functions</span> +<span class="go">i instance yes no 0 NONE instances of module or interface</span> +<span class="go">l ifclass yes no 0 NONE interface class</span> +<span class="go">m module yes no 0 NONE modules</span> +<span class="go">n net yes no 0 NONE net data types</span> +<span class="go">p port yes no 0 NONE ports</span> +<span class="go">q sequence yes no 0 NONE sequences</span> +<span class="go">r register yes no 0 NONE variable data types</span> +<span class="go">t task yes no 0 NONE tasks</span> +<span class="go">w member yes no 0 NONE struct and union members</span> +</pre></div> +</div> +<p>Note that <code class="docutils literal notranslate"><span class="pre">prototype</span></code> (<code class="docutils literal notranslate"><span class="pre">Q</span></code>) is disabled by default.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-kinds-full<span class="o">=</span>Verilog +<span class="gp">#</span>LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">b block yes no 0 NONE blocks (begin, fork)</span> +<span class="go">c constant yes no 0 NONE constants (define, parameter, specparam)</span> +<span class="go">e event yes no 0 NONE events</span> +<span class="go">f function yes no 0 NONE functions</span> +<span class="go">i instance yes no 0 NONE instances of module</span> +<span class="go">m module yes no 0 NONE modules</span> +<span class="go">n net yes no 0 NONE net data types</span> +<span class="go">p port yes no 0 NONE ports</span> +<span class="go">r register yes no 0 NONE variable data types</span> +<span class="go">t task yes no 0 NONE tasks</span> +</pre></div> +</div> +</section> +<section id="supported-language-specific-fields"> +<h3>Supported Language Specific Fields<a class="headerlink" href="#supported-language-specific-fields" title="Permalink to this headline">¶</a></h3> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-fields<span class="o">=</span>Verilog +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="go">- parameter no Verilog --b no parameter whose value can be overridden.</span> +<span class="gp">$ </span>ctags --list-fields<span class="o">=</span>SystemVerilog +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="go">- parameter no SystemVerilog --b no parameter whose value can be overridden.</span> +</pre></div> +</div> +<section id="parameter-field"> +<h4><code class="docutils literal notranslate"><span class="pre">parameter</span></code> field<a class="headerlink" href="#parameter-field" title="Permalink to this headline">¶</a></h4> +<p>If the field <code class="docutils literal notranslate"><span class="pre">parameter</span></code> is enabled, a field <code class="docutils literal notranslate"><span class="pre">parameter:</span></code> is added on a parameter whose +value can be overridden on an instantiated module, interface, or program. +This is useful for a editor plugin or extension to enable auto-instantiation of modules with +parameters which can be overridden.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags ... --fields-Verilog<span class="o">=</span>+<span class="o">{</span>parameter<span class="o">}</span> ... +<span class="gp">$ </span>ctags ... --fields-SystemVerilog<span class="o">=</span>+<span class="o">{</span>parameter<span class="o">}</span> ... +</pre></div> +</div> +<p>On the following source code fields <code class="docutils literal notranslate"><span class="pre">parameter:</span></code> are added on +parameters <code class="docutils literal notranslate"><span class="pre">P*</span></code>, not on ones <code class="docutils literal notranslate"><span class="pre">L*</span></code>. Note that <code class="docutils literal notranslate"><span class="pre">L4</span></code> and <code class="docutils literal notranslate"><span class="pre">L6</span></code> is declared by +<code class="docutils literal notranslate"><span class="pre">parameter</span></code> statement, but fields <code class="docutils literal notranslate"><span class="pre">parameter:</span></code> are not added, +because they cannot be overridden.</p> +<p>“input.sv”</p> +<div class="highlight-systemverilog notranslate"><div class="highlight"><pre><span></span><span class="c1">// compilation unit scope</span> +<span class="k">parameter</span> <span class="n">L1</span> <span class="o">=</span> <span class="s">"synonym for the localparam"</span><span class="p">;</span> + +<span class="k">module</span> <span class="n">with_parameter_port_list</span> <span class="p">#(</span> + <span class="n">P1</span><span class="p">,</span> + <span class="k">localparam</span> <span class="n">L2</span> <span class="o">=</span> <span class="n">P1</span><span class="o">+</span><span class="mi">1</span><span class="p">,</span> + <span class="k">parameter</span> <span class="n">P2</span><span class="p">)</span> + <span class="p">(</span> <span class="cm">/*port list...*/</span> <span class="p">);</span> + <span class="k">parameter</span> <span class="n">L3</span> <span class="o">=</span> <span class="s">"synonym for the localparam"</span><span class="p">;</span> + <span class="k">localparam</span> <span class="n">L4</span> <span class="o">=</span> <span class="s">"localparam"</span><span class="p">;</span> + <span class="c1">// ...</span> +<span class="k">endmodule</span> + +<span class="k">module</span> <span class="n">with_empty_parameter_port_list</span> <span class="p">#()</span> + <span class="p">(</span> <span class="cm">/*port list...*/</span> <span class="p">);</span> + <span class="k">parameter</span> <span class="n">L5</span> <span class="o">=</span> <span class="s">"synonym for the localparam"</span><span class="p">;</span> + <span class="k">localparam</span> <span class="n">L6</span> <span class="o">=</span> <span class="s">"localparam"</span><span class="p">;</span> + <span class="c1">// ...</span> +<span class="k">endmodule</span> + +<span class="k">module</span> <span class="n">no_parameter_port_list</span> + <span class="p">(</span> <span class="cm">/*port list...*/</span> <span class="p">);</span> + <span class="k">parameter</span> <span class="n">P3</span> <span class="o">=</span> <span class="s">"parameter"</span><span class="p">;</span> + <span class="k">localparam</span> <span class="n">L7</span> <span class="o">=</span> <span class="s">"localparam"</span><span class="p">;</span> + <span class="c1">// ...</span> +<span class="k">endmodule</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -uo - --fields-SystemVerilog<span class="o">=</span>+<span class="o">{</span>parameter<span class="o">}</span> input.sv +<span class="go">L1 input.sv /^parameter L1 = "synonym for the localparam";$/;" c parameter:</span> +<span class="go">with_parameter_port_list input.sv /^module with_parameter_port_list #($/;" m</span> +<span class="go">P1 input.sv /^ P1,$/;" c module:with_parameter_port_list parameter:</span> +<span class="go">L2 input.sv /^ localparam L2 = P1+1,$/;" c module:with_parameter_port_list</span> +<span class="go">P2 input.sv /^ parameter P2)$/;" c module:with_parameter_port_list parameter:</span> +<span class="go">L3 input.sv /^ parameter L3 = "synonym for the localparam";$/;" c module:with_parameter_port_list</span> +<span class="go">L4 input.sv /^ localparam L4 = "localparam";$/;" c module:with_parameter_port_list</span> +<span class="go">with_empty_parameter_port_list input.sv /^module with_empty_parameter_port_list #()$/;" m</span> +<span class="go">L5 input.sv /^ parameter L5 = "synonym for the localparam";$/;" c module:with_empty_parameter_port_list</span> +<span class="go">L6 input.sv /^ localparam L6 = "localparam";$/;" c module:with_empty_parameter_port_list</span> +<span class="go">no_parameter_port_list input.sv /^module no_parameter_port_list$/;" m</span> +<span class="go">P3 input.sv /^ parameter P3 = "parameter";$/;" c module:no_parameter_port_list parameter:</span> +<span class="go">L7 input.sv /^ localparam L7 = "localparam";$/;" c module:no_parameter_port_list</span> +</pre></div> +</div> +</section> +</section> +<section id="tips"> +<h3>TIPS<a class="headerlink" href="#tips" title="Permalink to this headline">¶</a></h3> +<p>If you want to map files <code class="docutils literal notranslate"><span class="pre">*.v</span></code> to SystemVerilog, add +<code class="docutils literal notranslate"><span class="pre">--langmap=SystemVerilog:.v</span></code> option.</p> +</section> +</section> +<section id="known-issues"> +<h2>KNOWN ISSUES<a class="headerlink" href="#known-issues" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/2674">https://github.com/universal-ctags/ctags/issues/2674</a> for more information.</p> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a></p></li> +<li><p><a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a></p></li> +<li><dl class="simple"> +<dt>Language Reference Manuals (LRM)</dt><dd><ul> +<li><p>IEEE Standard for SystemVerilog — Unified Hardware Design, Specification, and +Verification Language, IEEE Std 1800-2017, +<a class="reference external" href="https://ieeexplore.ieee.org/document/8299595">https://ieeexplore.ieee.org/document/8299595</a></p></li> +<li><p>IEEE Standard for Verilog Hardware Description Language, IEEE Std 1364-2005, +<a class="reference external" href="https://ieeexplore.ieee.org/document/1620780">https://ieeexplore.ieee.org/document/1620780</a></p></li> +</ul> +</dd> +</dl> +</li> +</ul> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-lang-verilog</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#supported-kinds">Supported Kinds</a></li> +<li><a class="reference internal" href="#supported-language-specific-fields">Supported Language Specific Fields</a><ul> +<li><a class="reference internal" href="#parameter-field"><code class="docutils literal notranslate"><span class="pre">parameter</span></code> field</a></li> +</ul> +</li> +<li><a class="reference internal" href="#tips">TIPS</a></li> +</ul> +</li> +<li><a class="reference internal" href="#known-issues">KNOWN ISSUES</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-lang-python.7.html" + title="previous chapter">ctags-lang-python</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-lang-inko.7.html" + title="next chapter">ctags-lang-inko</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-lang-inko.7.html" title="ctags-lang-inko" + >next</a> |</li> + <li class="right" > + <a href="ctags-lang-python.7.html" title="ctags-lang-python" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-lang-verilog</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags-optlib.7.html b/ctags/docs/man/ctags-optlib.7.html new file mode 100644 index 0000000..0f73ed2 --- /dev/null +++ b/ctags/docs/man/ctags-optlib.7.html @@ -0,0 +1,520 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags-optlib — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-client-tools" href="ctags-client-tools.7.html" /> + <link rel="prev" title="tags" href="tags.5.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-client-tools.7.html" title="ctags-client-tools" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="tags.5.html" title="tags" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-optlib</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags-optlib"> +<span id="ctags-optlib-7"></span><h1>ctags-optlib<a class="headerlink" href="#ctags-optlib" title="Permalink to this headline">¶</a></h1> +<p>Universal Ctags parser definition language</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>7</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [options] [file(s)]</div> +<div class="line"><strong>etags</strong> [options] [file(s)]</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p><em>Exuberant Ctags</em>, the ancestor of <em>Universal Ctags</em>, has provided +the way to define a new parser from command line. Universal Ctags +extends and refines this feature. <em>optlib parser</em> is the name for such +parser in Universal Ctags. “opt” intends a parser is defined with +combination of command line options. “lib” intends an optlib parser +can be more than ad-hoc personal configuration.</p> +<p>This man page is for people who want to define an optlib parser. The +readers should read <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> of Universal Ctags first.</p> +<p>Following options are for defining (or customizing) a parser:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></p></li> +</ul> +<p>Following options are for controlling loading parser definition:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">--options=<pathname></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--options-maybe=<pathname></span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--optlib-dir=[+]<directory></span></code></p></li> +</ul> +<p>The design of options and notations for defining a parser in +Exuberant Ctags may focus on reducing the number of typing by user. +Reducing the number of typing is important for users who want to +define (or customize) a parser quickly.</p> +<p>On the other hand, the design in Universal Ctags focuses on +maintainability. The notation of Universal Ctags is redundant than +that of Exuberant Ctags; the newly introduced kind should be declared +explicitly, (long) names are approved than one-letter flags +specifying kinds, and naming rules are stricter.</p> +<p>This man page explains only stable options and flags. Universal Ctags +also introduces experimental options and flags which have names starting +with <code class="docutils literal notranslate"><span class="pre">_</span></code>. For documentation on these options and flags, visit +Universal Ctags web site at <a class="reference external" href="https://ctags.io/">https://ctags.io/</a>.</p> +<section id="storing-a-parser-definition-to-a-file"> +<h3>Storing a parser definition to a file<a class="headerlink" href="#storing-a-parser-definition-to-a-file" title="Permalink to this headline">¶</a></h3> +<p>Though it is possible to define a parser from command line, you don’t +want to type the same command line each time when you need the parser. +You can store options for defining a parser into a file.</p> +<p>ctags loads files (preload files) listed in “FILES” +section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> at program starting up. You can put your parser +definition needed usually to the files.</p> +<p><code class="docutils literal notranslate"><span class="pre">--options=<pathname></span></code>, <code class="docutils literal notranslate"><span class="pre">--options-maybe=<pathname></span></code>, and +<code class="docutils literal notranslate"><span class="pre">--optlib-dir=[+]<directory></span></code> are for loading optlib files you need +occasionally. See “Option File Options” section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> for +these options.</p> +<p>As explained in “FILES” section of <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, options for defining a +parser listed line by line in an optlib file. Prefixed white spaces are +ignored. A line starting with ‘#’ is treated as a comment. Escaping +shell meta character is not needed.</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">.ctags</span></code> as file extension for optlib file. You can define +multiple parsers in an optlib file but it is better to make a file for +each parser definition.</p> +<p><code class="docutils literal notranslate"><span class="pre">--_echo=<msg></span></code> and <code class="docutils literal notranslate"><span class="pre">--_force-quit=<num></span></code> options are for debugging +optlib parser.</p> +</section> +<section id="overview-for-defining-a-parser"> +<h3>Overview for defining a parser<a class="headerlink" href="#overview-for-defining-a-parser" title="Permalink to this headline">¶</a></h3> +<ol class="arabic"> +<li><p>Design the parser</p> +<p>You need know both the target language and the ctags’ +concepts (definition, reference, kind, role, field, extra). About +the concepts, <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> of Universal Ctags may help you.</p> +</li> +<li><p>Give a name to the parser</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code> option. <em><name></em> is referred as <em><LANG></em> in +the later steps.</p> +</li> +<li><p>Give a file pattern or file extension for activating the parser</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code>.</p> +</li> +<li><p>Define kinds</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code> option. +Universal Ctags introduces this option. Exuberant Ctags doesn’t +have. In Exuberant Ctags, a kind is defined as a side effect of +specifying <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=</span></code> option. So user doesn’t have a +chance to recognize how important the definition of kind.</p> +</li> +<li><p>Define patterns</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code> +option for a single-line regular expression. You can also use +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code> +option for a multi-line regular expression.</p> +<p>As <em><kind-spec></em>, you can use the one-letter flag defined with +<code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code> option.</p> +</li> +</ol> +</section> +</section> +<section id="options"> +<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code></dt><dd><p>Defines a new user-defined language, <em><name></em>, to be parsed with regular +expressions. Once defined, <em><name></em> may be used in other options taking +language names.</p> +<p><em><name></em> must consist of alphanumeric characters, ‘<code class="docutils literal notranslate"><span class="pre">#</span></code>’, or ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ +(‘[a-zA-Z0-9#+]+’). The graph characters other than ‘<code class="docutils literal notranslate"><span class="pre">#</span></code>’ and +‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ are disallowed (or reserved). Some of them (<code class="docutils literal notranslate"><span class="pre">[-=:{.]</span></code>) are +disallowed because they can make the command line parser of +ctags confused. The rest of them are just +reserved for future extending ctags.</p> +<p><code class="docutils literal notranslate"><span class="pre">all</span></code> is an exception. <code class="docutils literal notranslate"><span class="pre">all</span></code> as <em><name></em> is not acceptable. It is +a reserved word. See the description of +<code class="docutils literal notranslate"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></code> option in <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> about how the +reserved word is used.</p> +<p>The names of built-in parsers are capitalized. When +ctags evaluates an option in a command line, and +chooses a parser, ctags uses the names of +parsers in a case-insensitive way. Therefore, giving a name +started from a lowercase character doesn’t help you to avoid the +parser name confliction. However, in a tags file, +ctags prints parser names in a case-sensitive +way; it prints a parser name as specified in <code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code> +option. Therefore, we recommend you to give a name started from a +lowercase character to your private optlib parser. With this +convention, people can know where a tag entry in a tag file comes +from a built-in parser or a private optlib parser.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code></dt><dd><p>Define a kind for <em><LANG></em>. +Be not confused this with <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>.</p> +<p><em><letter></em> must be an alphabetical character (‘[a-zA-EG-Z]’) +other than “F”. “F” has been reserved for representing a file +since Exuberant Ctags.</p> +<p><em><name></em> must start with an alphabetic character, and the rest +must be alphanumeric (‘[a-zA-Z][a-zA-Z0-9]*’). Do not use +“file” as <em><name></em>. It has been reserved for representing a file +since Exuberant Ctags.</p> +<p>Note that using a number character in a <em><name></em> violates the +version 2 of tags file format though ctags +accepts it. For more detail, see <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +<p><em><description></em> comes from any printable ASCII characters. The +exception is <code class="docutils literal notranslate"><span class="pre">{</span></code> and <code class="docutils literal notranslate"><span class="pre">\</span></code>. <code class="docutils literal notranslate"><span class="pre">{</span></code> is reserved for adding flags +this option in the future. So put <code class="docutils literal notranslate"><span class="pre">\</span></code> before <code class="docutils literal notranslate"><span class="pre">{</span></code> to include +<code class="docutils literal notranslate"><span class="pre">{</span></code> to a description. To include <code class="docutils literal notranslate"><span class="pre">\</span></code> itself to a description, +put <code class="docutils literal notranslate"><span class="pre">\</span></code> before <code class="docutils literal notranslate"><span class="pre">\</span></code>.</p> +<p>Both <em><letter></em>, <em><name></em> and their combination must be unique in +a <em><LANG></em>.</p> +<p>This option is newly introduced in Universal Ctags. This option +reduces the typing defining a regex pattern with +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=</span></code>, and keeps the consistency of kind +definitions in a language.</p> +<p>The <em><letter></em> can be used as an argument for <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> +option to enable or disable the kind. Unless <code class="docutils literal notranslate"><span class="pre">K</span></code> field is +enabled, the <em><letter></em> is used as value in the “kind” extension +field in tags output.</p> +<p>The <em><name></em> surrounded by braces can be used as an argument for +<code class="docutils literal notranslate"><span class="pre">--kind-<LANG></span></code> option. If <code class="docutils literal notranslate"><span class="pre">K</span></code> field is enabled, the <em><name></em> +is used as value in the “kind” extension field in tags output.</p> +<p>The <em><description></em> and <em><letter></em> are listed in <code class="docutils literal notranslate"><span class="pre">--list-kinds</span></code> +output. All three elements of the kind-spec are listed in +<code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> output. Don’t use braces in the +<em><description></em>. They will be used meta characters in the future.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define a single-line regular expression.</p> +<p>The <em>/<line_pattern>/<name_pattern>/</em> pair defines a regular expression +replacement pattern, similar in style to <code class="docutils literal notranslate"><span class="pre">sed</span></code> substitution +commands, <code class="docutils literal notranslate"><span class="pre">s/regexp/replacement/</span></code>, with which to generate tags from source files mapped to +the named language, <em><LANG></em>, (case-insensitive; either a built-in +or user-defined language).</p> +<p>The regular expression, <em><line_pattern></em>, defines +an extended regular expression (roughly that used by egrep(1)), +which is used to locate a single source line containing a tag and +may specify tab characters using <code class="docutils literal notranslate"><span class="pre">\t</span></code>.</p> +<p>When a matching line is +found, a tag will be generated for the name defined by +<em><name_pattern></em>, which generally will contain the special +back-references <code class="docutils literal notranslate"><span class="pre">\1</span></code> through <code class="docutils literal notranslate"><span class="pre">\9</span></code> to refer to matching sub-expression +groups within <em><line_pattern></em>.</p> +<p>The ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’ separator characters shown in the +parameter to the option can actually be replaced by any +character. Note that whichever separator character is used will +have to be escaped with a backslash (’<code class="docutils literal notranslate"><span class="pre">\</span></code>’) character wherever it is +used in the parameter as something other than a separator. The +regular expression defined by this option is added to the current +list of regular expressions for the specified language unless the +parameter is omitted, in which case the current list is cleared.</p> +<p>Unless modified by <em><flags></em>, <em><line_pattern></em> is interpreted as a POSIX +extended regular expression. The <em><name_pattern></em> should expand for all +matching lines to a non-empty string of characters, or a warning +message will be reported unless <code class="docutils literal notranslate"><span class="pre">{placeholder}</span></code> regex flag is +specified.</p> +<p>A kind specifier (<em><kind-spec></em>) for tags matching regexp may +follow <em><name_pattern></em>, which will determine what kind of tag is +reported in the <code class="docutils literal notranslate"><span class="pre">kind</span></code> extension field (see <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>).</p> +<p><em><kind-spec></em> has two forms: <em>one-letter form</em> and <em>full form</em>.</p> +<p>The one-letter form in the form of <code class="docutils literal notranslate"><span class="pre"><letter></span></code>. It just refers a kind +<em><letter></em> defined with <code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG></span></code>. This form is recommended in +Universal Ctags.</p> +<p>The full form of <em><kind-spec></em> is in the form of +<code class="docutils literal notranslate"><span class="pre"><letter>,<name>,<description></span></code>. Either the kind <em><name></em> and/or the +<em><description></em> can be omitted. See the description of +<code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code> option about the +elements.</p> +<p>The full form is supported only for keeping the compatibility with Exuberant +Ctags which does not have <code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG></span></code> option. Supporting the +form will be removed from Universal Ctags in the future.</p> +<p>About <em><flags></em>, see “FLAGS FOR <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> OPTION”.</p> +<p>For more information on the regular expressions used by +ctags, see either the regex(5,7) man page, or +the GNU info documentation for regex (e.g. “<code class="docutils literal notranslate"><span class="pre">info</span> <span class="pre">regex</span></code>”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-regex-flags</span></code></dt><dd><p>Lists the flags that can be used in <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-mline-regex-flags</span></code></dt><dd><p>Lists the flags that can be used in <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define a multi-line regular expression.</p> +<p>This option is similar to <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option except the pattern is +applied to the whole file’s contents, not line by line.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--_echo=<message></span></code></dt><dd><p>Print <em><message></em> to the standard error stream. This is helpful to +understand (and debug) optlib loading feature of Universal Ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--_force-quit[=<num>]</span></code></dt><dd><p>Exits immediately when this option is processed. If <em><num></em> is used +as exit status. The default is 0. This is helpful to debug optlib +loading feature of Universal Ctags.</p> +</dd> +</dl> +<section id="flags-for-regex-lang-option"> +<h3>FLAGS FOR <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> OPTION<a class="headerlink" href="#flags-for-regex-lang-option" title="Permalink to this headline">¶</a></h3> +<p>You can specify more than one flag, <code class="docutils literal notranslate"><span class="pre"><letter>|{<name>}</span></code>, at the end of <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> to +control how Universal Ctags uses the pattern.</p> +<p>Exuberant Ctags uses a <em><letter></em> to represent a flag. In +Universal Ctags, a <em><name></em> surrounded by braces (name form) can be used +in addition to <em><letter></em>. The name form makes a user reading an optlib +file easier.</p> +<p>The most of all flags newly added in Universal Ctags +don’t have the one-letter representation. All of them have only the name +representation. <code class="docutils literal notranslate"><span class="pre">--list-regex-flags</span></code> lists all the flags.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">basic</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">b</span></code>)</dt><dd><p>The pattern is interpreted as a POSIX basic regular expression.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">exclusive</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">x</span></code>)</dt><dd><p>Skip testing the other patterns if a line is matched to this +pattern. This is useful to avoid using CPU to parse line comments.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">extend</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">e</span></code>)</dt><dd><p>The pattern is interpreted as a POSIX extended regular +expression (default).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">icase</span></code> (one-letter form <code class="docutils literal notranslate"><span class="pre">i</span></code>)</dt><dd><p>The regular expression is to be applied in a case-insensitive +manner.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">placeholder</span></code></dt><dd><p>Don’t emit a tag captured with a regex pattern. The replacement +can be an empty string. See the following description of +<code class="docutils literal notranslate"><span class="pre">scope=...</span></code> flag about how this is useful.</p> +</dd> +</dl> +<p><code class="docutils literal notranslate"><span class="pre">scope=(ref|push|pop|clear|set)</span></code></p> +<blockquote> +<div><p>Specify what to do with the internal scope stack.</p> +<p>A parser programmed with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> has a stack (scope +stack) internally. You can use it for tracking scope +information. The <code class="docutils literal notranslate"><span class="pre">scope=...</span></code> flag is for manipulating and +utilizing the scope stack.</p> +<p>If <code class="docutils literal notranslate"><span class="pre">{scope=push}</span></code> is specified, a tag captured with +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> is pushed to the stack. <code class="docutils literal notranslate"><span class="pre">{scope=push}</span></code> +implies <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code>.</p> +<p>You can fill the scope field of captured tag with +<code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code>. If <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag is given, +ctags attaches the tag at the top to the tag +captured with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> as the value for the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> +field.</p> +<p>ctags pops the tag at the top of the stack when +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> with <code class="docutils literal notranslate"><span class="pre">{scope=pop}</span></code> is matched to the input +line.</p> +<p>Specifying <code class="docutils literal notranslate"><span class="pre">{scope=clear}</span></code> removes all the tags in the scope. +Specifying <code class="docutils literal notranslate"><span class="pre">{scope=set}</span></code> removes all the tags in the scope, and +then pushes the captured tag as <code class="docutils literal notranslate"><span class="pre">{scope=push}</span></code> does.</p> +<p>In some cases, you may want to use <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> only for its +side effects: using it only to manipulate the stack but not for +capturing a tag. In such a case, make <em><name_pattern></em> component of +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option empty while specifying <code class="docutils literal notranslate"><span class="pre">{placeholder}</span></code> +as a regex flag. For example, a non-named tag can be put on +the stack by giving a regex flag “<code class="docutils literal notranslate"><span class="pre">{scope=push}{placeholder}</span></code>”.</p> +<p>You may wonder what happens if a regex pattern with +<code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag matches an input line but the stack is empty, +or a non-named tag is at the top. If the regex pattern contains a +<code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag and the stack is empty, the <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> +flag is ignored and nothing is attached to the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> field.</p> +<p>If the top of the stack contains an unnamed tag, +ctags searches deeper into the stack to find the +top-most named tag. If it reaches the bottom of the stack without +finding a named tag, the <code class="docutils literal notranslate"><span class="pre">{scope=ref}</span></code> flag is ignored and +nothing is attached to the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> field.</p> +<p>When a named tag on the stack is popped or cleared as the side +effect of a pattern matching, ctags attaches the +line number of the match to the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field of +the named tag.</p> +<p>ctags clears all of the tags on the stack when it +reaches the end of the input source file. The line number of the +end is attached to the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field of the cleared tags.</p> +</div></blockquote> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">warning=<message></span></code></dt><dd><p>print the given <em><message></em> at WARNING level</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">fatal=<message></span></code></dt><dd><p>print the given <em><message></em> and exit</p> +</dd> +</dl> +</section> +</section> +<section id="examples"> +<h2>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2> +<section id="perl-pod"> +<h3>Perl Pod<a class="headerlink" href="#perl-pod" title="Permalink to this headline">¶</a></h3> +<p>This is the definition (pod.ctags) used in ctags for parsing Pod +(<a class="reference external" href="https://perldoc.perl.org/perlpod.html">https://perldoc.perl.org/perlpod.html</a>) file.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">pod</span> +<span class="kd">--map-</span><span class="nn">pod</span><span class="p">=+</span>.pod + +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">c</span><span class="p">,</span><span class="ni">chapter</span><span class="p">,</span><span class="sd">chapters</span> +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">s</span><span class="p">,</span><span class="ni">section</span><span class="p">,</span><span class="sd">sections</span> +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">S</span><span class="p">,</span><span class="ni">subsection</span><span class="p">,</span><span class="sd">subsections</span> +<span class="kd">--kinddef-</span><span class="nn">pod</span><span class="p">=</span><span class="ni">t</span><span class="p">,</span><span class="ni">subsubsection</span><span class="p">,</span><span class="sd">subsubsections</span> + +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head1[ \t]+(.+)/\1/c/ +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head2[ \t]+(.+)/\1/s/ +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head3[ \t]+(.+)/\1/S/ +<span class="kd">--regex-</span><span class="nn">pod</span><span class="p">=</span>/^=head4[ \t]+(.+)/\1/t/ +</pre></div> +</div> +</section> +<section id="using-scope-regex-flags"> +<h3>Using scope regex flags<a class="headerlink" href="#using-scope-regex-flags" title="Permalink to this headline">¶</a></h3> +<p>Let’s think about writing a parser for a very small subset of the Ruby +language.</p> +<p>input source file (<code class="docutils literal notranslate"><span class="pre">input.srb</span></code>):</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Example</span> + <span class="k">def</span> <span class="nf">methodA</span> + <span class="n">puts</span> <span class="s2">"in class_method"</span> + <span class="n">end</span> + <span class="k">def</span> <span class="nf">methodB</span> + <span class="n">puts</span> <span class="s2">"in class_method"</span> + <span class="n">end</span> +<span class="n">end</span> +</pre></div> +</div> +<p>The parser for the input should capture <code class="docutils literal notranslate"><span class="pre">Example</span></code> with <code class="docutils literal notranslate"><span class="pre">class</span></code> kind, +<code class="docutils literal notranslate"><span class="pre">methodA</span></code>, and <code class="docutils literal notranslate"><span class="pre">methodB</span></code> with <code class="docutils literal notranslate"><span class="pre">method</span></code> kind. <code class="docutils literal notranslate"><span class="pre">methodA</span></code> and <code class="docutils literal notranslate"><span class="pre">methodB</span></code> +should have <code class="docutils literal notranslate"><span class="pre">Example</span></code> as their scope. <code class="docutils literal notranslate"><span class="pre">end:</span></code> fields of each tag +should have proper values.</p> +<p>optlib file (<code class="docutils literal notranslate"><span class="pre">sub-ruby.ctags</span></code>):</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">subRuby</span> +<span class="kd">--map-</span><span class="nn">subRuby</span><span class="p">=</span>.srb +<span class="kd">--kinddef-</span><span class="nn">subRuby</span><span class="p">=</span><span class="ni">c</span><span class="p">,</span><span class="ni">class</span><span class="p">,</span><span class="sd">classes</span> +<span class="kd">--kinddef-</span><span class="nn">subRuby</span><span class="p">=</span><span class="ni">m</span><span class="p">,</span><span class="ni">method</span><span class="p">,</span><span class="sd">methods</span> +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^class[ \t]+([a-zA-Z][a-zA-Z0-9]+)/\1/c/{scope=push} +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^end///{scope=pop}{placeholder} +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^[ \t]+def[ \t]+([a-zA-Z][a-zA-Z0-9_]+)/\1/m/{scope=push} +<span class="kd">--regex-</span><span class="nn">subRuby</span><span class="p">=</span>/^[ \t]+end///{scope=pop}{placeholder} +</pre></div> +</div> +<p>command line and output:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --quiet --fields=+eK \ +--options=./sub-ruby.ctags -o - input.srb +Example input.srb /^class Example$/;" class end:8 +methodA input.srb /^ def methodA$/;" method class:Example end:4 +methodB input.srb /^ def methodB$/;" method class:Example end:7 +</pre></div> +</div> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>, regex(3), regex(7), egrep(1)</p> +</section> +<section id="author"> +<h2>AUTHOR<a class="headerlink" href="#author" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a> +(This man page partially derived from <a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> of +Executable-ctags)</p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert%40users.sourceforge.net">dhiebert<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags-optlib</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#storing-a-parser-definition-to-a-file">Storing a parser definition to a file</a></li> +<li><a class="reference internal" href="#overview-for-defining-a-parser">Overview for defining a parser</a></li> +</ul> +</li> +<li><a class="reference internal" href="#options">OPTIONS</a><ul> +<li><a class="reference internal" href="#flags-for-regex-lang-option">FLAGS FOR <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> OPTION</a></li> +</ul> +</li> +<li><a class="reference internal" href="#examples">EXAMPLES</a><ul> +<li><a class="reference internal" href="#perl-pod">Perl Pod</a></li> +<li><a class="reference internal" href="#using-scope-regex-flags">Using scope regex flags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#author">AUTHOR</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="tags.5.html" + title="previous chapter">tags</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-client-tools.7.html" + title="next chapter">ctags-client-tools</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-client-tools.7.html" title="ctags-client-tools" + >next</a> |</li> + <li class="right" > + <a href="tags.5.html" title="tags" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags-optlib</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/ctags.1.html b/ctags/docs/man/ctags.1.html new file mode 100644 index 0000000..18730d5 --- /dev/null +++ b/ctags/docs/man/ctags.1.html @@ -0,0 +1,1989 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>ctags — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="tags" href="tags.5.html" /> + <link rel="prev" title="Man pages" href="../man-pages.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="tags.5.html" title="tags" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="../man-pages.html" title="Man pages" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="ctags"> +<span id="ctags-1"></span><h1>ctags<a class="headerlink" href="#ctags" title="Permalink to this headline">¶</a></h1> +<p>Generate tag files for source code</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>1</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [<options>] [<source_file(s)>]</div> +<div class="line"><strong>etags</strong> [<options>] [<source_file(s)>]</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The <em>ctags</em> and <em>etags</em> (see <code class="docutils literal notranslate"><span class="pre">-e</span></code> option) programs +(hereinafter collectively referred to as ctags, +except where distinguished) generate an index (or “tag”) file for a +variety of <em>language objects</em> found in <em>source file(s)</em>. This tag file allows +these items to be quickly and easily located by a text editor or other +utilities (<em>client tools</em>). A <em>tag</em> signifies a language object for which an index entry is +available (or, alternatively, the index entry created for that object).</p> +<p>Alternatively, ctags can generate a cross reference +file which lists, in human readable form, information about the various +language objects found in a set of source files.</p> +<p>Tag index files are supported by numerous editors, which allow the user to +locate the object associated with a name appearing in a source file and +jump to the file and line which defines the name. See the manual of your +favorite editor about utilizing ctags command and +the tag index files in the editor.</p> +<p>ctags is capable of generating different <em>kinds</em> of tags +for each of many different <em>languages</em>. For a complete list of supported +languages, the names by which they are recognized, and the kinds of tags +which are generated for each, see the <code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> and <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> +options.</p> +<p>This man page describes <em>Universal Ctags</em>, an implementation of ctags +derived from <em>Exuberant Ctags</em>. The major incompatible changes between +Universal Ctags and Exuberant Ctags are enumerated in +<a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>.</p> +<p>One of the advantages of Exuberant Ctags is that it allows a user to +define a new parser from the command line. Extending this capability is one +of the major features of Universal Ctags. <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> +describes how the capability is extended.</p> +<p>Newly introduced experimental features are not explained here. If you +are interested in such features and ctags internals, +visit <a class="reference external" href="https://docs.ctags.io/">https://docs.ctags.io/</a>.</p> +</section> +<section id="command-line-interface"> +<h2>COMMAND LINE INTERFACE<a class="headerlink" href="#command-line-interface" title="Permalink to this headline">¶</a></h2> +<p>Despite the wealth of available options, defaults are set so that +ctags is most commonly executed without any options (e.g. +“<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">*</span></code>”, or “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-R</span></code>”), which will +create a tag file in the current directory for all recognized source +files. The options described below are provided merely to allow custom +tailoring to meet special needs.</p> +<p>Note that spaces separating the single-letter options from their parameters +are optional.</p> +<p>Note also that the boolean parameters to the long form options (those +beginning with <code class="docutils literal notranslate"><span class="pre">--</span></code> and that take a <code class="docutils literal notranslate"><span class="pre">[=(yes|no)]</span></code> parameter) may be omitted, +in which case <code class="docutils literal notranslate"><span class="pre">=yes</span></code> is implied. (e.g. <code class="docutils literal notranslate"><span class="pre">--sort</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">--sort=yes</span></code>). +Note further that <code class="docutils literal notranslate"><span class="pre">=1</span></code>, <code class="docutils literal notranslate"><span class="pre">=on</span></code>, and <code class="docutils literal notranslate"><span class="pre">=true</span></code> are considered synonyms for <code class="docutils literal notranslate"><span class="pre">=yes</span></code>, +and that <code class="docutils literal notranslate"><span class="pre">=0</span></code>, <code class="docutils literal notranslate"><span class="pre">=off</span></code>, and <code class="docutils literal notranslate"><span class="pre">=false</span></code> are considered synonyms for <code class="docutils literal notranslate"><span class="pre">=no</span></code>.</p> +<p>Some options are either ignored or useful only when used while running in +etags mode (see <code class="docutils literal notranslate"><span class="pre">-e</span></code> option). Such options will be noted.</p> +<p><em><options></em> must precede the <em><source_file(s)></em> following the standard POSIX +convention.</p> +<p>Options taking language names will accept those names in either upper or +lower case. See the <code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> option for a complete list of the +built-in language names.</p> +<section id="letters-and-names"> +<h3>Letters and names<a class="headerlink" href="#letters-and-names" title="Permalink to this headline">¶</a></h3> +<p>Some options take one-letter flags as parameters (e.g. <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> option). +Specifying just letters help a user create a complicated command line +quickly. However, a command line including sequences of one-letter flags +becomes difficult to understand.</p> +<p>Universal Ctags accepts long-name flags in +addition to such one-letter flags. The long-name and one-letter flags can be mixed in an +option parameter by surrounding each long-name by braces. Thus, for an +example, the following three notations for <code class="docutils literal notranslate"><span class="pre">--kinds-C</span></code> option have +the same meaning:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">kinds</span><span class="o">-</span><span class="n">C</span><span class="o">=+</span><span class="n">pLl</span> +<span class="o">--</span><span class="n">kinds</span><span class="o">-</span><span class="n">C</span><span class="o">=+</span><span class="p">{</span><span class="n">prototype</span><span class="p">}{</span><span class="n">label</span><span class="p">}{</span><span class="n">local</span><span class="p">}</span> +<span class="o">--</span><span class="n">kinds</span><span class="o">-</span><span class="n">C</span><span class="o">=+</span><span class="p">{</span><span class="n">prototype</span><span class="p">}</span><span class="n">L</span><span class="p">{</span><span class="n">local</span><span class="p">}</span> +</pre></div> +</div> +<p>Note that braces may be meta characters in your shell. Put +single quotes in such case.</p> +<p><code class="docutils literal notranslate"><span class="pre">--list-...</span></code> options shows one-letter flags and associated long-name flags.</p> +</section> +<section id="list-options"> +<h3>List options<a class="headerlink" href="#list-options" title="Permalink to this headline">¶</a></h3> +<p>Universal Ctags introduces many <code class="docutils literal notranslate"><span class="pre">--list-...</span></code> options that provide +the internal data of Universal Ctags (See “<a class="reference internal" href="#listing-options">Listing Options</a>”). Both users and client tools may +use the data. <code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code> and <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> options +adjust the output of the most of <code class="docutils literal notranslate"><span class="pre">--list-...</span></code> options.</p> +<p>The default setting (<code class="docutils literal notranslate"><span class="pre">--with-list-header=yes</span></code> and <code class="docutils literal notranslate"><span class="pre">--machinable=no</span></code>) +is for using interactively from a terminal. The header that explains +the meaning of columns is simply added to the output, and each column is +aligned in all lines. The header line starts with a hash (’<code class="docutils literal notranslate"><span class="pre">#</span></code>’) character.</p> +<p>For scripting in a client tool, <code class="docutils literal notranslate"><span class="pre">--with-list-header=no</span></code> and +<code class="docutils literal notranslate"><span class="pre">--machinable=yes</span></code> may be useful. The header is not added to the +output, and each column is separated by tab characters.</p> +<p>Note the order of columns will change in the future release. +However, labels in the header will not change. So by scanning +the header, a client tool can find the index for the target +column.</p> +</section> +</section> +<section id="options"> +<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> +<p>ctags has more options than listed here. +Options starting with an underscore character, such as <code class="docutils literal notranslate"><span class="pre">--_echo=<msg></span></code>, +are not listed here. They are experimental or for debugging purpose.</p> +<p>Notation: <code class="docutils literal notranslate"><span class="pre"><foo></span></code> is for a variable string <code class="docutils literal notranslate"><span class="pre">foo</span></code>, <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">...</span> <span class="pre">]</span></code> for optional, +<code class="docutils literal notranslate"><span class="pre">|</span></code> for selection, and <code class="docutils literal notranslate"><span class="pre">(</span> <span class="pre">...</span> <span class="pre">)</span></code> for grouping. For example +<code class="docutils literal notranslate"><span class="pre">--foo[=(yes|no)]''</span> <span class="pre">means</span> <span class="pre">``--foo</span></code>, <code class="docutils literal notranslate"><span class="pre">-foo=yes</span></code>, or <code class="docutils literal notranslate"><span class="pre">-foo=no</span></code>.</p> +<section id="input-output-file-options"> +<span id="option-input-output-file"></span><h3>Input/Output File Options<a class="headerlink" href="#input-output-file-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--exclude=<pattern></span></code></dt><dd><p>Add <em><pattern></em> to a list of excluded files and directories. This option may +be specified as many times as desired. For each file name considered +by ctags, each pattern specified using this option +will be compared against both the complete path (e.g. +<code class="docutils literal notranslate"><span class="pre">some/path/base.ext</span></code>) and the base name (e.g. <code class="docutils literal notranslate"><span class="pre">base.ext</span></code>) of the file, thus +allowing patterns which match a given file name irrespective of its +path, or match only a specific path.</p> +<p>If appropriate support is available +from the runtime library of your C compiler, then pattern may +contain the usual shell wildcards (not regular expressions) common on +Unix (be sure to quote the option parameter to protect the wildcards from +being expanded by the shell before being passed to ctags; +also be aware that wildcards can match the slash character, ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’). +You can determine if shell wildcards are available on your platform by +examining the output of the <code class="docutils literal notranslate"><span class="pre">--list-features</span></code> option, which will include +<code class="docutils literal notranslate"><span class="pre">wildcards</span></code> in the compiled feature list; otherwise, pattern is matched +against file names using a simple textual comparison.</p> +<p>If <em><pattern></em> begins with the character ‘<code class="docutils literal notranslate"><span class="pre">@</span></code>’, then the rest of the string +is interpreted as a file name from which to read exclusion patterns, +one per line. If pattern is empty, the list of excluded patterns is +cleared.</p> +<p>Note that at program startup, the default exclude list contains names of +common hidden and system files, patterns for binary files, and directories +for which it is generally not desirable to descend while processing the +<code class="docutils literal notranslate"><span class="pre">--recurse</span></code> option. To see the list of built-in exclude patterns, use +<code class="docutils literal notranslate"><span class="pre">--list-excludes</span></code>.</p> +<p>See also the description for <code class="docutils literal notranslate"><span class="pre">--exclude-exception=</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--exclude-exception=<pattern></span></code></dt><dd><p>Add <em><pattern></em> to a list of included files and directories. The pattern +affects the files and directories that are excluded by the pattern +specified with <code class="docutils literal notranslate"><span class="pre">--exclude=</span></code> option.</p> +<p>For an example, you want ctags to ignore all files +under <code class="docutils literal notranslate"><span class="pre">foo</span></code> directory except <code class="docutils literal notranslate"><span class="pre">foo/main.c</span></code>, use the following command +line: <code class="docutils literal notranslate"><span class="pre">--exclude=foo/*</span> <span class="pre">--exclude-exception=foo/main.c</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--filter[=(yes|no)]</span></code></dt><dd><p>Makes ctags behave as a filter, reading source +file names from standard input and printing their tags to standard +output on a file-by-file basis. If <code class="docutils literal notranslate"><span class="pre">--sort</span></code> is enabled, tags are sorted +only within the source file in which they are defined. File names are +read from standard input in line-oriented input mode (see note for <code class="docutils literal notranslate"><span class="pre">-L</span></code> +option) and only after file names listed on the command line or from +any file supplied using the <code class="docutils literal notranslate"><span class="pre">-L</span></code> option. When this option is enabled, +the options <code class="docutils literal notranslate"><span class="pre">-f</span></code>, <code class="docutils literal notranslate"><span class="pre">-o</span></code>, and <code class="docutils literal notranslate"><span class="pre">--totals</span></code> are ignored. This option is quite +esoteric and is disabled by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--filter-terminator=<string></span></code></dt><dd><p>Specifies a <em><string></em> to print to standard output following the tags for +each file name parsed when the <code class="docutils literal notranslate"><span class="pre">--filter</span></code> option is enabled. This may +permit an application reading the output of ctags +to determine when the output for each file is finished.</p> +<p>Note that if the +file name read is a directory and <code class="docutils literal notranslate"><span class="pre">--recurse</span></code> is enabled, this string will +be printed only once at the end of all tags found for by descending +the directory. This string will always be separated from the last tag +line for the file by its terminating newline.</p> +<p>This option is quite esoteric and is empty by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--links[=(yes|no)]</span></code></dt><dd><p>Indicates whether symbolic links (if supported) should be followed. +When disabled, symbolic links are ignored. This option is on by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--maxdepth=<N></span></code></dt><dd><p>Limits the depth of directory recursion enabled with the <code class="docutils literal notranslate"><span class="pre">--recurse</span></code> +(<code class="docutils literal notranslate"><span class="pre">-R</span></code>) option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--recurse[=(yes|no)]</span></code></dt><dd><p>Recurse into directories encountered in the list of supplied files.</p> +<p>If the list of supplied files is empty and no file list is specified with +the <code class="docutils literal notranslate"><span class="pre">-L</span></code> option, then the current directory (i.e. ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’) is assumed. +Symbolic links are followed by default (See <code class="docutils literal notranslate"><span class="pre">--links</span></code> option). If you don’t like these behaviors, either +explicitly specify the files or pipe the output of <code class="docutils literal notranslate"><span class="pre">find(1)</span></code> into +“<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-L</span> <span class="pre">-</span></code>” instead. See, also, the <code class="docutils literal notranslate"><span class="pre">--exclude</span></code> and +<code class="docutils literal notranslate"><span class="pre">--maxdepth</span></code> to limit recursion.</p> +<p>Note: This option is not supported on +all platforms at present. It is available if the output of the <code class="docutils literal notranslate"><span class="pre">--help</span></code> +option includes this option.</p> +</dd> +</dl> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">-R</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--recurse</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-L</span> <span class="pre"><file></span></code></dt><dd><p>Read from <em><file></em> a list of file names for which tags should be generated.</p> +<p>If file is specified as ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’, then file names are read from standard +input. File names read using this option are processed following file +names appearing on the command line. Options are also accepted in this +input. If this option is specified more than once, only the last will +apply.</p> +<p>Note: file is read in line-oriented mode, where a new line is +the only delimiter and non-trailing white space is considered significant, +in order that file names containing spaces may be supplied +(however, trailing white space is stripped from lines); this can affect +how options are parsed if included in the input.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--append[=(yes|no)]</span></code></dt><dd><p>Indicates whether tags generated from the specified files should be +appended to those already present in the tag file or should replace them. +This option is <code class="docutils literal notranslate"><span class="pre">no</span></code> by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-a</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--append</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre"><tagfile></span></code></dt><dd><p>Use the name specified by <em><tagfile></em> for the tag file (default is “<code class="docutils literal notranslate"><span class="pre">tags</span></code>”, +or “<code class="docutils literal notranslate"><span class="pre">TAGS</span></code>” when running in etags mode). If <em><tagfile></em> is specified as ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>‘, +then the tags are written to standard output instead.</p> +<p>ctags +will stubbornly refuse to take orders if tagfile exists and +its first line contains something other than a valid tags line. This +will save your neck if you mistakenly type “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-f</span> +<span class="pre">*.c</span></code>”, which would otherwise overwrite your first C file with the tags +generated by the rest! It will also refuse to accept a multi-character +file name which begins with a ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ (dash) character, since this most +likely means that you left out the tag file name and this option tried to +grab the next option as the file name. If you really want to name your +output tag file <code class="docutils literal notranslate"><span class="pre">-ugly</span></code>, specify it as “<code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">./-ugly</span></code>”.</p> +<p>This option must +appear before the first file name. If this option is specified more +than once, only the last will apply.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre"><tagfile></span></code></dt><dd><p>Equivalent to “<code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">tagfile</span></code>”.</p> +</dd> +</dl> +</section> +<section id="output-format-options"> +<span id="option-output-format"></span><h3>Output Format Options<a class="headerlink" href="#output-format-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--format=(1|2)</span></code></dt><dd><p>Change the format of the output tag file. Currently the only valid +values for level are 1 or 2. Level 1 specifies the original tag file +format and level 2 specifies a new extended format containing extension +fields (but in a manner which retains backward-compatibility with +original <code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> implementations). The default level is 2. +[Ignored in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--output-format=(u-ctags|e-ctags|etags|xref|json)</span></code></dt><dd><p>Specify the output format. The default is <code class="docutils literal notranslate"><span class="pre">u-ctags</span></code>. +See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> for <code class="docutils literal notranslate"><span class="pre">u-ctags</span></code> and <code class="docutils literal notranslate"><span class="pre">e-ctags</span></code>. +See <code class="docutils literal notranslate"><span class="pre">-e</span></code> for <code class="docutils literal notranslate"><span class="pre">etags</span></code>, and <code class="docutils literal notranslate"><span class="pre">-x</span></code> for <code class="docutils literal notranslate"><span class="pre">xref</span></code>. +<code class="docutils literal notranslate"><span class="pre">json</span></code> format is available only if +the ctags executable is built with <code class="docutils literal notranslate"><span class="pre">libjansson</span></code>. +See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more about <code class="docutils literal notranslate"><span class="pre">json</span></code> format.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-e</span></code></dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">--output-format=etags</span></code>. +Enable etags mode, which will create a tag file for use with the Emacs +editor. Alternatively, if ctags is invoked by a +name containing the string “etags” (either by renaming, +or creating a link to, the executable), etags mode will be enabled.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-x</span></code></dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">--output-format=xref</span></code>. +Print a tabular, human-readable cross reference (xref) file to standard +output instead of generating a tag file. The information contained in +the output includes: the tag name; the kind of tag; the line number, +file name, and source line (with extra white space condensed) of the +file which defines the tag. No tag file is written and all options +affecting tag file output will be ignored.</p> +<p>Example applications for this +feature are generating a listing of all functions located in a source +file (e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-x</span> <span class="pre">--kinds-c=f</span> <span class="pre">file</span></code>”), or generating +a list of all externally visible global variables located in a source +file (e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-x</span> <span class="pre">--kinds-c=v</span> <span class="pre">--extras=-F</span> <span class="pre">file</span></code>”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--sort=(yes|no|foldcase)</span></code></dt><dd><p>Indicates whether the tag file should be sorted on the tag name +(default is <code class="docutils literal notranslate"><span class="pre">yes</span></code>). Note that the original <code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> required sorted tags. +The <code class="docutils literal notranslate"><span class="pre">foldcase</span></code> value specifies case insensitive (or case-folded) sorting. +Fast binary searches of tag files sorted with case-folding will require +special support from tools using tag files, such as that found in the +ctags readtags library, or Vim version 6.2 or higher +(using “<code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">ignorecase</span></code>”). +[Ignored in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-u</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--sort=no</span></code> (i.e. “unsorted”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--etags-include=<file></span></code></dt><dd><p>Include a reference to <em><file></em> in the tag file. This option may be specified +as many times as desired. This supports Emacs’ capability to use a +tag file which <em>includes</em> other tag files. [Available only in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--input-encoding=<encoding></span></code></dt><dd><p>Specifies the <em><encoding></em> of the input files. +If this option is specified, Universal Ctags converts the input from this +encoding to the encoding specified by <code class="docutils literal notranslate"><span class="pre">--output-encoding=encoding</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--input-encoding-<LANG>=<encoding></span></code></dt><dd><p>Specifies a specific input <em><encoding></em> for <em><LANG></em>. It overrides the global +default value given with <code class="docutils literal notranslate"><span class="pre">--input-encoding</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--output-encoding=<encoding></span></code></dt><dd><p>Specifies the <em><encoding></em> of the tags file. +Universal Ctags converts the encoding of input files from the encoding +specified by <code class="docutils literal notranslate"><span class="pre">--input-encoding=<encoding></span></code> to this encoding.</p> +<p>In addition <em><encoding></em> is specified at the top the tags file as the +value for the <code class="docutils literal notranslate"><span class="pre">TAG_FILE_ENCODING</span></code> pseudo-tag. The default value of +<em><encoding></em> is <code class="docutils literal notranslate"><span class="pre">UTF-8</span></code>.</p> +</dd> +</dl> +</section> +<section id="language-selection-and-mapping-options"> +<span id="option-lang-mapping"></span><h3>Language Selection and Mapping Options<a class="headerlink" href="#language-selection-and-mapping-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--language-force=(<language>|auto)</span></code></dt><dd><p>By default, ctags automatically selects the language +of a source file, ignoring those files whose language cannot be +determined (see “<a class="reference internal" href="#determining-file-language">Determining file language</a>”). This option forces the specified +<em>language</em> (case-insensitive; either built-in or user-defined) to be used +for every supplied file instead of automatically selecting the language +based upon its extension.</p> +<p>In addition, the special value <code class="docutils literal notranslate"><span class="pre">auto</span></code> indicates +that the language should be automatically selected (which effectively +disables this option).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--languages=[+|-](<list>|all)</span></code></dt><dd><p>Specifies the languages for which tag generation is enabled, with <em><list></em> +containing a comma-separated list of language names (case-insensitive; +either built-in or user-defined).</p> +<p>If the first language of <em><list></em> is not +preceded by either a ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’, the current list (the current settings +of enabled/disabled languages managed in ctags internally) +will be cleared before adding or removing the languages in <em><list></em>. Until a ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ is +encountered, each language in the <em><list></em> will be added to the current list.</p> +<p>As either the ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ is encountered in the <em><list></em>, the languages +following it are added or removed from the current list, respectively. +Thus, it becomes simple to replace the current list with a new one, or +to add or remove languages from the current list.</p> +<p>The actual list of +files for which tags will be generated depends upon the language +extension mapping in effect (see the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option). Note that the most of +languages, including user-defined languages, are enabled unless explicitly +disabled using this option. Language names included in list may be any +built-in language or one previously defined with <code class="docutils literal notranslate"><span class="pre">--langdef</span></code>.</p> +<p>The default +is <code class="docutils literal notranslate"><span class="pre">all</span></code>, which is also accepted as a valid argument. See the +<code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> option for a list of the all (built-in and user-defined) +language names.</p> +<p>Note <code class="docutils literal notranslate"><span class="pre">--languages=</span></code> option works cumulative way; the option can be +specified with different arguments multiple times in a command line.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--alias-<LANG>=[+|-](<pattern>|default)</span></code></dt><dd><p>Adds (’<code class="docutils literal notranslate"><span class="pre">+</span></code>’) or removes (’<code class="docutils literal notranslate"><span class="pre">-</span></code>’) an alias <em><pattern></em> to a language specified +with <em><LANG></em>. ctags refers to the alias pattern in +“<a class="reference internal" href="#determining-file-language">Determining file language</a>” stage.</p> +<p>The parameter <em><pattern></em> is not a list. Use this option multiple +times in a command line to add or remove multiple alias +patterns.</p> +<p>To restore the default language aliases, specify <code class="docutils literal notranslate"><span class="pre">default</span></code>.</p> +<p>Using <code class="docutils literal notranslate"><span class="pre">all</span></code> for <em><LANG></em> has meaning in following two cases:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">--alias-all=</span></code></dt><dd><p>This clears aliases setting of all languages.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--alias-all=default</span></code></dt><dd><p>This restores the default languages aliases for all languages.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code></dt><dd><p>Looks into the file contents for heuristically guessing the proper language parser. +See “<a class="reference internal" href="#determining-file-language">Determining file language</a>”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-G</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--langmap=<map>[,<map>[...]]</span></code></dt><dd><p>Controls how file names are mapped to languages (see the <code class="docutils literal notranslate"><span class="pre">--list-maps</span></code> +option). Each comma-separated <em><map></em> consists of the language name (either +a built-in or user-defined language), a colon, and a list of <em>file +extensions</em> and/or <em>file name patterns</em>. A file extension is specified by +preceding the extension with a period (e.g. <code class="docutils literal notranslate"><span class="pre">.c</span></code>). A file name pattern +is specified by enclosing the pattern in parentheses (e.g. +<code class="docutils literal notranslate"><span class="pre">([Mm]akefile)</span></code>).</p> +<p>If appropriate support is available from the runtime +library of your C compiler, then the file name pattern may contain the usual +shell wildcards common on Unix (be sure to quote the option parameter to +protect the wildcards from being expanded by the shell before being +passed to ctags). You can determine if shell wildcards +are available on your platform by examining the output of the +<code class="docutils literal notranslate"><span class="pre">--list-features</span></code> option, which will include <code class="docutils literal notranslate"><span class="pre">wildcards</span></code> in the compiled +feature list; otherwise, the file name patterns are matched against +file names using a simple textual comparison.</p> +<p>When mapping a file extension with <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option, +it will first be unmapped from any other languages. (<code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> +option provides more fine-grained control.)</p> +<p>If the first character in a <em><map></em> is a plus sign (’<code class="docutils literal notranslate"><span class="pre">+</span></code>’), then the extensions and +file name patterns in that map will be appended to the current map +for that language; otherwise, the map will replace the current map. +For example, to specify that only files with extensions of <code class="docutils literal notranslate"><span class="pre">.c</span></code> and <code class="docutils literal notranslate"><span class="pre">.x</span></code> are +to be treated as C language files, use <code class="docutils literal notranslate"><span class="pre">--langmap=c:.c.x</span></code>; to also add +files with extensions of <code class="docutils literal notranslate"><span class="pre">.j</span></code> as Java language files, specify +<code class="docutils literal notranslate"><span class="pre">--langmap=c:.c.x,java:+.j</span></code>. To map makefiles (e.g. files named either +<code class="docutils literal notranslate"><span class="pre">Makefile</span></code>, <code class="docutils literal notranslate"><span class="pre">makefile</span></code>, or having the extension <code class="docutils literal notranslate"><span class="pre">.mak</span></code>) to a language +called <code class="docutils literal notranslate"><span class="pre">make</span></code>, specify <code class="docutils literal notranslate"><span class="pre">--langmap=make:([Mm]akefile).mak</span></code>. To map files +having no extension, specify a period not followed by a non-period +character (e.g. ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’, <code class="docutils literal notranslate"><span class="pre">..x</span></code>, <code class="docutils literal notranslate"><span class="pre">.x.</span></code>).</p> +<p>To clear the mapping for a +particular language (thus inhibiting automatic generation of tags for +that language), specify an empty extension list (e.g. <code class="docutils literal notranslate"><span class="pre">--langmap=fortran:</span></code>). +To restore the default language mappings for a particular language, +supply the keyword <code class="docutils literal notranslate"><span class="pre">default</span></code> for the mapping. To specify restore the +default language mappings for all languages, specify <code class="docutils literal notranslate"><span class="pre">--langmap=default</span></code>.</p> +<p>Note that file name patterns are tested before file extensions when inferring +the language of a file. This order of Universal Ctags is different from +Exuberant Ctags. See <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a> for the background of +this incompatible change.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code></dt><dd><p>This option provides the way to control mapping(s) of file names to +languages in a more fine-grained way than <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option.</p> +<p>In ctags, more than one language can map to a +file name <em><pattern></em> or file <em><extension></em> (<em>N:1 map</em>). Alternatively, +<code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option handle only <em>1:1 map</em>, only one language +mapping to one file name <em><pattern></em> or file <em><extension></em>. A typical N:1 +map is seen in C++ and ObjectiveC language; both languages have +a map to <code class="docutils literal notranslate"><span class="pre">.h</span></code> as a file extension.</p> +<p>A file extension is specified by preceding the extension with a period (e.g. <code class="docutils literal notranslate"><span class="pre">.c</span></code>). +A file name pattern is specified by enclosing the pattern in parentheses (e.g. +<code class="docutils literal notranslate"><span class="pre">([Mm]akefile)</span></code>). A prefixed plus (’<code class="docutils literal notranslate"><span class="pre">+</span></code>’) sign is for adding, and +minus (’<code class="docutils literal notranslate"><span class="pre">-</span></code>’) is for removing. No prefix means replacing the map of <em><LANG></em>.</p> +<p>Unlike <code class="docutils literal notranslate"><span class="pre">--langmap</span></code>, <em><extension></em> (or <em><pattern></em>) is not a list. +<code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> takes one extension (or pattern). However, +the option can be specified with different arguments multiple times +in a command line.</p> +</dd> +</dl> +</section> +<section id="tags-file-contents-options"> +<span id="option-tags-file-contents"></span><h3>Tags File Contents Options<a class="headerlink" href="#tags-file-contents-options" title="Permalink to this headline">¶</a></h3> +<p>See “<a class="reference internal" href="#id1">TAG ENTRIES</a>” about fields, kinds, roles, and extras.</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--excmd=(number|pattern|mix|combine)</span></code></dt><dd><p>Determines the type of <code class="docutils literal notranslate"><span class="pre">EX</span></code> command used to locate tags in the source +file. [Ignored in etags mode]</p> +<p>The valid values for type (either the entire word or the first letter +is accepted) are:</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">number</span></code></dt><dd><p>Use only line numbers in the tag file for locating tags. This has +four advantages:</p> +<ol class="arabic simple"> +<li><p>Significantly reduces the size of the resulting tag file.</p></li> +<li><p>Eliminates failures to find tags because the line defining the +tag has changed, causing the pattern match to fail (note that +some editors, such as <code class="docutils literal notranslate"><span class="pre">vim</span></code>, are able to recover in many such +instances).</p></li> +<li><p>Eliminates finding identical matching, but incorrect, source +lines (see “<a class="reference internal" href="#bugs">BUGS</a>”).</p></li> +<li><p>Retains separate entries in the tag file for lines which are +identical in content. In pattern mode, duplicate entries are +dropped because the search patterns they generate are identical, +making the duplicate entries useless.</p></li> +</ol> +<p>However, this option has one significant drawback: changes to the +source files can cause the line numbers recorded in the tag file +to no longer correspond to the lines in the source file, causing +jumps to some tags to miss the target definition by one or more +lines. Basically, this option is best used when the source code +to which it is applied is not subject to change. Selecting this +option type causes the following options to be ignored: <code class="docutils literal notranslate"><span class="pre">-B</span></code>, <code class="docutils literal notranslate"><span class="pre">-F</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">number</span></code> type is ignored in Xref and JSON output formats. Use +<code class="docutils literal notranslate"><span class="pre">--_xformat="...%n"</span></code> for Xref output format, or <code class="docutils literal notranslate"><span class="pre">--fields=+n-P</span></code> for +JSON output format.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">pattern</span></code></dt><dd><p>Use only search patterns for all tags, rather than the line numbers +usually used for macro definitions. This has the advantage of +not referencing obsolete line numbers when lines have been added or +removed since the tag file was generated.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">mixed</span></code></dt><dd><p>In this mode, patterns are generally used with a few exceptions. +For C, line numbers are used for macro definition tags. For Fortran, line numbers +are used for common blocks because their corresponding source lines +are generally identical, making pattern searches useless +for finding all matches.</p> +<p>This was the default format generated by the original ctags and is, +therefore, retained as the default for this option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">combine</span></code></dt><dd><p>Concatenate the line number and pattern with a semicolon in between.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-n</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--excmd=number</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-N</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--excmd=pattern</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--extras=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies whether to include extra tag entries for certain kinds of +information. See also “<a class="reference internal" href="#extras">Extras</a>” subsection to know what are extras.</p> +<p>The parameter <em><flags></em> is a set of one-letter flags (and/or long-name flags), each +representing one kind of extra tag entry to include in the tag file. +If flags is preceded by either the ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ character, the effect of +each flag is added to, or removed from, those currently enabled; +otherwise the flags replace any current settings. All entries are +included if ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is given.</p> +<p>This <code class="docutils literal notranslate"><span class="pre">--extras=</span></code> option is for controlling extras common in all +languages (or language-independent extras). Universal Ctags also +supports language-specific extras. (See “<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>” about the concept). Use <code class="docutils literal notranslate"><span class="pre">--extras-<LANG>=</span></code> option for +controlling them.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--extras-(<LANG>|all)=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies whether to include extra tag entries for certain kinds of +information for language <em><LANG></em>. Universal Ctags +introduces language-specific extras. See “<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>” about the concept. This option is for controlling them.</p> +<p>Specifies <code class="docutils literal notranslate"><span class="pre">all</span></code> as <em><LANG></em> to apply the parameter <em><flags></em> to all +languages; all extras are enabled with specifying ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as the +parameter flags. If specifying nothing as the parameter flags +(<code class="docutils literal notranslate"><span class="pre">--extras-all=</span></code>), all extras are disabled. These two combinations +are useful for testing.</p> +<p>Check the output of the <code class="docutils literal notranslate"><span class="pre">--list-extras=<LANG></span></code> option for the +extras of specific language <em><LANG></em>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--fields=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies which language-independent fields are to be included in the tag +entries. Language-independent fields are extension fields which are common +in all languages. See “<a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a>” section, and “<a class="reference internal" href="#extension-fields">Extension fields</a>” +subsection, for details of extension fields.</p> +<p>The parameter <em><flags></em> is a set of one-letter or long-name flags, +each representing one type of extension field to include. +Each flag or group of flags may be preceded by either ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ to add it +to the default set, or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ to exclude it. In the absence of any +preceding ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ sign, only those fields explicitly listed in flags +will be included in the output (i.e. overriding the default set). All +fields are included if ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is given.</p> +<p>This option is ignored if the +option <code class="docutils literal notranslate"><span class="pre">--format=1</span></code> (legacy tag file format) has been specified.</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--fields-<LANG>=</span></code> option for controlling language-specific fields.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--fields-(<LANG>|all)=[+|-][<flags>|*]</span></code></dt><dd><p>Specifies which language-specific fields are to be included in +the tag entries. Universal Ctags +supports language-specific fields. (See “<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>” about the concept).</p> +<p>Specify <code class="docutils literal notranslate"><span class="pre">all</span></code> as <em><LANG></em> to apply the parameter <em><flags></em> to all +languages; all fields are enabled with specifying ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as the +parameter flags. If specifying nothing as the parameter <em><flags></em> +(i.e. <code class="docutils literal notranslate"><span class="pre">--fields-all=</span></code>), all fields are disabled. These two combinations +are useful for testing.</p> +<p>See the description of <code class="docutils literal notranslate"><span class="pre">--fields=[+|-][<flags>|*]</span></code> about <em><flags></em>.</p> +<p>Use <code class="docutils literal notranslate"><span class="pre">--fields=</span></code> option for controlling language-independent fields.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></code></dt><dd><p>Specifies a list of language-specific <em><kinds></em> of tags (or kinds) to +include in the output file for a particular language, where <em><LANG></em> is +case-insensitive and is one of the built-in language names (see the +<code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> option for a complete list).</p> +<p>The parameter <em><kinds></em> is a group +of one-letter or long-name flags designating kinds of tags (particular to the language) +to either include or exclude from the output. The specific sets of +flags recognized for each language, their meanings and defaults may be +list using the <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> option.</p> +<p>Each letter or group of letters +may be preceded by either ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ to add it to, or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ to remove it from, +the default set. In the absence of any preceding ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ sign, only +those kinds explicitly listed in kinds will be included in the output +(i.e. overriding the default for the specified language).</p> +<p>Specify ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as the parameter to include all kinds implemented +in <em><LANG></em> in the output. Furthermore if <code class="docutils literal notranslate"><span class="pre">all</span></code> is given as <em><LANG></em>, +specification of the parameter <code class="docutils literal notranslate"><span class="pre">kinds</span></code> affects all languages defined +in ctags. Giving <code class="docutils literal notranslate"><span class="pre">all</span></code> makes sense only when ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ or +‘<code class="docutils literal notranslate"><span class="pre">F</span></code>’ is given as the parameter <code class="docutils literal notranslate"><span class="pre">kinds</span></code>.</p> +<p>As an example for the C language, in order to add prototypes and +external variable declarations to the default set of tag kinds, +but exclude macros, use <code class="docutils literal notranslate"><span class="pre">--kinds-c=+px-d</span></code>; to include only tags for +functions, use <code class="docutils literal notranslate"><span class="pre">--kinds-c=f</span></code>.</p> +<p>Some kinds of C and C++ languages are synchronized; enabling +(or disabling) a kind in one language enables the kind having +the same one-letter and long-name in the other language. See also the +description of <code class="docutils literal notranslate"><span class="pre">MASTER</span></code> column of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code>.</p> +</dd> +</dl> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--pattern-length-limit=<N></span></code></dt><dd><p>Truncate patterns of tag entries after <em><N></em> characters. Disable by setting to 0 +(default is 96).</p> +<p>An input source file with long lines and multiple tag matches per +line can generate an excessively large tags file with an +unconstrained pattern length. For example, running ctags on a +minified JavaScript source file often exhibits this behavior.</p> +<p>The truncation avoids cutting in the middle of a UTF-8 code point +spanning multiple bytes to prevent writing invalid byte sequences from +valid input files. This handling allows for an extra 3 bytes above the +configured limit in the worse case of a 4 byte code point starting +right before the limit. Please also note that this handling is fairly +naive and fast, and although it is resistant against any input, it +requires a valid input to work properly; it is not guaranteed to work +as the user expects when dealing with partially invalid UTF-8 input. +This also partially affect non-UTF-8 input, if the byte sequence at +the truncation length looks like a multibyte UTF-8 sequence. This +should however be rare, and in the worse case will lead to including +up to an extra 3 bytes above the limit.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--pseudo-tags=[+|-](<pseudo-tag>|*)</span></code></dt><dd><p>Enable/disable emitting pseudo-tag named <em><pseudo-tag></em>. +If ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is given, enable/disable emitting all pseudo-tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--put-field-prefix</span></code></dt><dd><p>Put <code class="docutils literal notranslate"><span class="pre">UCTAGS</span></code> as prefix for the name of fields newly introduced in +Universal Ctags.</p> +<p>Some fields are newly introduced in Universal Ctags and more will +be introduced in the future. Other tags generators may also +introduce their specific fields.</p> +<p>In such a situation, there is a concern about conflicting field +names; mixing tags files generated by multiple tags generators +including Universal Ctags is difficult. This option provides a +workaround for such station.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span><span class="s1">'{line}{end}'</span> -o - hello.c +<span class="go">main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6</span> +<span class="gp">$ </span>ctags --put-field-prefix --fields<span class="o">=</span><span class="s1">'{line}{end}'</span> -o - hello.c +<span class="go">main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6</span> +</pre></div> +</div> +<p>In the above example, the prefix is put to <code class="docutils literal notranslate"><span class="pre">end</span></code> field which is +newly introduced in Universal Ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]</span></code></dt><dd><p>Specifies a list of kind-specific roles of tags to include in the +output file for a particular language. +<em><kind></em> specifies the kind where the <em><roles></em> are defined. +<em><LANG></em> specifies the language where the kind is defined. +Each role in <em><roles></em> must be surrounded by braces (e.g. <code class="docutils literal notranslate"><span class="pre">{system}</span></code> +for a role named “system”).</p> +<p>Like <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> option, ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ is for adding the role to the +list, and ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ is for removing from the list. ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ is for including +all roles of the kind to the list. The option with no argument +makes the list empty.</p> +<p>Both a one-letter flag or a long name flag surrounded by braces are +acceptable for specifying a kind (e.g. <code class="docutils literal notranslate"><span class="pre">--roles-C.h=+{system}{local}</span></code> +or <code class="docutils literal notranslate"><span class="pre">--roles-C.{header}=+{system}{local}</span></code>). ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ can be used for <em><KIND></em> +only for adding/removing all roles of all kinds in a language to/from +the list (e.g. <code class="docutils literal notranslate"><span class="pre">--roles-C.*=*</span></code> or <code class="docutils literal notranslate"><span class="pre">--roles-C.*=</span></code>).</p> +<p><code class="docutils literal notranslate"><span class="pre">all</span></code> can be used for <em><LANG></em> only for adding/removing all roles of +all kinds in all languages to/from the list +(e.g. <code class="docutils literal notranslate"><span class="pre">--roles-all.*=*</span></code> or <code class="docutils literal notranslate"><span class="pre">--roles-all.*=</span></code>).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--tag-relative=(yes|no|always|never)</span></code></dt><dd><p>Specifies how the file paths recorded in the tag file. +The default is <code class="docutils literal notranslate"><span class="pre">yes</span></code> when running in etags mode (see +the <code class="docutils literal notranslate"><span class="pre">-e</span></code> option), <code class="docutils literal notranslate"><span class="pre">no</span></code> otherwise.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">yes</span></code></dt><dd><p>indicates that the file paths recorded in the tag file should be +<em>relative to the directory containing the tag file</em> +unless the files supplied on the command line +are specified with absolute paths.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">no</span></code></dt><dd><p>indicates that the file paths recorded in the tag file should be +<em>relative to the current directory</em> +unless the files supplied on the command line +are specified with absolute paths.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">always</span></code></dt><dd><p>indicates the recorded file paths should be relative +even if source file names are passed in with absolute paths.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">never</span></code></dt><dd><p>indicates the recorded file paths should be absolute +even if source file names are passed in with relative paths.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--use-slash-as-filename-separator[=(yes|no)]</span></code></dt><dd><p>Uses slash (’<code class="docutils literal notranslate"><span class="pre">/</span></code>’) character as filename separators instead of backslash +(’<code class="docutils literal notranslate"><span class="pre">\</span></code>’) character when printing <code class="docutils literal notranslate"><span class="pre">input:</span></code> field. +The default is <code class="docutils literal notranslate"><span class="pre">yes</span></code> for the default “u-ctags” output format, and +<code class="docutils literal notranslate"><span class="pre">no</span></code> for the other formats.</p> +<p>This option is available on MS Windows only.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-B</span></code></dt><dd><p>Use backward searching patterns (e.g. <code class="docutils literal notranslate"><span class="pre">?pattern?</span></code>). [Ignored in etags mode]</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-F</span></code></dt><dd><p>Use forward searching patterns (e.g. <code class="docutils literal notranslate"><span class="pre">/pattern/</span></code>) (default). [Ignored +in etags mode]</p> +</dd> +</dl> +</section> +<section id="option-file-options"> +<h3>Option File Options<a class="headerlink" href="#option-file-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--options=<pathname></span></code></dt><dd><p>Read additional options from file or directory.</p> +<p>ctags searches <em><pathname></em> in the optlib path list +first. If ctags cannot find a file or directory +in the list, ctags reads a file or directory +at the specified <em><pathname></em>.</p> +<p>If a file is specified, it should contain one option per line. If +a directory is specified, files suffixed with <code class="docutils literal notranslate"><span class="pre">.ctags</span></code> under it +are read in alphabetical order.</p> +<p>As a special case, if <code class="docutils literal notranslate"><span class="pre">--options=NONE</span></code> is specified as the first +option on the command line, preloading is disabled; the option +will disable the automatic reading of any configuration options +from a file (see “<a class="reference internal" href="#files">FILES</a>”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--options-maybe=<pathname></span></code></dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">--options</span></code> but doesn’t cause an error if file +(or directory) specified with <em><pathname></em> doesn’t exist.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--optlib-dir=[+]<directory></span></code></dt><dd><p>Add an optlib <em><directory></em> to or reset the optlib path list. +By default, the optlib path list is empty.</p> +</dd> +</dl> +</section> +<section id="optlib-options"> +<h3>optlib Options<a class="headerlink" href="#optlib-options" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> for details of each option.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></code></dt><dd><p>Define a kind for <em><LANG></em>. +Don’t be confused this with <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--langdef=<name></span></code></dt><dd><p>Defines a new user-defined language, <em><name></em>, to be parsed with regular +expressions.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define multi-line regular expression for locating tags in specific language.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></code></dt><dd><p>Define single-line regular expression for locating tags in specific language.</p> +</dd> +</dl> +</section> +<section id="language-specific-options"> +<span id="option-lang-specific"></span><h3>Language Specific Options<a class="headerlink" href="#language-specific-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--if0[=(yes|no)]</span></code></dt><dd><p>Indicates a preference as to whether code within an “<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code>” branch of a +preprocessor conditional should be examined for non-macro tags (macro +tags are always included). Because the intent of this construct is to +disable code, the default value of this option is <code class="docutils literal notranslate"><span class="pre">no</span></code> (disabled).</p> +<p>Note that this +indicates a preference only and does not guarantee skipping code within +an “<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code>” branch, since the fall-back algorithm used to generate +tags when preprocessor conditionals are too complex follows all branches +of a conditional.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--line-directives[=(yes|no)]</span></code></dt><dd><p>Specifies whether <code class="docutils literal notranslate"><span class="pre">#line</span></code> directives should be recognized. These are +present in the output of a preprocessor and contain the line number, and +possibly the file name, of the original source file(s) from which the +preprocessor output file was generated. This option is off by default.</p> +<p>When enabled, this option will +cause ctags to generate tag entries marked with the +file names and line numbers of their locations original source file(s), +instead of their actual locations in the preprocessor output. The actual +file names placed into the tag file will have the same leading path +components as the preprocessor output file, since it is assumed that +the original source files are located relative to the preprocessor +output file (unless, of course, the <code class="docutils literal notranslate"><span class="pre">#line</span></code> directive specifies an +absolute path).</p> +<p>Note: This option is generally +only useful when used together with the <code class="docutils literal notranslate"><span class="pre">--excmd=number</span></code> (<code class="docutils literal notranslate"><span class="pre">-n</span></code>) option. +Also, you may have to use either the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> or <code class="docutils literal notranslate"><span class="pre">--language-force</span></code> option +if the extension of the preprocessor output file is not known to +ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-D</span> <span class="pre"><macro>=<definition></span></code></dt><dd><p>Defines a C preprocessor <em><macro></em>. This emulates the behavior of the +corresponding gcc option. All types of macros are supported, +including the ones with parameters and variable arguments. +Stringification, token pasting and recursive macro expansion are also +supported. +This extends the function provided by <code class="docutils literal notranslate"><span class="pre">-I</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-h</span> <span class="pre">(<list>|default)</span></code></dt><dd><p>Specifies a <em><list></em> of file extensions, separated by periods, which are +to be interpreted as include (or header) files. To indicate files having +no extension, use a period not followed by a non-period character +(e.g. ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’, <code class="docutils literal notranslate"><span class="pre">..x</span></code>, <code class="docutils literal notranslate"><span class="pre">.x.</span></code>).</p> +<p>This option only affects how the scoping of +particular kinds of tags are interpreted (i.e. whether or not they are +considered as globally visible or visible only within the file in which +they are defined); it does not map the extension to any particular +language. Any tag which is located in a non-include file and cannot be +seen (e.g. linked to) from another file is considered to have file-limited +(e.g. static) scope. No kind of tag appearing in an include file +will be considered to have file-limited scope.</p> +<p>If the first character in the list is ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’, then the extensions in the list will be +appended to the current list; otherwise, the list will replace the +current list. See, also, the <code class="docutils literal notranslate"><span class="pre">fileScope</span></code>/<code class="docutils literal notranslate"><span class="pre">F</span></code> flag of <code class="docutils literal notranslate"><span class="pre">--extras</span></code> option.</p> +<p>The default list is +<code class="docutils literal notranslate"><span class="pre">.h.H.hh.hpp.hxx.h++.inc.def</span></code>. To restore the default list, specify “<code class="docutils literal notranslate"><span class="pre">-h</span> +<span class="pre">default</span></code>”.</p> +<p>Note that if an extension supplied to this option is not +already mapped to a particular language (see “<a class="reference internal" href="#determining-file-language">Determining file language</a>”, above), +you will also need to use either the <code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> or +<code class="docutils literal notranslate"><span class="pre">--language-force</span></code> option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre"><identifier-list></span></code></dt><dd><p>Specifies a <em><identifier-list></em> of identifiers which are to be specially handled while +parsing C and C++ source files. This option is specifically provided +to handle special cases arising through the use of preprocessor macros. +When the identifiers listed are simple identifiers, these identifiers +will be ignored during parsing of the source files.</p> +<p>If an identifier is +suffixed with a ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ character (i.e. “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">FOO+</span></code>”), ctags will also +ignore any parenthesis-enclosed argument list which may immediately +follow the identifier in the source files. See the example of “<code class="docutils literal notranslate"><span class="pre">-I</span> +<span class="pre">MODULE_VERSION+</span></code>” below.</p> +<p>If two identifiers are +separated with the ‘<code class="docutils literal notranslate"><span class="pre">=</span></code>’ character (i.e. <code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">FOO=BAR</span></code>), the first identifiers is replaced by +the second identifiers for parsing purposes. The list of identifiers may +be supplied directly on the command line or read in from a separate file. +See the example of “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">CLASS=class</span></code>” below.</p> +<p>If the first character of <em><identifier-list></em> is ‘<code class="docutils literal notranslate"><span class="pre">@</span></code>’, ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’ or a pathname +separator (’<code class="docutils literal notranslate"><span class="pre">/</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">\</span></code>’), or the first two characters specify a drive +letter (e.g. <code class="docutils literal notranslate"><span class="pre">C:</span></code>), the parameter <em><identifier-list></em> will be interpreted as +a filename from which to read a list of identifiers, one per input line.</p> +<p>Otherwise, <em><identifier-list></em> is a list of identifiers (or identifier +pairs) to be specially handled, each delimited by either a comma or +by white space (in which case the list should be quoted to keep the +entire list as one command line argument).</p> +<p>Multiple <code class="docutils literal notranslate"><span class="pre">-I</span></code> options may be +supplied. To clear the list of ignore identifiers, supply a single +dash (’<code class="docutils literal notranslate"><span class="pre">-</span></code>’) for <em><identifier-list></em>.</p> +<p>This feature is useful when preprocessor macros are used in such a way +that they cause syntactic confusion due to their presence. Indeed, +this is the best way of working around a number of problems caused by +the presence of syntax-busting macros in source files (see “<a class="reference internal" href="#caveats">CAVEATS</a>”). +Some examples will illustrate this point.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">foo</span> <span class="n">ARGDECL4</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">,</span> <span class="n">ptr</span><span class="p">,</span> <span class="kt">long</span> <span class="kt">int</span><span class="p">,</span> <span class="n">nbytes</span><span class="p">)</span> +</pre></div> +</div> +<p>In the above example, the macro <code class="docutils literal notranslate"><span class="pre">ARGDECL4</span></code> would be mistakenly +interpreted to be the name of the function instead of the correct name +of <code class="docutils literal notranslate"><span class="pre">foo</span></code>. Specifying “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">ARGDECL4</span></code>” results in the correct behavior.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="cm">/* creates an RCS version string in module */</span> +<span class="n">MODULE_VERSION</span><span class="p">(</span><span class="s">"$Revision$"</span><span class="p">)</span> +</pre></div> +</div> +<p>In the above example the macro invocation looks too much like a function +definition because it is not followed by a semicolon (indeed, it +could even be followed by a global variable definition that would look +much like a K&R style function parameter declaration). In fact, this +seeming function definition could possibly even cause the rest of the +file to be skipped over while trying to complete the definition. +Specifying “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">MODULE_VERSION+</span></code>” would avoid such a problem.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">CLASS</span> <span class="n">Example</span> <span class="p">{</span> + <span class="c1">// your content here</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The example above uses <code class="docutils literal notranslate"><span class="pre">CLASS</span></code> as a preprocessor macro which expands to +something different for each platform. For instance <code class="docutils literal notranslate"><span class="pre">CLASS</span></code> may be +defined as <code class="docutils literal notranslate"><span class="pre">class</span> <span class="pre">__declspec(dllexport)</span></code> on Win32 platforms and simply +<code class="docutils literal notranslate"><span class="pre">class</span></code> on UNIX. Normally, the absence of the C++ keyword <code class="docutils literal notranslate"><span class="pre">class</span></code> +would cause the source file to be incorrectly parsed. Correct behavior +can be restored by specifying “<code class="docutils literal notranslate"><span class="pre">-I</span> <span class="pre">CLASS=class</span></code>”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--param-<LANG>:<name>=<argument></span></code></dt><dd><p>Set a <em><LANG></em> specific parameter, a parameter specific to the <em><LANG></em>.</p> +<p>Available parameters can be listed with <code class="docutils literal notranslate"><span class="pre">--list-params</span></code>.</p> +</dd> +</dl> +</section> +<section id="listing-options"> +<span id="option-listing"></span><h3>Listing Options<a class="headerlink" href="#listing-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--list-aliases[=(<language>|all)]</span></code></dt><dd><p>Lists the aliases for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted. +The aliases are used when heuristically testing a language parser for a +source file.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-excludes</span></code></dt><dd><p>Lists the current exclusion patterns used to exclude files.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-extras[=(<language>|all)]</span></code></dt><dd><p>Lists the extras recognized for either the specified <em><language></em> or +<code class="docutils literal notranslate"><span class="pre">all</span></code> languages. See “<a class="reference internal" href="#extras">Extras</a>” subsection to know what are extras. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>An extra can be enabled or disabled with <code class="docutils literal notranslate"><span class="pre">--extras=</span></code> for common +extras in all languages, or <code class="docutils literal notranslate"><span class="pre">--extras-<LANG>=</span></code> for the specified +language. These option takes one-letter flag or long-name flag as a parameter +for specifying an extra.</p> +<p>The meaning of columns in output are as follows:</p> +<dl class="simple"> +<dt>LETTER</dt><dd><p>One-letter flag. ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ means the extra does not have one-letter flag.</p> +</dd> +<dt>NAME</dt><dd><p>Long-name flag. The long-name is used in <code class="docutils literal notranslate"><span class="pre">extras</span></code> field.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the extra is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>LANGUAGE</dt><dd><p>The name of language if the extra is owned by a parser. +<code class="docutils literal notranslate"><span class="pre">NONE</span></code> means the extra is common in parsers.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the extra.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-features</span></code></dt><dd><p>Lists the compiled features.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-fields[=(<language>|all)]</span></code></dt><dd><p>Lists the fields recognized for either the specified <em><language></em> or +<code class="docutils literal notranslate"><span class="pre">all</span></code> languages. See “<a class="reference internal" href="#extension-fields">Extension fields</a>” subsection to know what are fields. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>The meaning of columns are as follows:</p> +<dl> +<dt>LETTER</dt><dd><p>One-letter flag. ‘<code class="docutils literal notranslate"><span class="pre">-</span></code>’ means the field does not have one-letter flag.</p> +</dd> +<dt>NAME</dt><dd><p>Long-name of field.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the field is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>LANGUAGE</dt><dd><p>The name of language if the field is owned by a parser. +<code class="docutils literal notranslate"><span class="pre">NONE</span></code> means that the field is a language-independent field which is +common in all languages.</p> +</dd> +<dt>JSTYPE</dt><dd><p>JSON type used in printing the value of field when <code class="docutils literal notranslate"><span class="pre">--output-format=json</span></code> +is specified. See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a>.</p> +</dd> +<dt>FIXED</dt><dd><p>Whether this field can be disabled or not in tags output.</p> +<p>Some fields are printed always in tags output. +They have <code class="docutils literal notranslate"><span class="pre">yes</span></code> as the value for this column.</p> +<p>Unlike the tag output mode, JSON output mode allows disabling +any fields.</p> +</dd> +<dt>OP</dt><dd><p>How this field can be accessed from optscript code. +This field is for Universal Ctags developers.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the field.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-kinds[=(<language>|all)]</span></code></dt><dd><p>Subset of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code>. This option is kept for +backward-compatibility with Exuberant Ctags.</p> +<p>This option prints only LETTER, DESCRIPTION, and ENABLED fields +of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> output. However, the presentation of +ENABLED column is different from that of <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> +option; <code class="docutils literal notranslate"><span class="pre">[off]</span></code> follows after description if the kind is disabled, +and nothing follows if enabled. The most of all kinds are enabled +by default.</p> +<p>The critical weakness of this option is that this option does not +print the name of kind. Universal Ctags introduces +<code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> because it considers that names are +important.</p> +<p>This option does not work with <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> nor +<code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-kinds-full[=(<language>|all)]</span></code></dt><dd><p>Lists the tag kinds recognized for either the specified <em><language></em> +or <code class="docutils literal notranslate"><span class="pre">all</span></code> languages, and then exits. See “<a class="reference internal" href="#kinds">Kinds</a>” subsection to +learn what kinds are. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>Each kind of tag recorded in the tag file is represented by a +one-letter flag, or a long-name flag. They are also used to filter the tags +placed into the output through use of the <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> +option.</p> +<p>The meaning of columns are as follows:</p> +<dl> +<dt>LANGUAGE</dt><dd><p>The name of language having the kind.</p> +</dd> +<dt>LETTER</dt><dd><p>One-letter flag. This must be unique in a language.</p> +</dd> +<dt>NAME</dt><dd><p>The long-name flag of the kind. This can be used as the alternative +to the one-letter flag described above. If enabling <code class="docutils literal notranslate"><span class="pre">K</span></code> field with +<code class="docutils literal notranslate"><span class="pre">--fields=+K</span></code>, ctags uses long-names instead of +one-letters in tags output. To enable/disable a kind with +<code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> option, long-name surrounded by braces instead +of one-letter. See “<a class="reference internal" href="#letters-and-names">Letters and names</a>” for details. This must be +unique in a language.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the kind is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>REFONLY</dt><dd><p>Whether the kind is specialized for reference tagging or not. +If the column is <code class="docutils literal notranslate"><span class="pre">yes</span></code>, the kind is for reference tagging, and +it is never used for definition tagging. See also “<a class="reference internal" href="#id1">TAG ENTRIES</a>”.</p> +</dd> +<dt>NROLES</dt><dd><p>The number of roles this kind has. See also “<a class="reference internal" href="#roles">Roles</a>”.</p> +</dd> +<dt>MASTER</dt><dd><p>The master parser controlling enablement of the kind. +A kind belongs to a language (owner) in Universal Ctags; +enabling and disabling a kind in a language has no effect on +a kind in another language even if both kinds has the +same one-letter flag and/or the same long-name flag. In other words, +the namespace of kinds are separated by language.</p> +<p>However, Exuberant Ctags does not separate the kinds of C and +C++. Enabling/disabling kindX in C language enables/disables a +kind in C++ language having the same long-name flag with kindX. To +emulate this behavior in Universal Ctags, a concept named +<em>master parser</em> is introduced. Enabling/disabling some kinds +are synchronized under the control of a master language.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --kinds-C<span class="o">=</span>+<span class="s1">'{local}'</span> --list-kinds-full <span class="se">\</span> +<span class="go"> | grep -E '^(#|C\+\+ .* local)'</span> +<span class="gp">#</span>LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">C++ l local yes no 0 C local variables</span> +<span class="gp">$ </span>ctags --kinds-C<span class="o">=</span>-<span class="s1">'{local}'</span> --list-kinds-full <span class="se">\</span> +<span class="go"> | grep -E '^(#|C\+\+ .* local)'</span> +<span class="gp">#</span>LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="go">C++ l local no no 0 C local variables</span> +</pre></div> +</div> +<p>You see <code class="docutils literal notranslate"><span class="pre">ENABLED</span></code> field of <code class="docutils literal notranslate"><span class="pre">local</span></code> kind of C++ language is changed +Though <code class="docutils literal notranslate"><span class="pre">local</span></code> kind of C language is enabled/disabled. If you swap the languages, you +see the same result.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the kind.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-languages</span></code></dt><dd><p>Lists the names of the languages understood by ctags, +and then exits. These language names are case insensitive and may be +used in many other options like <code class="docutils literal notranslate"><span class="pre">--language-force</span></code>, +<code class="docutils literal notranslate"><span class="pre">--languages</span></code>, <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>, and so on.</p> +<p>Each language listed is disabled if followed by <code class="docutils literal notranslate"><span class="pre">[disabled]</span></code>. +To use the parser for such a language, specify the language as an +argument of <code class="docutils literal notranslate"><span class="pre">--languages=+</span></code> option.</p> +<p><code class="docutils literal notranslate"><span class="pre">--machinable</span></code> and <code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code> options are ignored if they are +specified with this option.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-map-extensions[=(<language>|all)]</span></code></dt><dd><p>Lists the file extensions which associate a file +name with a language for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-map-patterns[=(<language>|all)]</span></code></dt><dd><p>Lists the file name patterns which associate a file +name with a language for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-maps[=(<language>|all)]</span></code></dt><dd><p>Lists file name patterns and the file extensions which associate a file +name with a language for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>To list the file extensions or file name patterns individually, use +<code class="docutils literal notranslate"><span class="pre">--list-map-extensions</span></code> or <code class="docutils literal notranslate"><span class="pre">--list-map-patterns</span></code> option. +See the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> option, and “<a class="reference internal" href="#determining-file-language">Determining file language</a>”, above.</p> +<p>This option does not work with <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> nor +<code class="docutils literal notranslate"><span class="pre">--with-list-header</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-mline-regex-flags</span></code></dt><dd><p>Output list of flags which can be used in a multiline regex parser +definition. +See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-params[=(<language>|all)]</span></code></dt><dd><p>Lists the parameters for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> +languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code></dt><dd><p>Output list of pseudo-tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-regex-flags</span></code></dt><dd><p>Lists the flags that can be used in <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option. +See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-roles[=(<language>|all)[.(<kind-specs>|*)]]</span></code></dt><dd><p>List the roles for either the specified <em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> languages. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +<p>If the parameter <em><kindspecs></em> is given after the parameter +<em><language></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> with concatenating with ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’, list only roles +defined in the kinds. Both one-letter flags and long name flags surrounded +by braces are acceptable as the parameter <em><kindspecs></em>.</p> +<p>The meaning of columns are as follows:</p> +<dl class="simple"> +<dt>LANGUAGE</dt><dd><p>The name of language having the role.</p> +</dd> +<dt>KIND(L/N)</dt><dd><p>The one-letter flag and the long-name flag of kind having the role.</p> +</dd> +<dt>NAME</dt><dd><p>The long-name flag of the role.</p> +</dd> +<dt>ENABLED</dt><dd><p>Whether the kind is enabled or not. It takes <code class="docutils literal notranslate"><span class="pre">yes</span></code> or <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt>DESCRIPTION</dt><dd><p>Human readable description for the role.</p> +</dd> +</dl> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--list-subparsers[=(<baselang>|all)]</span></code></dt><dd><p>Lists the subparsers for a base language for either the specified +<em><baselang></em> or <code class="docutils literal notranslate"><span class="pre">all</span></code> languages, and then exits. +<code class="docutils literal notranslate"><span class="pre">all</span></code> is used as default value if the option argument is omitted.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--machinable[=(yes|no)]</span></code></dt><dd><p>Use tab character as separators for <code class="docutils literal notranslate"><span class="pre">--list-</span></code> option output. It +may be suitable for scripting. See “<a class="reference internal" href="#list-options">List options</a>” for considered +use cases. Disabled by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--with-list-header[=(yes|no)]</span></code></dt><dd><p>Print headers describing columns in <code class="docutils literal notranslate"><span class="pre">--list-</span></code> option output. +See also “<a class="reference internal" href="#list-options">List options</a>”.</p> +</dd> +</dl> +</section> +<section id="miscellaneous-options"> +<span id="option-misc"></span><h3>Miscellaneous Options<a class="headerlink" href="#miscellaneous-options" title="Permalink to this headline">¶</a></h3> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">--help</span></code></dt><dd><p>Prints to standard output a detailed usage description, and then exits.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-?</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--help</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--help-full</span></code></dt><dd><p>Prints to standard output a detailed usage description including experimental +features, and then exits. Visit <a class="reference external" href="https://docs.ctags.io/">https://docs.ctags.io/</a> for information +about the latest exciting experimental features.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--license</span></code></dt><dd><p>Prints a summary of the software license to standard output, and then exits.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--print-language</span></code></dt><dd><p>Just prints the language parsers for specified source files, and then exits.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--quiet[=(yes|no)]</span></code></dt><dd><p>Write fewer messages (default is <code class="docutils literal notranslate"><span class="pre">no</span></code>).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--totals[=(yes|no|extra)]</span></code></dt><dd><p>Prints statistics about the source files read and the tag file written +during the current invocation of ctags. This option +is <code class="docutils literal notranslate"><span class="pre">no</span></code> by default.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">extra</span></code> value prints parser specific statistics for parsers +gathering such information.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--verbose[=(yes|no)]</span></code></dt><dd><p>Enable verbose mode. This prints out information on option processing +and a brief message describing what action is being taken for each file +considered by ctags. Normally, ctags +does not read command line arguments until after options are read +from the configuration files (see “<a class="reference internal" href="#files">FILES</a>”, below). +However, if this option is the first argument on +the command line, it will take effect before any options are read from +these sources. The default is <code class="docutils literal notranslate"><span class="pre">no</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-V</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--verbose</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--version</span></code></dt><dd><p>Prints a version identifier for ctags to standard +output, and then exits. This is guaranteed to always contain the string +“Universal Ctags”.</p> +</dd> +</dl> +</section> +<section id="obsoleted-options"> +<h3>Obsoleted Options<a class="headerlink" href="#obsoleted-options" title="Permalink to this headline">¶</a></h3> +<p>These options are kept for backward-compatibility with Exuberant Ctags.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-w</span></code></dt><dd><p>This option is silently ignored for backward-compatibility with the +ctags of SVR4 Unix.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--file-scope[=(yes|no)]</span></code></dt><dd><p>This options is removed. Use <code class="docutils literal notranslate"><span class="pre">--extras=[+|-]F</span></code> or +<code class="docutils literal notranslate"><span class="pre">--extras=[+|-]{fileScope}</span></code> instead.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--extra=[+|-][<flags>|*]</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--extras=[+|-][<flags>|*]</span></code>, which was introduced to make +the option naming convention align to the other options like +<code class="docutils literal notranslate"><span class="pre">--kinds-<LANG>=</span></code> and <code class="docutils literal notranslate"><span class="pre">--fields=</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--<LANG>-kinds=[+|-](<kinds>|*)</span></code></dt><dd><p>This option is obsolete. Use <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG>=...</span></code> instead.</p> +</dd> +</dl> +</section> +</section> +<section id="operational-details"> +<h2>OPERATIONAL DETAILS<a class="headerlink" href="#operational-details" title="Permalink to this headline">¶</a></h2> +<p>As ctags considers each source file name in turn, it tries to +determine the language of the file by applying tests described in +“<a class="reference internal" href="#determining-file-language">Determining file language</a>”.</p> +<p>If a language was identified, the file is opened and then the appropriate +language parser is called to operate on the currently open file. The parser +parses through the file and adds an entry to the tag file for each +language object it is written to handle. See “<a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a>”, below, +for details on these entries.</p> +<section id="notes-for-c-c-parser"> +<h3>Notes for C/C++ Parser<a class="headerlink" href="#notes-for-c-c-parser" title="Permalink to this headline">¶</a></h3> +<p>This implementation of ctags imposes no formatting +requirements on C code as do legacy implementations. Older implementations +of ctags tended to rely upon certain formatting assumptions in order to +help it resolve coding dilemmas caused by preprocessor conditionals.</p> +<p>In general, ctags tries to be smart about conditional +preprocessor directives. If a preprocessor conditional is encountered +within a statement which defines a tag, ctags follows +only the first branch of that conditional (except in the special case of +<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">0</span></code>, in which case it follows only the last branch). The reason for +this is that failing to pursue only one branch can result in ambiguous +syntax, as in the following example:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="cp">#ifdef TWO_ALTERNATIVES</span> +<span class="k">struct</span> <span class="p">{</span> +<span class="cp">#else</span> +<span class="k">union</span> <span class="p">{</span> +<span class="cp">#endif</span> + <span class="kt">short</span> <span class="n">a</span><span class="p">;</span> + <span class="kt">long</span> <span class="n">b</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Both branches cannot be followed, or braces become unbalanced and +ctags would be unable to make sense of the syntax.</p> +<p>If the application of this heuristic fails to properly parse a file, +generally due to complicated and inconsistent pairing within the +conditionals, ctags will retry the file using a +different heuristic which does not selectively follow conditional +preprocessor branches, but instead falls back to relying upon a closing +brace (’<code class="docutils literal notranslate"><span class="pre">}</span></code>’) in column 1 as indicating the end of a block once any brace +imbalance results from following a <code class="docutils literal notranslate"><span class="pre">#if</span></code> conditional branch.</p> +<p>ctags will also try to specially handle arguments lists +enclosed in double sets of parentheses in order to accept the following +conditional construct:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">extern</span> <span class="n">void</span> <span class="n">foo</span> <span class="n">__ARGS</span><span class="p">((</span><span class="nb">int</span> <span class="n">one</span><span class="p">,</span> <span class="n">char</span> <span class="n">two</span><span class="p">));</span> +</pre></div> +</div> +<p>Any name immediately preceding the ‘<code class="docutils literal notranslate"><span class="pre">((</span></code>’ will be automatically ignored and +the previous name will be used.</p> +<p>C++ operator definitions are specially handled. In order for consistency +with all types of operators (overloaded and conversion), the operator +name in the tag file will always be preceded by the string “operator ” +(i.e. even if the actual operator definition was written as “operator<<”).</p> +<p>After creating or appending to the tag file, it is sorted by the tag name, +removing identical tag lines.</p> +</section> +<section id="determining-file-language"> +<span id="guessing"></span><h3>Determining file language<a class="headerlink" href="#determining-file-language" title="Permalink to this headline">¶</a></h3> +<section id="file-name-mapping"> +<h4>File name mapping<a class="headerlink" href="#file-name-mapping" title="Permalink to this headline">¶</a></h4> +<p>Unless the <code class="docutils literal notranslate"><span class="pre">--language-force</span></code> option is specified, the language of each source +file is automatically selected based upon a <em>mapping</em> of file names to +languages. The mappings in effect for each language may be displayed using +the <code class="docutils literal notranslate"><span class="pre">--list-maps</span></code> option and may be changed using the <code class="docutils literal notranslate"><span class="pre">--langmap</span></code> or +<code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> options.</p> +<p>If the name of a file is not mapped to a language, ctags tries +to heuristically guess the language for the file by inspecting its content.</p> +<p>All files that have no file name mapping and no guessed parser are +ignored. This permits running ctags on all files in +either a single directory (e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">*</span></code>”), or on +all files in an entire source directory tree +(e.g. “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">-R</span></code>”), since only those files whose +names are mapped to languages will be scanned.</p> +<p>An extension may be mapped to multiple parsers. For example, <code class="docutils literal notranslate"><span class="pre">.h</span></code> +are mapped to C++, C and ObjectiveC. These mappings can cause +issues. ctags tries to select the proper parser +for the source file by applying heuristics to its content, however +it is not perfect. In case of issues one can use <code class="docutils literal notranslate"><span class="pre">--language-force=<language></span></code>, +<code class="docutils literal notranslate"><span class="pre">--langmap=<map>[,<map>[...]]</span></code>, or the <code class="docutils literal notranslate"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></code> +options. (Some of the heuristics are applied whether <code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code> +is given or not.)</p> +</section> +<section id="heuristically-guessing"> +<h4>Heuristically guessing<a class="headerlink" href="#heuristically-guessing" title="Permalink to this headline">¶</a></h4> +<p>If ctags cannot select a parser from the mapping of file names, +various heuristic tests are conducted to determine the language:</p> +<dl> +<dt>template file name testing</dt><dd><p>If the file name has an <code class="docutils literal notranslate"><span class="pre">.in</span></code> extension, ctags applies +the mapping to the file name without the extension. For example, +<code class="docutils literal notranslate"><span class="pre">config.h</span></code> is tested for a file named <code class="docutils literal notranslate"><span class="pre">config.h.in</span></code>.</p> +</dd> +<dt>“interpreter” testing</dt><dd><p>The first line of the file is checked to see if the file is a <code class="docutils literal notranslate"><span class="pre">#!</span></code> +script for a recognized language. ctags looks for +a parser having the same name.</p> +<p>If ctags finds no such parser, +ctags looks for the name in alias lists. For +example, consider if the first line is <code class="docutils literal notranslate"><span class="pre">#!/bin/sh</span></code>. Though +ctags has a “shell” parser, it doesn’t have a “sh” +parser. However, <code class="docutils literal notranslate"><span class="pre">sh</span></code> is listed as an alias for <code class="docutils literal notranslate"><span class="pre">shell</span></code>, therefore +ctags selects the “shell” parser for the file.</p> +<p>An exception is <code class="docutils literal notranslate"><span class="pre">env</span></code>. If <code class="docutils literal notranslate"><span class="pre">env</span></code> is specified (for example +“<code class="docutils literal notranslate"><span class="pre">#!/usr/bin/env</span> <span class="pre">python</span></code>”), ctags +reads more lines to find real interpreter specification.</p> +<p>To display the list of aliases, use <code class="docutils literal notranslate"><span class="pre">--list-aliases</span></code> option. +To add an item to the list or to remove an item from the list, use the +<code class="docutils literal notranslate"><span class="pre">--alias-<LANG>=+<pattern></span></code> or <code class="docutils literal notranslate"><span class="pre">--alias-<LANG>=-<pattern></span></code> option +respectively.</p> +</dd> +<dt>“zsh autoload tag” testing</dt><dd><p>If the first line starts with <code class="docutils literal notranslate"><span class="pre">#compdef</span></code> or <code class="docutils literal notranslate"><span class="pre">#autoload</span></code>, +ctags regards the line as “zsh”.</p> +</dd> +<dt>“emacs mode at the first line” testing</dt><dd><p>The Emacs editor has multiple editing modes specialized for programming +languages. Emacs can recognize a marker called modeline in a file +and utilize the marker for the mode selection. This heuristic test does +the same as what Emacs does.</p> +<p>ctags treats <code class="docutils literal notranslate"><span class="pre">MODE</span></code> as a name of interpreter and applies the same +rule of “interpreter” testing if the first line has one of +the following patterns:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-*-</span> <span class="n">mode</span><span class="p">:</span> <span class="n">MODE</span> <span class="o">-*-</span> +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-*-</span> <span class="n">MODE</span> <span class="o">-*-</span> +</pre></div> +</div> +</dd> +<dt>“emacs mode at the EOF” testing</dt><dd><p>Emacs editor recognizes another marker at the end of file as a +mode specifier. This heuristic test does the same as what Emacs does.</p> +<p>ctags treats <code class="docutils literal notranslate"><span class="pre">MODE</span></code> as a name of an interpreter and applies the same +rule of “interpreter” heuristic testing, if the lines at the tail of the file +have the following pattern:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Local</span> <span class="n">Variables</span><span class="p">:</span> +<span class="o">...</span> +<span class="n">mode</span><span class="p">:</span> <span class="n">MODE</span> +<span class="o">...</span> +<span class="n">End</span><span class="p">:</span> +</pre></div> +</div> +<p>3000 characters are sought from the end of file to find the pattern.</p> +</dd> +<dt>“vim modeline” testing</dt><dd><p>Like the modeline of the Emacs editor, Vim editor has the same concept. +ctags treats <code class="docutils literal notranslate"><span class="pre">TYPE</span></code> as a name of interpreter and applies the same +rule of “interpreter” heuristic testing if the last 5 lines of the file +have one of the following patterns:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">filetype</span><span class="o">=</span><span class="n">TYPE</span> +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ft</span><span class="o">=</span><span class="n">TYPE</span> +</pre></div> +</div> +</dd> +<dt>“PHP marker” testing</dt><dd><p>If the first line is started with <code class="docutils literal notranslate"><span class="pre"><?php</span></code>, +ctags regards the line as “php”.</p> +</dd> +</dl> +<p>Looking into the file contents is a more expensive operation than file +name matching. So ctags runs the testings in limited +conditions. “interpreter” testing is enabled only when a file is an +executable or the <code class="docutils literal notranslate"><span class="pre">--guess-language-eagerly</span></code> (<code class="docutils literal notranslate"><span class="pre">-G</span></code> in short) option is +given. The other heuristic tests are enabled only when <code class="docutils literal notranslate"><span class="pre">-G</span></code> option is +given.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">--print-language</span></code> option can be used just to print the results of +parser selections for given files instead of generating a tags file.</p> +<p>Examples:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --print-language config.h.in input.m input.unknown +<span class="go">config.h.in: C++</span> +<span class="go">input.m: MatLab</span> +<span class="go">input.unknown: NONE</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">NONE</span></code> means that ctags does not select any parser for the file.</p> +</section> +</section> +</section> +<section id="tag-file-format"> +<h2>TAG FILE FORMAT<a class="headerlink" href="#tag-file-format" title="Permalink to this headline">¶</a></h2> +<p>This section describes the tag file format briefly. See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> and +<a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more details.</p> +<p>When not running in etags mode, each entry in the tag file consists of a +separate line, each looking like this, called <em>regular tags</em>, in the most general case:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">tag_name</span><span class="o">><</span><span class="n">TAB</span><span class="o">><</span><span class="n">file_name</span><span class="o">><</span><span class="n">TAB</span><span class="o">><</span><span class="n">ex_cmd</span><span class="o">></span><span class="p">;</span><span class="s2">"<TAB><extension_fields></span> +</pre></div> +</div> +<p>The fields and separators of these lines are specified as follows:</p> +<blockquote> +<div><ol class="arabic"> +<li><p><code class="docutils literal notranslate"><span class="pre"><tag_name></span></code>: tag name</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><TAB></span></code>: single tab character</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><file_name></span></code>: name of the file in which the object associated with the tag is located</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><TAB></span></code>: single tab character</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre"><ex_cmd></span></code>: EX command used to locate the tag within the file; generally a +search pattern (either <code class="docutils literal notranslate"><span class="pre">/pattern/</span></code> or <code class="docutils literal notranslate"><span class="pre">?pattern?</span></code>) or line number (see +<code class="docutils literal notranslate"><span class="pre">--excmd=<type></span></code> option).</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">;"<TAB><extension_fields></span></code>: a set of extension fields. See +“<a class="reference internal" href="#extension-fields">Extension fields</a>” for more details.</p> +<p>Tag file format 2 (see <code class="docutils literal notranslate"><span class="pre">--format</span></code>) extends the EX command +to include the extension fields embedded in an EX comment immediately appended +to the EX command, which leaves it backward-compatible with original +<code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> implementations.</p> +</li> +</ol> +</div></blockquote> +<p>A few special tags, called <em>pseudo tags</em>, are written into the tag file for internal purposes.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/ +!_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/ +... +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--pseudo-tags=[+|-](<pseudo-tag>|*)</span></code> option enables or disables emitting pseudo-tags.</p> +<p>See the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-pseudo-tags</span></code>” for the list of +the kinds. +See also <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> and <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more details of the pseudo tags.</p> +<p>These tags are composed in such a way that they always sort to the top of +the file. Therefore, the first two characters of these tags are used a magic +number to detect a tag file for purposes of determining whether a +valid tag file is being overwritten rather than a source file.</p> +<p>Note that the name of each source file will be recorded in the tag file +exactly as it appears on the command line. Therefore, if the path you +specified on the command line was relative to the current directory, then +it will be recorded in that same manner in the tag file. See, however, +the <code class="docutils literal notranslate"><span class="pre">--tag-relative=(yes|no|always|never)</span></code> option for how this behavior can be +modified.</p> +</section> +<section id="tag-entries"> +<span id="id1"></span><h2>TAG ENTRIES<a class="headerlink" href="#tag-entries" title="Permalink to this headline">¶</a></h2> +<p>A tag is an index for a language object. The concept of a tag and related +items in Exuberant Ctags are refined and extended in Universal Ctags.</p> +<p>A tag is categorized into <em>definition tags</em> or <em>reference tags</em>. +In general, Exuberant Ctags only tags <em>definitions</em> of +language objects: places where newly named language objects <em>are introduced</em>. +Universal Ctags, on the other hand, can also tag <em>references</em> of language +objects: places where named language objects <em>are used</em>. However, support +for generating reference tags is new and limited to specific areas of +specific languages in the current version.</p> +<section id="extension-fields"> +<h3>Extension fields<a class="headerlink" href="#extension-fields" title="Permalink to this headline">¶</a></h3> +<p>A tag can record various information, called <em>extension fields</em>.</p> +<p>Extension fields are tab-separated key-value pairs appended to the end of +the EX command as a comment, as described above. These key value pairs +appear in the general form <code class="docutils literal notranslate"><span class="pre">key:value</span></code>.</p> +<p>In addition, information on the scope of the tag definition may be +available, with the key portion equal to some language-dependent construct +name and its value the name declared for that construct in the program. +This scope entry indicates the scope in which the tag was found. +For example, a tag generated for a C structure member would have a scope +looking like <code class="docutils literal notranslate"><span class="pre">struct:myStruct</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">--fields=[+|-][<flags>|*]</span></code> and <code class="docutils literal notranslate"><span class="pre">--fields-(<LANG>|all)=[+|-][<flags>|*]</span></code> options specifies +which available extension fields are to be included in the tag entries.</p> +<p>See the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-fields</span></code>” for the list of +extension fields. +The essential fields are <code class="docutils literal notranslate"><span class="pre">name</span></code>, <code class="docutils literal notranslate"><span class="pre">input</span></code>, <code class="docutils literal notranslate"><span class="pre">pattern</span></code>, and <code class="docutils literal notranslate"><span class="pre">line</span></code>. +The meaning of major fields is as follows (long-name flag/one-letter flag):</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">access</span></code>/<code class="docutils literal notranslate"><span class="pre">a</span></code></dt><dd><p>Indicates the visibility of this class member, where value is specific +to the language.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">end</span></code>/<code class="docutils literal notranslate"><span class="pre">e</span></code></dt><dd><p>Indicates the line number of the end lines of the language object.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">extras</span></code>/<code class="docutils literal notranslate"><span class="pre">E</span></code></dt><dd><p>Extra tag type information. See “<a class="reference internal" href="#extras">Extras</a>” for details.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">file</span></code>/<code class="docutils literal notranslate"><span class="pre">f</span></code></dt><dd><p>Indicates that the tag has file-limited visibility. This key has no +corresponding value. Enabled by default.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">implementation</span></code>/<code class="docutils literal notranslate"><span class="pre">m</span></code></dt><dd><p>When present, this indicates a limited implementation (abstract vs. +concrete) of a routine or class, where value is specific to the +language (<code class="docutils literal notranslate"><span class="pre">virtual</span></code> or <code class="docutils literal notranslate"><span class="pre">pure</span> <span class="pre">virtual</span></code> for C++; <code class="docutils literal notranslate"><span class="pre">abstract</span></code> for Java).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">inherits</span></code>/<code class="docutils literal notranslate"><span class="pre">i</span></code></dt><dd><p>When present, value is a comma-separated list of classes from which +this class is derived (i.e. inherits from).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">input</span></code>/<code class="docutils literal notranslate"><span class="pre">F</span></code></dt><dd><p>The name of source file where <code class="docutils literal notranslate"><span class="pre">name</span></code> is defined or referenced.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">k</span></code></dt><dd><p><a class="reference external" href="Kinds">Kind</a> of tag as one-letter. Enabled by default. +This field has no long-name. +See also <code class="docutils literal notranslate"><span class="pre">kind</span></code>/<code class="docutils literal notranslate"><span class="pre">z</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">K</span></code></dt><dd><p><a class="reference external" href="Kinds">Kind</a> of tag as long-name. +This field has no long-name. +See also <code class="docutils literal notranslate"><span class="pre">kind</span></code>/<code class="docutils literal notranslate"><span class="pre">z</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">kind</span></code>/<code class="docutils literal notranslate"><span class="pre">z</span></code></dt><dd><p>Include the <code class="docutils literal notranslate"><span class="pre">kind:</span></code> key in <a class="reference external" href="Kinds">kind field</a>. See also <code class="docutils literal notranslate"><span class="pre">k</span></code> and <code class="docutils literal notranslate"><span class="pre">K</span></code> flags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">language</span></code>/<code class="docutils literal notranslate"><span class="pre">l</span></code></dt><dd><p>Language of source file containing tag</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">line</span></code>/<code class="docutils literal notranslate"><span class="pre">n</span></code></dt><dd><p>The line number where <code class="docutils literal notranslate"><span class="pre">name</span></code> is defined or referenced in <code class="docutils literal notranslate"><span class="pre">input</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">name</span></code>/<code class="docutils literal notranslate"><span class="pre">N</span></code></dt><dd><p>The name of language objects.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">pattern</span></code>/<code class="docutils literal notranslate"><span class="pre">P</span></code></dt><dd><p>Can be used to search the <code class="docutils literal notranslate"><span class="pre">name</span></code> in <code class="docutils literal notranslate"><span class="pre">input</span></code></p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">roles</span></code>/<code class="docutils literal notranslate"><span class="pre">r</span></code></dt><dd><p>Roles assigned to the tag. See “<a class="reference internal" href="#roles">Roles</a>” for more details.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">s</span></code></dt><dd><p>Scope of tag definition. Enabled by default. +This field has no long-name. +See also <code class="docutils literal notranslate"><span class="pre">scope</span></code>/<code class="docutils literal notranslate"><span class="pre">Z</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">scope</span></code>/<code class="docutils literal notranslate"><span class="pre">Z</span></code></dt><dd><p>Prepend the <code class="docutils literal notranslate"><span class="pre">scope:</span></code> key to scope (<code class="docutils literal notranslate"><span class="pre">s</span></code>) field. +See also <code class="docutils literal notranslate"><span class="pre">s</span></code> flag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">scopeKind</span></code>/<code class="docutils literal notranslate"><span class="pre">p</span></code></dt><dd><p>Kind of scope as long-name</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">signature</span></code>/<code class="docutils literal notranslate"><span class="pre">S</span></code></dt><dd><p>When present, value is a language-dependent representation of the +signature of a routine (e.g. prototype or parameter list). A routine signature in its complete form +specifies the return type of a routine and its formal argument list. +This extension field is presently supported only for C-based +languages and does not include the return type.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">typeref</span></code>/<code class="docutils literal notranslate"><span class="pre">t</span></code></dt><dd><p>Type and name of a variable, typedef, or return type of +callable like function as <code class="docutils literal notranslate"><span class="pre">typeref:</span></code> field. +Enabled by default.</p> +</dd> +</dl> +<section id="kinds"> +<h4>Kinds<a class="headerlink" href="#kinds" title="Permalink to this headline">¶</a></h4> +<p><code class="docutils literal notranslate"><span class="pre">kind</span></code> is a field which represents the <em>kind</em> of language object +specified by a tag. Kinds used and defined are very different between +parsers. For example, C language defines <code class="docutils literal notranslate"><span class="pre">macro</span></code>, <code class="docutils literal notranslate"><span class="pre">function</span></code>, +<code class="docutils literal notranslate"><span class="pre">variable</span></code>, <code class="docutils literal notranslate"><span class="pre">typedef</span></code>, etc.</p> +<p><code class="docutils literal notranslate"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></code> option specifies a list of language-specific +kinds of tags (or kinds) to include in the output file for a particular +language.</p> +<p>See the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-kinds-full</span></code>” for the complete +list of the kinds.</p> +<p>Its value is either one of the +corresponding one-letter flags or a long-name flag. It is permitted +(and is, in fact, the default) for the key portion of this field to be +omitted. The optional behaviors are controlled with the <code class="docutils literal notranslate"><span class="pre">--fields</span></code> option as follows.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" f typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+k -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" f typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+K -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" function typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+z -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" kind:f typeref:typename:int</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+zK -o - kinds.c +<span class="go">foo kinds.c /^int foo() {$/;" kind:function typeref:typename:int</span> +</pre></div> +</div> +</section> +<section id="roles"> +<h4>Roles<a class="headerlink" href="#roles" title="Permalink to this headline">¶</a></h4> +<p><em>Role</em> is a newly introduced concept in Universal Ctags. Role is a +concept associated with reference tags, and is not implemented widely yet.</p> +<p>As described previously in “<a class="reference internal" href="#kinds">Kinds</a>”, the <code class="docutils literal notranslate"><span class="pre">kind</span></code> field represents the type +of language object specified with a tag, such as a function vs. a variable. +Specific kinds are defined for reference tags, such as the C++ kind <code class="docutils literal notranslate"><span class="pre">header</span></code> for +header file, or Java kind <code class="docutils literal notranslate"><span class="pre">package</span></code> for package statements. For such reference +kinds, a <code class="docutils literal notranslate"><span class="pre">roles</span></code> field can be added to distinguish the role of the reference +kind. In other words, the <code class="docutils literal notranslate"><span class="pre">kind</span></code> field identifies the <em>what</em> of the language +object, whereas the <code class="docutils literal notranslate"><span class="pre">roles</span></code> field identifies the <em>how</em> of a referenced language +object. Roles are only used with specific kinds.</p> +<p>For a definition tag, this field takes <code class="docutils literal notranslate"><span class="pre">def</span></code> as a value.</p> +<p>For example, <code class="docutils literal notranslate"><span class="pre">Baz</span></code> is tagged as a reference tag with kind <code class="docutils literal notranslate"><span class="pre">package</span></code> and with +role <code class="docutils literal notranslate"><span class="pre">imported</span></code> with the following code.</p> +<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kn">package</span> <span class="nn">Bar</span><span class="p">;</span> +<span class="kn">import</span> <span class="nn">Baz</span><span class="p">;</span> + +<span class="kd">class</span> <span class="nc">Foo</span> <span class="p">{</span> + <span class="c1">// ...</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>+KEr -uo - roles.java +<span class="go">Bar roles.java /^package Bar;$/;" package roles:def</span> +<span class="go">Foo roles.java /^class Foo {$/;" class roles:def</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+EKr --extras<span class="o">=</span>+r -uo - roles.java +<span class="go">Bar roles.java /^package Bar;$/;" package roles:def</span> +<span class="go">Baz roles.java /^import Baz;$/;" package roles:imported extras:reference</span> +<span class="go">Foo roles.java /^class Foo {$/;" class roles:def</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]</span></code> option specifies a list of kind-specific +roles of tags to include in the output file for a particular language.</p> +<p>Inquire the output of “<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-roles</span></code>” for the list of +roles.</p> +</section> +</section> +<section id="extras"> +<h3>Extras<a class="headerlink" href="#extras" title="Permalink to this headline">¶</a></h3> +<p>Generally, ctags tags only language objects appearing +in source files, as is. In other words, a value for a <code class="docutils literal notranslate"><span class="pre">name:</span></code> field +should be found on the source file associated with the <code class="docutils literal notranslate"><span class="pre">name:</span></code>. An +<code class="docutils literal notranslate"><span class="pre">extra</span></code> type tag (<em>extra</em>) is for tagging a language object with a processed +name, or for tagging something not associated with a language object. A typical +extra tag is <code class="docutils literal notranslate"><span class="pre">qualified</span></code>, which tags a language object with a +class-qualified or scope-qualified name.</p> +<p><code class="docutils literal notranslate"><span class="pre">--extras-(<LANG>|all)=[+|-][<flags>|*]</span></code> option specifies +whether to include extra tag entries for certain kinds of information.</p> +<p>Inquire the output of <code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-extras</span></code> for the list of extras. +The meaning of major extras is as follows (long-name flag/one-letter flag):</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">anonymous</span></code>/none</dt><dd><p>Include an entry for the language object that has no name like lambda +function. This extra has no one-letter flag and is enabled by +default.</p> +<p>The extra tag is useful as a placeholder to fill scope fields +for language objects defined in a language object with no name.</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="p">{</span> + <span class="kt">double</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">;</span> +<span class="p">}</span> <span class="n">p</span> <span class="o">=</span> <span class="p">{</span> <span class="p">.</span><span class="n">x</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span> <span class="p">.</span><span class="n">y</span> <span class="o">=</span> <span class="mf">0.0</span> <span class="p">};</span> +</pre></div> +</div> +<p>‘<code class="docutils literal notranslate"><span class="pre">x</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">y</span></code>’ are the members of a structure. When filling the scope +fields for them, ctags has trouble because the struct +where ‘<code class="docutils literal notranslate"><span class="pre">x</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">y</span></code>’ belong to has no name. For overcoming the trouble, +ctags generates an anonymous extra tag for the struct +and fills the scope fields with the name of the extra tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>-f -uo - input.c +<span class="go">__anon9f26d2460108 input.c /^struct {$/;" s</span> +<span class="go">x input.c /^ double x, y;$/;" m struct:__anon9f26d2460108</span> +<span class="go">y input.c /^ double x, y;$/;" m struct:__anon9f26d2460108</span> +<span class="go">p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;" v typeref:struct:__anon9f26d2460108</span> +</pre></div> +</div> +<p>The above tag output has <code class="docutils literal notranslate"><span class="pre">__anon9f26d2460108</span></code> as an anonymous extra tag. +The typeref field of ‘<code class="docutils literal notranslate"><span class="pre">p</span></code>’ also receives the benefit of it.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">fileScope</span></code>/<code class="docutils literal notranslate"><span class="pre">F</span></code></dt><dd><p>Indicates whether tags scoped only for a single file (i.e. tags which +cannot be seen outside of the file in which they are defined, such as +language objects with <code class="docutils literal notranslate"><span class="pre">static</span></code> modifier of C language) should be included +in the output. See also the <code class="docutils literal notranslate"><span class="pre">-h</span></code> option.</p> +<p>This extra tag is enabled by default. Add <code class="docutils literal notranslate"><span class="pre">--extras=-F</span></code> option not to +output tags scoped only for a single-file. This is the replacement for +<code class="docutils literal notranslate"><span class="pre">--file-scope</span></code> option of Exuberant Ctags.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span> + <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> +<span class="p">}</span> +<span class="kt">int</span> <span class="nf">g</span><span class="p">()</span> <span class="p">{</span> + <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -uo - filescope.c +<span class="go">f filescope.c /^static int f() {$/;" f typeref:typename:int file:</span> +<span class="go">g filescope.c /^int g() {$/;" f typeref:typename:int</span> +<span class="gp">$ </span>ctags --extras<span class="o">=</span>-F -uo - filescope.c +<span class="go">g filescope.c /^int g() {$/;" f typeref:typename:int</span> +</pre></div> +</div> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">inputFile</span></code>/<code class="docutils literal notranslate"><span class="pre">f</span></code></dt><dd><p>Include an entry for the base file name of every source file +(e.g. <code class="docutils literal notranslate"><span class="pre">example.c</span></code>), which addresses the first line of the file. +This flag is the replacement for <code class="docutils literal notranslate"><span class="pre">--file-tags</span></code> hidden option of +Exuberant Ctags.</p> +<p>If the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field is enabled, the end line number of the file can be +attached to the tag. (However, ctags omits the <code class="docutils literal notranslate"><span class="pre">end:</span></code> field +if no newline is in the file like an empty file.)</p> +<p>By default, ctags doesn’t create the <code class="docutils literal notranslate"><span class="pre">inputFile</span></code>/<code class="docutils literal notranslate"><span class="pre">f</span></code> extra +tag for the source file when ctags doesn’t find a parser +for it. Enabling <code class="docutils literal notranslate"><span class="pre">Unknown</span></code> parser with <code class="docutils literal notranslate"><span class="pre">--languages=+Unknown</span></code> forces +ctags to create the extra tags for any source files.</p> +<p>The etags mode enables the <code class="docutils literal notranslate"><span class="pre">Unknown</span></code> parser implicitly.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">pseudo</span></code>/<code class="docutils literal notranslate"><span class="pre">p</span></code></dt><dd><p>Include pseudo-tags. Enabled by default unless the tag file is +written to standard output. See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> about +the detail of pseudo-tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">qualified</span></code>/<code class="docutils literal notranslate"><span class="pre">q</span></code></dt><dd><p>Include an extra class-qualified or namespace-qualified tag entry +for each tag which is a member of a class or a namespace.</p> +<p>This may allow easier location of a specific tags when +multiple occurrences of a tag name occur in the tag file. +Note, however, that this could potentially more than double +the size of the tag file.</p> +<p>The actual form of the qualified tag depends upon the language +from which the tag was derived (using a form that is most +natural for how qualified calls are specified in the +language). For C++ and Perl, it is in the form +<code class="docutils literal notranslate"><span class="pre">class::member</span></code>; for Eiffel and Java, it is in the form +<code class="docutils literal notranslate"><span class="pre">class.member</span></code>.</p> +<p>Note: Using backslash characters as separators forming +qualified name in PHP. However, in tags output of +Universal Ctags, a backslash character in a name is escaped +with a backslash character. See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> about the escaping.</p> +<p>The following example demonstrates the <code class="docutils literal notranslate"><span class="pre">qualified</span></code> extra tag.</p> +<div class="highlight-Java notranslate"><div class="highlight"><pre><span></span><span class="kd">class</span> <span class="nc">point</span> <span class="p">{</span> + <span class="kt">double</span> <span class="n">x</span><span class="p">;</span> +<span class="p">};</span> +</pre></div> +</div> +<p>For the above source file, ctags tags <code class="docutils literal notranslate"><span class="pre">point</span></code> and <code class="docutils literal notranslate"><span class="pre">x</span></code> by +default. If the <code class="docutils literal notranslate"><span class="pre">qualified</span></code> extra is enabled from the command line +(<code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code>), then <code class="docutils literal notranslate"><span class="pre">point.x</span></code> is also tagged even though the string +“<code class="docutils literal notranslate"><span class="pre">point.x</span></code>” is not in the source code.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>+K -uo - qualified.java +<span class="go">point qualified.java /^class point {$/;" class</span> +<span class="go">x qualified.java /^ double x;$/;" field class:point</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+K --extras<span class="o">=</span>+q -uo - qualified.java +<span class="go">point qualified.java /^class point {$/;" class</span> +<span class="go">x qualified.java /^ double x;$/;" field class:point</span> +<span class="go">point.x qualified.java /^ double x;$/;" field class:point</span> +</pre></div> +</div> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">reference</span></code>/<code class="docutils literal notranslate"><span class="pre">r</span></code></dt><dd><p>Include reference tags. See “<a class="reference internal" href="#id1">TAG ENTRIES</a>” about reference tags.</p> +<p>The following example demonstrates the <code class="docutils literal notranslate"><span class="pre">reference</span></code> extra tag.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span> +<span class="cp">#include</span> <span class="cpf">"utils.h"</span><span class="cp"></span> +<span class="cp">#define X</span> +<span class="cp">#undef X</span> +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">roles:system</span></code> or <code class="docutils literal notranslate"><span class="pre">roles:local</span></code> fields will be +added depending on whether the include file name begins with ‘<code class="docutils literal notranslate"><span class="pre"><</span></code>’ or not.</p> +<p>“<code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">X</span></code>” emits a definition tag. On the other hand “<code class="docutils literal notranslate"><span class="pre">#undef</span> <span class="pre">X</span></code>” emits a +reference tag.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>+EKr -uo - inc.c +<span class="go">X inc.c /^#define X$/;" macro file: roles:def extras:fileScope</span> +<span class="gp">$ </span>ctags --fields<span class="o">=</span>+EKr --extras<span class="o">=</span>+r -uo - inc.c +<span class="go">stdio.h inc.c /^#include <stdio.h>/;" header roles:system extras:reference</span> +<span class="go">utils.h inc.c /^#include "utils.h"/;" header roles:local extras:reference</span> +<span class="go">X inc.c /^#define X$/;" macro file: roles:def extras:fileScope</span> +<span class="go">X inc.c /^#undef X$/;" macro file: roles:undef extras:fileScope,reference</span> +</pre></div> +</div> +</dd> +</dl> +</section> +<section id="language-specific-fields-and-extras"> +<h3>Language-specific fields and extras<a class="headerlink" href="#language-specific-fields-and-extras" title="Permalink to this headline">¶</a></h3> +<p>Exuberant Ctags has the concept of <em>fields</em> and <em>extras</em>. They are common +between parsers of different languages. Universal Ctags extends this concept +by providing language-specific fields and extras.</p> +</section> +</section> +<section id="how-to-use-with-vi"> +<h2>HOW TO USE WITH VI<a class="headerlink" href="#how-to-use-with-vi" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">vi(1)</span></code> will, by default, expect a tag file by the name <code class="docutils literal notranslate"><span class="pre">tags</span></code> in the current +directory. Once the tag file is built, the following commands exercise +the tag indexing feature:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">vi</span> <span class="pre">-t</span> <span class="pre">tag</span></code></dt><dd><p>Start vi and position the cursor at the file and line where <code class="docutils literal notranslate"><span class="pre">tag</span></code> +is defined.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">:ta</span> <span class="pre">tag</span></code></dt><dd><p>Find a tag.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">Ctrl-]</span></code></dt><dd><p>Find the tag under the cursor.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">Ctrl-T</span></code></dt><dd><p>Return to previous location before jump to tag (not widely implemented).</p> +</dd> +</dl> +</section> +<section id="how-to-use-with-gnu-emacs"> +<h2>HOW TO USE WITH GNU EMACS<a class="headerlink" href="#how-to-use-with-gnu-emacs" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">emacs(1)</span></code> will, by default, expect a tag file by the name <code class="docutils literal notranslate"><span class="pre">TAGS</span></code> in the +current directory. Once the tag file is built, the following commands +exercise the tag indexing feature:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">M-x</span> <span class="pre">visit-tags-table</span> <span class="pre"><RET></span> <span class="pre">FILE</span> <span class="pre"><RET></span></code></dt><dd><p>Select the tag file, <code class="docutils literal notranslate"><span class="pre">FILE</span></code>, to use.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">M-.</span> <span class="pre">[TAG]</span> <span class="pre"><RET></span></code></dt><dd><p>Find the first definition of TAG. The default tag is the identifier +under the cursor.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">M-*</span></code></dt><dd><p>Pop back to where you previously invoked <code class="docutils literal notranslate"><span class="pre">M-.</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">C-u</span> <span class="pre">M-.</span></code></dt><dd><p>Find the next definition for the last tag.</p> +</dd> +</dl> +<p>For more commands, see the Tags topic in the Emacs info document.</p> +</section> +<section id="how-to-use-with-nedit"> +<h2>HOW TO USE WITH NEDIT<a class="headerlink" href="#how-to-use-with-nedit" title="Permalink to this headline">¶</a></h2> +<p>NEdit version 5.1 and later can handle the new extended tag file format +(see <code class="docutils literal notranslate"><span class="pre">--format</span></code>).</p> +<ul class="simple"> +<li><p>To make NEdit use the tag file, select “File->Load Tags File”.</p></li> +<li><p>To jump to the definition for a tag, highlight the word, then press <code class="docutils literal notranslate"><span class="pre">Ctrl-D</span></code>.</p></li> +</ul> +<p>NEdit 5.1 can read multiple tag files from different +directories. Setting the X resource <code class="docutils literal notranslate"><span class="pre">nedit.tagFile</span></code> to the name of a tag +file instructs NEdit to automatically load that tag file at startup time.</p> +</section> +<section id="caveats"> +<h2>CAVEATS<a class="headerlink" href="#caveats" title="Permalink to this headline">¶</a></h2> +<p>Because ctags is neither a preprocessor nor a compiler, +use of preprocessor macros can fool ctags into either +missing tags or improperly generating inappropriate tags. Although +ctags has been designed to handle certain common cases, +this is the single biggest cause of reported problems. In particular, +the use of preprocessor constructs which alter the textual syntax of C +can fool ctags. You can work around many such problems +by using the <code class="docutils literal notranslate"><span class="pre">-I</span></code> option.</p> +<p>Note that since ctags generates patterns for locating +tags (see the <code class="docutils literal notranslate"><span class="pre">--excmd</span></code> option), it is entirely possible that the wrong line +may be found by your editor if there exists another source line which is +identical to the line containing the tag. The following example +demonstrates this condition:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">variable</span><span class="p">;</span> + +<span class="cm">/* ... */</span> +<span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="n">variable</span><span class="p">)</span> +<span class="kt">int</span> <span class="n">variable</span><span class="p">;</span> +<span class="p">{</span> + <span class="cm">/* ... */</span> +<span class="p">}</span> +</pre></div> +</div> +<p>Depending upon which editor you use and where in the code you happen to be, +it is possible that the search pattern may locate the local parameter +declaration before it finds the actual global variable definition, +since the lines (and therefore their search patterns) are +identical.</p> +<p>This can be avoided by use of the <code class="docutils literal notranslate"><span class="pre">--excmd=n</span></code> option.</p> +</section> +<section id="bugs"> +<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2> +<p>ctags has more options than <code class="docutils literal notranslate"><span class="pre">ls(1)</span></code>.</p> +<p>ctags assumes the input file is written in the correct +grammar. Otherwise output of ctags is undefined. In other words it has garbage +in, garbage out (GIGO) feature.</p> +<p>When parsing a C++ member function definition (e.g. <code class="docutils literal notranslate"><span class="pre">className::function</span></code>), +ctags cannot determine whether the scope specifier +is a class name or a namespace specifier and always lists it as a class name +in the scope portion of the extension fields. Also, if a C++ function +is defined outside of the class declaration (the usual case), the access +specification (i.e. public, protected, or private) and implementation +information (e.g. virtual, pure virtual) contained in the function +declaration are not known when the tag is generated for the function +definition. It will, however be available for prototypes (e.g. <code class="docutils literal notranslate"><span class="pre">--kinds-c++=+p</span></code>).</p> +<p>No qualified tags are generated for language objects inherited into a class.</p> +</section> +<section id="environment-variables"> +<h2>ENVIRONMENT VARIABLES<a class="headerlink" href="#environment-variables" title="Permalink to this headline">¶</a></h2> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">TMPDIR</span></code></dt><dd><p>On Unix-like hosts where <code class="docutils literal notranslate"><span class="pre">mkstemp(3)</span></code> is available, the value of this +variable specifies the directory in which to place temporary files. +This can be useful if the size of a temporary file becomes too large +to fit on the partition holding the default temporary directory +defined at compilation time.</p> +<p>ctags creates temporary +files only if either (1) an emacs-style tag file is being +generated, (2) the tag file is being sent to standard output, or +(3) the program was compiled to use an internal sort algorithm to sort +the tag files instead of the <code class="docutils literal notranslate"><span class="pre">sort(1)</span></code> utility of the operating system. +If the <code class="docutils literal notranslate"><span class="pre">sort(1)</span></code> utility of the operating system is being used, it will +generally observe this variable also.</p> +<p>Note that if ctags +is setuid, the value of <code class="docutils literal notranslate"><span class="pre">TMPDIR</span></code> will be ignored.</p> +</dd> +</dl> +</section> +<section id="files"> +<h2>FILES<a class="headerlink" href="#files" title="Permalink to this headline">¶</a></h2> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">tags</span></code></dt><dd><p>The default tag file created by ctags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">TAGS</span></code></dt><dd><p>The default tag file created by etags.</p> +</dd> +</dl> +<p><code class="docutils literal notranslate"><span class="pre">$XDG_CONFIG_HOME/ctags/*.ctags</span></code>, or <code class="docutils literal notranslate"><span class="pre">$HOME/.config/ctags/*.ctags</span></code> if +<code class="docutils literal notranslate"><span class="pre">$XDG_CONFIG_HOME</span></code> is not defined +(on other than MS Windows)</p> +<p><code class="docutils literal notranslate"><span class="pre">$HOME/.ctags.d/*.ctags</span></code></p> +<p><code class="docutils literal notranslate"><span class="pre">$HOMEDRIVE$HOMEPATH/ctags.d/*.ctags</span></code> (on MS Windows only)</p> +<p><code class="docutils literal notranslate"><span class="pre">.ctags.d/*.ctags</span></code></p> +<p><code class="docutils literal notranslate"><span class="pre">ctags.d/*.ctags</span></code></p> +<blockquote> +<div><p>If any of these configuration files exist, each will be expected to +contain a set of default options which are read in the order listed +when ctags starts, but before any command line options +are read. This makes it possible to set up personal or project-level defaults.</p> +<p>It +is possible to compile ctags to read an additional +configuration file before any of those shown above, which will be +indicated if the output produced by the <code class="docutils literal notranslate"><span class="pre">--version</span></code> option lists the +<code class="docutils literal notranslate"><span class="pre">custom-conf</span></code> feature.</p> +<p>Options appearing on the command line will override options +specified in these files. Only options will be read from these +files.</p> +<p>Note that the option +files are read in line-oriented mode in which spaces are significant +(since shell quoting is not possible) but spaces at the beginning +of a line are ignored. Each line of the file is read as +one command line parameter (as if it were quoted with single quotes). +Therefore, use new lines to indicate separate command-line arguments.</p> +<p>A line starting with ‘<code class="docutils literal notranslate"><span class="pre">#</span></code>’ is treated as a comment.</p> +<p><code class="docutils literal notranslate"><span class="pre">*.ctags</span></code> files in a directory are loaded in alphabetical order.</p> +</div></blockquote> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> for defining (or extending) a parser +in a configuration file.</p> +<p>See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> for the format of tag files.</p> +<p>See <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a> about known incompatible changes +with Exuberant Ctags.</p> +<p>See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> if you are interested in writing +a tool for processing tags files.</p> +<p>See <a class="reference internal" href="ctags-lang-python.7.html#ctags-lang-python-7"><span class="std std-ref">ctags-lang-python(7)</span></a> about python input specific notes.</p> +<p>See <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a> about a client tool for binary searching a +name in a sorted tags file.</p> +<p>The official Universal Ctags web site at: <a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Also <code class="docutils literal notranslate"><span class="pre">ex(1)</span></code>, <code class="docutils literal notranslate"><span class="pre">vi(1)</span></code>, <code class="docutils literal notranslate"><span class="pre">elvis(1)</span></code>, or, better yet, <code class="docutils literal notranslate"><span class="pre">vim(1)</span></code>, the official editor of ctags. +For more information on <code class="docutils literal notranslate"><span class="pre">vim(1)</span></code>, see the Vim web site at: <a class="reference external" href="https://www.vim.org/">https://www.vim.org/</a></p> +</section> +<section id="author"> +<h2>AUTHOR<a class="headerlink" href="#author" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert%40users.sourceforge.net">dhiebert<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +</section> +<section id="motivation"> +<h2>MOTIVATION<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2> +<p>“Think ye at all times of rendering some service to every member of the +human race.”</p> +<p>“All effort and exertion put forth by man from the fullness of his heart is +worship, if it is prompted by the highest motives and the will to do +service to humanity.”</p> +<p>-- From the Baha’i Writings</p> +</section> +<section id="credits"> +<h2>CREDITS<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2> +<p>This version of ctags (Universal Ctags) derived from +the repository, known as fishman-ctags, started by Reza Jelveh.</p> +<p>The fishman-ctags was derived from Exuberant Ctags.</p> +<p>Some parsers are taken from <code class="docutils literal notranslate"><span class="pre">tagmanager</span></code> of the Geany (<a class="reference external" href="https://www.geany.org/">https://www.geany.org/</a>) +project.</p> +<p>Exuberant Ctags was originally derived from and +inspired by the ctags program by Steve Kirkendall <<a class="reference external" href="mailto:kirkenda%40cs.pdx.edu">kirkenda<span>@</span>cs<span>.</span>pdx<span>.</span>edu</a>> +that comes with the Elvis vi clone (though virtually none of the original +code remains).</p> +<p>Credit is also due Bram Moolenaar <<a class="reference external" href="mailto:Bram%40vim.org">Bram<span>@</span>vim<span>.</span>org</a>>, the author of vim, +who has devoted so much of his time and energy both to developing the editor +as a service to others, and to helping the orphans of Uganda.</p> +<p>The section entitled “<a class="reference internal" href="#how-to-use-with-gnu-emacs">HOW TO USE WITH GNU EMACS</a>” was shamelessly stolen +from the info page for GNU etags.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">ctags</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#command-line-interface">COMMAND LINE INTERFACE</a><ul> +<li><a class="reference internal" href="#letters-and-names">Letters and names</a></li> +<li><a class="reference internal" href="#list-options">List options</a></li> +</ul> +</li> +<li><a class="reference internal" href="#options">OPTIONS</a><ul> +<li><a class="reference internal" href="#input-output-file-options">Input/Output File Options</a></li> +<li><a class="reference internal" href="#output-format-options">Output Format Options</a></li> +<li><a class="reference internal" href="#language-selection-and-mapping-options">Language Selection and Mapping Options</a></li> +<li><a class="reference internal" href="#tags-file-contents-options">Tags File Contents Options</a></li> +<li><a class="reference internal" href="#option-file-options">Option File Options</a></li> +<li><a class="reference internal" href="#optlib-options">optlib Options</a></li> +<li><a class="reference internal" href="#language-specific-options">Language Specific Options</a></li> +<li><a class="reference internal" href="#listing-options">Listing Options</a></li> +<li><a class="reference internal" href="#miscellaneous-options">Miscellaneous Options</a></li> +<li><a class="reference internal" href="#obsoleted-options">Obsoleted Options</a></li> +</ul> +</li> +<li><a class="reference internal" href="#operational-details">OPERATIONAL DETAILS</a><ul> +<li><a class="reference internal" href="#notes-for-c-c-parser">Notes for C/C++ Parser</a></li> +<li><a class="reference internal" href="#determining-file-language">Determining file language</a><ul> +<li><a class="reference internal" href="#file-name-mapping">File name mapping</a></li> +<li><a class="reference internal" href="#heuristically-guessing">Heuristically guessing</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a></li> +<li><a class="reference internal" href="#tag-entries">TAG ENTRIES</a><ul> +<li><a class="reference internal" href="#extension-fields">Extension fields</a><ul> +<li><a class="reference internal" href="#kinds">Kinds</a></li> +<li><a class="reference internal" href="#roles">Roles</a></li> +</ul> +</li> +<li><a class="reference internal" href="#extras">Extras</a></li> +<li><a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and extras</a></li> +</ul> +</li> +<li><a class="reference internal" href="#how-to-use-with-vi">HOW TO USE WITH VI</a></li> +<li><a class="reference internal" href="#how-to-use-with-gnu-emacs">HOW TO USE WITH GNU EMACS</a></li> +<li><a class="reference internal" href="#how-to-use-with-nedit">HOW TO USE WITH NEDIT</a></li> +<li><a class="reference internal" href="#caveats">CAVEATS</a></li> +<li><a class="reference internal" href="#bugs">BUGS</a></li> +<li><a class="reference internal" href="#environment-variables">ENVIRONMENT VARIABLES</a></li> +<li><a class="reference internal" href="#files">FILES</a></li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#author">AUTHOR</a></li> +<li><a class="reference internal" href="#motivation">MOTIVATION</a></li> +<li><a class="reference internal" href="#credits">CREDITS</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="../man-pages.html" + title="previous chapter">Man pages</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="tags.5.html" + title="next chapter">tags</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="tags.5.html" title="tags" + >next</a> |</li> + <li class="right" > + <a href="../man-pages.html" title="Man pages" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">ctags</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/readtags.1.html b/ctags/docs/man/readtags.1.html new file mode 100644 index 0000000..0a8e867 --- /dev/null +++ b/ctags/docs/man/readtags.1.html @@ -0,0 +1,449 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>readtags — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="Parsers" href="../parsers.html" /> + <link rel="prev" title="ctags-incompatibilities" href="ctags-incompatibilities.7.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="../parsers.html" title="Parsers" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags-incompatibilities.7.html" title="ctags-incompatibilities" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">readtags</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="readtags"> +<span id="readtags-1"></span><h1>readtags<a class="headerlink" href="#readtags" title="Permalink to this headline">¶</a></h1> +<p>Find tag file entries matching specified names</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>5.9.0</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>1</p> +</dd> +</dl> +<section id="synopsis"> +<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line"><strong>readtags</strong> -h | --help</div> +<div class="line"><strong>readtags</strong> (-H | --help-expression) (filter|sorter)</div> +<div class="line"><strong>readtags</strong> [OPTION]… ACTION</div> +</div> +</section> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The <strong>readtags</strong> program filters, sorts and prints tag entries in a tags file. +The basic filtering is done using <strong>actions</strong>, by which you can list all +regular tags, pseudo tags or regular tags matching specific name. Then, further +filtering and sorting can be done using <strong>post processors</strong>, namely <strong>filter +expressions</strong> and <strong>sorter expressions</strong>.</p> +</section> +<section id="actions"> +<h2>ACTIONS<a class="headerlink" href="#actions" title="Permalink to this headline">¶</a></h2> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-l</span></code>, <code class="docutils literal notranslate"><span class="pre">--list</span></code></dt><dd><p>List regular tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">[-]</span> <span class="pre">NAME</span></code></dt><dd><p>List regular tags matching NAME. +“-” as NAME indicates arguments after this as NAME even if they start with -.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-D</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code></dt><dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code>.</p> +</dd> +</dl> +</section> +<section id="options"> +<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2> +<section id="controlling-the-tags-reading-behavior"> +<h3>Controlling the Tags Reading Behavior<a class="headerlink" href="#controlling-the-tags-reading-behavior" title="Permalink to this headline">¶</a></h3> +<p>The behavior of reading tags can be controlled using these options:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-t</span> <span class="pre">TAGFILE</span></code>, <code class="docutils literal notranslate"><span class="pre">--tag-file</span> <span class="pre">TAGFILE</span></code></dt><dd><p>Use specified tag file (default: “tags”).</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-s[0|1|2]</span></code>, <code class="docutils literal notranslate"><span class="pre">--override-sort-detection</span> <span class="pre">METHOD</span></code></dt><dd><p>Override sort detection of tag file. +METHOD: unsorted|sorted|foldcase</p> +</dd> +</dl> +<p>The NAME action will perform binary search on sorted (including “foldcase”) +tags files, which is much faster then on unsorted tags files.</p> +</section> +<section id="controlling-the-name-action-behavior"> +<h3>Controlling the NAME Action Behavior<a class="headerlink" href="#controlling-the-name-action-behavior" title="Permalink to this headline">¶</a></h3> +<p>The behavior of the NAME action can be controlled using these options:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-i</span></code>, <code class="docutils literal notranslate"><span class="pre">--icase-match</span></code></dt><dd><p>Perform case-insensitive matching in the NAME action.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-p</span></code>, <code class="docutils literal notranslate"><span class="pre">--prefix-match</span></code></dt><dd><p>Perform prefix matching in the NAME action.</p> +</dd> +</dl> +</section> +<section id="controlling-the-output"> +<h3>Controlling the Output<a class="headerlink" href="#controlling-the-output" title="Permalink to this headline">¶</a></h3> +<p>By default, the output of readtags contains only the name, input and pattern +field. The Output can be tweaked using these options:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-d</span></code>, <code class="docutils literal notranslate"><span class="pre">--debug</span></code></dt><dd><p>Turn on debugging output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-E</span></code>, <code class="docutils literal notranslate"><span class="pre">--escape-output</span></code></dt><dd><p>Escape characters like tabs in output as described in <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-e</span></code>, <code class="docutils literal notranslate"><span class="pre">--extension-fields</span></code></dt><dd><p>Include extension fields in output.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-n</span></code>, <code class="docutils literal notranslate"><span class="pre">--line-number</span></code></dt><dd><p>Also include the line number field when <code class="docutils literal notranslate"><span class="pre">-e</span></code> option is give.</p> +</dd> +</dl> +<p>About the <code class="docutils literal notranslate"><span class="pre">-E</span></code> option: certain characters are escaped in a tags file, to make +it machine-readable. e.g., ensuring no tabs character appear in fields other +than the pattern field. By default, readtags translates them to make it +human-readable, but when utilizing readtags output in a script or a client +tool, <code class="docutils literal notranslate"><span class="pre">-E</span></code> option should be used. See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for more +discussion on this.</p> +</section> +<section id="filtering-and-sorting"> +<h3>Filtering and Sorting<a class="headerlink" href="#filtering-and-sorting" title="Permalink to this headline">¶</a></h3> +<p>Further filtering and sorting on the tags listed by actions are performed using:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">-Q</span> <span class="pre">EXP</span></code>, <code class="docutils literal notranslate"><span class="pre">--filter</span> <span class="pre">EXP</span></code></dt><dd><p>Filter the tags listed by ACTION with EXP before printing.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">-S</span> <span class="pre">EXP</span></code>, <code class="docutils literal notranslate"><span class="pre">--sorter</span> <span class="pre">EXP</span></code></dt><dd><p>Sort the tags listed by ACTION with EXP before printing.</p> +</dd> +</dl> +<p>These are discussed in the <a class="reference internal" href="#expression">EXPRESSION</a> section.</p> +</section> +<section id="examples"> +<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3> +<ul> +<li><p>List all tags in “/path/to/tags”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -t /path/to/tags -l +</pre></div> +</div> +</li> +<li><p>List all tags in “tags” that start with “mymethod”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -p - mymethod +</pre></div> +</div> +</li> +<li><p>List all tags matching “mymethod”, case insensitively:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -i - mymethod +</pre></div> +</div> +</li> +<li><p>List all tags start with “myvar”, and printing all fields (i.e., the whole line):</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -p -ne - myvar +</pre></div> +</div> +</li> +</ul> +</section> +</section> +<section id="expression"> +<h2>EXPRESSION<a class="headerlink" href="#expression" title="Permalink to this headline">¶</a></h2> +<p>Scheme-style expressions are used for the <code class="docutils literal notranslate"><span class="pre">-Q</span></code> and <code class="docutils literal notranslate"><span class="pre">-S</span></code> options. For those +who doesn’t know Scheme or Lisp, just remember:</p> +<ul class="simple"> +<li><p>A function call is wrapped in a pair of parenthesis. The first item in it is +the function/operator name, the others are arguments.</p></li> +<li><p>Function calls can be nested.</p></li> +<li><p>Missing values and boolean false are represented by <code class="docutils literal notranslate"><span class="pre">#f</span></code>. <code class="docutils literal notranslate"><span class="pre">#t</span></code> and all +other values are considered to be true.</p></li> +</ul> +<p>So, <code class="docutils literal notranslate"><span class="pre">(+</span> <span class="pre">1</span> <span class="pre">(+</span> <span class="pre">2</span> <span class="pre">3))</span></code> means add 2 and 3 first, then add the result with 1. +<code class="docutils literal notranslate"><span class="pre">(and</span> <span class="pre">"string"</span> <span class="pre">1</span> <span class="pre">#t)</span></code> means logical AND on <code class="docutils literal notranslate"><span class="pre">"string"</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="docutils literal notranslate"><span class="pre">#t</span></code>, +and the result is true since there is no <code class="docutils literal notranslate"><span class="pre">#f</span></code>.</p> +<section id="filtering"> +<h3>Filtering<a class="headerlink" href="#filtering" title="Permalink to this headline">¶</a></h3> +<p>The tag entries that make the filter expression produces true value are printed +by readtags.</p> +<p>The basic operators for filtering are <code class="docutils literal notranslate"><span class="pre">eq?</span></code>, <code class="docutils literal notranslate"><span class="pre">prefix?</span></code>, <code class="docutils literal notranslate"><span class="pre">suffix?</span></code>, +<code class="docutils literal notranslate"><span class="pre">substr?</span></code>, and <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code>. Language common fields can be accessed using +variables starting with <code class="docutils literal notranslate"><span class="pre">$</span></code>, e.g., <code class="docutils literal notranslate"><span class="pre">$language</span></code> represents the language field. +For example:</p> +<ul> +<li><p>List all tags start with “myfunc” in Python code files:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -p -Q <span class="s1">'(eq? $language "Python")'</span> - myfunc +</pre></div> +</div> +</li> +</ul> +<p><code class="docutils literal notranslate"><span class="pre">downcase</span></code> or <code class="docutils literal notranslate"><span class="pre">upcase</span></code> operators can be used to perform case-insensitive +matching:</p> +<ul> +<li><p>List all tags containing “my”, case insensitively:</p> +<blockquote> +<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(substr? (downcase $name) "my")'</span> -l +</pre></div> +</div> +</div></blockquote> +</li> +</ul> +<p>We have logical operators like <code class="docutils literal notranslate"><span class="pre">and</span></code>, <code class="docutils literal notranslate"><span class="pre">or</span></code> and <code class="docutils literal notranslate"><span class="pre">not</span></code>. The value of a +missing field is #f, so we could deal with missing fields:</p> +<ul> +<li><p>List all tags containing “impl” in Python code files, but allow the +<code class="docutils literal notranslate"><span class="pre">language:</span></code> field to be missing:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span>$ readtags -Q '(and (substr? $name "impl")\ + (or (not $language)\ + (eq? $language "Python")))' -l +</pre></div> +</div> +</li> +</ul> +<p><code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> is for the case when string predicates (<code class="docutils literal notranslate"><span class="pre">prefix?</span></code>, <code class="docutils literal notranslate"><span class="pre">suffix?</span></code>, +and <code class="docutils literal notranslate"><span class="pre">substr?</span></code>) are not enough. You can use “Posix extended regular expression” +as PATTERN.</p> +<ul> +<li><p>List all tags inherits from the class “A”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(#/(^|,) ?A(,|$)/ $inherits)'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>Here <code class="docutils literal notranslate"><span class="pre">$inherits</span></code> is a comma-separated class list like “A,B,C”, “P, A, Q”, or +just “A”. Notice that this filter works on both situations where there’s a +space after each comma or there’s not.</p> +<p>Case-insensitive matching can be performed by <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code>:</p> +<ul> +<li><p>List all tags inherits from the class “A” or “a”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(#/(^|,) ?A(,|$)/i $inherits)'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>To include “/” in a pattern, prefix <code class="docutils literal notranslate"><span class="pre">\</span></code> to the “/”.</p> +<p>NOTE: The above regular expression pattern for inspecting inheritances is just +an example to show how to use <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> expression. Tags file generators +have no consensus about the format of <code class="docutils literal notranslate"><span class="pre">inherits:</span></code>, e.g., whether there should +be a space after a comma. Even parsers in ctags have no consensus. Noticing the +format of the <code class="docutils literal notranslate"><span class="pre">inherits:</span></code> field of specific languages is needed for such +queries.</p> +<p>The expressions <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> and <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code> are for interactive use. +Readtags also offers an alias <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code>, so <code class="docutils literal notranslate"><span class="pre">#/PATTERN/</span></code> is equal to +<code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN")</span></code>, and <code class="docutils literal notranslate"><span class="pre">#/PATTERN/i</span></code> is equal to +<code class="docutils literal notranslate"><span class="pre">(string->regexp</span> <span class="pre">"PATTERN"</span> <span class="pre">:case-fold</span> <span class="pre">#t)</span></code>. <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code> doesn’t need +to prefix <code class="docutils literal notranslate"><span class="pre">\</span></code> for including “/” in a pattern. <code class="docutils literal notranslate"><span class="pre">string->regexp</span></code> may simplify +a client tool building an expression. See also <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for +building expressions in your tool.</p> +<p>Let’s now consider missing fields. The tags file may have tag entries that has +no <code class="docutils literal notranslate"><span class="pre">inherits:</span></code> field. In that case <code class="docutils literal notranslate"><span class="pre">$inherits</span></code> is #f, and the regular +expression matching raises an error, since string operators only work for +strings. To avoid this problem:</p> +<ul> +<li><p>Safely list all tags inherits from the class “A”:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(and $inherits (#/(^|,) ?A(,|$)/ $inherits))'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>This makes sure <code class="docutils literal notranslate"><span class="pre">$inherits</span></code> is not missing first, then match it by regexp.</p> +<p>Sometimes you want to keep tags where the field <em>is</em> missing. For example, your +want to exclude reference tags, which is marked by the <code class="docutils literal notranslate"><span class="pre">extras:</span></code> field, then +you want to keep tags who doesn’t have <code class="docutils literal notranslate"><span class="pre">extras:</span></code> field since they are also +not reference tags. Here’s how to do it:</p> +<ul> +<li><p>List all tags but the reference tags:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))'</span> -l +</pre></div> +</div> +</li> +</ul> +<p>Notice that <code class="docutils literal notranslate"><span class="pre">(not</span> <span class="pre">$extras)</span></code> produces <code class="docutils literal notranslate"><span class="pre">#t</span></code> when <code class="docutils literal notranslate"><span class="pre">$extras</span></code> is missing, so +the whole <code class="docutils literal notranslate"><span class="pre">or</span></code> expression produces <code class="docutils literal notranslate"><span class="pre">#t</span></code>.</p> +<p>Run “readtags -H filter” to know about all valid functions and variables.</p> +</section> +<section id="sorting"> +<h3>Sorting<a class="headerlink" href="#sorting" title="Permalink to this headline">¶</a></h3> +<p>When sorting, the sorter expression is evaluated on two tag entries to decide +which should sort before the other one, until the order of all tag entries is +decided.</p> +<p>In a sorter expression, <code class="docutils literal notranslate"><span class="pre">$</span></code> and <code class="docutils literal notranslate"><span class="pre">&</span></code> are used to access the fields in the +two tag entries, and let’s call them $-entry and &-entry. The sorter expression +should have a value of -1, 0 or 1. The value -1 means the $-entry should be put +above the &-entry, 1 means the contrary, and 0 makes their order in the output +uncertain.</p> +<p>The core operator of sorting is <code class="docutils literal notranslate"><span class="pre"><></span></code>. It’s used to compare two strings or two +numbers (numbers are for the <code class="docutils literal notranslate"><span class="pre">line:</span></code> or <code class="docutils literal notranslate"><span class="pre">end:</span></code> fields). In <code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">a</span> <span class="pre">b)</span></code>, if +<code class="docutils literal notranslate"><span class="pre">a</span></code> < <code class="docutils literal notranslate"><span class="pre">b</span></code>, the result is -1; <code class="docutils literal notranslate"><span class="pre">a</span></code> > <code class="docutils literal notranslate"><span class="pre">b</span></code> produces 1, and <code class="docutils literal notranslate"><span class="pre">a</span></code> = <code class="docutils literal notranslate"><span class="pre">b</span></code> +produces 0. Strings are compared using the <code class="docutils literal notranslate"><span class="pre">strcmp</span></code> function, see strcmp(3).</p> +<p>For example, sort by names, and make those shorter or alphabetically smaller +ones appear before the others:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -S <span class="s1">'(<> $name &name)'</span> -l +</pre></div> +</div> +<p>This reads “If the tag name in the $-entry is smaller, it goes before the +&-entry”.</p> +<p>The <code class="docutils literal notranslate"><span class="pre"><or></span></code> operator is used to chain multiple expressions until one returns +-1 or 1. For example, sort by input file names, then line numbers if in the +same file:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -S <span class="s1">'(<or> (<> $input &input) (<> $line &line))'</span> -l +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">*-</span></code> operator is used to flip the compare result. i.e., <code class="docutils literal notranslate"><span class="pre">(*-</span> <span class="pre">(<></span> <span class="pre">a</span> <span class="pre">b))</span></code> +is the same as <code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">b</span> <span class="pre">a)</span></code>.</p> +<p>Filter expressions can be used in sorter expressions. The technique is use +<code class="docutils literal notranslate"><span class="pre">if</span></code> to produce integers that can be compared based on the filter, like:</p> +<div class="highlight-lisp notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nv"><></span> <span class="p">(</span><span class="k">if</span> <span class="nv">filter-expr-on-$-entry</span> <span class="mi">-1</span> <span class="mi">1</span><span class="p">)</span> + <span class="p">(</span><span class="k">if</span> <span class="nv">filter-expr-on-&-entry</span> <span class="mi">-1</span> <span class="mi">1</span><span class="p">))</span> +</pre></div> +</div> +<p>So if $-entry satisfies the filter, while &-entry doesn’t, it’s the same as +<code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">-1</span> <span class="pre">1)</span></code>, which produces <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p> +<p>For example, we want to put tags with “file” kind below other tags, then the +sorter would look like:</p> +<div class="highlight-lisp notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nv"><></span> <span class="p">(</span><span class="k">if</span> <span class="p">(</span><span class="nv">eq?</span> <span class="nv">$kind</span> <span class="s">"file"</span><span class="p">)</span> <span class="mi">1</span> <span class="mi">-1</span><span class="p">)</span> + <span class="p">(</span><span class="k">if</span> <span class="p">(</span><span class="nv">eq?</span> <span class="nv">&kind</span> <span class="s">"file"</span><span class="p">)</span> <span class="mi">1</span> <span class="mi">-1</span><span class="p">))</span> +</pre></div> +</div> +<p>A quick read tells us: If $-entry has “file” kind, and &-entry doesn’t, the +sorter becomes <code class="docutils literal notranslate"><span class="pre">(<></span> <span class="pre">1</span> <span class="pre">-1)</span></code>, which produces <code class="docutils literal notranslate"><span class="pre">1</span></code>, so the $-entry is put below +the &-entry, exactly what we want.</p> +</section> +<section id="inspecting-the-behavior-of-expressions"> +<h3>Inspecting the Behavior of Expressions<a class="headerlink" href="#inspecting-the-behavior-of-expressions" title="Permalink to this headline">¶</a></h3> +<p>The <cite>print</cite> operator can be used to print the value of an expression. For +example:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(print $name)'</span> -l +</pre></div> +</div> +<p>prints the name of each tag entry before it. Since the return value of +<code class="docutils literal notranslate"><span class="pre">print</span></code> is not #f, all the tag entries are printed. We could control this +using the <code class="docutils literal notranslate"><span class="pre">begin</span></code> or <code class="docutils literal notranslate"><span class="pre">begin0</span></code> operator. <code class="docutils literal notranslate"><span class="pre">begin</span></code> returns the value of its +last argument, and <code class="docutils literal notranslate"><span class="pre">begin0</span></code> returns the value of its first argument. For +example:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>readtags -Q <span class="s1">'(begin0 #f (print (prefix? "ctags" "ct")))'</span> -l +</pre></div> +</div> +<p>prints a bunch of “#t” (depending on how many lines are in the tags file), and +the actual tag entries are not printed.</p> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="tags.5.html#tags-5"><span class="std std-ref">tags(5)</span></a> for the details of tags file format.</p> +<p>See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> for the tips writing a +tool utilizing tags file.</p> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>The git repository for the library used in readtags command:</p> +<p><a class="reference external" href="https://github.com/universal-ctags/libreadtags">https://github.com/universal-ctags/libreadtags</a></p> +</section> +<section id="credits"> +<h2>CREDITS<a class="headerlink" href="#credits" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert%40users.sourceforge.net">dhiebert<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +<p>The readtags command and libreadtags maintained at Universal Ctags +are derived from readtags.c and readtags.h developd at +<a class="reference external" href="http://ctags.sourceforge.net">http://ctags.sourceforge.net</a>.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">readtags</a><ul> +<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#actions">ACTIONS</a></li> +<li><a class="reference internal" href="#options">OPTIONS</a><ul> +<li><a class="reference internal" href="#controlling-the-tags-reading-behavior">Controlling the Tags Reading Behavior</a></li> +<li><a class="reference internal" href="#controlling-the-name-action-behavior">Controlling the NAME Action Behavior</a></li> +<li><a class="reference internal" href="#controlling-the-output">Controlling the Output</a></li> +<li><a class="reference internal" href="#filtering-and-sorting">Filtering and Sorting</a></li> +<li><a class="reference internal" href="#examples">Examples</a></li> +</ul> +</li> +<li><a class="reference internal" href="#expression">EXPRESSION</a><ul> +<li><a class="reference internal" href="#filtering">Filtering</a></li> +<li><a class="reference internal" href="#sorting">Sorting</a></li> +<li><a class="reference internal" href="#inspecting-the-behavior-of-expressions">Inspecting the Behavior of Expressions</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +<li><a class="reference internal" href="#credits">CREDITS</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags-incompatibilities.7.html" + title="previous chapter">ctags-incompatibilities</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="../parsers.html" + title="next chapter">Parsers</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="../parsers.html" title="Parsers" + >next</a> |</li> + <li class="right" > + <a href="ctags-incompatibilities.7.html" title="ctags-incompatibilities" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">readtags</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/man/tags.5.html b/ctags/docs/man/tags.5.html new file mode 100644 index 0000000..e9747f4 --- /dev/null +++ b/ctags/docs/man/tags.5.html @@ -0,0 +1,619 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>tags — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="../_static/classic.css" /> + + <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> + <script src="../_static/jquery.js"></script> + <script src="../_static/underscore.js"></script> + <script src="../_static/doctools.js"></script> + + <link rel="index" title="Index" href="../genindex.html" /> + <link rel="search" title="Search" href="../search.html" /> + <link rel="next" title="ctags-optlib" href="ctags-optlib.7.html" /> + <link rel="prev" title="ctags" href="ctags.1.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="ctags-optlib.7.html" title="ctags-optlib" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="ctags.1.html" title="ctags" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" accesskey="U">Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">tags</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="tags"> +<span id="tags-5"></span><h1>tags<a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h1> +<p>Vi tags file format extended in ctags projects</p> +<dl class="field-list simple"> +<dt class="field-odd">Version</dt> +<dd class="field-odd"><p>2+</p> +</dd> +<dt class="field-even">Manual group</dt> +<dd class="field-even"><p>Universal Ctags</p> +</dd> +<dt class="field-odd">Manual section</dt> +<dd class="field-odd"><p>5</p> +</dd> +</dl> +<section id="description"> +<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2> +<p>The contents of next section is a copy of FORMAT file in Exuberant +Ctags source code in its subversion repository at sourceforge.net.</p> +<p>Exceptions introduced in Universal Ctags are explained inline with +“EXCEPTION” marker.</p> +</section> +<hr class="docutils" /> +<section id="proposal-for-extended-vi-tags-file-format"> +<h2>Proposal for extended Vi tags file format<a class="headerlink" href="#proposal-for-extended-vi-tags-file-format" title="Permalink to this headline">¶</a></h2> +<div class="line-block"> +<div class="line">Version: 0.06 DRAFT</div> +<div class="line">Date: 1998 Feb 8</div> +<div class="line">Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net></div> +</div> +<section id="introduction"> +<h3>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h3> +<p>The file format for the “tags” file, as used by Vi and many of its +descendants, has limited capabilities.</p> +<p>This additional functionality is desired:</p> +<ol class="arabic simple"> +<li><p>Static or local tags. +The scope of these tags is the file where they are defined. The same tag +can appear in several files, without really being a duplicate.</p></li> +<li><p>Duplicate tags. +Allow the same tag to occur more then once. They can be located in +a different file and/or have a different command.</p></li> +<li><p>Support for C++. +A tag is not only specified by its name, but also by the context (the +class name).</p></li> +<li><p>Future extension. +When even more additional functionality is desired, it must be possible to +add this later, without breaking programs that don’t support it.</p></li> +</ol> +</section> +<section id="from-proposal-to-standard"> +<h3>From proposal to standard<a class="headerlink" href="#from-proposal-to-standard" title="Permalink to this headline">¶</a></h3> +<p>To make this proposal into a standard for tags files, it needs to be supported +by most people working on versions of Vi, ctags, etc.. Currently this +standard is supported by:</p> +<dl class="simple"> +<dt>Darren Hiebert <dhiebert at users.sourceforge.net></dt><dd><p>Exuberant Ctags</p> +</dd> +<dt>Bram Moolenaar <Bram at vim.org></dt><dd><p>Vim (Vi IMproved)</p> +</dd> +</dl> +<p>These have been or will be asked to support this standard:</p> +<dl class="simple"> +<dt>Nvi</dt><dd><p>Keith Bostic <bostic at bsdi.com></p> +</dd> +<dt>Vile</dt><dd><p>Tom E. Dickey <dickey at clark.net></p> +</dd> +<dt>NEdit</dt><dd><p>Mark Edel <edel at ltx.com></p> +</dd> +<dt>CRiSP</dt><dd><p>Paul Fox <fox at crisp.demon.co.uk></p> +</dd> +<dt>Lemmy</dt><dd><p>James Iuliano <jai at accessone.com></p> +</dd> +<dt>Zeus</dt><dd><p>Jussi Jumppanen <jussij at ca.com.au></p> +</dd> +<dt>Elvis</dt><dd><p>Steve Kirkendall <kirkenda at cs.pdx.edu></p> +</dd> +<dt>FTE</dt><dd><p>Marko Macek <Marko.Macek at snet.fri.uni-lj.si></p> +</dd> +</dl> +</section> +<section id="backwards-compatibility"> +<h3>Backwards compatibility<a class="headerlink" href="#backwards-compatibility" title="Permalink to this headline">¶</a></h3> +<p>A tags file that is generated in the new format should still be usable by Vi. +This makes it possible to distribute tags files that are usable by all +versions and descendants of Vi.</p> +<p>This restricts the format to what Vi can handle. The format is:</p> +<ol class="arabic"> +<li><p>The tags file is a list of lines, each line in the format:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">tagname</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagfile</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagaddress</span><span class="p">}</span> +</pre></div> +</div> +<dl> +<dt>{tagname}</dt><dd><p>Any identifier, not containing white space..</p> +<p>EXCEPTION: Universal Ctags violates this item of the proposal; +tagname may contain spaces. However, tabs are not allowed.</p> +</dd> +<dt><Tab></dt><dd><p>Exactly one TAB character (although many versions of Vi can +handle any amount of white space).</p> +</dd> +<dt>{tagfile}</dt><dd><p>The name of the file where {tagname} is defined, relative to +the current directory (or location of the tags file?).</p> +</dd> +<dt>{tagaddress}</dt><dd><p>Any Ex command. When executed, it behaves like ‘magic’ was +not set.</p> +</dd> +</dl> +</li> +<li><p>The tags file is sorted on {tagname}. This allows for a binary search in +the file.</p></li> +<li><p>Duplicate tags are allowed, but which one is actually used is +unpredictable (because of the binary search).</p></li> +</ol> +<p>The best way to add extra text to the line for the new functionality, without +breaking it for Vi, is to put a comment in the {tagaddress}. This gives the +freedom to use any text, and should work in any traditional Vi implementation.</p> +<p>For example, when the old tags file contains:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>main main.c /^main(argc, argv)$/ +DEBUG defines.c 89 +</pre></div> +</div> +<p>The new lines can be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>main main.c /^main(argc, argv)$/;"any additional text +DEBUG defines.c 89;"any additional text +</pre></div> +</div> +<p>Note that the ‘;’ is required to put the cursor in the right line, and then +the ‘”’ is recognized as the start of a comment.</p> +<p>For Posix compliant Vi versions this will NOT work, since only a line number +or a search command is recognized. I hope Posix can be adjusted. Nvi suffers +from this.</p> +</section> +<section id="security"> +<h3>Security<a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h3> +<p>Vi allows the use of any Ex command in a tags file. This has the potential of +a trojan horse security leak.</p> +<p>The proposal is to allow only Ex commands that position the cursor in a single +file. Other commands, like editing another file, quitting the editor, +changing a file or writing a file, are not allowed. It is therefore logical +to call the command a tagaddress.</p> +<p>Specifically, these two Ex commands are allowed:</p> +<ul> +<li><p>A decimal line number:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">89</span> +</pre></div> +</div> +</li> +<li><p>A search command. It is a regular expression pattern, as used by Vi, +enclosed in // or ??:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>/^int c;$/ +?main()? +</pre></div> +</div> +</li> +</ul> +<p>There are two combinations possible:</p> +<ul> +<li><p>Concatenation of the above, with ‘;’ in between. The meaning is that the +first line number or search command is used, the cursor is positioned in +that line, and then the second search command is used (a line number would +not be useful). This can be done multiple times. This is useful when the +information in a single line is not unique, and the search needs to start +in a specified line.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">struct</span> <span class="n">xyz</span> <span class="p">{</span><span class="o">/</span><span class="p">;</span><span class="o">/</span><span class="nb">int</span> <span class="n">count</span><span class="p">;</span><span class="o">/</span> +<span class="mi">389</span><span class="p">;</span><span class="o">/</span><span class="n">struct</span> <span class="n">foo</span><span class="o">/</span><span class="p">;</span><span class="o">/</span><span class="n">char</span> <span class="o">*</span><span class="n">s</span><span class="p">;</span><span class="o">/</span> +</pre></div> +</div> +</li> +<li><p>A trailing comment can be added, starting with ‘;”’ (two characters: +semi-colon and double-quote). This is used below.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">89</span><span class="p">;</span><span class="s2">" foo bar</span> +</pre></div> +</div> +</li> +</ul> +<p>This might be extended in the future. What is currently missing is a way to +position the cursor in a certain column.</p> +</section> +<section id="goals"> +<h3>Goals<a class="headerlink" href="#goals" title="Permalink to this headline">¶</a></h3> +<p>Now the usage of the comment text has to be defined. The following is aimed +at:</p> +<ol class="arabic simple"> +<li><p>Keep the text short, because:</p> +<ul class="simple"> +<li><p>The line length that Vi can handle is limited to 512 characters.</p></li> +<li><p>Tags files can contain thousands of tags. I have seen tags files of +several Mbytes.</p></li> +<li><p>More text makes searching slower.</p></li> +</ul> +</li> +<li><p>Keep the text readable, because:</p> +<ul class="simple"> +<li><p>It is often necessary to check the output of a new ctags program.</p></li> +<li><p>Be able to edit the file by hand.</p></li> +<li><p>Make it easier to write a program to produce or parse the file.</p></li> +</ul> +</li> +<li><p>Don’t use special characters, because:</p> +<ul class="simple"> +<li><p>It should be possible to treat a tags file like any normal text file.</p></li> +</ul> +</li> +</ol> +</section> +<section id="proposal"> +<h3>Proposal<a class="headerlink" href="#proposal" title="Permalink to this headline">¶</a></h3> +<p>Use a comment after the {tagaddress} field. The format would be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">tagname</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagfile</span><span class="p">}</span><span class="o"><</span><span class="n">Tab</span><span class="o">></span><span class="p">{</span><span class="n">tagaddress</span><span class="p">}[;</span><span class="s2">"<Tab></span><span class="si">{tagfield}</span><span class="s2">..]</span> +</pre></div> +</div> +<dl> +<dt>{tagname}</dt><dd><p>Any identifier, not containing white space..</p> +<p>EXCEPTION: Universal Ctags violates this item of the proposal; +name may contain spaces. However, tabs are not allowed. +Conversion, for some characters including <Tab> in the “value”, +explained in the last of this section is applied.</p> +</dd> +<dt><Tab></dt><dd><p>Exactly one TAB character (although many versions of Vi can +handle any amount of white space).</p> +</dd> +<dt>{tagfile}</dt><dd><p>The name of the file where {tagname} is defined, relative to +the current directory (or location of the tags file?).</p> +</dd> +<dt>{tagaddress}</dt><dd><p>Any Ex command. When executed, it behaves like ‘magic’ was +not set. It may be restricted to a line number or a search +pattern (Posix).</p> +</dd> +</dl> +<p>Optionally:</p> +<dl class="simple"> +<dt>;”</dt><dd><p>semicolon + doublequote: Ends the tagaddress in way that looks +like the start of a comment to Vi.</p> +</dd> +<dt>{tagfield}</dt><dd><p>See below.</p> +</dd> +</dl> +<p>A tagfield has a name, a colon, and a value: “name:value”.</p> +<ul> +<li><p>The name consist only out of alphabetical characters. Upper and lower case +are allowed. Lower case is recommended. Case matters (“kind:” and “Kind: +are different tagfields).</p> +<p>EXCEPTION: Universal Ctags allows users to use a numerical character +in the name other than its initial letter.</p> +</li> +<li><p>The value may be empty. +It cannot contain a <Tab>.</p> +<ul class="simple"> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\t</span></code>, this stands for a <Tab>.</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\r</span></code>, this stands for a <CR>.</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\n</span></code>, this stands for a <NL>.</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\\</span></code>, this stands for a single <code class="docutils literal notranslate"><span class="pre">\</span></code> character.</p></li> +</ul> +<p>Other use of the backslash character is reserved for future expansion. +Warning: When a tagfield value holds an MS-DOS file name, the backslashes +must be doubled!</p> +<p>EXCEPTION: Universal Ctags introduces more conversion rules.</p> +<ul class="simple"> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\a</span></code>, this stands for a <BEL> (0x07).</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\b</span></code>, this stands for a <BS> (0x08).</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\v</span></code>, this stands for a <VT> (0x0b).</p></li> +<li><p>When a value contains a <code class="docutils literal notranslate"><span class="pre">\f</span></code>, this stands for a <FF> (0x0c).</p></li> +<li><p>The characters in range 0x01 to 0x1F included, and 0x7F are +converted to <code class="docutils literal notranslate"><span class="pre">\x</span></code> prefixed hexadecimal number if the characters are +not handled in the above “value” rules.</p></li> +<li><p>The leading space (0x20) and <code class="docutils literal notranslate"><span class="pre">!</span></code> (0x21) in {tagname} are converted +to <code class="docutils literal notranslate"><span class="pre">\x</span></code> prefixed hexadecimal number (<code class="docutils literal notranslate"><span class="pre">\x20</span></code> and <code class="docutils literal notranslate"><span class="pre">\x21</span></code>) if the +tag is not a pseudo-tag. As described later, a pseudo-tag starts with +<code class="docutils literal notranslate"><span class="pre">!</span></code>. These rules are for distinguishing pseudo-tags and non pseudo-tags +(regular tags) when tags lines in a tag file are sorted.</p></li> +</ul> +</li> +</ul> +<p>Proposed tagfield names:</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 16%" /> +<col style="width: 84%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>FIELD-NAME</p></th> +<th class="head"><p>DESCRIPTION</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>arity</p></td> +<td><p>Number of arguments for a function tag.</p></td> +</tr> +<tr class="row-odd"><td><p>class</p></td> +<td><p>Name of the class for which this tag is a member or method.</p></td> +</tr> +<tr class="row-even"><td><p>enum</p></td> +<td><p>Name of the enumeration in which this tag is an enumerator.</p></td> +</tr> +<tr class="row-odd"><td><p>file</p></td> +<td><p>Static (local) tag, with a scope of the specified file. When +the value is empty, {tagfile} is used.</p></td> +</tr> +<tr class="row-even"><td><p>function</p></td> +<td><p>Function in which this tag is defined. Useful for local +variables (and functions). When functions nest (e.g., in +Pascal), the function names are concatenated, separated with +‘/’, so it looks like a path.</p></td> +</tr> +<tr class="row-odd"><td><p>kind</p></td> +<td><p>Kind of tag. The value depends on the language. For C and +C++ these kinds are recommended:</p> +<dl class="simple"> +<dt>c</dt><dd><p>class name</p> +</dd> +<dt>d</dt><dd><p>define (from #define XXX)</p> +</dd> +<dt>e</dt><dd><p>enumerator</p> +</dd> +<dt>f</dt><dd><p>function or method name</p> +</dd> +<dt>F</dt><dd><p>file name</p> +</dd> +<dt>g</dt><dd><p>enumeration name</p> +</dd> +<dt>m</dt><dd><p>member (of structure or class data)</p> +</dd> +<dt>p</dt><dd><p>function prototype</p> +</dd> +<dt>s</dt><dd><p>structure name</p> +</dd> +<dt>t</dt><dd><p>typedef</p> +</dd> +<dt>u</dt><dd><p>union name</p> +</dd> +<dt>v</dt><dd><p>variable</p> +</dd> +</dl> +<p>When this field is omitted, the kind of tag is undefined.</p> +</td> +</tr> +<tr class="row-even"><td><p>struct</p></td> +<td><p>Name of the struct in which this tag is a member.</p></td> +</tr> +<tr class="row-odd"><td><p>union</p></td> +<td><p>Name of the union in which this tag is a member.</p></td> +</tr> +</tbody> +</table> +<p>Note that these are mostly for C and C++. When tags programs are written for +other languages, this list should be extended to include the used field names. +This will help users to be independent of the tags program used.</p> +<p>Examples:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>asdf sub.cc /^asdf()$/;" new_field:some\svalue file: +foo_t sub.h /^typedef foo_t$/;" kind:t +func3 sub.p /^func3()$/;" function:/func1/func2 file: +getflag sub.c /^getflag(arg)$/;" kind:f file: +inc sub.cc /^inc()$/;" file: class:PipeBuf +</pre></div> +</div> +<p>The name of the “kind:” field can be omitted. This is to reduce the size of +the tags file by about 15%. A program reading the tags file can recognize the +“kind:” field by the missing ‘:’. Examples:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>foo_t sub.h /^typedef foo_t$/;" t +getflag sub.c /^getflag(arg)$/;" f file: +</pre></div> +</div> +<p>Additional remarks:</p> +<ul class="simple"> +<li><p>When a tagfield appears twice in a tag line, only the last one is used.</p></li> +</ul> +<p>Note about line separators:</p> +<p>Vi traditionally runs on Unix systems, where the line separator is a single +linefeed character <NL>. On MS-DOS and compatible systems <CR><NL> is the +standard line separator. To increase portability, this line separator is also +supported.</p> +<p>On the Macintosh a single <CR> is used for line separator. Supporting this on +Unix systems causes problems, because most fgets() implementation don’t see +the <CR> as a line separator. Therefore the support for a <CR> as line +separator is limited to the Macintosh.</p> +<p>Summary:</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 23%" /> +<col style="width: 36%" /> +<col style="width: 41%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>line separator</p></th> +<th class="head"><p>generated on</p></th> +<th class="head"><p>accepted on</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><LF></p></td> +<td><p>Unix</p></td> +<td><p>Unix, MS-DOS, Macintosh</p></td> +</tr> +<tr class="row-odd"><td><p><CR></p></td> +<td><p>Macintosh</p></td> +<td><p>Macintosh</p></td> +</tr> +<tr class="row-even"><td><p><CR><LF></p></td> +<td><p>MS-DOS</p></td> +<td><p>Unix, MS-DOS, Macintosh</p></td> +</tr> +</tbody> +</table> +<p>The characters <CR> and <LF> cannot be used inside a tag line. This is not +mentioned elsewhere (because it’s obvious).</p> +<p>Note about white space:</p> +<p>Vi allowed any white space to separate the tagname from the tagfile, and the +filename from the tagaddress. This would need to be allowed for backwards +compatibility. However, all known programs that generate tags use a single +<Tab> to separate fields.</p> +<p>There is a problem for using file names with embedded white space in the +tagfile field. To work around this, the same special characters could be used +as in the new fields, for example <code class="docutils literal notranslate"><span class="pre">\s</span></code>. But, unfortunately, in MS-DOS the +backslash character is used to separate file names. The file name +<code class="docutils literal notranslate"><span class="pre">c:\vim\sap</span></code> contains <code class="docutils literal notranslate"><span class="pre">\s</span></code>, but this is not a <Space>. The number of +backslashes could be doubled, but that will add a lot of characters, and make +parsing the tags file slower and clumsy.</p> +<p>To avoid these problems, we will only allow a <Tab> to separate fields, and +not support a file name or tagname that contains a <Tab> character. This +means that we are not 100% Vi compatible. However, there is no known tags +program that uses something else than a <Tab> to separate the fields. Only +when a user typed the tags file himself, or made his own program to generate a +tags file, we could run into problems. To solve this, the tags file should be +filtered, to replace the arbitrary white space with a single <Tab>. This Vi +command can be used:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">:</span><span class="o">%</span><span class="n">s</span><span class="o">/^</span>\<span class="p">([</span><span class="o">^</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*</span>\<span class="p">)[</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*</span>\<span class="p">([</span><span class="o">^</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*</span>\<span class="p">)[</span> <span class="o">^</span><span class="n">I</span><span class="p">]</span><span class="o">*/</span>\<span class="mi">1</span><span class="o">^</span><span class="n">I</span>\<span class="mi">2</span><span class="o">^</span><span class="n">I</span><span class="o">/</span> +</pre></div> +</div> +<p>(replace ^I with a real <Tab>).</p> +<p>TAG FILE INFORMATION:</p> +<p>Pseudo-tag lines can be used to encode information into the tag file regarding +details about its content (e.g. have the tags been sorted?, are the optional +tagfields present?), and regarding the program used to generate the tag file. +This information can be used both to optimize use of the tag file (e.g. +enable/disable binary searching) and provide general information (what version +of the generator was used).</p> +<p>The names of the tags used in these lines may be suitably chosen to ensure +that when sorted, they will always be located near the first lines of the tag +file. The use of “!_TAG_” is recommended. Note that a rare tag like “!” +can sort to before these lines. The program reading the tags file should be +smart enough to skip over these tags.</p> +<p>The lines described below have been chosen to convey a select set of +information.</p> +<p>Tag lines providing information about the content of the tag file:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_FILE_FORMAT {version-number} /optional comment/ +!_TAG_FILE_SORTED {0|1} /0=unsorted, 1=sorted/ +</pre></div> +</div> +<p>The {version-number} used in the tag file format line reserves the value of +“1” for tag files complying with the original UNIX vi/ctags format, and +reserves the value “2” for tag files complying with this proposal. This value +may be used to determine if the extended features described in this proposal +are present.</p> +<p>Tag lines providing information about the program used to generate the tag +file, and provided solely for documentation purposes:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_PROGRAM_AUTHOR {author-name} /{email-address}/ +!_TAG_PROGRAM_NAME {program-name} /optional comment/ +!_TAG_PROGRAM_URL {URL} /optional comment/ +!_TAG_PROGRAM_VERSION {version-id} /optional comment/ +</pre></div> +</div> +<p>EXCEPTION: Universal Ctags introduces more kinds of pseudo-tags. +See <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> about them.</p> +</section> +</section> +<hr class="docutils" /> +<section id="exceptions-in-universal-ctags"> +<h2>Exceptions in Universal Ctags<a class="headerlink" href="#exceptions-in-universal-ctags" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags supports this proposal with some +exceptions.</p> +<section id="exceptions"> +<h3>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h3> +<ol class="arabic simple"> +<li><p>{tagname} in tags file generated by Universal Ctags may contain +spaces and several escape sequences. Parsers for documents like Tex and +reStructuredText, or liberal languages such as JavaScript need these +exceptions. See {tagname} of Proposal section for more detail about the +conversion.</p></li> +<li><p>“name” part of {tagfield} in a tag generated by Universal Ctags may +contain numeric characters, but the first character of the “name” +must be alphabetic.</p> +</li> +</ol> +</section> +<section id="compatible-output-and-weakness"> +<span id="compat-output"></span><h3>Compatible output and weakness<a class="headerlink" href="#compatible-output-and-weakness" title="Permalink to this headline">¶</a></h3> +<p>Default behavior (<code class="docutils literal notranslate"><span class="pre">--output-format=u-ctags</span></code> option) has the +exceptions. In other hand, with <code class="docutils literal notranslate"><span class="pre">--output-format=e-ctags</span></code> option +ctags has no exception; Universal Ctags command may use the same file +format as Exuberant Ctags. However, <code class="docutils literal notranslate"><span class="pre">--output-format=e-ctags</span></code> throws +away a tag entry which name includes a space or a tab +character. <code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code> pseudo-tag tells which format is +used when ctags generating tags file.</p> +</section> +</section> +<section id="see-also"> +<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2> +<p><a class="reference internal" href="ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>, <a class="reference internal" href="ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a>, <a class="reference internal" href="ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>, <a class="reference internal" href="readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a></p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="../index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">tags</a><ul> +<li><a class="reference internal" href="#description">DESCRIPTION</a></li> +<li><a class="reference internal" href="#proposal-for-extended-vi-tags-file-format">Proposal for extended Vi tags file format</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#from-proposal-to-standard">From proposal to standard</a></li> +<li><a class="reference internal" href="#backwards-compatibility">Backwards compatibility</a></li> +<li><a class="reference internal" href="#security">Security</a></li> +<li><a class="reference internal" href="#goals">Goals</a></li> +<li><a class="reference internal" href="#proposal">Proposal</a></li> +</ul> +</li> +<li><a class="reference internal" href="#exceptions-in-universal-ctags">Exceptions in Universal Ctags</a><ul> +<li><a class="reference internal" href="#exceptions">Exceptions</a></li> +<li><a class="reference internal" href="#compatible-output-and-weakness">Compatible output and weakness</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also">SEE ALSO</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="ctags.1.html" + title="previous chapter">ctags</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="ctags-optlib.7.html" + title="next chapter">ctags-optlib</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="../search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="../genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="ctags-optlib.7.html" title="ctags-optlib" + >next</a> |</li> + <li class="right" > + <a href="ctags.1.html" title="ctags" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="../index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="../man-pages.html" >Man pages</a> »</li> + <li class="nav-item nav-item-this"><a href="">tags</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/news.html b/ctags/docs/news.html new file mode 100644 index 0000000..f3f84a9 --- /dev/null +++ b/ctags/docs/news.html @@ -0,0 +1,673 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Other changes — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Extending ctags with Regex parser (optlib)" href="optlib.html" /> + <link rel="prev" title="Interactive mode" href="interactive-mode.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="optlib.html" title="Extending ctags with Regex parser (optlib)" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="interactive-mode.html" title="Interactive mode" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Other changes</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="other-changes"> +<h1>Other changes<a class="headerlink" href="#other-changes" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#new-and-extended-options" id="id1">New and extended options</a></p> +<ul> +<li><p><a class="reference internal" href="#exclude-exception-an-option-complementing-exclude" id="id2"><code class="docutils literal notranslate"><span class="pre">--exclude-exception</span></code>, an option complementing <code class="docutils literal notranslate"><span class="pre">--exclude</span></code></a></p></li> +<li><p><a class="reference internal" href="#maxdepth-option" id="id3"><code class="docutils literal notranslate"><span class="pre">--maxdepth</span></code> option</a></p></li> +<li><p><a class="reference internal" href="#input-encoding-encoding-and-output-encoding-encoding" id="id4"><code class="docutils literal notranslate"><span class="pre">--input-encoding=ENCODING</span></code> and <code class="docutils literal notranslate"><span class="pre">--output-encoding=ENCODING</span></code></a></p></li> +<li><p><a class="reference internal" href="#map-lang-option" id="id5"><code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> option</a></p></li> +<li><p><a class="reference internal" href="#guessing-parser-from-file-contents-g-option" id="id6">Guessing parser from file contents (<code class="docutils literal notranslate"><span class="pre">-G</span></code> option)</a></p></li> +<li><p><a class="reference internal" href="#including-line-number-to-pattern-field" id="id7">Including line number to pattern field</a></p></li> +<li><p><a class="reference internal" href="#long-names-in-kinds-fields-and-extra-options" id="id8">Long names in kinds, fields, and extra options</a></p></li> +<li><p><a class="reference internal" href="#wildcard-in-options" id="id9">Wildcard in options</a></p></li> +<li><p><a class="reference internal" href="#extra-tag-entries-extras" id="id10">Extra tag entries (<code class="docutils literal notranslate"><span class="pre">--extras</span></code>)</a></p></li> +<li><p><a class="reference internal" href="#kinds-synchronization" id="id11">Kinds synchronization</a></p></li> +<li><p><a class="reference internal" href="#enabling-disabling-pseudo-tags-pseudo-tags-option" id="id12">Enabling/disabling pseudo-tags (<code class="docutils literal notranslate"><span class="pre">--pseudo-tags</span></code> option)</a></p></li> +<li><p><a class="reference internal" href="#put-field-prefix-options" id="id13"><code class="docutils literal notranslate"><span class="pre">--put-field-prefix</span></code> options</a></p></li> +<li><p><a class="reference internal" href="#always-and-never-as-an-argument-for-tag-relative" id="id14">“always” and “never” as an argument for <code class="docutils literal notranslate"><span class="pre">--tag-relative</span></code></a></p></li> +<li><p><a class="reference internal" href="#defining-a-parser-specific-extra" id="id15">Defining a parser specific extra</a></p></li> +<li><p><a class="reference internal" href="#defining-a-cpreprocessor-macro-from-command-line" id="id16">Defining a CPreProcessor macro from command line</a></p></li> +<li><p><a class="reference internal" href="#options-for-inspecting-ctags-internals" id="id17">Options for inspecting ctags internals</a></p></li> +<li><p><a class="reference internal" href="#notice-messages-and-quiet" id="id18">Notice messages and <code class="docutils literal notranslate"><span class="pre">--quiet</span></code></a></p></li> +<li><p><a class="reference internal" href="#skipping-utf-8-bom" id="id19">Skipping utf-8 BOM</a></p></li> +<li><p><a class="reference internal" href="#interactive-mode" id="id20">Interactive mode</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#incompatible-changes-in-command-line" id="id21">Incompatible changes in command line</a></p> +<ul> +<li><p><a class="reference internal" href="#d-option" id="id22"><code class="docutils literal notranslate"><span class="pre">-D</span></code> option</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#changes-imported-from-exuberant-ctags" id="id23">Changes imported from Exuberant Ctags</a></p></li> +<li><p><a class="reference internal" href="#parser-related-changes" id="id24">Parser related changes</a></p> +<ul> +<li><p><a class="reference internal" href="#new-parsers" id="id25">New parsers</a></p></li> +<li><p><a class="reference internal" href="#fully-improved-parsers" id="id26">Fully improved parsers</a></p></li> +<li><p><a class="reference internal" href="#automatically-expanding-cpreprocessor-macros-defined-in-the-same-input-file-highly-experimental" id="id27">Automatically expanding CPreProcessor macros defined in the same input file (HIGHLY EXPERIMENTAL)</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#readtags" id="id28">Readtags</a></p> +<ul> +<li><p><a class="reference internal" href="#printing-line-numbers-with-n" id="id29">Printing line numbers with <code class="docutils literal notranslate"><span class="pre">-n</span></code></a></p></li> +<li><p><a class="reference internal" href="#filtering-in-readtags-command" id="id30">Filtering in readtags command</a></p></li> +<li><p><a class="reference internal" href="#sorting-in-readtags-command" id="id31">Sorting in readtags command</a></p></li> +<li><p><a class="reference internal" href="#listing-pseudo-tags-with-d" id="id32">Listing pseudo tags with <code class="docutils literal notranslate"><span class="pre">-D</span></code></a></p></li> +</ul> +</li> +</ul> +</div> +<hr class="docutils" /> +<p>Many changes have been introduced in Universal Ctags. Use git-log to +review changes not enumerated here, especially in language parsers.</p> +<section id="new-and-extended-options"> +<h2><a class="toc-backref" href="#id1">New and extended options</a><a class="headerlink" href="#new-and-extended-options" title="Permalink to this headline">¶</a></h2> +<section id="exclude-exception-an-option-complementing-exclude"> +<h3><a class="toc-backref" href="#id2"><code class="docutils literal notranslate"><span class="pre">--exclude-exception</span></code>, an option complementing <code class="docutils literal notranslate"><span class="pre">--exclude</span></code></a><a class="headerlink" href="#exclude-exception-an-option-complementing-exclude" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/ctags.1.html#option-input-output-file"><span class="std std-ref">Input/Output File Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="maxdepth-option"> +<h3><a class="toc-backref" href="#id3"><code class="docutils literal notranslate"><span class="pre">--maxdepth</span></code> option</a><a class="headerlink" href="#maxdepth-option" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/ctags.1.html#option-input-output-file"><span class="std std-ref">Input/Output File Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="input-encoding-encoding-and-output-encoding-encoding"> +<h3><a class="toc-backref" href="#id4"><code class="docutils literal notranslate"><span class="pre">--input-encoding=ENCODING</span></code> and <code class="docutils literal notranslate"><span class="pre">--output-encoding=ENCODING</span></code></a><a class="headerlink" href="#input-encoding-encoding-and-output-encoding-encoding" title="Permalink to this headline">¶</a></h3> +<p>People may use their own native language in source code comments (or +sometimes in identifiers) and in such cases encoding may become an issue. +Nowadays UTF-8 is the most widely used encoding, but some source codes +still use legacy encodings like latin1, cp932 and so on. These options +are useful for such files.</p> +<p>ctags doesn’t consider the input encoding; it just reads input as a +sequence of bytes and uses them as is when writing tags entries.</p> +<p>On the other hand Vim does consider input encoding. When loading a +file, Vim converts the file contents into an internal format with one +of the encodings specified in its <cite>fileencodings</cite> option.</p> +<p>As a result of this difference, Vim cannot always move the cursor to +the definition of a tag as users expect when attempting to match the +patterns in a tags file.</p> +<p>The good news is that there is a way to notify Vim of the encoding +used in a tags file with the <code class="docutils literal notranslate"><span class="pre">TAG_FILE_ENCODING</span></code> pseudo-tag.</p> +<p>Two new options have been introduced (<code class="docutils literal notranslate"><span class="pre">--input-encoding=IN</span></code> and +<code class="docutils literal notranslate"><span class="pre">--output-encoding=OUT</span></code>).</p> +<p>Using the encoding specified with these options ctags converts input +from <code class="docutils literal notranslate"><span class="pre">IN</span></code> to <code class="docutils literal notranslate"><span class="pre">OUT</span></code>. ctags uses the converted strings when writing +the pattern parts of each tag line. As a result the tags output is +encoded in <code class="docutils literal notranslate"><span class="pre">OUT</span></code> encoding.</p> +<p>In addition <code class="docutils literal notranslate"><span class="pre">OUT</span></code> is specified at the top the tags file as the +value for the <code class="docutils literal notranslate"><span class="pre">TAG_FILE_ENCODING</span></code> pseudo-tag. The default value of +<code class="docutils literal notranslate"><span class="pre">OUT</span></code> is UTF-8.</p> +<p>NOTE: Converted input is NOT passed to language parsers. +The parsers still deal with input as a byte sequence.</p> +<p>With <code class="docutils literal notranslate"><span class="pre">--input-encoding-<LANG>=IN</span></code>, you can specify a specific input +encoding for <code class="docutils literal notranslate"><span class="pre">LANG</span></code>. It overrides the global default value given +with <code class="docutils literal notranslate"><span class="pre">--input-encoding</span></code>.</p> +<p>The example usage can be found in <em>Tmain/{input,output}-encoding-option.d</em>.</p> +<p>Acceptable <code class="docutils literal notranslate"><span class="pre">IN</span></code> and <code class="docutils literal notranslate"><span class="pre">OUT</span></code> values can be listed with <em>iconv -l</em> or +<em>iconv --list</em>. It is platform dependant.</p> +<p>To enable the option, libiconv is needed on your platform. +On Windows mingw (without msys2), you must specify <code class="docutils literal notranslate"><span class="pre">WITH_ICONV=yes</span></code> +like this:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">C</span><span class="p">:</span>\<span class="n">dev</span>\<span class="n">ctags</span><span class="o">></span><span class="n">mingw32</span><span class="o">-</span><span class="n">make</span> <span class="o">-</span><span class="n">f</span> <span class="n">mk_mingw</span><span class="o">.</span><span class="n">mak</span> <span class="n">WITH_ICONV</span><span class="o">=</span><span class="n">yes</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--list-features</span></code> helps you to know whether your ctags executable +links to libiconv or not. You will find <code class="docutils literal notranslate"><span class="pre">iconv</span></code> in the output if it +links to.</p> +<p>See also <a class="reference internal" href="man/ctags.1.html#option-output-format"><span class="std std-ref">Output Format Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="map-lang-option"> +<h3><a class="toc-backref" href="#id5"><code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> option</a><a class="headerlink" href="#map-lang-option" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> is newly introduced to control the file name +to language mappings (langmap) with finer granularity than +<code class="docutils literal notranslate"><span class="pre">--langmap</span></code> allows.</p> +<p>A langmap entry is defined as a pair; the name of the language and a +file name extension (or pattern).</p> +<p>Here we use “spec” as a generic term representing both file name +extensions and patterns.</p> +<p><code class="docutils literal notranslate"><span class="pre">--langmap</span></code> maps specs to languages exclusively:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --langdef=FOO --langmap=FOO:+.ABC \ + --langdef=BAR --langmap=BAR:+.ABC \ + --list-maps | grep '\*.ABC$' +BAR *.ABC +</pre></div> +</div> +<p>Though language <cite>FOO</cite> is added before <cite>BAR</cite>, only <cite>BAR</cite> is set as a +handler for the spec <cite>*.ABC</cite>.</p> +<p>Universal Ctags enables multiple parsers to be configured for a spec. +The appropriate parser for a given input file can then be chosen by a +variety of internal guessing strategies (see <a class="reference internal" href="man/ctags.1.html#guessing"><span class="std std-ref">Determining file language</span></a>).</p> +<p>Let’s see how specs can be mapped non-exclusively with +<code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --langdef=FOO --map-FOO=+.ABC \ + --langdef=BAR --map-BAR=+.ABC \ + --list-maps | grep '\*.ABC$' +FOO *.ABC +BAR *.ABC +</pre></div> +</div> +<p>Both <cite>FOO</cite> and <cite>BAR</cite> are registered as handlers for the spec <cite>*.ABC</cite>.</p> +<p><code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> can also be used for removing a langmap entry.:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --langdef=FOO --map-FOO=+.ABC \ + --langdef=BAR --map-BAR=+.ABC \ + --map-FOO=-.ABC --list-maps | grep '\*.ABC$' +BAR *.ABC + +$ ctags --langdef=FOO --map-FOO=+.ABC \ + --langdef=BAR --map-BAR=+.ABC \ + --map-BAR=-.ABC --list-maps | grep '\*.ABC$' +FOO *.ABC + +$ ctags --langdef=FOO --map-FOO=+.ABC \ + --langdef=BAR --map-BAR=+.ABC \ + --map-BAR=-.ABC --map-FOO=-.ABC --list-maps | grep '\*.ABC$' +(NOTHING) +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--langmap</span></code> provides a way to manipulate the langmap in a +spec-centric manner and <code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> provides a way to manipulate +the langmap in a parser-centric manner.</p> +<p>See also <a class="reference internal" href="man/ctags.1.html#option-lang-mapping"><span class="std std-ref">Language Selection and Mapping Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="guessing-parser-from-file-contents-g-option"> +<h3><a class="toc-backref" href="#id6">Guessing parser from file contents (<code class="docutils literal notranslate"><span class="pre">-G</span></code> option)</a><a class="headerlink" href="#guessing-parser-from-file-contents-g-option" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/ctags.1.html#guessing"><span class="std std-ref">Determining file language</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="including-line-number-to-pattern-field"> +<h3><a class="toc-backref" href="#id7">Including line number to pattern field</a><a class="headerlink" href="#including-line-number-to-pattern-field" title="Permalink to this headline">¶</a></h3> +<p>Use <code class="docutils literal notranslate"><span class="pre">--excmd=number</span></code>. +See <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="long-names-in-kinds-fields-and-extra-options"> +<h3><a class="toc-backref" href="#id8">Long names in kinds, fields, and extra options</a><a class="headerlink" href="#long-names-in-kinds-fields-and-extra-options" title="Permalink to this headline">¶</a></h3> +<p>A letter is used for specifying a kind, a field, or an extra entry. +In Universal Ctags a name can also be used.</p> +<p>Surround the name with braces (<cite>{</cite> and <cite>}</cite>) in values assigned to the +options, <code class="docutils literal notranslate"><span class="pre">--kind-<LANG>=</span></code>, <code class="docutils literal notranslate"><span class="pre">--fields=</span></code>, or <code class="docutils literal notranslate"><span class="pre">--extras=</span></code>.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --kinds-C<span class="o">=</span>+L-d ... +</pre></div> +</div> +<p>This command line uses the letters, <cite>L</cite> for enabling the label kind +and <cite>d</cite> for disabling the macro kind of C. The command line can be +rewritten with the associated names.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --kinds-C<span class="o">=</span><span class="s1">'+{label}-{macro}'</span> ... +</pre></div> +</div> +<p>The quotes are needed because braces are interpreted as meta +characters by the shell.</p> +<p>The available names can be listed with <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code>, +<code class="docutils literal notranslate"><span class="pre">--list-fields</span></code>, or <code class="docutils literal notranslate"><span class="pre">--list-extras</span></code>.</p> +<p>See also <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="wildcard-in-options"> +<h3><a class="toc-backref" href="#id9">Wildcard in options</a><a class="headerlink" href="#wildcard-in-options" title="Permalink to this headline">¶</a></h3> +<p>For the purpose of gathering as much as information as possible from +source code the “wildcard”(<code class="docutils literal notranslate"><span class="pre">*</span></code>) option value has been introduced.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">--extras=*</span></code></dt><dd><p>Enables all extra tags.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--fields=*</span></code></dt><dd><p>Enables all available fields.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--kinds-<LANG>=*</span></code></dt><dd><p>Enables all available kinds for <code class="docutils literal notranslate"><span class="pre">LANG</span></code>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--kinds-all=*</span></code></dt><dd><p>Enables all available kinds for all available language parsers.</p> +</dd> +</dl> +<p>See also <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="extra-tag-entries-extras"> +<h3><a class="toc-backref" href="#id10">Extra tag entries (<code class="docutils literal notranslate"><span class="pre">--extras</span></code>)</a><a class="headerlink" href="#extra-tag-entries-extras" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">--extra</span></code> option in Exuberant Ctags is renamed to <code class="docutils literal notranslate"><span class="pre">--extras</span></code> (plural) in +Universal Ctags for making consistent with <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> and <code class="docutils literal notranslate"><span class="pre">--fields</span></code>.</p> +<p>These extra tag entries are newly introduced.</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">F</span></code></dt><dd><p>Replacement for --file-scope.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">p</span></code></dt><dd><p>Include pseudo-tags.</p> +</dd> +</dl> +<p>See also <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="kinds-synchronization"> +<h3><a class="toc-backref" href="#id11">Kinds synchronization</a><a class="headerlink" href="#kinds-synchronization" title="Permalink to this headline">¶</a></h3> +<p>See the description about <code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code> and <code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> +option on <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="enabling-disabling-pseudo-tags-pseudo-tags-option"> +<h3><a class="toc-backref" href="#id12">Enabling/disabling pseudo-tags (<code class="docutils literal notranslate"><span class="pre">--pseudo-tags</span></code> option)</a><a class="headerlink" href="#enabling-disabling-pseudo-tags-pseudo-tags-option" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> and +<a class="reference internal" href="man/ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> about the option.</p> +</section> +<section id="put-field-prefix-options"> +<h3><a class="toc-backref" href="#id13"><code class="docutils literal notranslate"><span class="pre">--put-field-prefix</span></code> options</a><a class="headerlink" href="#put-field-prefix-options" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="always-and-never-as-an-argument-for-tag-relative"> +<h3><a class="toc-backref" href="#id14">“always” and “never” as an argument for <code class="docutils literal notranslate"><span class="pre">--tag-relative</span></code></a><a class="headerlink" href="#always-and-never-as-an-argument-for-tag-relative" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">--tag-relative</span></code> option is extend. +See <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="defining-a-parser-specific-extra"> +<h3><a class="toc-backref" href="#id15">Defining a parser specific extra</a><a class="headerlink" href="#defining-a-parser-specific-extra" title="Permalink to this headline">¶</a></h3> +<p>A new <code class="docutils literal notranslate"><span class="pre">--_extradef-<LANG>=name,description</span></code> option allows you to +defining a parser specific extra which turning on and off can be +referred from a regex based parser for <code class="docutils literal notranslate"><span class="pre"><LANG></span></code>.</p> +<p>See <a class="reference internal" href="optlib.html#extras"><span class="std std-ref">Conditional tagging with extras</span></a> for more details.</p> +</section> +<section id="defining-a-cpreprocessor-macro-from-command-line"> +<h3><a class="toc-backref" href="#id16">Defining a CPreProcessor macro from command line</a><a class="headerlink" href="#defining-a-cpreprocessor-macro-from-command-line" title="Permalink to this headline">¶</a></h3> +<p>Newly introduced <code class="docutils literal notranslate"><span class="pre">-D</span></code> option extends the function provided by +<code class="docutils literal notranslate"><span class="pre">-I</span></code> option.</p> +<p><code class="docutils literal notranslate"><span class="pre">-D</span></code> emulates the behaviour of the corresponding gcc option: +it defines a C preprocessor macro.</p> +<p>See <a class="reference internal" href="man/ctags.1.html#option-tags-file-contents"><span class="std std-ref">Tags File Contents Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a> and +<a class="reference internal" href="parser-cxx.html#cxx"><span class="std std-ref">The new C/C++ parser</span></a> for more details.</p> +</section> +<section id="options-for-inspecting-ctags-internals"> +<h3><a class="toc-backref" href="#id17">Options for inspecting ctags internals</a><a class="headerlink" href="#options-for-inspecting-ctags-internals" title="Permalink to this headline">¶</a></h3> +<p>Exuberant Ctags provides a way to inspect its internals via +<code class="docutils literal notranslate"><span class="pre">--list-kinds</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-languages</span></code>, and <code class="docutils literal notranslate"><span class="pre">--list-maps</span></code>.</p> +<p>This idea has been expanded in Universal Ctags with +<code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-map-extensions</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-extras</span></code>, +<code class="docutils literal notranslate"><span class="pre">--list-features</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-map-patterns</span></code>, and +<code class="docutils literal notranslate"><span class="pre">--list-pseudo-tags</span></code> being added.</p> +<p>The original three <code class="docutils literal notranslate"><span class="pre">--list-</span></code> options are not changed for +compatibility reasons, however, the newly introduced options are +recommended for all future use.</p> +<p>By default, interactive use is assumed and ctags tries aligning the +list output in columns for easier reading.</p> +<p>When <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> is given before a <code class="docutils literal notranslate"><span class="pre">--list-</span></code> option, ctags +outputs the list in a format more suitable for processing by scripts. +Tab characters are used as separators between columns. The alignment +of columns is never considered when <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> is given.</p> +<p>Currently only <code class="docutils literal notranslate"><span class="pre">--list-extras</span></code>, <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> and +<code class="docutils literal notranslate"><span class="pre">--list-kinds-full</span></code> support <code class="docutils literal notranslate"><span class="pre">--machinable</span></code> output.</p> +<p>These new <code class="docutils literal notranslate"><span class="pre">--list-</span></code> options also print a column header, a line +representing the name of each column. The header may help users and +scripts to understand and recognize the columns. Ignoring the column +header is easy because it starts with a <cite>#</cite> character.</p> +<p><code class="docutils literal notranslate"><span class="pre">--with-list-header=no</span></code> suppresses output of the column header.</p> +<p>See also <a class="reference internal" href="man/ctags.1.html#option-listing"><span class="std std-ref">Listing Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="notice-messages-and-quiet"> +<h3><a class="toc-backref" href="#id18">Notice messages and <code class="docutils literal notranslate"><span class="pre">--quiet</span></code></a><a class="headerlink" href="#notice-messages-and-quiet" title="Permalink to this headline">¶</a></h3> +<p>There were 3 classes of message in Exuberant Ctags. +In addition to them Universal Ctags introduced a new class of message, <em>notice</em>.</p> +<dl class="simple"> +<dt><em>fatal</em></dt><dd><p>A critical error has occurred and ctags aborts the execution.</p> +</dd> +<dt><em>warning</em></dt><dd><p>An error has occurred but ctags continues the execution.</p> +</dd> +<dt><em>notice</em> (new)</dt><dd><p>It is less important than <em>warning</em> but more important for users than <em>verbose</em>.</p> +</dd> +<dt><em>verbose</em></dt><dd><p>Mainly used for debugging purposes.</p> +</dd> +</dl> +<p>Generally the user can ignore <em>notice</em> class messages and <code class="docutils literal notranslate"><span class="pre">--quiet</span></code> +can be used to disable them.</p> +<p><em>verbose</em> class messages are disabled by default, and <code class="docutils literal notranslate"><span class="pre">--verbose</span></code> or <code class="docutils literal notranslate"><span class="pre">-V</span></code> +can be used to enable them.</p> +<p>See also <a class="reference internal" href="man/ctags.1.html#option-misc"><span class="std std-ref">Miscellaneous Options</span></a> in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="skipping-utf-8-bom"> +<h3><a class="toc-backref" href="#id19">Skipping utf-8 BOM</a><a class="headerlink" href="#skipping-utf-8-bom" title="Permalink to this headline">¶</a></h3> +<p>The three bytes sequence(<code class="docutils literal notranslate"><span class="pre">\xEF\xBB\xBF</span></code>) at the head of an input +file is skipped when parsing.</p> +<p>TODO:</p> +<ul class="simple"> +<li><p>Do the same in guessing and selecting parser stage.</p></li> +<li><p>Refect the BOM detection to encoding option</p></li> +</ul> +</section> +<section id="interactive-mode"> +<h3><a class="toc-backref" href="#id20">Interactive mode</a><a class="headerlink" href="#interactive-mode" title="Permalink to this headline">¶</a></h3> +<p>A new <code class="docutils literal notranslate"><span class="pre">--_interactive</span></code> option launches a JSON based command REPL which +can be used to control ctags generation programmatically.</p> +<p>See <a class="reference internal" href="interactive-mode.html#interactive-mode"><span class="std std-ref">Interactive mode</span></a> for more details.</p> +</section> +</section> +<section id="incompatible-changes-in-command-line"> +<h2><a class="toc-backref" href="#id21">Incompatible changes in command line</a><a class="headerlink" href="#incompatible-changes-in-command-line" title="Permalink to this headline">¶</a></h2> +<section id="d-option"> +<h3><a class="toc-backref" href="#id22"><code class="docutils literal notranslate"><span class="pre">-D</span></code> option</a><a class="headerlink" href="#d-option" title="Permalink to this headline">¶</a></h3> +<p>For a ctags binary that had debugging output enabled in the build config +stage, <code class="docutils literal notranslate"><span class="pre">-D</span></code> was used for specifying the level of debugging +output. It is changed to <code class="docutils literal notranslate"><span class="pre">-d</span></code>. This change is not critical because +<code class="docutils literal notranslate"><span class="pre">-D</span></code> option was not described in ctags.1 man page.</p> +<p>Instead <code class="docutils literal notranslate"><span class="pre">-D</span></code> is used for defining a macro in CPreProcessor parser.</p> +</section> +</section> +<section id="changes-imported-from-exuberant-ctags"> +<h2><a class="toc-backref" href="#id23">Changes imported from Exuberant Ctags</a><a class="headerlink" href="#changes-imported-from-exuberant-ctags" title="Permalink to this headline">¶</a></h2> +<p>See “Exuberant Ctags” in “Tracking other projects” for detailed +information regarding imported changes.</p> +<p>Some changes have also been imported from Fedora and Debian.</p> +</section> +<section id="parser-related-changes"> +<h2><a class="toc-backref" href="#id24">Parser related changes</a><a class="headerlink" href="#parser-related-changes" title="Permalink to this headline">¶</a></h2> +<section id="new-parsers"> +<h3><a class="toc-backref" href="#id25">New parsers</a><a class="headerlink" href="#new-parsers" title="Permalink to this headline">¶</a></h3> +<p>The following parsers have been added:</p> +<ul class="simple"> +<li><p>Abaqus</p></li> +<li><p>Abc</p></li> +<li><p>Ada</p></li> +<li><p>AnsiblePlaybook <em>libyaml</em></p></li> +<li><p>Asciidoc</p></li> +<li><p>Autoconf</p></li> +<li><p>Automake</p></li> +<li><p>AutoIt</p></li> +<li><p>BibTeX</p></li> +<li><p>Clojure</p></li> +<li><p>CMake <em>optlib</em></p></li> +<li><p>CSS</p></li> +<li><p>Ctags option library <em>optlib</em></p></li> +<li><p>CUDA</p></li> +<li><p>D</p></li> +<li><p>DBusIntrospect <em>libxml</em></p></li> +<li><p>Diff</p></li> +<li><p>DTD</p></li> +<li><p>DTS</p></li> +<li><p>Elixir <em>optlib</em></p></li> +<li><p>Elm <em>optlib</em></p></li> +<li><p>Falcon</p></li> +<li><p>FunctionParameters <em>perl based subparser</em></p></li> +<li><p>Gdbinit script <em>optlib</em></p></li> +<li><p>Glade <em>libxml</em></p></li> +<li><p>Go</p></li> +<li><p>Haskell</p></li> +<li><p>Haxe</p></li> +<li><p>iPythonCell <em>optlib</em>, <em>pthon based subparser</em></p></li> +<li><p>Inko <em>optlib</em></p></li> +<li><p>JavaProperties</p></li> +<li><p>JSON</p></li> +<li><p>Julia</p></li> +<li><p>Kconfig <em>optlib</em></p></li> +<li><p>Kotlin <em>peg/packcc</em></p></li> +<li><p>GNU linker script(LdScript)</p></li> +<li><p>Man page <em>optlib</em></p></li> +<li><p>Markdown <em>optlib</em></p></li> +<li><p>Maven2 <em>libxml</em></p></li> +<li><p>MesonBuild (Meson) <em>optlib</em></p></li> +<li><p>MesonOptions <em>optlib+script</em></p></li> +<li><p>Moose <em>perl based subparser</em></p></li> +<li><p>Myrddin</p></li> +<li><p>M4</p></li> +<li><p>NSIS</p></li> +<li><p>ObjectiveC</p></li> +<li><p>Passwd <em>optlib</em></p></li> +<li><p>PuppetManifest <em>optlib</em></p></li> +<li><p>Perl6</p></li> +<li><p>Pod <em>optlib</em></p></li> +<li><p>PowerShell</p></li> +<li><p>PropertyList(plist) <em>libxml</em></p></li> +<li><p>Protobuf</p></li> +<li><p>PythonLoggingConfig</p></li> +<li><p>QemuHX <em>optlib</em></p></li> +<li><p>QtMoc</p></li> +<li><p>R</p></li> +<li><p>R6Class <em>R based subparser</em></p></li> +<li><p>RelaxNG <em>libxml</em></p></li> +<li><p>ReStructuredText</p></li> +<li><p>Robot</p></li> +<li><p>RpmSpec</p></li> +<li><p>RSpec <em>optlib</em></p></li> +<li><p>Rust</p></li> +<li><p>S4Class <em>R based subparser</em></p></li> +<li><p>SCSS <em>optlib</em></p></li> +<li><p>SystemdUnit</p></li> +<li><p>SystemTap <em>optlib</em></p></li> +<li><p>SystemVerilog</p></li> +<li><p>SVG <em>libxml</em></p></li> +<li><p>TclOO (see <a class="reference internal" href="parser-tcl.html#tcl"><span class="std std-ref">The new Tcl parser</span></a>)</p></li> +<li><p>TTCN</p></li> +<li><p>Txt2tags</p></li> +<li><p>TypeScript</p></li> +<li><p>Varlink <em>peg/packcc</em></p></li> +<li><p>WindRes</p></li> +<li><p>XSLT v1.0 <em>libxml</em></p></li> +<li><p>Yacc</p></li> +<li><p>Yaml <em>libyaml</em></p></li> +<li><p>YumRepo</p></li> +<li><p>Zephir</p></li> +</ul> +<p>See <a class="reference internal" href="optlib.html#optlib"><span class="std std-ref">Extending ctags with Regex parser (optlib)</span></a> for details on <em>optlib</em>. +Libxml2 is required to use the parser(s) marked with <em>libxml</em>. +Libyaml is required to use the parser(s) marked with <em>libyaml</em>.</p> +<p>TIPS: you can list newly introduced parsers if you also have +Exuberant Ctags installed with following command line:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>diff -ruN <<span class="o">(</span>universal-ctags --list-languages<span class="o">)</span> <<span class="o">(</span>exuberant-ctags --list-languages<span class="o">)</span> <span class="p">|</span> grep <span class="s1">'^[-+]'</span> +</pre></div> +</div> +</section> +<section id="fully-improved-parsers"> +<h3><a class="toc-backref" href="#id26">Fully improved parsers</a><a class="headerlink" href="#fully-improved-parsers" title="Permalink to this headline">¶</a></h3> +<ul class="simple"> +<li><p>C (see <a class="reference internal" href="parser-cxx.html#cxx"><span class="std std-ref">The new C/C++ parser</span></a>)</p></li> +<li><p>C++ (see <a class="reference internal" href="parser-cxx.html#cxx"><span class="std std-ref">The new C/C++ parser</span></a>)</p></li> +<li><p>Python (see <a class="reference internal" href="parser-python.html#python"><span class="std std-ref">The new Python parser</span></a>)</p></li> +<li><p>HTML (see <a class="reference internal" href="parser-html.html#html"><span class="std std-ref">The new HTML parser</span></a>)</p></li> +<li><p>Tcl (see <a class="reference internal" href="parser-tcl.html#tcl"><span class="std std-ref">The new Tcl parser</span></a>)</p></li> +<li><p>ITcl (see <a class="reference internal" href="parser-tcl.html#tcl"><span class="std std-ref">The new Tcl parser</span></a>)</p></li> +<li><p>Ant (rewritten with <em>libxml</em>)</p></li> +<li><p>PHP</p></li> +<li><p>Verilog/SystemVerilog</p></li> +</ul> +</section> +<section id="automatically-expanding-cpreprocessor-macros-defined-in-the-same-input-file-highly-experimental"> +<h3><a class="toc-backref" href="#id27">Automatically expanding CPreProcessor macros defined in the same input file (HIGHLY EXPERIMENTAL)</a><a class="headerlink" href="#automatically-expanding-cpreprocessor-macros-defined-in-the-same-input-file-highly-experimental" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="parser-cxx.html#cxx"><span class="std std-ref">The new C/C++ parser</span></a> for more details.</p> +</section> +</section> +<section id="readtags"> +<h2><a class="toc-backref" href="#id28">Readtags</a><a class="headerlink" href="#readtags" title="Permalink to this headline">¶</a></h2> +<section id="printing-line-numbers-with-n"> +<h3><a class="toc-backref" href="#id29">Printing line numbers with <code class="docutils literal notranslate"><span class="pre">-n</span></code></a><a class="headerlink" href="#printing-line-numbers-with-n" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a>.</p> +</section> +<section id="filtering-in-readtags-command"> +<h3><a class="toc-backref" href="#id30">Filtering in readtags command</a><a class="headerlink" href="#filtering-in-readtags-command" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a>.</p> +<p>readtags has ability to find tag entries by name.</p> +<p>The concept of filtering is inspired by the display filter of +Wireshark. You can specify more complex conditions for searching.</p> +<p>All symbols starting with <cite>$</cite> represent a field of a tag entry which +is being tested against the S expression. Most will evaluate as a +string or <cite>#f</cite>. It evaluates to <cite>#f</cite> when the field doesn’t exist.</p> +<p>The <cite>scope</cite> field holds structured data: the kind and name of the +upper scope combined with <cite>:</cite>. The hold the value is stored to +<cite>$scope</cite>. The kind part is mapped to <cite>$scope-kind</cite>, and the name part +to <cite>$scope-name</cite>.</p> +<p><cite>$scope-kind</cite> and <cite>$scope-name</cite> can only be used if the input tags +file is generated by ctags with <code class="docutils literal notranslate"><span class="pre">--fields=+Z</span></code>.</p> +<p><cite>$</cite> is a generic accessor for accessing extension fields. +<cite>$</cite> takes one argument: the name of an extension field. +It returns the value of the field as a string if a value +is given, or <cite>#f</cite>.</p> +<p>Following examples shows how <cite>prefix?</cite>, <cite>suffix?</cite>, and +<cite>substr?</cite> work.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>(prefix? "TARGET" "TA") +=> #t + +(prefix? "TARGET" "RGET") +=> #f + +(prefix? "TARGET" "RGE") +=> #f + +(suffix? "TARGET" "TA") +=> #f + +(suffix? "TARGET" "RGET") +=> #t + +(suffix? "TARGET" "RGE") +=> #f + +(substr? "TARGET" "TA") +=> #t + +(suffix? "TARGET" "RGET") +=> #t + +(suffix? "TARGET" "RGE") +=> #t + +(and (suffix? "TARGET" "TARGET") + (prefix? "TARGET" "TARGET") + (substr? "TARGET" "TARGET") +=> #t +</pre></div> +</div> +</section> +<section id="sorting-in-readtags-command"> +<h3><a class="toc-backref" href="#id31">Sorting in readtags command</a><a class="headerlink" href="#sorting-in-readtags-command" title="Permalink to this headline">¶</a></h3> +<p>readtags can sort the tag entries before printing. +You can specify the way to sort with -S option. Like <code class="docutils literal notranslate"><span class="pre">-Q</span></code> option, <code class="docutils literal notranslate"><span class="pre">-S</span></code> +also takes an S expression.</p> +<p>See <a class="reference internal" href="man/readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a>.</p> +</section> +<section id="listing-pseudo-tags-with-d"> +<h3><a class="toc-backref" href="#id32">Listing pseudo tags with <code class="docutils literal notranslate"><span class="pre">-D</span></code></a><a class="headerlink" href="#listing-pseudo-tags-with-d" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference internal" href="man/readtags.1.html#readtags-1"><span class="std std-ref">readtags(1)</span></a>.</p> +</section> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Other changes</a><ul> +<li><a class="reference internal" href="#new-and-extended-options">New and extended options</a><ul> +<li><a class="reference internal" href="#exclude-exception-an-option-complementing-exclude"><code class="docutils literal notranslate"><span class="pre">--exclude-exception</span></code>, an option complementing <code class="docutils literal notranslate"><span class="pre">--exclude</span></code></a></li> +<li><a class="reference internal" href="#maxdepth-option"><code class="docutils literal notranslate"><span class="pre">--maxdepth</span></code> option</a></li> +<li><a class="reference internal" href="#input-encoding-encoding-and-output-encoding-encoding"><code class="docutils literal notranslate"><span class="pre">--input-encoding=ENCODING</span></code> and <code class="docutils literal notranslate"><span class="pre">--output-encoding=ENCODING</span></code></a></li> +<li><a class="reference internal" href="#map-lang-option"><code class="docutils literal notranslate"><span class="pre">--map-<LANG></span></code> option</a></li> +<li><a class="reference internal" href="#guessing-parser-from-file-contents-g-option">Guessing parser from file contents (<code class="docutils literal notranslate"><span class="pre">-G</span></code> option)</a></li> +<li><a class="reference internal" href="#including-line-number-to-pattern-field">Including line number to pattern field</a></li> +<li><a class="reference internal" href="#long-names-in-kinds-fields-and-extra-options">Long names in kinds, fields, and extra options</a></li> +<li><a class="reference internal" href="#wildcard-in-options">Wildcard in options</a></li> +<li><a class="reference internal" href="#extra-tag-entries-extras">Extra tag entries (<code class="docutils literal notranslate"><span class="pre">--extras</span></code>)</a></li> +<li><a class="reference internal" href="#kinds-synchronization">Kinds synchronization</a></li> +<li><a class="reference internal" href="#enabling-disabling-pseudo-tags-pseudo-tags-option">Enabling/disabling pseudo-tags (<code class="docutils literal notranslate"><span class="pre">--pseudo-tags</span></code> option)</a></li> +<li><a class="reference internal" href="#put-field-prefix-options"><code class="docutils literal notranslate"><span class="pre">--put-field-prefix</span></code> options</a></li> +<li><a class="reference internal" href="#always-and-never-as-an-argument-for-tag-relative">“always” and “never” as an argument for <code class="docutils literal notranslate"><span class="pre">--tag-relative</span></code></a></li> +<li><a class="reference internal" href="#defining-a-parser-specific-extra">Defining a parser specific extra</a></li> +<li><a class="reference internal" href="#defining-a-cpreprocessor-macro-from-command-line">Defining a CPreProcessor macro from command line</a></li> +<li><a class="reference internal" href="#options-for-inspecting-ctags-internals">Options for inspecting ctags internals</a></li> +<li><a class="reference internal" href="#notice-messages-and-quiet">Notice messages and <code class="docutils literal notranslate"><span class="pre">--quiet</span></code></a></li> +<li><a class="reference internal" href="#skipping-utf-8-bom">Skipping utf-8 BOM</a></li> +<li><a class="reference internal" href="#interactive-mode">Interactive mode</a></li> +</ul> +</li> +<li><a class="reference internal" href="#incompatible-changes-in-command-line">Incompatible changes in command line</a><ul> +<li><a class="reference internal" href="#d-option"><code class="docutils literal notranslate"><span class="pre">-D</span></code> option</a></li> +</ul> +</li> +<li><a class="reference internal" href="#changes-imported-from-exuberant-ctags">Changes imported from Exuberant Ctags</a></li> +<li><a class="reference internal" href="#parser-related-changes">Parser related changes</a><ul> +<li><a class="reference internal" href="#new-parsers">New parsers</a></li> +<li><a class="reference internal" href="#fully-improved-parsers">Fully improved parsers</a></li> +<li><a class="reference internal" href="#automatically-expanding-cpreprocessor-macros-defined-in-the-same-input-file-highly-experimental">Automatically expanding CPreProcessor macros defined in the same input file (HIGHLY EXPERIMENTAL)</a></li> +</ul> +</li> +<li><a class="reference internal" href="#readtags">Readtags</a><ul> +<li><a class="reference internal" href="#printing-line-numbers-with-n">Printing line numbers with <code class="docutils literal notranslate"><span class="pre">-n</span></code></a></li> +<li><a class="reference internal" href="#filtering-in-readtags-command">Filtering in readtags command</a></li> +<li><a class="reference internal" href="#sorting-in-readtags-command">Sorting in readtags command</a></li> +<li><a class="reference internal" href="#listing-pseudo-tags-with-d">Listing pseudo tags with <code class="docutils literal notranslate"><span class="pre">-D</span></code></a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="interactive-mode.html" + title="previous chapter">Interactive mode</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="optlib.html" + title="next chapter">Extending ctags with Regex parser (<em>optlib</em>)</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="optlib.html" title="Extending ctags with Regex parser (optlib)" + >next</a> |</li> + <li class="right" > + <a href="interactive-mode.html" title="Interactive mode" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Other changes</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/objects.inv b/ctags/docs/objects.inv Binary files differnew file mode 100644 index 0000000..8afde2b --- /dev/null +++ b/ctags/docs/objects.inv diff --git a/ctags/docs/option-file.html b/ctags/docs/option-file.html new file mode 100644 index 0000000..412d8d5 --- /dev/null +++ b/ctags/docs/option-file.html @@ -0,0 +1,284 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Option files — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Output formats" href="output-format.html" /> + <link rel="prev" title="XSLT parser" href="parser-xslt.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="output-format.html" title="Output formats" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-xslt.html" title="XSLT parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Option files</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="option-files"> +<span id="id1"></span><h1>Option files<a class="headerlink" href="#option-files" title="Permalink to this headline">¶</a></h1> +<p>An “option file” is a file in which command line options are written line +by line. <code class="docutils literal notranslate"><span class="pre">ctags</span></code> loads it and runs as if the options in the file were +passed through command line.</p> +<p>The following file is an example of an option file:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="c1"># Exclude directories that don't contain real code</span> +--exclude=Units +<span class="w"> </span><span class="c1"># indentation is ignored</span> +<span class="w"> </span>--exclude=tinst-root +--exclude=Tmain +</pre></div> +</div> +<p>The character <cite>#</cite> can be used as a start marker of a line comment. +Whitespaces at the start of lines are ignored during loading.</p> +<p>And it works exactly as if we had called:</p> +<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>ctags --exclude<span class="o">=</span>Units --exclude<span class="o">=</span>tinst-root --exclude<span class="o">=</span>Tmain +</pre></div> +</div> +<section id="order-of-loading-option-files"> +<h2>Order of loading option files<a class="headerlink" href="#order-of-loading-option-files" title="Permalink to this headline">¶</a></h2> +<p>Option files are loaded by <code class="docutils literal notranslate"><span class="pre">ctags</span></code> automatically at start-up time.</p> +<p>Which files are loaded at start-up time are very different from Exuberant Ctags. +See <a class="reference internal" href="#option-file-difference"><span class="std std-ref">Difference from Exuberant Ctags</span></a> for the differences and their intentions.</p> +<p>At start-up time, <code class="docutils literal notranslate"><span class="pre">ctags</span></code> loads files having <code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> as a +file extension under the following statically defined directories:</p> +<ol class="arabic simple"> +<li><p><code class="file docutils literal notranslate"><span class="pre">$XDG_CONFIG_HOME/ctags/</span></code>, or <code class="file docutils literal notranslate"><span class="pre">$HOME/.config/ctags/</span></code> if <code class="file docutils literal notranslate"><span class="pre">$XDG_CONFIG_HOME</span></code> is not defined (on other than Windows)</p></li> +<li><p><code class="file docutils literal notranslate"><span class="pre">$HOME/.ctags.d/</span></code></p></li> +<li><p><code class="file docutils literal notranslate"><span class="pre">$HOMEDRIVE$HOMEPATH/ctags.d/</span></code> (on Windows)</p></li> +<li><p><code class="file docutils literal notranslate"><span class="pre">./.ctags.d/</span></code></p></li> +<li><p><code class="file docutils literal notranslate"><span class="pre">./ctags.d/</span></code></p></li> +</ol> +<p><code class="docutils literal notranslate"><span class="pre">ctags</span></code> visits the directories in the order listed above for preloading files. +<code class="docutils literal notranslate"><span class="pre">ctags</span></code> loads files having <code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> as file extension in alphabetical +order (<code class="docutils literal notranslate"><span class="pre">strcmp(3)</span></code> is used for comparing, so for example +<code class="file docutils literal notranslate"><span class="pre">.ctags.d/ZZZ.ctags</span></code> will be loaded <em>before</em> <code class="file docutils literal notranslate"><span class="pre">.ctags.d/aaa.ctags</span></code> in an ordinary locale).</p> +<p>If a option file includes <code class="docutils literal notranslate"><span class="pre">--options=PATHNAME</span></code> option, specified files are +loaded immediately as described in the next section. <code class="docutils literal notranslate"><span class="pre">ctags</span></code> load a option +file only once if it is specified multiple times.</p> +<p>Finally if <code class="docutils literal notranslate"><span class="pre">--options=PATHNAME</span></code> option is specified on <code class="docutils literal notranslate"><span class="pre">ctags</span></code> command line, +option files specified are load.</p> +</section> +<section id="options-pathname-option"> +<h2><code class="docutils literal notranslate"><span class="pre">--options=PATHNAME</span></code> option<a class="headerlink" href="#options-pathname-option" title="Permalink to this headline">¶</a></h2> +<p>Exuberant Ctags also has the <code class="docutils literal notranslate"><span class="pre">--options</span></code> option, but you can only specify a +single file to load. Universal Ctags extends the option in two aspects:</p> +<ul class="simple"> +<li><p>You can specify a directory, to load all the files in that directory.</p></li> +<li><p>You can specify a PATH list to look in. See next section for details.</p></li> +</ul> +<section id="specifying-a-directory"> +<h3>Specifying a directory<a class="headerlink" href="#specifying-a-directory" title="Permalink to this headline">¶</a></h3> +<p>If you specify a directory instead of a file as the argument for the +<code class="docutils literal notranslate"><span class="pre">--options=PATHNAME</span></code>, <code class="docutils literal notranslate"><span class="pre">ctags</span></code> will load all files having a +<code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> extension under said directory in alphabetical order.</p> +</section> +<section id="specifying-an-optlib-path-list"> +<h3>Specifying an optlib PATH list<a class="headerlink" href="#specifying-an-optlib-path-list" title="Permalink to this headline">¶</a></h3> +<p>Much like a command line shell, <code class="docutils literal notranslate"><span class="pre">ctags</span></code> has an <em>optlib PATH list</em> in which it +can look for a file (or directory) to load.</p> +<p>When loading a file (or directory) specified with <code class="docutils literal notranslate"><span class="pre">--options=PATHNAME</span></code>, +ctags first checks if <code class="docutils literal notranslate"><span class="pre">PATHNAME</span></code> is an absolute path or a relative path. +An absolute path starts with ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’ or ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’. +If <code class="docutils literal notranslate"><span class="pre">PATHNAME</span></code> is an absolute path, ctags tries to load it immediately.</p> +<p>If, on the contrary, is a relative path, <code class="docutils literal notranslate"><span class="pre">ctags</span></code> does two things: First, +looks for the file (or directory) in <em>optlib PATH list</em> and tries to load it.</p> +<p>If the file doesn’t exist in the PATH list, <code class="docutils literal notranslate"><span class="pre">ctags</span></code> treats <code class="docutils literal notranslate"><span class="pre">PATHNAME</span></code> as a +path relative to the working directory and loads the file.</p> +<p>By default, <em>optlib PATH list</em> is empty. To set or add a directory +path to the list, use <code class="docutils literal notranslate"><span class="pre">--optlib-dir=PATH</span></code>.</p> +<p>For setting (adding one after clearing):</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">optlib</span><span class="o">-</span><span class="nb">dir</span><span class="o">=</span><span class="n">PATH</span> +</pre></div> +</div> +<p>For adding on the beginning of the PATH list:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">optlib</span><span class="o">-</span><span class="nb">dir</span><span class="o">=+</span><span class="n">PATH</span> +</pre></div> +</div> +</section> +</section> +<section id="tips-for-writing-an-option-file"> +<h2>Tips for writing an option file<a class="headerlink" href="#tips-for-writing-an-option-file" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>Use <code class="docutils literal notranslate"><span class="pre">--quiet</span> <span class="pre">--options=NONE</span></code> to disable preloading.</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">--_echo=MSG</span></code> and <code class="docutils literal notranslate"><span class="pre">--_force-quit=[NUM]</span></code> options are introduced for +debugging the process of loading option files. See “OPTIONS” +section of <a class="reference internal" href="man/ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p></li> +<li><p>Universal Ctags has an <code class="docutils literal notranslate"><span class="pre">optlib2c</span></code> script that translates an option file +into C source code. Your optlib parser can thus easily become a built-in parser. +See <a class="reference internal" href="optlib.html#optlib2c"><span class="std std-ref">Translating an option file into C source code (optlib2c)</span></a> for details.</p></li> +</ul> +</section> +<section id="difference-from-exuberant-ctags"> +<span id="option-file-difference"></span><h2>Difference from Exuberant Ctags<a class="headerlink" href="#difference-from-exuberant-ctags" title="Permalink to this headline">¶</a></h2> +<p>Quoted from man page of Exuberant Ctags:</p> +<blockquote> +<div><dl class="simple"> +<dt>FILES</dt><dd><ul class="simple"> +<li><p>/ctags.cnf (on MSDOS, MSWindows only)</p></li> +<li><p>/etc/ctags.conf</p></li> +<li><p>/usr/local/etc/ctags.conf</p></li> +<li><p>$HOME/.ctags</p></li> +<li><p>$HOME/ctags.cnf (on MSDOS, MSWindows only)</p></li> +<li><p>.ctags</p></li> +<li><p>ctags.cnf (on MSDOS, MSWindows only)</p></li> +</ul> +</dd> +</dl> +<p>If any of these configuration files exist, each will +be expected to contain a set of default options +which are read in the order listed when ctags +starts, but before the CTAGS environment variable is +read or any command line options are read. This +makes it possible to set up site-wide, personal or +project-level defaults. It is possible to compile +ctags to read an additional configuration file +before any of those shown above, which will be +indicated if the output produced by the --version +option lists the “custom-conf” feature. Options +appearing in the CTAGS environment variable or on +the command line will override options specified in +these files. Only options will be read from these +files. Note that the option files are read in +line-oriented mode in which spaces are significant +(since shell quoting is not possible). Each line of +the file is read as one command line parameter (as +if it were quoted with single quotes). Therefore, +use new lines to indicate separate command-line +arguments.</p> +</div></blockquote> +<p>What follows explains the differences and their intentions…</p> +<section id="directory-oriented-configuration-management"> +<h3>Directory oriented configuration management<a class="headerlink" href="#directory-oriented-configuration-management" title="Permalink to this headline">¶</a></h3> +<p>Exuberant Ctags provides a way to customize ctags with options like +<code class="docutils literal notranslate"><span class="pre">--langdef=<LANG></span></code> and <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>. These options are +powerful and make ctags popular for programmers.</p> +<p>Universal Ctags extends this idea; we have added new options for +defining a parser, and have extended existing options. Defining +a new parser with the options is more than “customizing” in +Universal Ctags.</p> +<p>To make easier the maintenance a parser defined using the options, you can put +each language parser in a different options file. Universal Ctags doesn’t +preload a single file. Instead, Universal Ctags loads all the files having the +<code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> extension under the previously specified directories. If you +have multiple parser definitions, put them in different files.</p> +</section> +<section id="avoiding-option-incompatibility-issues"> +<h3>Avoiding option incompatibility issues<a class="headerlink" href="#avoiding-option-incompatibility-issues" title="Permalink to this headline">¶</a></h3> +<p>The Universal Ctags options are different from those of Exuberant Ctags, +therefore Universal Ctags doesn’t load any of the files Exuberant Ctags loads at +start-up. Otherwise there would be incompatibility issues if Exuberant Ctags +loaded an option file that used a newly introduced option in Universal Ctags, +and vice versa.</p> +</section> +<section id="no-system-wide-configuration"> +<h3>No system wide configuration<a class="headerlink" href="#no-system-wide-configuration" title="Permalink to this headline">¶</a></h3> +<p>To make the preload path list short and because it was rarely ever used, +Universal Ctags does not load any option files for system wide configuration. +(i.e., no <code class="file docutils literal notranslate"><span class="pre">/etc/ctags.d</span></code>)</p> +</section> +<section id="using-ctags-for-the-file-extension"> +<h3>Using <code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> for the file extension<a class="headerlink" href="#using-ctags-for-the-file-extension" title="Permalink to this headline">¶</a></h3> +<p>Extensions <code class="file docutils literal notranslate"><span class="pre">.cnf</span></code> and <code class="file docutils literal notranslate"><span class="pre">.conf</span></code> are obsolete. +Use the unified extension <code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> only.</p> +</section> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Option files</a><ul> +<li><a class="reference internal" href="#order-of-loading-option-files">Order of loading option files</a></li> +<li><a class="reference internal" href="#options-pathname-option"><code class="docutils literal notranslate"><span class="pre">--options=PATHNAME</span></code> option</a><ul> +<li><a class="reference internal" href="#specifying-a-directory">Specifying a directory</a></li> +<li><a class="reference internal" href="#specifying-an-optlib-path-list">Specifying an optlib PATH list</a></li> +</ul> +</li> +<li><a class="reference internal" href="#tips-for-writing-an-option-file">Tips for writing an option file</a></li> +<li><a class="reference internal" href="#difference-from-exuberant-ctags">Difference from Exuberant Ctags</a><ul> +<li><a class="reference internal" href="#directory-oriented-configuration-management">Directory oriented configuration management</a></li> +<li><a class="reference internal" href="#avoiding-option-incompatibility-issues">Avoiding option incompatibility issues</a></li> +<li><a class="reference internal" href="#no-system-wide-configuration">No system wide configuration</a></li> +<li><a class="reference internal" href="#using-ctags-for-the-file-extension">Using <code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> for the file extension</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="parser-xslt.html" + title="previous chapter">XSLT parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="output-format.html" + title="next chapter">Output formats</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="output-format.html" title="Output formats" + >next</a> |</li> + <li class="right" > + <a href="parser-xslt.html" title="XSLT parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Option files</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/optlib.html b/ctags/docs/optlib.html new file mode 100644 index 0000000..d0b29c7 --- /dev/null +++ b/ctags/docs/optlib.html @@ -0,0 +1,1610 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Extending ctags with Regex parser (optlib) — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Optscript, a programming language for extending optlib parsers" href="optscript.html" /> + <link rel="prev" title="Other changes" href="news.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="optscript.html" title="Optscript, a programming language for extending optlib parsers" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="news.html" title="Other changes" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Extending ctags with Regex parser (<em>optlib</em>)</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="extending-ctags-with-regex-parser-optlib"> +<span id="optlib"></span><h1>Extending ctags with Regex parser (<em>optlib</em>)<a class="headerlink" href="#extending-ctags-with-regex-parser-optlib" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#regular-expression-regex-engine" id="id4">Regular expression (regex) engine</a></p></li> +<li><p><a class="reference internal" href="#regex-option-argument-flags" id="id5">Regex option argument flags</a></p> +<ul> +<li><p><a class="reference internal" href="#regex-control-flags" id="id6">Regex control flags</a></p></li> +<li><p><a class="reference internal" href="#exclusive-flag-in-regex" id="id7">Exclusive flag in regex</a></p></li> +<li><p><a class="reference internal" href="#experimental-flags" id="id8">Experimental flags</a></p> +<ul> +<li><p><a class="reference internal" href="#conditional-tagging-with-extras" id="id9">Conditional tagging with extras</a></p></li> +<li><p><a class="reference internal" href="#adding-custom-fields-to-the-tag-output" id="id10">Adding custom fields to the tag output</a></p></li> +<li><p><a class="reference internal" href="#capturing-reference-tags" id="id11">Capturing reference tags</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#scope-tracking-in-a-regex-parser" id="id12">Scope tracking in a regex parser</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#overriding-the-letter-for-file-kind" id="id13">Overriding the letter for file kind</a></p></li> +<li><p><a class="reference internal" href="#generating-fully-qualified-tags-automatically-from-scope-information" id="id14">Generating fully qualified tags automatically from scope information</a></p> +<ul> +<li><p><a class="reference internal" href="#customizing-scope-separators" id="id15">Customizing scope separators</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#multi-line-pattern-match" id="id16">Multi-line pattern match</a></p> +<ul> +<li><p><a class="reference internal" href="#multiline-pattern-flags" id="id17">Multiline pattern flags</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#advanced-pattern-matching-with-multiple-regex-tables" id="id18">Advanced pattern matching with multiple regex tables</a></p> +<ul> +<li><p><a class="reference internal" href="#declaring-a-new-regex-table" id="id19">Declaring a new regex table</a></p></li> +<li><p><a class="reference internal" href="#adding-a-regex-to-a-regex-table" id="id20">Adding a regex to a regex table</a></p></li> +<li><p><a class="reference internal" href="#skipping-block-comments" id="id21">Skipping block comments</a></p></li> +<li><p><a class="reference internal" href="#capturing-variables-in-a-sequence" id="id22">Capturing variables in a sequence</a></p></li> +<li><p><a class="reference internal" href="#running-our-example" id="id23">Running our example</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#scheduling-a-guest-parser-with-guest-regex-flag" id="id24">Scheduling a guest parser with <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag</a></p> +<ul> +<li><p><a class="reference internal" href="#the-parser-field-of-guest-regex-flag" id="id25">The <em><PARSER></em> field of <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag</a></p></li> +<li><p><a class="reference internal" href="#the-start-and-end-fields-of-guest-regex-flag" id="id26">The <em><START></em> and <em><END></em> fields of <cite>_guest</cite> regex flag</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#defining-a-subparser" id="id27">Defining a subparser</a></p> +<ul> +<li><p><a class="reference internal" href="#basic" id="id28">Basic</a></p></li> +<li><p><a class="reference internal" href="#direction-flags" id="id29">Direction flags</a></p> +<ul> +<li><p><a class="reference internal" href="#shared-combination" id="id30">shared combination</a></p></li> +<li><p><a class="reference internal" href="#dedicated-combination" id="id31">dedicated combination</a></p></li> +<li><p><a class="reference internal" href="#bidirectional-combination" id="id32">bidirectional combination</a></p></li> +</ul> +</li> +</ul> +</li> +<li><p><a class="reference internal" href="#translating-an-option-file-into-c-source-code-optlib2c" id="id33">Translating an option file into C source code (optlib2c)</a></p></li> +</ul> +</div> +<p>Exuberant Ctags allows a user to add a new parser to ctags with <code class="docutils literal notranslate"><span class="pre">--langdef=<LANG></span></code> +and <code class="docutils literal notranslate"><span class="pre">--regex-<LANG>=...</span></code> options. +Universal Ctags follows and extends the design of Exuberant Ctags in more +powerful ways and call the feature as <em>optlib parser</em>, which is described in in +<a class="reference internal" href="man/ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> and the following sections.</p> +<p><a class="reference internal" href="man/ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a> is the primary document of the optlib +parser feature. The following sections provide additional information and more +advanced features. Note that some of the features are experimental, and will be +marked as such in the documentation.</p> +<p>Lots of optlib parsers are included in Universal Ctags, +<a class="reference external" href="https://github.com/universal-ctags/ctags/tree/master/optlib">optlib/*.ctags</a>. +They will be good examples when you develop your own parsers.</p> +<p>A optlib parser can be translated into C source code. Your optlib parser can +thus easily become a built-in parser. See “<a class="reference internal" href="#optlib2c"><span class="std std-ref">Translating an option file into C source code (optlib2c)</span></a>” for details.</p> +<section id="regular-expression-regex-engine"> +<h2><a class="toc-backref" href="#id4">Regular expression (regex) engine</a><a class="headerlink" href="#regular-expression-regex-engine" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags currently uses the same regex engine as Exuberant Ctags: +the POSIX.2 regex engine in GNU glibc-2.10.1. By default it uses the Extended +Regular Expressions (ERE) syntax, as used by most engines today; however it does +<em>not</em> support many of the “modern” extensions such as lazy captures, +non-capturing grouping, atomic grouping, possessive quantifiers, look-ahead/behind, +etc. It is also notoriously slow when backtracking, and has some known “quirks” +with respect to escaping special characters in bracket expressions.</p> +<p>For example, a pattern of <code class="docutils literal notranslate"><span class="pre">[^\]]+</span></code> is invalid in POSIX.2, because the ‘<code class="docutils literal notranslate"><span class="pre">]</span></code>’ is +<em>not</em> special inside a bracket expression, and thus should <strong>not</strong> be escaped. +Most regex engines ignore this subtle detail in POSIX.2, and instead allow +escaping it with ‘<code class="docutils literal notranslate"><span class="pre">\]</span></code>’ inside the bracket expression and treat it as the +literal character ‘<code class="docutils literal notranslate"><span class="pre">]</span></code>’. GNU glibc, however, does not generate an error but +instead considers it undefined behavior, and in fact it will match very odd +things. Instead you <strong>must</strong> use the more unintuitive <code class="docutils literal notranslate"><span class="pre">[^]]+</span></code> syntax. The same +is technically true of other special characters inside a bracket expression, +such as <code class="docutils literal notranslate"><span class="pre">[^\)]+</span></code>, which should instead be <code class="docutils literal notranslate"><span class="pre">[^)]+</span></code>. The <code class="docutils literal notranslate"><span class="pre">[^\)]+</span></code> will +appear to work usually, but only because what it is really doing is matching any +character but ‘<code class="docutils literal notranslate"><span class="pre">\</span></code>’ <em>or</em> ‘<code class="docutils literal notranslate"><span class="pre">)</span></code>’. The only exceptions for using ‘<code class="docutils literal notranslate"><span class="pre">\</span></code>’ inside a +bracket expression are for ‘<code class="docutils literal notranslate"><span class="pre">\t</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">\n</span></code>’, which ctags converts to their +single literal character control codes before passing the pattern to glibc.</p> +<p>Another detail to keep in mind is how the regex engine treats newlines. +Universal Ctags compiles the regular expressions in the <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> and +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> options with <code class="docutils literal notranslate"><span class="pre">REG_NEWLINE</span></code> set. What that means is documented +in the +<a class="reference external" href="https://pubs.opengroup.org/onlinepubs/009695399/functions/regcomp.html">POSIX spec</a>. +One obvious effect is that the regex special dot any-character ‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’ does not match +newline characters, the ‘<code class="docutils literal notranslate"><span class="pre">^</span></code>’ anchor <em>does</em> match right after a newline, and +the ‘<code class="docutils literal notranslate"><span class="pre">$</span></code>’ anchor matches right before a newline. A more subtle issue is this text from the +chapter “<a class="reference external" href="https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html">Regular Expressions</a>”; +“the use of literal <newline>s or any escape sequence equivalent produces undefined +results”. What that means is using a regex pattern with <code class="docutils literal notranslate"><span class="pre">[^\n]+</span></code> is invalid, +and indeed in glibc produces very odd results. <strong>Never use</strong> ‘<code class="docutils literal notranslate"><span class="pre">\n</span></code>’ in patterns +for <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>, and <strong>never use them</strong> in non-matching bracket expressions +for <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> patterns. For the experimental <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> +you can safely use ‘<code class="docutils literal notranslate"><span class="pre">\n</span></code>’ because that regex is not compiled with <code class="docutils literal notranslate"><span class="pre">REG_NEWLINE</span></code>.</p> +<p>You should always test your regex patterns against test files with strings that +do and do not match. Pay particular emphasis to when it should <em>not</em> match, and +how <em>much</em> it matches when it should. A common error is forgetting that a +POSIX.2 ERE engine is always <em>greedy</em>; the ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’ quantifiers match +as much as possible, before backtracking from the end of their match.</p> +<p>For example this pattern:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">foo</span><span class="o">.*</span><span class="n">bar</span> +</pre></div> +</div> +<p>Will match this entire string, not just the first part:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">foobar</span><span class="p">,</span> <span class="n">bar</span><span class="p">,</span> <span class="ow">and</span> <span class="n">even</span> <span class="n">more</span> <span class="n">bar</span> +</pre></div> +</div> +</section> +<section id="regex-option-argument-flags"> +<h2><a class="toc-backref" href="#id5">Regex option argument flags</a><a class="headerlink" href="#regex-option-argument-flags" title="Permalink to this headline">¶</a></h2> +<p>Many regex-based options described in this document support additional arguments +in the form of long flags. Long flags are specified with surrounding ‘<code class="docutils literal notranslate"><span class="pre">{</span></code>’ and +‘<code class="docutils literal notranslate"><span class="pre">}</span></code>’.</p> +<p>The general format and placement is as follows:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>--regex-<LANG>=<PATTERN>/<NAME>/[<KIND>/]LONGFLAGS +</pre></div> +</div> +<p>Some examples:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--regex-</span><span class="nn">Pod</span><span class="p">=</span>/^=head1[ \t]+(.+)/\1/c/ +<span class="kd">--regex-</span><span class="nn">Foo</span><span class="p">=</span>/set=[^;]+/\1/v/{icase} +<span class="kd">--regex-</span><span class="nn">Man</span><span class="p">=</span>/^\.TH[[:space:]]{1,}"([^"]{1,})".*/\1/t/{exclusive}{icase}{scope=push} +<span class="kd">--regex-</span><span class="nn">Gdbinit</span><span class="p">=</span>/^#//{exclusive} +</pre></div> +</div> +<p>Note that the last example only has two ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’ forward-slashes following +the regex pattern, as a shortened form when no kind-spec exists.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> option also follows the above format. The +experimental <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> option follows a slightly +modified version as well.</p> +<section id="regex-control-flags"> +<h3><a class="toc-backref" href="#id6">Regex control flags</a><a class="headerlink" href="#regex-control-flags" title="Permalink to this headline">¶</a></h3> +<p>The regex matching can be controlled by adding flags to the <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>, +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code>, and experimental <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> options. +This is done by either using the single character short flags <code class="docutils literal notranslate"><span class="pre">b</span></code>, <code class="docutils literal notranslate"><span class="pre">e</span></code> and +<code class="docutils literal notranslate"><span class="pre">i</span></code> flags as explained in the <em>ctags.1</em> man page, or by using long flags +described earlier. The long flags require more typing but are much more +readable.</p> +<p>The mapping between the older short flag names and long flag names is:</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 15%" /> +<col style="width: 15%" /> +<col style="width: 70%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>short flag</p></th> +<th class="head"><p>long flag</p></th> +<th class="head"><p>description</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p>b</p></td> +<td><p>basic</p></td> +<td><p>Posix basic regular expression syntax.</p></td> +</tr> +<tr class="row-odd"><td><p>e</p></td> +<td><p>extend</p></td> +<td><p>Posix extended regular expression syntax (default).</p></td> +</tr> +<tr class="row-even"><td><p>i</p></td> +<td><p>icase</p></td> +<td><p>Case-insensitive matching.</p></td> +</tr> +</tbody> +</table> +<p>So the following <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> expression:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--kinddef-</span><span class="nn">m4</span><span class="p">=</span><span class="ni">d</span><span class="p">,</span><span class="ni">definition</span><span class="p">,</span><span class="sd">definitions</span> +<span class="kd">--regex-</span><span class="nn">m4</span><span class="p">=</span>/^m4_define\(\[([^]$\(]+).+$/\1/d/x +</pre></div> +</div> +<p>is the same as:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--kinddef-</span><span class="nn">m4</span><span class="p">=</span><span class="ni">d</span><span class="p">,</span><span class="ni">definition</span><span class="p">,</span><span class="sd">definitions</span> +<span class="kd">--regex-</span><span class="nn">m4</span><span class="p">=</span>/^m4_define\(\[([^]$\(]+).+$/\1/d/{extend} +</pre></div> +</div> +<p>The characters ‘<code class="docutils literal notranslate"><span class="pre">{</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">}</span></code>’ may not be suitable for command line +use, but long flags are mostly intended for option files.</p> +</section> +<section id="exclusive-flag-in-regex"> +<h3><a class="toc-backref" href="#id7">Exclusive flag in regex</a><a class="headerlink" href="#exclusive-flag-in-regex" title="Permalink to this headline">¶</a></h3> +<p>By default, lines read from the input files will be matched against all the +regular expressions defined with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>. Each successfully matched +regular expression will emit a tag.</p> +<p>In some cases another policy, exclusive-matching, is preferable to the +all-matching policy. Exclusive-matching means the rest of regular +expressions are not tried if one of regular expressions is matched +successfully, for that input line.</p> +<p>For specifying exclusive-matching the flags <code class="docutils literal notranslate"><span class="pre">exclusive</span></code> (long) and <code class="docutils literal notranslate"><span class="pre">x</span></code> +(short) were introduced. For example, this is used in +<code class="file docutils literal notranslate"><span class="pre">optlib/gdbinit.ctags</span></code> for ignoring comment lines in gdb files, +as follows:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--regex-</span><span class="nn">Gdbinit</span><span class="p">=</span>/^#//{exclusive} +</pre></div> +</div> +<p>Comments in gdb files start with ‘<code class="docutils literal notranslate"><span class="pre">#</span></code>’ so the above line is the first regex +match line in <code class="file docutils literal notranslate"><span class="pre">gdbinit.ctags</span></code>, so that subsequent regex matches are +not tried for the input line.</p> +<p>If an empty name pattern (<code class="docutils literal notranslate"><span class="pre">//</span></code>) is used for the <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option, +ctags warns it as a wrong usage of the option. However, if the flags +<code class="docutils literal notranslate"><span class="pre">exclusive</span></code> or <code class="docutils literal notranslate"><span class="pre">x</span></code> is specified, the warning is suppressed. +This is useful to ignore matched patterns as above.</p> +<p>NOTE: This flag does not make sense in the multi-line <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> +option nor the multi-table <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> option.</p> +</section> +<section id="experimental-flags"> +<h3><a class="toc-backref" href="#id8">Experimental flags</a><a class="headerlink" href="#experimental-flags" title="Permalink to this headline">¶</a></h3> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>These flags are experimental. They apply to all regex option +types: basic <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>, multi-line <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code>, +and the experimental multi-table <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> option.</p> +</div> +<p><code class="docutils literal notranslate"><span class="pre">_extra</span></code></p> +<blockquote> +<div><p>This flag indicates the tag should only be generated if the given +<code class="docutils literal notranslate"><span class="pre">extra</span></code> type is enabled, as explained in “<a class="reference internal" href="#extras"><span class="std std-ref">Conditional tagging with extras</span></a>”.</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">_field</span></code></p> +<blockquote> +<div><p>This flag allows a regex match to add additional custom fields to the +generated tag entry, as explained in “<a class="reference internal" href="#fields"><span class="std std-ref">Adding custom fields to the tag output</span></a>”.</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">_role</span></code></p> +<blockquote> +<div><p>This flag allows a regex match to generate a reference tag entry and +specify the role of the reference, as explained in “<a class="reference internal" href="#roles"><span class="std std-ref">Capturing reference tags</span></a>”.</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">_anonymous=PREFIX</span></code></p> +<blockquote> +<div><p>This flag allows a regex match to generate an anonymous tag entry. +ctags gives a name starting with <code class="docutils literal notranslate"><span class="pre">PREFIX</span></code> and emits it. +This flag is useful to record the position for a language object +having no name. A lambda function in a functional programming +language is a typical example of a language object having no name.</p> +<p>Consider following input (<code class="docutils literal notranslate"><span class="pre">input.foo</span></code>):</p> +<div class="highlight-lisp notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="k">let</span> <span class="p">((</span><span class="nv">f</span> <span class="p">(</span><span class="k">lambda</span> <span class="p">(</span><span class="nv">x</span><span class="p">)</span> <span class="p">(</span><span class="nb">+</span> <span class="mi">1</span> <span class="nv">x</span><span class="p">))))</span> + <span class="o">...</span> + <span class="p">)</span> +</pre></div> +</div> +<p>Consider following optlib file (<code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code>):</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">Foo</span> +<span class="kd">--map-</span><span class="nn">Foo</span><span class="p">=+</span>.foo +<span class="kd">--kinddef-</span><span class="nn">Foo</span><span class="p">=</span><span class="ni">l</span><span class="p">,</span><span class="ni">lambda</span><span class="p">,</span><span class="sd">lambda functions</span> +<span class="hll"><span class="kd">--regex-</span><span class="nn">Foo</span><span class="p">=</span>/.*\(lambda .*//l/{_anonymous=L} +</span></pre></div> +</div> +<p>You can get following tags file:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>u-ctags --options<span class="o">=</span>foo.ctags -o - /tmp/input.foo +<span class="go">Le4679d360100 /tmp/input.foo /^(let ((f (lambda (x) (+ 1 x))))$/;" l</span> +</pre></div> +</div> +</div></blockquote> +<section id="conditional-tagging-with-extras"> +<span id="extras"></span><h4><a class="toc-backref" href="#id9">Conditional tagging with extras</a><a class="headerlink" href="#conditional-tagging-with-extras" title="Permalink to this headline">¶</a></h4> +<p>If a matched pattern should only be tagged when an <code class="docutils literal notranslate"><span class="pre">extra</span></code> flag is enabled, +mark the pattern with <code class="docutils literal notranslate"><span class="pre">{_extra=XNAME}</span></code> where <code class="docutils literal notranslate"><span class="pre">XNAME</span></code> is the name of the +extra. You must define a <code class="docutils literal notranslate"><span class="pre">XNAME</span></code> with the +<code class="docutils literal notranslate"><span class="pre">--_extradef-<LANG>=XNAME,DESCRIPTION</span></code> option before defining a regex flag +marked <code class="docutils literal notranslate"><span class="pre">{_extra=XNAME}</span></code>.</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span> + <span class="n">do_something</span><span class="p">()</span> +</pre></div> +</div> +<p>To capture the lines above in a python program (<code class="docutils literal notranslate"><span class="pre">input.py</span></code>), an <code class="docutils literal notranslate"><span class="pre">extra</span></code> flag can +be used.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="kd">--_extradef-</span><span class="nn">Python</span><span class="p">=</span><span class="nv">main</span><span class="p">,</span><span class="sd">__main__ entry points</span> +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">Python</span><span class="p">=</span>/^if __name__ == '__main__':/__main__/f/{_extra=main} +</span></pre></div> +</div> +<p>The above optlib (<code class="docutils literal notranslate"><span class="pre">python-main.ctags</span></code>) introduces <code class="docutils literal notranslate"><span class="pre">main</span></code> extra to the Python parser. +The pattern matching is done only when the <code class="docutils literal notranslate"><span class="pre">main</span></code> is enabled.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --options<span class="o">=</span>python-main.ctags -o - --extras-Python<span class="o">=</span><span class="s1">'+{main}'</span> input.py +<span class="go">__main__ input.py /^if __name__ == '__main__':$/;" f</span> +</pre></div> +</div> +</section> +<section id="adding-custom-fields-to-the-tag-output"> +<span id="fields"></span><h4><a class="toc-backref" href="#id10">Adding custom fields to the tag output</a><a class="headerlink" href="#adding-custom-fields-to-the-tag-output" title="Permalink to this headline">¶</a></h4> +<p>Exuberant Ctags allows just one of the specified groups in a regex pattern to +be used as a part of the name of a tag entry.</p> +<p>Universal Ctags allows using the other groups in the regex pattern. +An optlib parser can have its specific fields. The groups can be used as a +value of the fields of a tag entry.</p> +<p>Let’s think about <cite>Unknown</cite>, an imaginary language. +Here is a source file (<code class="docutils literal notranslate"><span class="pre">input.unknown</span></code>) written in <cite>Unknown</cite>:</p> +<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="kd">public</span> <span class="n">func</span> <span class="nf">foo</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">m</span><span class="p">);</span> +<span class="kd">protected</span> <span class="n">func</span> <span class="nf">bar</span><span class="p">(</span><span class="n">n</span><span class="p">);</span> +<span class="kd">private</span> <span class="n">func</span> <span class="nf">baz</span><span class="p">(</span><span class="n">n</span><span class="p">,...);</span> +</pre></div> +</div> +<p>With <code class="docutils literal notranslate"><span class="pre">--regex-Unknown=...</span></code> Exuberant Ctags can capture <code class="docutils literal notranslate"><span class="pre">foo</span></code>, <code class="docutils literal notranslate"><span class="pre">bar</span></code>, and <code class="docutils literal notranslate"><span class="pre">baz</span></code> +as names. Universal Ctags can attach extra context information to the +names as values for fields. Let’s focus on <code class="docutils literal notranslate"><span class="pre">bar</span></code>. <code class="docutils literal notranslate"><span class="pre">protected</span></code> is a +keyword to control how widely the identifier <code class="docutils literal notranslate"><span class="pre">bar</span></code> can be accessed. +<code class="docutils literal notranslate"><span class="pre">(n)</span></code> is the parameter list of <code class="docutils literal notranslate"><span class="pre">bar</span></code>. <code class="docutils literal notranslate"><span class="pre">protected</span></code> and <code class="docutils literal notranslate"><span class="pre">(n)</span></code> are +extra context information of <code class="docutils literal notranslate"><span class="pre">bar</span></code>.</p> +<p>With the following optlib file (<code class="docutils literal notranslate"><span class="pre">unknown.ctags</span></code>), ctags can attach +<code class="docutils literal notranslate"><span class="pre">protected</span></code> to the field protection and <code class="docutils literal notranslate"><span class="pre">(n)</span></code> to the field signature.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">unknown</span> +<span class="kd">--kinddef-</span><span class="nn">unknown</span><span class="p">=</span><span class="ni">f</span><span class="p">,</span><span class="ni">func</span><span class="p">,</span><span class="sd">functions</span> +<span class="kd">--map-</span><span class="nn">unknown</span><span class="p">=+</span>.unknown + +<span class="hll"><span class="kd">--_fielddef-</span><span class="nn">unknown</span><span class="p">=</span><span class="n n-Type">protection</span><span class="p">,</span><span class="sd">access scope</span> +</span><span class="hll"><span class="kd">--_fielddef-</span><span class="nn">unknown</span><span class="p">=</span><span class="n n-Type">signature</span><span class="p">,</span><span class="sd">signatures</span> +</span><span class="hll"> +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">unknown</span><span class="p">=</span>/^((public|protected|private) +)?func ([^\(]+)\((.*)\)/\3/f/{_field=protection:\1}{_field=signature:(\4)} +</span><span class="hll"><span class="k">--fields-</span><span class="nn">unknown</span><span class="p">=+</span>'{protection}{signature}' +</span></pre></div> +</div> +<p>For the line <code class="docutils literal notranslate"><span class="pre">protected</span> <span class="pre">func</span> <span class="pre">bar(n);</span></code> you will get following tags output:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>bar input.unknown /^protected func bar(n);$/;" f protection:protected signature:(n) +</pre></div> +</div> +<p>Let’s see the detail of <code class="docutils literal notranslate"><span class="pre">unknown.ctags</span></code>.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--_fielddef-</span><span class="nn">unknown</span><span class="p">=</span><span class="n n-Type">protection</span><span class="p">,</span><span class="sd">access scope</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--_fielddef-<LANG>=name,description</span></code> defines a new field for a parser +specified by <em><LANG></em>. Before defining a new field for the parser, +the parser must be defined with <code class="docutils literal notranslate"><span class="pre">--langdef=<LANG></span></code>. <code class="docutils literal notranslate"><span class="pre">protection</span></code> is +the field name used in tags output. <code class="docutils literal notranslate"><span class="pre">access</span> <span class="pre">scope</span></code> is the description +used in the output of <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> and <code class="docutils literal notranslate"><span class="pre">--list-fields=Unknown</span></code>.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--_fielddef-</span><span class="nn">unknown</span><span class="p">=</span><span class="n n-Type">signature</span><span class="p">,</span><span class="sd">signatures</span> +</pre></div> +</div> +<p>This defines a field named <code class="docutils literal notranslate"><span class="pre">signature</span></code>.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--regex-</span><span class="nn">unknown</span><span class="p">=</span>/^((public|protected|private) +)?func ([^\(]+)\((.*)\)/\3/f/{_field=protection:\1}{_field=signature:(\4)} +</pre></div> +</div> +<p>This option requests making a tag for the name that is specified with the group 3 of the +pattern, attaching the group 1 as a value for <code class="docutils literal notranslate"><span class="pre">protection</span></code> field to the tag, and attaching +the group 4 as a value for <code class="docutils literal notranslate"><span class="pre">signature</span></code> field to the tag. You can use the long regex flag +<code class="docutils literal notranslate"><span class="pre">_field</span></code> for attaching fields to a tag with the following notation rule:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">_field</span><span class="o">=</span><span class="n">FIELDNAME</span><span class="p">:</span><span class="n">GROUP</span><span class="p">}</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--fields-<LANG>=[+|-]{FIELDNAME}</span></code> can be used to enable or disable specified field.</p> +<p>When defining a new parser specific field, it is disabled by default. Enable the +field explicitly to use the field. See “<a class="reference internal" href="output-tags.html#parser-specific-fields"><span class="std std-ref">Parser specific fields</span></a>” +about <code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code> option.</p> +<p><cite>passwd</cite> parser is a simple example that uses <code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code> option.</p> +</section> +<section id="capturing-reference-tags"> +<span id="roles"></span><h4><a class="toc-backref" href="#id11">Capturing reference tags</a><a class="headerlink" href="#capturing-reference-tags" title="Permalink to this headline">¶</a></h4> +<p>To make a reference tag with an optlib parser, specify a role with +<code class="docutils literal notranslate"><span class="pre">_role</span></code> long regex flag. Let’s see an example:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">FOO</span> +<span class="kd">--kinddef-</span><span class="nn">FOO</span><span class="p">=</span><span class="ni">m</span><span class="p">,</span><span class="ni">module</span><span class="p">,</span><span class="sd">modules</span> +<span class="hll"><span class="kd">--_roledef-</span><span class="nn">FOO</span><span class="p">.</span><span class="ni">m</span><span class="p">=</span><span class="nd">imported</span><span class="p">,</span><span class="sd">imported module</span> +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">FOO</span><span class="p">=</span>/import[ \t]+([a-z]+)/\1/m/{_role=imported} +</span><span class="hll"><span class="k">--extras</span><span class="p">=+</span>r +</span><span class="hll"><span class="k">--fields</span><span class="p">=+</span>r +</span></pre></div> +</div> +<p>A role must be defined before specifying it as value for <code class="docutils literal notranslate"><span class="pre">_role</span></code> flag. +<code class="docutils literal notranslate"><span class="pre">--_roledef-<LANG>.<KIND>=<ROLE>,<ROLEDESC></span></code> option is for defining a role. +See the line, <code class="docutils literal notranslate"><span class="pre">--regex-FOO=...</span></code>. In this parser <cite>FOO</cite>, the name of an +imported module is captured as a reference tag with role <code class="docutils literal notranslate"><span class="pre">imported</span></code>.</p> +<p>For specifying <em><KIND></em> where the role is defined, you can use either a +kind letter or a kind name surrounded by ‘<code class="docutils literal notranslate"><span class="pre">{</span></code>’ and ‘<code class="docutils literal notranslate"><span class="pre">}</span></code>’.</p> +<p>The option has two parameters separated by a comma:</p> +<p><em><ROLE></em></p> +<blockquote> +<div><p>the role name, and</p> +</div></blockquote> +<p><em><ROLEDESC></em></p> +<blockquote> +<div><p>the description of the role.</p> +</div></blockquote> +<p>The first parameter is the name of the role. The role is defined in +the kind <em><KIND></em> of the language <em><LANG></em>. In the example, +<code class="docutils literal notranslate"><span class="pre">imported</span></code> role is defined in the <code class="docutils literal notranslate"><span class="pre">module</span></code> kind, which is specified +with <code class="docutils literal notranslate"><span class="pre">m</span></code>. You can use <code class="docutils literal notranslate"><span class="pre">{module}</span></code>, the name of the kind instead.</p> +<p>The kind specified in <code class="docutils literal notranslate"><span class="pre">--_roledef-<LANG>.<KIND></span></code> option must be +defined <em>before</em> using the option. See the description of +<code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG></span></code> for defining a kind.</p> +<p>The roles are listed with <code class="docutils literal notranslate"><span class="pre">--list-roles=<LANG></span></code>. The name and description +passed to <code class="docutils literal notranslate"><span class="pre">--_roledef-<LANG>.<KIND></span></code> option are used in the output like:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --langdef=FOO --kinddef-FOO=m,module,modules \ + --_roledef-FOO.m='imported,imported module' --list-roles=FOO +#KIND(L/N) NAME ENABLED DESCRIPTION +m/module imported on imported module +</pre></div> +</div> +<p>If specifying <code class="docutils literal notranslate"><span class="pre">_role</span></code> regex flag multiple times with different roles, you can +assign multiple roles to a reference tag. See following input of C language</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> +<span class="n">i</span> <span class="o">+=</span> <span class="mi">1</span><span class="p">;</span> +</pre></div> +</div> +<p>An ultra fine grained C parser may capture the variable <code class="docutils literal notranslate"><span class="pre">x</span></code> with +<code class="docutils literal notranslate"><span class="pre">lvalue</span></code> role and the variable <code class="docutils literal notranslate"><span class="pre">i</span></code> with <code class="docutils literal notranslate"><span class="pre">lvalue</span></code> and <code class="docutils literal notranslate"><span class="pre">incremented</span></code> +roles.</p> +<p>You can implement such roles by extending the built-in C parser:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="c1"># c-extra.ctags</span> +<span class="hll"><span class="kd">--_roledef-</span><span class="nn">C</span><span class="p">.</span><span class="ni">v</span><span class="p">=</span><span class="nd">lvalue</span><span class="p">,</span><span class="sd">locator values</span> +</span><span class="hll"><span class="kd">--_roledef-</span><span class="nn">C</span><span class="p">.</span><span class="ni">v</span><span class="p">=</span><span class="nd">incremented</span><span class="p">,</span><span class="sd">incremented with ++ operator</span> +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">C</span><span class="p">=</span>/([a-zA-Z_][a-zA-Z_0-9]*) *=/\1/v/{_role=lvalue} +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">C</span><span class="p">=</span>/([a-zA-Z_][a-zA-Z_0-9]*) *\+=/\1/v/{_role=lvalue}{_role=incremented} +</span></pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags with --options<span class="o">=</span>c-extra.ctags --extras<span class="o">=</span>+r --fields<span class="o">=</span>+r +<span class="go">i input.c /^i += 1;$/;" v roles:lvalue,incremented</span> +<span class="go">x input.c /^x = 0;$/;" v roles:lvalue</span> +</pre></div> +</div> +</section> +</section> +<section id="scope-tracking-in-a-regex-parser"> +<h3><a class="toc-backref" href="#id12">Scope tracking in a regex parser</a><a class="headerlink" href="#scope-tracking-in-a-regex-parser" title="Permalink to this headline">¶</a></h3> +<p>About the <code class="docutils literal notranslate"><span class="pre">{scope=..}</span></code> flag itself for scope tracking, see “FLAGS FOR +--regex-<LANG> OPTION” section of <a class="reference internal" href="man/ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +<p>Example 1:</p> +<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># in /tmp/input.foo</span> +<span class="k">class</span> <span class="nc">foo</span><span class="p">:</span> +<span class="k">def</span> <span class="nf">bar</span><span class="p">(</span><span class="n">baz</span><span class="p">):</span> + <span class="nb">print</span><span class="p">(</span><span class="n">baz</span><span class="p">)</span> +<span class="k">class</span> <span class="nc">goo</span><span class="p">:</span> +<span class="k">def</span> <span class="nf">gar</span><span class="p">(</span><span class="n">gaz</span><span class="p">):</span> + <span class="nb">print</span><span class="p">(</span><span class="n">gaz</span><span class="p">)</span> +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="c1"># in /tmp/foo.ctags:</span> +<span class="kn">--langdef</span><span class="p">=</span><span class="nn">Foo</span> +<span class="kd">--map-</span><span class="nn">Foo</span><span class="p">=+</span>.foo +<span class="kd">--kinddef-</span><span class="nn">Foo</span><span class="p">=</span><span class="ni">c</span><span class="p">,</span><span class="ni">class</span><span class="p">,</span><span class="sd">classes</span> +<span class="kd">--kinddef-</span><span class="nn">Foo</span><span class="p">=</span><span class="ni">d</span><span class="p">,</span><span class="ni">definition</span><span class="p">,</span><span class="sd">definitions</span> + +<span class="hll"><span class="kd">--regex-</span><span class="nn">Foo</span><span class="p">=</span>/^class[[:blank:]]+([[:alpha:]]+):/\1/c/{scope=set} +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">Foo</span><span class="p">=</span>/^[[:blank:]]+def[[:blank:]]+([[:alpha:]]+).*:/\1/d/{scope=ref} +</span></pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --options<span class="o">=</span>/tmp/foo.ctags -o - /tmp/input.foo +<span class="go">bar /tmp/input.foo /^ def bar(baz):$/;" d class:foo</span> +<span class="go">foo /tmp/input.foo /^class foo:$/;" c</span> +<span class="go">gar /tmp/input.foo /^ def gar(gaz):$/;" d class:goo</span> +<span class="go">goo /tmp/input.foo /^class goo:$/;" c</span> +</pre></div> +</div> +<p>Example 2:</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// in /tmp/input.pp</span> +<span class="n">class</span> <span class="n">foo</span> <span class="p">{</span> + <span class="kt">int</span> <span class="n">bar</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="c1"># in /tmp/pp.ctags:</span> +<span class="kn">--langdef</span><span class="p">=</span><span class="nn">pp</span> +<span class="kd">--map-</span><span class="nn">pp</span><span class="p">=+</span>.pp +<span class="kd">--kinddef-</span><span class="nn">pp</span><span class="p">=</span><span class="ni">c</span><span class="p">,</span><span class="ni">class</span><span class="p">,</span><span class="sd">classes</span> +<span class="kd">--kinddef-</span><span class="nn">pp</span><span class="p">=</span><span class="ni">v</span><span class="p">,</span><span class="ni">variable</span><span class="p">,</span><span class="sd">variables</span> + +<span class="hll"><span class="kd">--regex-</span><span class="nn">pp</span><span class="p">=</span>/^[[:blank:]]*\}//{scope=pop}{exclusive} +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">pp</span><span class="p">=</span>/^class[[:blank:]]*([[:alnum:]]+)[[[:blank:]]]*\{/\1/c/{scope=push} +</span><span class="hll"><span class="kd">--regex-</span><span class="nn">pp</span><span class="p">=</span>/^[[:blank:]]*int[[:blank:]]*([[:alnum:]]+)/\1/v/{scope=ref} +</span></pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --options<span class="o">=</span>/tmp/pp.ctags -o - /tmp/input.pp +<span class="go">bar /tmp/input.pp /^ include bar$/;" v class:foo</span> +<span class="go">foo /tmp/input.pp /^class foo {$/;" c</span> +</pre></div> +</div> +<p>NOTE: This flag doesn’t work well with <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG>=</span></code>.</p> +</section> +</section> +<section id="overriding-the-letter-for-file-kind"> +<h2><a class="toc-backref" href="#id13">Overriding the letter for file kind</a><a class="headerlink" href="#overriding-the-letter-for-file-kind" title="Permalink to this headline">¶</a></h2> +<p>One of the built-in tag kinds in Universal Ctags is the <code class="docutils literal notranslate"><span class="pre">F</span></code> file kind. +Overriding the letter for file kind is not allowed in Universal Ctags.</p> +<div class="admonition warning"> +<p class="admonition-title">Warning</p> +<p>Don’t use <code class="docutils literal notranslate"><span class="pre">F</span></code> as a kind letter in your parser. (See issue <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/317">#317</a> on github)</p> +</div> +</section> +<section id="generating-fully-qualified-tags-automatically-from-scope-information"> +<h2><a class="toc-backref" href="#id14">Generating fully qualified tags automatically from scope information</a><a class="headerlink" href="#generating-fully-qualified-tags-automatically-from-scope-information" title="Permalink to this headline">¶</a></h2> +<p>If scope fields are filled properly with <code class="docutils literal notranslate"><span class="pre">{scope=...}</span></code> regex flags, +you can use the field values for generating fully qualified tags. +About the <code class="docutils literal notranslate"><span class="pre">{scope=..}</span></code> flag itself, see “FLAGS FOR --regex-<LANG> +OPTION” section of <a class="reference internal" href="man/ctags-optlib.7.html#ctags-optlib-7"><span class="std std-ref">ctags-optlib(7)</span></a>.</p> +<p>Specify <code class="docutils literal notranslate"><span class="pre">{_autoFQTag}</span></code> to the end of <code class="docutils literal notranslate"><span class="pre">--langdef=<LANG></span></code> option like +<code class="docutils literal notranslate"><span class="pre">--langdef=Foo{_autoFQTag}</span></code> to make ctags generate fully qualified +tags automatically.</p> +<p>‘<code class="docutils literal notranslate"><span class="pre">.</span></code>’ is the (ctags global) default separator combining names into a +fully qualified tag. You can customize separators with +<code class="docutils literal notranslate"><span class="pre">--_scopesep-<LANG>=...</span></code> option.</p> +<p>input.foo:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">X</span> + <span class="n">var</span> <span class="n">y</span> +<span class="n">end</span> +</pre></div> +</div> +<p>foo.ctags:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="kn">--langdef</span><span class="p">=</span><span class="nn">foo</span>{_autoFQTag} +</span><span class="kd">--map-</span><span class="nn">foo</span><span class="p">=+</span>.foo +<span class="kd">--kinddef-</span><span class="nn">foo</span><span class="p">=</span><span class="ni">c</span><span class="p">,</span><span class="ni">class</span><span class="p">,</span><span class="sd">classes</span> +<span class="kd">--kinddef-</span><span class="nn">foo</span><span class="p">=</span><span class="ni">v</span><span class="p">,</span><span class="ni">var</span><span class="p">,</span><span class="sd">variables</span> +<span class="kd">--regex-</span><span class="nn">foo</span><span class="p">=</span>/class ([A-Z]*)/\1/c/{scope=push} +<span class="kd">--regex-</span><span class="nn">foo</span><span class="p">=</span>/end///{placeholder}{scope=pop} +<span class="kd">--regex-</span><span class="nn">foo</span><span class="p">=</span>/[ \t]*var ([a-z]*)/\1/v/{scope=ref} +</pre></div> +</div> +<p>Output:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ u-ctags --quiet --options=./foo.ctags -o - input.foo +X input.foo /^class X$/;" c +y input.foo /^ var y$/;" v class:X + +$ u-ctags --quiet --options=./foo.ctags --extras=+q -o - input.foo +X input.foo /^class X$/;" c +X.y input.foo /^ var y$/;" v class:X +y input.foo /^ var y$/;" v class:X +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">X.y</span></code> is printed as a fully qualified tag when <code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code> is given.</p> +<section id="customizing-scope-separators"> +<h3><a class="toc-backref" href="#id15">Customizing scope separators</a><a class="headerlink" href="#customizing-scope-separators" title="Permalink to this headline">¶</a></h3> +<p>Use <code class="docutils literal notranslate"><span class="pre">--_scopesep-<LANG>=[<parent-kindLetter>]/<child-kindLetter>:<sep></span></code> +option for customizing if the language uses <code class="docutils literal notranslate"><span class="pre">{_autoFQTag}</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">parent-kindLetter</span></code></p> +<blockquote> +<div><p>The kind letter for a tag of outer-scope.</p> +<p>You can use ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ for specifying as wildcards that means +<em>any kinds</em> for a tag of outer-scope.</p> +<p>If you omit <code class="docutils literal notranslate"><span class="pre">parent-kindLetter</span></code>, the separator is used as +a prefix for tags having the kind specified with <code class="docutils literal notranslate"><span class="pre">child-kindLetter</span></code>. +This prefix can be used to refer to global namespace or similar concepts if the +language has one.</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">child-kindLetter</span></code></p> +<blockquote> +<div><p>The kind letter for a tag of inner-scope.</p> +<p>You can use ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ for specifying as wildcards that means +<em>any kinds</em> for a tag of inner-scope.</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">sep</span></code></p> +<blockquote> +<div><p>In a qualified tag, if the outer-scope has kind and <code class="docutils literal notranslate"><span class="pre">parent-kindLetter</span></code> +the inner-scope has <code class="docutils literal notranslate"><span class="pre">child-kindLetter</span></code>, then <code class="docutils literal notranslate"><span class="pre">sep</span></code> is instead in +between the scope names in the generated tags file.</p> +</div></blockquote> +<p>specifying ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as both <code class="docutils literal notranslate"><span class="pre">parent-kindLetter</span></code> and <code class="docutils literal notranslate"><span class="pre">child-kindLetter</span></code> +sets <code class="docutils literal notranslate"><span class="pre">sep</span></code> as the language default separator. It is used as fallback.</p> +<p>Specifying ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as <code class="docutils literal notranslate"><span class="pre">child-kindLetter</span></code> and omitting <code class="docutils literal notranslate"><span class="pre">parent-kindLetter</span></code> +sets <code class="docutils literal notranslate"><span class="pre">sep</span></code> as the language default prefix. It is used as fallback.</p> +<p>NOTE: There is no ctags global default prefix.</p> +<p>NOTE: <code class="docutils literal notranslate"><span class="pre">_scopesep-<LANG>=...</span></code> option affects only a parser that +enables <code class="docutils literal notranslate"><span class="pre">_autoFQTag</span></code>. A parser building full qualified tags +manually ignores the option.</p> +<p>Let’s see an example. +The input file is written in Tcl. Tcl parser is not an optlib +parser. However, it uses the <code class="docutils literal notranslate"><span class="pre">_autoFQTag</span></code> feature internally. +Therefore, <code class="docutils literal notranslate"><span class="pre">_scopesep-Tcl=</span></code> option works well. Tcl parser +defines two kinds <code class="docutils literal notranslate"><span class="pre">n</span></code> (<code class="docutils literal notranslate"><span class="pre">namespace</span></code>) and <code class="docutils literal notranslate"><span class="pre">p</span></code> (<code class="docutils literal notranslate"><span class="pre">procedure</span></code>).</p> +<p>By default, Tcl parser uses <code class="docutils literal notranslate"><span class="pre">::</span></code> as scope separator. The parser also +uses <code class="docutils literal notranslate"><span class="pre">::</span></code> as root prefix.</p> +<div class="highlight-tcl notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> eval N <span class="k">{</span> + <span class="k">namespace</span> eval M <span class="k">{</span> + <span class="k">proc</span> pr0 <span class="k">{</span><span class="nv">s</span><span class="k">}</span> <span class="k">{</span> + <span class="nb">puts</span> <span class="nv">$s</span> + <span class="k">}</span> + <span class="k">}</span> +<span class="k">}</span> + +<span class="k">proc</span> pr1 <span class="k">{</span><span class="nv">s</span><span class="k">}</span> <span class="k">{</span> + <span class="nb">puts</span> <span class="nv">$s</span> +<span class="k">}</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">M</span></code> is defined under the scope of <code class="docutils literal notranslate"><span class="pre">N</span></code>. <code class="docutils literal notranslate"><span class="pre">pr0</span></code> is defined under the scope +of <code class="docutils literal notranslate"><span class="pre">M</span></code>. <code class="docutils literal notranslate"><span class="pre">N</span></code> and <code class="docutils literal notranslate"><span class="pre">pr1</span></code> are at top level (so they are candidates to be added +prefixes). <code class="docutils literal notranslate"><span class="pre">M</span></code> and <code class="docutils literal notranslate"><span class="pre">N</span></code> are language objects with <code class="docutils literal notranslate"><span class="pre">n</span></code> (<code class="docutils literal notranslate"><span class="pre">namespace</span></code>) kind. +<code class="docutils literal notranslate"><span class="pre">pr0</span></code> and <code class="docutils literal notranslate"><span class="pre">pr1</span></code> are language objects with <code class="docutils literal notranslate"><span class="pre">p</span></code> (<code class="docutils literal notranslate"><span class="pre">procedure</span></code>) kind.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+q input.tcl +<span class="go">::N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">::N::M input.tcl /^ namespace eval M {$/;" n namespace:::N</span> +<span class="go">::N::M::pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:::N::M</span> +<span class="go">::pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +<span class="go">M input.tcl /^ namespace eval M {$/;" n namespace:::N</span> +<span class="go">N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:::N::M</span> +<span class="go">pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +</pre></div> +</div> +<p>Let’s change the default separator to <code class="docutils literal notranslate"><span class="pre">-></span></code>:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+q --_scopesep-Tcl<span class="o">=</span><span class="s1">'*/*:->'</span> input.tcl +</span><span class="go">::N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">::N->M input.tcl /^ namespace eval M {$/;" n namespace:::N</span> +<span class="go">::N->M->pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:::N->M</span> +<span class="go">::pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +<span class="go">M input.tcl /^ namespace eval M {$/;" n namespace:::N</span> +<span class="go">N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:::N->M</span> +<span class="go">pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +</pre></div> +</div> +<p>Let’s define ‘<code class="docutils literal notranslate"><span class="pre">^</span></code>’ as default prefix:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+q --_scopesep-Tcl<span class="o">=</span><span class="s1">'*/*:->'</span> --_scopesep-Tcl<span class="o">=</span><span class="s1">'/*:^'</span> input.tcl +</span><span class="go">M input.tcl /^ namespace eval M {$/;" n namespace:^N</span> +<span class="go">N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">^N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">^N->M input.tcl /^ namespace eval M {$/;" n namespace:^N</span> +<span class="go">^N->M->pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:^N->M</span> +<span class="go">^pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +<span class="go">pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:^N->M</span> +<span class="go">pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +</pre></div> +</div> +<p>Let’s override the specification of separator for combining a +namespace and a procedure with ‘<code class="docutils literal notranslate"><span class="pre">+</span></code>’: (About the separator for +combining a namespace and another namespace, ctags uses the default separator.)</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+q --_scopesep-Tcl<span class="o">=</span><span class="s1">'*/*:->'</span> --_scopesep-Tcl<span class="o">=</span><span class="s1">'/*:^'</span> --_scopesep-Tcl<span class="o">=</span><span class="s1">'n/p:+'</span> input.tcl +</span><span class="go">M input.tcl /^ namespace eval M {$/;" n namespace:^N</span> +<span class="go">N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">^N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">^N->M input.tcl /^ namespace eval M {$/;" n namespace:^N</span> +<span class="go">^N->M+pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:^N->M</span> +<span class="go">^pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +<span class="go">pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:^N->M</span> +<span class="go">pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +</pre></div> +</div> +<p>Let’s override the definition of prefix for a namespace with ‘<code class="docutils literal notranslate"><span class="pre">@</span></code>’: +(About the prefix for procedures, ctags uses the default prefix.)</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+q --_scopesep-Tcl<span class="o">=</span><span class="s1">'*/*:->'</span> --_scopesep-Tcl<span class="o">=</span><span class="s1">'/*:^'</span> --_scopesep-Tcl<span class="o">=</span><span class="s1">'n/p:+'</span> --_scopesep-Tcl<span class="o">=</span><span class="s1">'/n:@'</span> input.tcl +</span><span class="go">@N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">@N->M input.tcl /^ namespace eval M {$/;" n namespace:@N</span> +<span class="go">@N->M+pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:@N->M</span> +<span class="go">M input.tcl /^ namespace eval M {$/;" n namespace:@N</span> +<span class="go">N input.tcl /^namespace eval N {$/;" n</span> +<span class="go">^pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +<span class="go">pr0 input.tcl /^ proc pr0 {s} {$/;" p namespace:@N->M</span> +<span class="go">pr1 input.tcl /^proc pr1 {s} {$/;" p</span> +</pre></div> +</div> +</section> +</section> +<section id="multi-line-pattern-match"> +<h2><a class="toc-backref" href="#id16">Multi-line pattern match</a><a class="headerlink" href="#multi-line-pattern-match" title="Permalink to this headline">¶</a></h2> +<p>We often need to scan multiple lines to generate a tag, whether due to +needing contextual information to decide whether to tag or not, or to +constrain generating tags to only certain cases, or to grab multiple +substrings to generate the tag name.</p> +<p>Universal Ctags has two ways to accomplish this: <em>multi-line regex options</em>, +and an experimental <em>multi-table regex options</em> described later.</p> +<p>The newly introduced <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> is similar to <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> +except the pattern is applied to the whole file’s contents, not line by line.</p> +<p>This example is based on an issue <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/219">#219</a> posted by +@andreicristianpetcu:</p> +<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="c1">// in input.java:</span> + +<span class="nd">@Subscribe</span> +<span class="kd">public</span> <span class="kt">void</span> <span class="nf">catchEvent</span><span class="p">(</span><span class="n">SomeEvent</span> <span class="n">e</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">return</span><span class="p">;</span> +<span class="p">}</span> + +<span class="nd">@Subscribe</span> +<span class="kd">public</span> <span class="kt">void</span> +<span class="nf">recover</span><span class="p">(</span><span class="n">Exception</span> <span class="n">e</span><span class="p">)</span> +<span class="p">{</span> + <span class="k">return</span><span class="p">;</span> +<span class="p">}</span> +</pre></div> +</div> +<p>The above java code is similar to the Java <a class="reference external" href="https://spring.io">Spring</a> +framework. The <code class="docutils literal notranslate"><span class="pre">@Subscribe</span></code> annotation is a keyword for the framework, and the +developer would like to have a tag generated for each method annotated with +<code class="docutils literal notranslate"><span class="pre">@Subscribe</span></code>, using the name of the method followed by a dash followed by the +type of the argument. For example the developer wants the tag name +<code class="docutils literal notranslate"><span class="pre">Event-SomeEvent</span></code> generated for the first method shown above.</p> +<p>To accomplish this, the developer creates a <code class="file docutils literal notranslate"><span class="pre">spring.ctags</span></code> file with +the following:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="c1"># in spring.ctags:</span> +<span class="kn">--langdef</span><span class="p">=</span><span class="nn">javaspring</span> +<span class="kd">--map-</span><span class="nn">javaspring</span><span class="p">=+</span>.java +<span class="hll"><span class="kd">--mline-regex-</span><span class="nn">javaspring</span><span class="p">=</span>/@Subscribe([[:space:]])*([a-z ]+)[[:space:]]*([a-zA-Z]*)\(([a-zA-Z]*)/\3-\4/s,subscription/{mgroup=3} +</span><span class="k">--fields</span><span class="p">=+</span>ln +</pre></div> +</div> +<p>And now using <code class="file docutils literal notranslate"><span class="pre">spring.ctags</span></code> the tag file has this:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - --options<span class="o">=</span>./spring.ctags input.java +<span class="go">Event-SomeEvent input.java /^public void catchEvent(SomeEvent e)$/;" s line:2 language:javaspring</span> +<span class="go">recover-Exception input.java /^ recover(Exception e)$/;" s line:10 language:javaspring</span> +</pre></div> +</div> +<section id="multiline-pattern-flags"> +<h3><a class="toc-backref" href="#id17">Multiline pattern flags</a><a class="headerlink" href="#multiline-pattern-flags" title="Permalink to this headline">¶</a></h3> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>These flags also apply to the experimental <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> +option described later.</p> +</div> +<p><code class="docutils literal notranslate"><span class="pre">{mgroup=N}</span></code></p> +<blockquote> +<div><p>This flag indicates the pattern should be applied to the whole file +contents, not line by line. <code class="docutils literal notranslate"><span class="pre">N</span></code> is the number of a capture group in the +pattern, which is used to record the line number location of the tag. In the +above example <code class="docutils literal notranslate"><span class="pre">3</span></code> is specified. The start position of the regex capture +group 3, relative to the whole file is used.</p> +</div></blockquote> +<div class="admonition warning"> +<p class="admonition-title">Warning</p> +<p>You <strong>must</strong> add an <code class="docutils literal notranslate"><span class="pre">{mgroup=N}</span></code> flag to the multi-line +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> option, even if the <code class="docutils literal notranslate"><span class="pre">N</span></code> is <code class="docutils literal notranslate"><span class="pre">0</span></code> (meaning the +start position of the whole regex pattern). You do not need to add it for +the multi-table <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code>.</p> +</div> +<p><code class="docutils literal notranslate"><span class="pre">{_advanceTo=N[start|end]}</span></code></p> +<blockquote> +<div><p>A regex pattern is applied to whole file’s contents iteratively. This long +flag specifies from where the pattern should be applied in the next +iteration for regex matching. When a pattern matches, the next pattern +matching starts from the start or end of capture group <code class="docutils literal notranslate"><span class="pre">N</span></code>. By default it +advances to the end of the whole match (i.e., <code class="docutils literal notranslate"><span class="pre">{_advanceTo=0end}</span></code> is +the default).</p> +<p>Let’s think about following input</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">def</span> <span class="n">abc</span> +</pre></div> +</div> +<p>Consider two sets of options, <code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code> and <code class="docutils literal notranslate"><span class="pre">bar.ctags</span></code>.</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="c1"># foo.ctags:</span> +<span class="kn">--langdef</span><span class="p">=</span><span class="nn">foo</span> +<span class="kd">--langmap</span><span class="p">=</span><span class="nn">foo</span><span class="p">:</span>.foo +<span class="kd">--kinddef-</span><span class="nn">foo</span><span class="p">=</span><span class="ni">a</span><span class="p">,</span><span class="ni">something</span><span class="p">,</span><span class="sd">something</span> +<span class="hll"><span class="kd">--mline-regex-</span><span class="nn">foo</span><span class="p">=</span>/def *([a-z]+)/\1/a/{mgroup=1} +</span></pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="c1"># bar.ctags:</span> +<span class="kn">--langdef</span><span class="p">=</span><span class="nn">bar</span> +<span class="kd">--langmap</span><span class="p">=</span><span class="nn">bar</span><span class="p">:</span>.bar +<span class="kd">--kinddef-</span><span class="nn">bar</span><span class="p">=</span><span class="ni">a</span><span class="p">,</span><span class="ni">something</span><span class="p">,</span><span class="sd">something</span> +<span class="hll"><span class="kd">--mline-regex-</span><span class="nn">bar</span><span class="p">=</span>/def *([a-z]+)/\1/a/{mgroup=1}{_advanceTo=1start} +</span></pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code> emits following tags output:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>def input.foo /^def def abc$/;" a +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">bar.ctags</span></code> emits following tags output:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>def input-0.bar /^def def abc$/;" a +abc input-0.bar /^def def abc$/;" a +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">_advanceTo=1start</span></code> is specified in <code class="docutils literal notranslate"><span class="pre">bar.ctags</span></code>. +This allows ctags to capture <code class="docutils literal notranslate"><span class="pre">abc</span></code>.</p> +<p>At the first iteration, the patterns of both +<code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code> and <code class="docutils literal notranslate"><span class="pre">bar.ctags</span></code> match as follows</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">0</span> <span class="mi">1</span> <span class="p">(</span><span class="n">start</span><span class="p">)</span> +<span class="n">v</span> <span class="n">v</span> +<span class="k">def</span> <span class="nf">def</span> <span class="n">abc</span> + <span class="o">^</span> + <span class="mi">0</span><span class="p">,</span><span class="mi">1</span> <span class="p">(</span><span class="n">end</span><span class="p">)</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">def</span></code> at the group 1 is captured as a tag in +both languages. At the next iteration, the positions +where the pattern matching is applied to are not the +same in the languages.</p> +<p><code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code></p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="mi">0</span><span class="n">end</span> <span class="p">(</span><span class="n">default</span><span class="p">)</span> + <span class="n">v</span> +<span class="k">def</span> <span class="nf">def</span> <span class="n">abc</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">bar.ctags</span></code></p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="mi">1</span><span class="n">start</span> <span class="p">(</span><span class="k">as</span> <span class="n">specified</span> <span class="ow">in</span> <span class="n">_advanceTo</span> <span class="n">long</span> <span class="n">flag</span><span class="p">)</span> + <span class="n">v</span> +<span class="k">def</span> <span class="nf">def</span> <span class="n">abc</span> +</pre></div> +</div> +<p>This difference of positions makes the difference of tags output.</p> +<p>A more relevant use-case is when <code class="docutils literal notranslate"><span class="pre">{_advanceTo=N[start|end]}</span></code> is used in +the experimental <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code>, to “advance” back to the +beginning of a match, so that one can generate multiple tags for the same +input line(s).</p> +</div></blockquote> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>This flag doesn’t work well with scope related flags and <code class="docutils literal notranslate"><span class="pre">exclusive</span></code> flags.</p> +</div> +</section> +</section> +<section id="advanced-pattern-matching-with-multiple-regex-tables"> +<h2><a class="toc-backref" href="#id18">Advanced pattern matching with multiple regex tables</a><a class="headerlink" href="#advanced-pattern-matching-with-multiple-regex-tables" title="Permalink to this headline">¶</a></h2> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>This is a highly experimental feature. This will not go into +the man page of 6.0. But let’s be honest, it’s the most exciting feature!</p> +</div> +<p>In some cases, the <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> and <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> options are not +sufficient to generate the tags for a particular language. Some of the common +reasons for this are:</p> +<ul class="simple"> +<li><p>To ignore commented lines or sections for the language file, so that +tags aren’t generated for symbols that are within the comments.</p></li> +<li><p>To enter and exit scope, and use it for tagging based on contextual +state or with end-scope markers that are difficult to match to their +associated scope entry point.</p></li> +<li><p>To support nested scopes.</p></li> +<li><p>To change the pattern searched for, or the resultant tag for the same +pattern, based on scoping or contextual location.</p></li> +<li><p>To break up an overly complicated <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> pattern into +separate regex patterns, for performance or readability reasons.</p></li> +</ul> +<p>To help handle such things, Universal Ctags has been enhanced with multi-table +regex matching. The feature is inspired by <cite>lex</cite>, the fast lexical analyzer +generator, which is a popular tool on Unix environments for writing parsers, and +<a class="reference external" href="http://pygments.org/docs/lexerdevelopment/">RegexLexer</a> of Pygments. +Knowledge about them will help you understand the new options.</p> +<p>The new options are:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">--_tabledef-<LANG></span></code></dt><dd><p>Declares a new regex matching table of a given name for the language, +as described in “<a class="reference internal" href="#tabledef"><span class="std std-ref">Declaring a new regex table</span></a>”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code></dt><dd><p>Adds a regex pattern and associated tag generation information and flags, to +the given table, as described in “<a class="reference internal" href="#mtable-regex"><span class="std std-ref">Adding a regex to a regex table</span></a>”.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">--_mtable-extend-<LANG></span></code></dt><dd><p>Includes a previously-defined regex table to the named one.</p> +</dd> +</dl> +<p>The above will be discussed in more detail shortly.</p> +<p>First, let’s explain the feature with an example. Consider an +imaginary language <cite>X</cite> has a similar syntax as JavaScript: <code class="docutils literal notranslate"><span class="pre">var</span></code> is +used as defining variable(s), and “<code class="docutils literal notranslate"><span class="pre">/*</span> <span class="pre">...</span> <span class="pre">*/</span></code>” is used for block +comments.</p> +<p>Here is our input, <code class="file docutils literal notranslate"><span class="pre">input.x</span></code>:</p> +<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="cm">/* BLOCK COMMENT</span> +<span class="cm">var dont_capture_me;</span> +<span class="cm">*/</span> +<span class="kd">var</span> <span class="n">a</span> <span class="cm">/* ANOTHER BLOCK COMMENT */</span><span class="p">,</span> <span class="n">b</span><span class="p">;</span> +</pre></div> +</div> +<p>We want ctags to capture <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> - but it is difficult to write a parser +that will ignore <code class="docutils literal notranslate"><span class="pre">dont_capture_me</span></code> in the comment with a classical regex +parser defined with <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> or <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code>, because of +the block comments.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> option only works on one line at a time, so can not know +<code class="docutils literal notranslate"><span class="pre">dont_capture_me</span></code> is within comments. The <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> could +do it in theory, but due to the greedy nature of the regex engine it is +impractical and potentially inefficient to do so, given that there could be +multiple block comments in the file, with ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ inside them, etc.</p> +<p>A parser written with multi-table regex, on the other hand, can capture only +<code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> safely. But it is more complicated to understand.</p> +<p>Here is the 1st version of <code class="file docutils literal notranslate"><span class="pre">X.ctags</span></code>:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">X</span> +<span class="kd">--map-</span><span class="nn">X</span><span class="p">=</span>.x +<span class="kd">--kinddef-</span><span class="nn">X</span><span class="p">=</span><span class="ni">v</span><span class="p">,</span><span class="ni">var</span><span class="p">,</span><span class="sd">variables</span> +</pre></div> +</div> +<p>Not so interesting. It doesn’t really <em>do</em> anything yet. It just creates a new +language named <code class="docutils literal notranslate"><span class="pre">X</span></code>, for files ending with a <code class="file docutils literal notranslate"><span class="pre">.x</span></code> suffix, and defines a +new tag for variable kinds.</p> +<p>When writing a multi-table parser, you have to think about the necessary states +of parsing. For the parser of language <cite>X</cite>, we need the following states:</p> +<ul class="simple"> +<li><p><cite>toplevel</cite> (initial state)</p></li> +<li><p><cite>comment</cite> (inside comment)</p></li> +<li><p><cite>vars</cite> (var statements)</p></li> +</ul> +<section id="declaring-a-new-regex-table"> +<span id="tabledef"></span><h3><a class="toc-backref" href="#id19">Declaring a new regex table</a><a class="headerlink" href="#declaring-a-new-regex-table" title="Permalink to this headline">¶</a></h3> +<p>Before adding regular expressions, you have to declare tables for each state +with the <code class="docutils literal notranslate"><span class="pre">--_tabledef-<LANG>=<TABLE></span></code> option.</p> +<p>Here is the 2nd version of <code class="file docutils literal notranslate"><span class="pre">X.ctags</span></code> doing so:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">X</span> +<span class="kd">--map-</span><span class="nn">X</span><span class="p">=</span>.x +<span class="kd">--kinddef-</span><span class="nn">X</span><span class="p">=</span><span class="ni">v</span><span class="p">,</span><span class="ni">var</span><span class="p">,</span><span class="sd">variables</span> + +<span class="hll"><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span> +</span><span class="hll"><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span> +</span><span class="hll"><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span> +</span></pre></div> +</div> +<p>For table names, only characters in the range <code class="docutils literal notranslate"><span class="pre">[0-9a-zA-Z_]</span></code> are acceptable.</p> +<p>For a given language, for each file’s input the ctags multi-table parser begins +with the first declared table. For <code class="file docutils literal notranslate"><span class="pre">X.ctags</span></code>, <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> is the one. +The other tables are only ever entered/checked if another table specified to do +so, starting with the first table. In other words, if the first declared table +does not find a match for the current input, and does not specify to go to +another table, the other tables for that language won’t be used. The flags to go +to another table are <code class="docutils literal notranslate"><span class="pre">{tenter}</span></code>, <code class="docutils literal notranslate"><span class="pre">{tleave}</span></code>, and <code class="docutils literal notranslate"><span class="pre">{tjump}</span></code>, as described +later.</p> +</section> +<section id="adding-a-regex-to-a-regex-table"> +<span id="mtable-regex"></span><h3><a class="toc-backref" href="#id20">Adding a regex to a regex table</a><a class="headerlink" href="#adding-a-regex-to-a-regex-table" title="Permalink to this headline">¶</a></h3> +<p>The new option to add a regex to a declared table is <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code>, +and it follows this form:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>--_mtable-regex-<LANG>=<TABLE>/<PATTERN>/<NAME>/[<KIND>]/LONGFLAGS +</pre></div> +</div> +<p>The parameters for <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> look complicated. However, +<code class="docutils literal notranslate"><span class="pre"><PATTERN></span></code>, <code class="docutils literal notranslate"><span class="pre"><NAME></span></code>, and <code class="docutils literal notranslate"><span class="pre"><KIND></span></code> are the same as the parameters of the +<code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> and <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> options. <code class="docutils literal notranslate"><span class="pre"><TABLE></span></code> is simply +the name of a table previously declared with the <code class="docutils literal notranslate"><span class="pre">--_tabledef-<LANG></span></code> option.</p> +<p>A regex pattern added to a parser with <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> is matched +against the input at the current byte position, not line. Even if you do not +specify the ‘<code class="docutils literal notranslate"><span class="pre">^</span></code>’ anchor at the start of the pattern, ctags adds ‘<code class="docutils literal notranslate"><span class="pre">^</span></code>’ to +the pattern automatically. Unlike the <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> and +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> options, a ‘<code class="docutils literal notranslate"><span class="pre">^</span></code>’ anchor does not mean “beginning of +line” in <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code>; instead it means the beginning of the +input string (i.e., the current byte position).</p> +<p>The <code class="docutils literal notranslate"><span class="pre">LONGFLAGS</span></code> include the already discussed flags for <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> and +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code>: <code class="docutils literal notranslate"><span class="pre">{scope=...}</span></code>, <code class="docutils literal notranslate"><span class="pre">{mgroup=N}</span></code>, <code class="docutils literal notranslate"><span class="pre">{_advanceTo=N}</span></code>, +<code class="docutils literal notranslate"><span class="pre">{basic}</span></code>, <code class="docutils literal notranslate"><span class="pre">{extend}</span></code>, and <code class="docutils literal notranslate"><span class="pre">{icase}</span></code>. The <code class="docutils literal notranslate"><span class="pre">{exclusive}</span></code> flag does not +make sense for multi-table regex.</p> +<p>In addition, several new flags are introduced exclusively for multi-table +regex use:</p> +<dl class="simple"> +<dt><code class="docutils literal notranslate"><span class="pre">{tenter}</span></code></dt><dd><p>Push the current table on the stack, and enter another table.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">{tleave}</span></code></dt><dd><p>Leave the current table, pop the stack, and go to the table that was +just popped from the stack.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">{tjump}</span></code></dt><dd><p>Jump to another table, without affecting the stack.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">{treset}</span></code></dt><dd><p>Clear the stack, and go to another table.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">{tquit}</span></code></dt><dd><p>Clear the stack, and stop processing the current input file for this +language.</p> +</dd> +</dl> +<p>To explain the above new flags, we’ll continue using our example in the +next section.</p> +</section> +<section id="skipping-block-comments"> +<h3><a class="toc-backref" href="#id21">Skipping block comments</a><a class="headerlink" href="#skipping-block-comments" title="Permalink to this headline">¶</a></h3> +<p>Let’s continue with our example. Here is the 3rd version of <code class="file docutils literal notranslate"><span class="pre">X.ctags</span></code>:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">X</span> +<span class="linenos"> 2</span><span class="kd">--map-</span><span class="nn">X</span><span class="p">=</span>.x +<span class="linenos"> 3</span><span class="kd">--kinddef-</span><span class="nn">X</span><span class="p">=</span><span class="ni">v</span><span class="p">,</span><span class="ni">var</span><span class="p">,</span><span class="sd">variables</span> +<span class="linenos"> 4</span> +<span class="linenos"> 5</span><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span> +<span class="linenos"> 6</span><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span> +<span class="linenos"> 7</span><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span> +<span class="linenos"> 8</span> +<span class="hll"><span class="linenos"> 9</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/\/\*//{tenter=comment} +</span><span class="hll"><span class="linenos">10</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/.// +</span><span class="hll"><span class="linenos">11</span> +</span><span class="hll"><span class="linenos">12</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/\*\///{tleave} +</span><span class="hll"><span class="linenos">13</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/.// +</span></pre></div> +</div> +<p>Four <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-X</span></code> lines are added for skipping the block comments. Let’s +discuss them one by one.</p> +<p>For each new file it scans, ctags always chooses the first pattern of the +first table of the parser. Even if it’s an empty table, ctags will only try +the first declared table. (in such a case it would immediately fail to match +anything, and thus stop processing the input file and effectively do nothing)</p> +<p>The first declared table (<code class="docutils literal notranslate"><span class="pre">toplevel</span></code>) has the following regex added to +it first:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">9</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/\/\*//{tenter=comment} +</pre></div> +</div> +<p>A pattern of <code class="docutils literal notranslate"><span class="pre">\/\*</span></code> is added to the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table, to match the +beginning of a block comment. A backslash character is used in front of the +leading ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’ to escape the separation character ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’ that separates the fields +of <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code>. Another backslash inside the pattern is used +before the asterisk ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’, to make it a literal asterisk character in regex.</p> +<p>The last <code class="docutils literal notranslate"><span class="pre">//</span></code> means ctags should not tag something matching this pattern. +In <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code> you never use <code class="docutils literal notranslate"><span class="pre">//</span></code> because it would be pointless to +match something and not tag it using and single-line <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>; in +multi-line <code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code> you rarely see it, because it would rarely +be useful. But in multi-table regex it’s quite common, since you frequently +want to transition from one state to another (i.e., <code class="docutils literal notranslate"><span class="pre">tenter</span></code> or <code class="docutils literal notranslate"><span class="pre">tjump</span></code> +from one table to another).</p> +<p>The long flag added to our first regex of our first table is <code class="docutils literal notranslate"><span class="pre">tenter</span></code>, which +is a long flag for switching the table and pushing on the stack. <code class="docutils literal notranslate"><span class="pre">{tenter=comment}</span></code> +means “switch the table from toplevel to comment”.</p> +<p>So given the input file <code class="file docutils literal notranslate"><span class="pre">input.x</span></code> shown earlier, ctags will begin at +the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table and try to match the first regex. It will succeed, and +thus push on the stack and go to the <code class="docutils literal notranslate"><span class="pre">comment</span></code> table.</p> +<p>It will begin at the top of the <code class="docutils literal notranslate"><span class="pre">comment</span></code> table (it always begins at the top +of a given table), and try each regex line in sequence until it finds a match. +If it fails to find a match, it will pop the stack and go to the table that was +just popped from the stack, and begin trying to match at the top of <em>that</em> table. +If it continues failing to find a match, and ultimately reaches the end of the +stack, it will stop processing for this file. For the next input file, it will +begin again from the top of the first declared table.</p> +<p>Getting back to our example, the top of the <code class="docutils literal notranslate"><span class="pre">comment</span></code> table has this regex:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">12</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/\*\///{tleave} +</pre></div> +</div> +<p>Similar to the previous <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table pattern, this one for <code class="docutils literal notranslate"><span class="pre">\*\/</span></code> uses +a backslash to escape the separator ‘<code class="docutils literal notranslate"><span class="pre">/</span></code>’, as well as one before the ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ to +make it a literal asterisk in regex. So what it’s looking for, from a simple +string perspective, is the sequence <code class="docutils literal notranslate"><span class="pre">*/</span></code>. Note that this means even though +you see three backslashes <code class="docutils literal notranslate"><span class="pre">///</span></code> at the end, the first one is escaped and used +for the pattern itself, and the <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-X</span></code> only has <code class="docutils literal notranslate"><span class="pre">//</span></code> to +separate the regex pattern from the long flags, instead of the usual <code class="docutils literal notranslate"><span class="pre">///</span></code>. +Thus it’s using the shorthand form of the <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-X</span></code> option. +It could instead have been:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/\*\////{tleave} +</pre></div> +</div> +<p>The above would have worked exactly the same.</p> +<p>Getting back to our example, remember we’re looking at the <code class="file docutils literal notranslate"><span class="pre">input.x</span></code> +file, currently using the <code class="docutils literal notranslate"><span class="pre">comment</span></code> table, and trying to match the first +regex of that table, shown above, at the following location:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="p">,</span><span class="n">ctags</span> <span class="ow">is</span> <span class="n">trying</span> <span class="n">to</span> <span class="n">match</span> <span class="n">starting</span> <span class="n">here</span> + <span class="n">v</span> +<span class="o">/*</span> <span class="n">BLOCK</span> <span class="n">COMMENT</span> +<span class="n">var</span> <span class="n">dont_capture_me</span><span class="p">;</span> +<span class="o">*/</span> +<span class="n">var</span> <span class="n">a</span> <span class="o">/*</span> <span class="n">ANOTHER</span> <span class="n">BLOCK</span> <span class="n">COMMENT</span> <span class="o">*/</span><span class="p">,</span> <span class="n">b</span><span class="p">;</span> +</pre></div> +</div> +<p>The pattern doesn’t match for the position just after <code class="docutils literal notranslate"><span class="pre">/*</span></code>, because that +position is a space character. So ctags tries the next pattern in the same +table:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">13</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/.// +</pre></div> +</div> +<p>This pattern matches any any one character including newline; the current +position moves one character forward. Now the character at the current position is +‘<code class="docutils literal notranslate"><span class="pre">B</span></code>’. The first pattern of the table <code class="docutils literal notranslate"><span class="pre">*/</span></code> still does not match with the input. So +ctags uses next pattern again. When the current position moves to the <code class="docutils literal notranslate"><span class="pre">*/</span></code> +of the 3rd line of <code class="file docutils literal notranslate"><span class="pre">input.x</span></code>, it will finally match this:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">12</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/\*\///{tleave} +</pre></div> +</div> +<p>In this pattern, the long flag <code class="docutils literal notranslate"><span class="pre">{tleave}</span></code> is specified. This triggers table +switching again. <code class="docutils literal notranslate"><span class="pre">{tleave}</span></code> makes ctags switch the table back to the last +table used before doing <code class="docutils literal notranslate"><span class="pre">{tenter}</span></code>. In this case, <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> is the table. +ctags manages a stack where references to tables are put. <code class="docutils literal notranslate"><span class="pre">{tenter}</span></code> pushes +the current table to the stack. <code class="docutils literal notranslate"><span class="pre">{tleave}</span></code> pops the table at the top of the +stack and chooses it.</p> +<p>So now ctags is back to the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table, and tries the first regex +of that table, which was this:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">9</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/\/\*//{tenter=comment} +</pre></div> +</div> +<p>It tries to match that against its current position, which is now the +newline on line 3, between the <code class="docutils literal notranslate"><span class="pre">*/</span></code> and the word <code class="docutils literal notranslate"><span class="pre">var</span></code>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/*</span> <span class="n">BLOCK</span> <span class="n">COMMENT</span> +<span class="n">var</span> <span class="n">dont_capture_me</span><span class="p">;</span> +<span class="o">*/</span> <span class="o"><---</span> <span class="n">ctags</span> <span class="ow">is</span> <span class="n">now</span> <span class="n">at</span> <span class="n">this</span> <span class="n">newline</span> <span class="p">(</span><span class="o">/</span><span class="n">n</span><span class="p">)</span> <span class="n">character</span> +<span class="n">var</span> <span class="n">a</span> <span class="o">/*</span> <span class="n">ANOTHER</span> <span class="n">BLOCK</span> <span class="n">COMMENT</span> <span class="o">*/</span><span class="p">,</span> <span class="n">b</span><span class="p">;</span> +</pre></div> +</div> +<p>The first regex of the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table does not match a newline, so it tries +the second regex:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">13</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/.// +</pre></div> +</div> +<p>This matches a newline successfully, but has no actions to perform. So ctags +moves one character forward (the newline it just matched), and goes back to the +top of the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table, and tries the first regex again. Eventually we’ll +reach the beginning of the second block comment, and do the same things as before.</p> +<p>When ctags finally reaches the end of the file (the position after <code class="docutils literal notranslate"><span class="pre">b;</span></code>), +it will not be able to match either the first or second regex of the +<code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table, and quit processing the input file.</p> +<p>So far, we’ve successfully skipped over block comments for our new <code class="docutils literal notranslate"><span class="pre">X</span></code> +language, but haven’t generated any tags. The point of ctags is to generate +tags, not just keep your computer warm. So now let’s move onto actually tagging +variables…</p> +</section> +<section id="capturing-variables-in-a-sequence"> +<h3><a class="toc-backref" href="#id22">Capturing variables in a sequence</a><a class="headerlink" href="#capturing-variables-in-a-sequence" title="Permalink to this headline">¶</a></h3> +<p>Here is the 4th version of <code class="file docutils literal notranslate"><span class="pre">X.ctags</span></code>:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">X</span> +<span class="linenos"> 2</span><span class="kd">--map-</span><span class="nn">X</span><span class="p">=</span>.x +<span class="linenos"> 3</span><span class="kd">--kinddef-</span><span class="nn">X</span><span class="p">=</span><span class="ni">v</span><span class="p">,</span><span class="ni">var</span><span class="p">,</span><span class="sd">variables</span> +<span class="linenos"> 4</span> +<span class="linenos"> 5</span><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span> +<span class="linenos"> 6</span><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span> +<span class="linenos"> 7</span><span class="kd">--_tabledef-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span> +<span class="linenos"> 8</span> +<span class="linenos"> 9</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/\/\*//{tenter=comment} +<span class="hll"><span class="linenos">10</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/var[ \n\t]//{tenter=vars} +</span><span class="linenos">11</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/.// +<span class="linenos">12</span> +<span class="linenos">13</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/\*\///{tleave} +<span class="linenos">14</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">comment</span>/.// +<span class="linenos">15</span> +<span class="hll"><span class="linenos">16</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/;//{tleave} +</span><span class="hll"><span class="linenos">17</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/\/\*//{tenter=comment} +</span><span class="hll"><span class="linenos">18</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/([a-zA-Z][a-zA-Z0-9]*)/\1/v/ +</span><span class="hll"><span class="linenos">19</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/.// +</span></pre></div> +</div> +<p>One pattern in <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> was added, and a new table <code class="docutils literal notranslate"><span class="pre">vars</span></code> with four +patterns was also added.</p> +<p>The new regex in <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> is this:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">10</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">toplevel</span>/var[ \n\t]//{tenter=vars} +</pre></div> +</div> +<p>The purpose of this being in <cite>toplevel</cite> is to switch to the <cite>vars</cite> table when +the keyword <code class="docutils literal notranslate"><span class="pre">var</span></code> is found in the input stream. We need to switch states +(i.e., tables) because we can’t simply capture the variables <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> +with a single regex pattern in the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table, because there might be +block comments inside the <code class="docutils literal notranslate"><span class="pre">var</span></code> statement (as there are in our +<code class="file docutils literal notranslate"><span class="pre">input.x</span></code>), and we also need to create <em>two</em> tags: one for <code class="docutils literal notranslate"><span class="pre">a</span></code> and one +for <code class="docutils literal notranslate"><span class="pre">b</span></code>, even though the word <code class="docutils literal notranslate"><span class="pre">var</span></code> only appears once. In other words, we +need to “remember” that we saw the keyword <code class="docutils literal notranslate"><span class="pre">var</span></code>, when we later encounter the +names <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code>, so that we know to tag each of them; and saving that +“in-variable-statement” state is accomplished by switching tables to the +<code class="docutils literal notranslate"><span class="pre">vars</span></code> table.</p> +<p>The first regex in our new <code class="docutils literal notranslate"><span class="pre">vars</span></code> table is:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">16</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/;//{tleave} +</pre></div> +</div> +<p>This pattern is used to match a single semi-colon ‘<code class="docutils literal notranslate"><span class="pre">;</span></code>’, and if it matches +pop back to the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table using the <code class="docutils literal notranslate"><span class="pre">{tleave}</span></code> long flag. We +didn’t have to make this the first regex pattern, because it doesn’t overlap +with any of the other ones other than the <code class="docutils literal notranslate"><span class="pre">/.//</span></code> last one (which must be +last for this example to work).</p> +<p>The second regex in our <code class="docutils literal notranslate"><span class="pre">vars</span></code> table is:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">17</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/\/\*//{tenter=comment} +</pre></div> +</div> +<p>We need this because block comments can be in variable definitions:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">var</span> <span class="n">a</span> <span class="o">/*</span> <span class="n">ANOTHER</span> <span class="n">BLOCK</span> <span class="n">COMMENT</span> <span class="o">*/</span><span class="p">,</span> <span class="n">b</span><span class="p">;</span> +</pre></div> +</div> +<p>So to skip block comments in such a position, the pattern <code class="docutils literal notranslate"><span class="pre">\/\*</span></code> is used just +like it was used in the <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> table: to find the literal <code class="docutils literal notranslate"><span class="pre">/*</span></code> beginning +of the block comment and enter the <code class="docutils literal notranslate"><span class="pre">comment</span></code> table. Because we’re using +<code class="docutils literal notranslate"><span class="pre">{tenter}</span></code> and <code class="docutils literal notranslate"><span class="pre">{tleave}</span></code> to push/pop from a stack of tables, we can +use the same <code class="docutils literal notranslate"><span class="pre">comment</span></code> table for both <code class="docutils literal notranslate"><span class="pre">toplevel</span></code> and <code class="docutils literal notranslate"><span class="pre">vars</span></code> to go to, +because ctags will <em>remember</em> the previous table and <code class="docutils literal notranslate"><span class="pre">{tleave}</span></code> will +pop back to the right one.</p> +<p>The third regex in our <code class="docutils literal notranslate"><span class="pre">vars</span></code> table is:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">18</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/([a-zA-Z][a-zA-Z0-9]*)/\1/v/ +</pre></div> +</div> +<p>This is nothing special, but is the one that actually tags something: it +captures the variable name and uses it for generating a <code class="docutils literal notranslate"><span class="pre">variable</span></code> (shorthand +<code class="docutils literal notranslate"><span class="pre">v</span></code>) tag kind.</p> +<p>The last regex in the <code class="docutils literal notranslate"><span class="pre">vars</span></code> table we’ve seen before:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="linenos">19</span><span class="kd">--_mtable-regex-</span><span class="nn">X</span><span class="p">=</span><span class="nf">vars</span>/.// +</pre></div> +</div> +<p>This makes ctags ignore any other characters, such as whitespace or the +comma ‘<code class="docutils literal notranslate"><span class="pre">,</span></code>’.</p> +</section> +<section id="running-our-example"> +<h3><a class="toc-backref" href="#id23">Running our example</a><a class="headerlink" href="#running-our-example" title="Permalink to this headline">¶</a></h3> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.x +<span class="go">/* BLOCK COMMENT</span> +<span class="go">var dont_capture_me;</span> +<span class="go">*/</span> +<span class="go">var a /* ANOTHER BLOCK COMMENT */, b;</span> + +<span class="gp">$ </span>u-ctags -o - --fields<span class="o">=</span>+n --options<span class="o">=</span>X.ctags input.x +<span class="go">u-ctags -o - --fields=+n --options=X.ctags input.x</span> +<span class="go">a input.x /^var a \/* ANOTHER BLOCK COMMENT *\/, b;$/;" v line:4</span> +<span class="go">b input.x /^var a \/* ANOTHER BLOCK COMMENT *\/, b;$/;" v line:4</span> +</pre></div> +</div> +<p>It works!</p> +<p>You can find additional examples of multi-table regex in our github repo, under +the <code class="docutils literal notranslate"><span class="pre">optlib</span></code> directory. For example <code class="docutils literal notranslate"><span class="pre">puppetManifest.ctags</span></code> is a serious +example. It is the primary parser for testing multi-table regex parsers, and +used in the actual ctags program for parsing puppet manifest files.</p> +</section> +</section> +<section id="scheduling-a-guest-parser-with-guest-regex-flag"> +<span id="guest-regex-flag"></span><h2><a class="toc-backref" href="#id24">Scheduling a guest parser with <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag</a><a class="headerlink" href="#scheduling-a-guest-parser-with-guest-regex-flag" title="Permalink to this headline">¶</a></h2> +<p>With <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag, you can run a parser (a guest parser) on an +area of the current input file. +See “<a class="reference internal" href="running-multi-parsers.html#host-guest-parsers"><span class="std std-ref">Guest parser: Applying a parser to specified areas of input file</span></a>” about the concept of the guest parser.</p> +<p>The <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag specifies a <em>guest spec</em>, and attaches it to +the associated regex pattern.</p> +<p>A guest spec has three fields: <em><PARSER></em>, <em><START></em> of area, and <em><END></em> of area. +The <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag has following forms:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">_guest</span><span class="o">=<</span><span class="n">PARSER</span><span class="o">></span><span class="p">,</span><span class="o"><</span><span class="n">START</span><span class="o">></span><span class="p">,</span><span class="o"><</span><span class="n">END</span><span class="o">></span><span class="p">}</span> +</pre></div> +</div> +<p>ctags maintains a data called <em>guest request</em> during parsing. A +guest request also has three fields: <cite>parser</cite>, <cite>start of area</cite>, and +<cite>end of area</cite>.</p> +<p>You, a parser developer, have to fill the fields of guest specs. +ctags inquiries the guest spec when matching the regex pattern +associated with it, tries to fill the fields of the guest request, +and runs a guest parser when all the fields of the guest request are +filled.</p> +<p>If you use <a class="reference internal" href="#multi-line-pattern-match">Multi-line pattern match</a> to define a host parser, +you must specify all the fields of <cite>guest request</cite>.</p> +<p>On the other hand if you don’t use <a class="reference internal" href="#multi-line-pattern-match">Multi-line pattern match</a> to define a host parser, +ctags can fill fields of <cite>guest request</cite> incrementally; more than +one guest specs are used to fill the fields. In other words, you can +make some of the fields of a guest spec empty.</p> +<section id="the-parser-field-of-guest-regex-flag"> +<h3><a class="toc-backref" href="#id25">The <em><PARSER></em> field of <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag</a><a class="headerlink" href="#the-parser-field-of-guest-regex-flag" title="Permalink to this headline">¶</a></h3> +<p>For <em><PARSER></em>, you can specify one of the following items:</p> +<p>a name of a parser</p> +<blockquote> +<div><p>If you know the guest parser you want to run before parsing +the input file, specify the name of the parser.</p> +<p>An example of running C parser as a guest parser:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">_guest</span><span class="o">=</span><span class="n">C</span><span class="p">,</span><span class="o">...</span> +</pre></div> +</div> +</div></blockquote> +<p>the group number of a regex pattern started from ‘<code class="docutils literal notranslate"><span class="pre">\</span></code>’ (backslash)</p> +<blockquote> +<div><p>If a parser name appears in an input file, write a regex pattern +to capture the name. Specify the group number where the name is +stored to the parser. In such case, use ‘<code class="docutils literal notranslate"><span class="pre">\</span></code>’ as the prefix for +the number.</p> +<p>Let’s see an example. Git Flavor Markdown (GFM) is a language for +documentation. It provides a notation for quoting a snippet of +program code; the language treats the area started from <code class="docutils literal notranslate"><span class="pre">~~~</span></code> to +<code class="docutils literal notranslate"><span class="pre">~~~</span></code> as a snippet. You can specify a programming language of +the snippet with starting the area with +<code class="docutils literal notranslate"><span class="pre">~~~<THE_NAME_OF_LANGUAGE></span></code>, like <code class="docutils literal notranslate"><span class="pre">~~~C</span></code> or <code class="docutils literal notranslate"><span class="pre">~~~Java</span></code>.</p> +<p>To run a guest parser on the area, you have to capture the +<em><THE_NAME_OF_LANGUAGE></em> with a regex pattern:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--_mtable-regex-</span><span class="nn">Markdown</span><span class="p">=</span><span class="nf">main</span>/~~~([a-zA-Z0-9][-#+a-zA-Z0-9]*)[\n]//{_guest=\1,0end,} +</pre></div> +</div> +<p>The pattern captures the language name in the input file with the +regex group 1, and specify it to <em><PARSER></em>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">guest</span><span class="o">=</span>\<span class="mi">1</span><span class="p">,</span><span class="o">...</span> +</pre></div> +</div> +</div></blockquote> +<p>the group number of a regex pattern started from ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ (asterisk)</p> +<blockquote> +<div><p>If a file name implying a programming language appears in an input +file, capture the file name with the regex pattern where the guest +spec attaches to. ctags tries to find a proper parser for the +file name by inquiring the langmap.</p> +<p>Use ‘<code class="docutils literal notranslate"><span class="pre">*</span></code>’ as the prefix to the number for specifying the group of +the regex pattern that captures the file name.</p> +<p>Let’s see an example. Consider you have a shell script that emits +a program code instantiated from one of the templates. Here documents +are used to represent the templates like:</p> +<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nv">i</span><span class="o">=</span>... +cat > foo.c <span class="s"><<EOF</span> +<span class="s"> int main (void) { return $i; }</span> +<span class="s">EOF</span> + +cat > foo.el <span class="s"><<EOF</span> +<span class="s"> (defun foo () (1+ $i))</span> +<span class="s">EOF</span> +</pre></div> +</div> +<p>To run guest parsers for the here document areas, the shell +script parser of ctags must choose the parsers from the file +names (<code class="docutils literal notranslate"><span class="pre">foo.c</span></code> and <code class="docutils literal notranslate"><span class="pre">foo.el</span></code>):</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kd">--regex-</span><span class="nn">sh</span><span class="p">=</span>/cat > ([a-z.]+) <<EOF//{_guest=*1,0end,} +</pre></div> +</div> +<p>The pattern captures the file name in the input file with the +regex group 1, and specify it to <em><PARSER></em>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">_guest</span><span class="o">=*</span><span class="mi">1</span><span class="p">,</span><span class="o">...</span> +</pre></div> +</div> +</div></blockquote> +</section> +<section id="the-start-and-end-fields-of-guest-regex-flag"> +<h3><a class="toc-backref" href="#id26">The <em><START></em> and <em><END></em> fields of <cite>_guest</cite> regex flag</a><a class="headerlink" href="#the-start-and-end-fields-of-guest-regex-flag" title="Permalink to this headline">¶</a></h3> +<p>The <em><START></em> and <em><END></em> fields specify the area the <em><PARSER></em> parses. <em><START></em> +specifies the start of the area. <em><END></em> specifies the end of the area.</p> +<p>The forms of the two fields are the same: a regex group number +followed by <code class="docutils literal notranslate"><span class="pre">start</span></code> or <code class="docutils literal notranslate"><span class="pre">end</span></code>. e.g. <code class="docutils literal notranslate"><span class="pre">3start</span></code>, <code class="docutils literal notranslate"><span class="pre">0end</span></code>. The suffixes, +<code class="docutils literal notranslate"><span class="pre">start</span></code> and <code class="docutils literal notranslate"><span class="pre">end</span></code>, represents one of two boundaries of the group.</p> +<p>Let’s see an example:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="n">_guest</span><span class="o">=</span><span class="n">C</span><span class="p">,</span><span class="mi">2</span><span class="n">end</span><span class="p">,</span><span class="mi">3</span><span class="n">start</span><span class="p">}</span> +</pre></div> +</div> +<p>This guest regex flag means running C parser on the area between +<code class="docutils literal notranslate"><span class="pre">2end</span></code> and <code class="docutils literal notranslate"><span class="pre">3start</span></code>. <code class="docutils literal notranslate"><span class="pre">2end</span></code> means the area starts from the end of +matching of the 2nd regex group associated with the flag. <code class="docutils literal notranslate"><span class="pre">3start</span></code> +means the area ends at the beginning of matching of the 3rd regex +group associated with the flag.</p> +<p>Let’s more realistic example. +Here is an optlib file for an imaginary language <cite>single</cite>:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="kn">--langdef</span><span class="p">=</span><span class="nn">single</span> +<span class="kd">--map-</span><span class="nn">single</span><span class="p">=</span>.single +<span class="hll"><span class="kd">--regex-</span><span class="nn">single</span><span class="p">=</span>/^(BEGIN_C<).*(>END_C)$//{_guest=C,1end,2start} +</span></pre></div> +</div> +<p>This parser can run C parser and extract <code class="docutils literal notranslate"><span class="pre">main</span></code> function from the +following input file:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>BEGIN_C<int main (int argc, char **argv) { return 0; }>END_C + ^ ^ + `- "1end" points here. | + "2start" points here. -+ +</pre></div> +</div> +</section> +</section> +<section id="defining-a-subparser"> +<span id="defining-subparsers"></span><h2><a class="toc-backref" href="#id27">Defining a subparser</a><a class="headerlink" href="#defining-a-subparser" title="Permalink to this headline">¶</a></h2> +<section id="basic"> +<h3><a class="toc-backref" href="#id28">Basic</a><a class="headerlink" href="#basic" title="Permalink to this headline">¶</a></h3> +<p>About the concept of subparser, see “<a class="reference internal" href="running-multi-parsers.html#base-sub-parsers"><span class="std std-ref">Subparser: Tagging definitions of higher (upper) level language</span></a>”.</p> +<p><code class="docutils literal notranslate"><span class="pre">--langdef=<LANG></span></code> option is extended as +<code class="docutils literal notranslate"><span class="pre">--langdef=<LANG>[{base=<LANG>}[{shared|dedicated|bidirectional}]][{_autoFQTag}]</span></code> to define +a subparser for a specified base parser. Combining with <code class="docutils literal notranslate"><span class="pre">--kinddef-<LANG></span></code> +and <code class="docutils literal notranslate"><span class="pre">--regex-<KIND></span></code> options, you can extend an existing parser +without risk of kind confliction.</p> +<p>Let’s see an example.</p> +<p>input.c</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span> <span class="nf">set_one_prio</span><span class="p">(</span><span class="k">struct</span> <span class="nc">task_struct</span> <span class="o">*</span><span class="n">p</span><span class="p">,</span> <span class="kt">int</span> <span class="n">niceval</span><span class="p">,</span> <span class="kt">int</span> <span class="n">error</span><span class="p">)</span> +<span class="p">{</span> +<span class="p">}</span> + +<span class="n">SYSCALL_DEFINE3</span><span class="p">(</span><span class="n">setpriority</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">which</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">who</span><span class="p">,</span> <span class="kt">int</span><span class="p">,</span> <span class="n">niceval</span><span class="p">)</span> +<span class="p">{</span> + <span class="p">...;</span> +<span class="p">}</span> +</pre></div> +</div> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -x --_xformat<span class="o">=</span><span class="s2">"%20N %10K %10l"</span> -o - input.c +<span class="go"> set_one_prio function C</span> +<span class="go"> SYSCALL_DEFINE3 function C</span> +</pre></div> +</div> +<p>C parser doesn’t understand that <code class="docutils literal notranslate"><span class="pre">SYSCALL_DEFINE3</span></code> is a macro for defining an +entry point for a system.</p> +<p>Let’s define <cite>linux</cite> subparser which using C parser as a base parser (<code class="docutils literal notranslate"><span class="pre">linux.ctags</span></code>):</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="kn">--langdef</span><span class="p">=</span><span class="nn">linux</span>{base=C} +</span><span class="kd">--kinddef-</span><span class="nn">linux</span><span class="p">=</span><span class="ni">s</span><span class="p">,</span><span class="ni">syscall</span><span class="p">,</span><span class="sd">system calls</span> +<span class="hll"><span class="kd">--regex-</span><span class="nn">linux</span><span class="p">=</span>/SYSCALL_DEFINE[0-9]\(([^, )]+)[\),]*/\1/s/ +</span></pre></div> +</div> +<p>The output is change as follows with <cite>linux</cite> parser:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --options<span class="o">=</span>./linux.ctags -x --_xformat<span class="o">=</span><span class="s2">"%20N %10K %10l"</span> -o - input.c +<span class="hll"><span class="go"> setpriority syscall linux</span> +</span><span class="go"> set_one_prio function C</span> +<span class="go"> SYSCALL_DEFINE3 function C</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">setpriority</span></code> is recognized as a <code class="docutils literal notranslate"><span class="pre">syscall</span></code> of <cite>linux</cite>.</p> +<p>Using only <code class="docutils literal notranslate"><span class="pre">--regex-C=...</span></code> you can capture <code class="docutils literal notranslate"><span class="pre">setpriority</span></code>. +However, there were concerns about kind confliction; when introducing +a new kind with <code class="docutils literal notranslate"><span class="pre">--regex-C=...</span></code>, you cannot use a letter and name already +used in C parser and <code class="docutils literal notranslate"><span class="pre">--regex-C=...</span></code> options specified in the other places.</p> +<p>You can use a newly defined subparser as a new namespace of kinds. +In addition you can enable/disable with the subparser usable +<code class="docutils literal notranslate"><span class="pre">--languages=[+|-]</span></code> option:</p> +</section> +<section id="direction-flags"> +<span id="optlib-directions"></span><h3><a class="toc-backref" href="#id29">Direction flags</a><a class="headerlink" href="#direction-flags" title="Permalink to this headline">¶</a></h3> +<p>As explained in “<a class="reference internal" href="running-multi-parsers.html#multiple-parsers-directions"><span class="std std-ref">Direction flags</span></a>” in +“<a class="reference internal" href="running-multi-parsers.html#multiple-parsers"><span class="std std-ref">Running multiple parsers on an input file</span></a>”, you can choose direction(s) how a base parser and a +guest parser work together with direction flags.</p> +<p>The following examples are taken from <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/1409">#1409</a> submitted by @sgraham on +github Universal Ctags repository.</p> +<p><code class="docutils literal notranslate"><span class="pre">input.cc</span></code> and <code class="docutils literal notranslate"><span class="pre">input.mojom</span></code> are input files, and have the same +contents:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ABC</span><span class="p">();</span> +<span class="nb">int</span> <span class="n">main</span><span class="p">(</span><span class="n">void</span><span class="p">)</span> +<span class="p">{</span> +<span class="p">}</span> +</pre></div> +</div> +<p>C++ parser can capture <code class="docutils literal notranslate"><span class="pre">main</span></code> as a function. <cite>Mojom</cite> subparser defined in the +later runs on C++ parser and is for capturing <code class="docutils literal notranslate"><span class="pre">ABC</span></code>.</p> +<section id="shared-combination"> +<h4><a class="toc-backref" href="#id30">shared combination</a><a class="headerlink" href="#shared-combination" title="Permalink to this headline">¶</a></h4> +<p><code class="docutils literal notranslate"><span class="pre">{shared}</span></code> is specified, for <code class="docutils literal notranslate"><span class="pre">input.cc</span></code>, both tags capture by C++ parser +and mojom parser are recorded to tags file. For <code class="docutils literal notranslate"><span class="pre">input.mojom</span></code>, only +tags captured by mojom parser are recorded to tags file.</p> +<p>mojom-shared.ctags:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="kn">--langdef</span><span class="p">=</span><span class="nn">mojom</span>{base=C++}{shared} +</span><span class="kd">--map-</span><span class="nn">mojom</span><span class="p">=+</span>.mojom +<span class="kd">--kinddef-</span><span class="nn">mojom</span><span class="p">=</span><span class="ni">f</span><span class="p">,</span><span class="ni">function</span><span class="p">,</span><span class="sd">functions</span> +<span class="kd">--regex-</span><span class="nn">mojom</span><span class="p">=</span>/^[ ]+([a-zA-Z]+)\(/\1/f/ +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>$ ctags --options=mojom-shared.ctags --fields=+l -o - input.cc +<span class="hll">ABC input.cc /^ ABC();$/;" f language:mojom +</span>main input.cc /^int main(void)$/;" f language:C++ typeref:typename:int +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>$ ctags --options=mojom-shared.ctags --fields=+l -o - input.mojom +<span class="hll">ABC input.mojom /^ ABC();$/;" f language:mojom +</span></pre></div> +</div> +<p>Mojom parser uses C++ parser internally but tags captured by C++ parser are +dropped in the output.</p> +</section> +<section id="dedicated-combination"> +<h4><a class="toc-backref" href="#id31">dedicated combination</a><a class="headerlink" href="#dedicated-combination" title="Permalink to this headline">¶</a></h4> +<p><code class="docutils literal notranslate"><span class="pre">{dedicated}</span></code> is specified, for <code class="docutils literal notranslate"><span class="pre">input.cc</span></code>, only tags capture by C++ +parser are recorded to tags file. For <code class="docutils literal notranslate"><span class="pre">input.mojom</span></code>, both tags capture +by C++ parser and mojom parser are recorded to tags file.</p> +<p>mojom-dedicated.ctags:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="kn">--langdef</span><span class="p">=</span><span class="nn">mojom</span>{base=C++}{dedicated} +</span><span class="kd">--map-</span><span class="nn">mojom</span><span class="p">=+</span>.mojom +<span class="kd">--kinddef-</span><span class="nn">mojom</span><span class="p">=</span><span class="ni">f</span><span class="p">,</span><span class="ni">function</span><span class="p">,</span><span class="sd">functions</span> +<span class="kd">--regex-</span><span class="nn">mojom</span><span class="p">=</span>/^[ ]+([a-zA-Z]+)\(/\1/f/ +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>$ ctags --options=mojom-dedicated.ctags --fields=+l -o - input.cc +main input.cc /^int main(void)$/;" f language:C++ typeref:typename:int +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>$ ctags --options=mojom-dedicated.ctags --fields=+l -o - input.mojom +<span class="hll">ABC input.mojom /^ ABC();$/;" f language:mojom +</span><span class="hll">main input.mojom /^int main(void)$/;" f language:C++ typeref:typename:int +</span></pre></div> +</div> +<p>Mojom parser works only when <code class="docutils literal notranslate"><span class="pre">.mojom</span></code> file is given as input.</p> +</section> +<section id="bidirectional-combination"> +<h4><a class="toc-backref" href="#id32">bidirectional combination</a><a class="headerlink" href="#bidirectional-combination" title="Permalink to this headline">¶</a></h4> +<p><code class="docutils literal notranslate"><span class="pre">{bidirectional}</span></code> is specified, both tags capture by C++ parser and +mojom parser are recorded to tags file for either input <code class="docutils literal notranslate"><span class="pre">input.cc</span></code> and +<code class="docutils literal notranslate"><span class="pre">input.mojom</span></code>.</p> +<p>mojom-bidirectional.ctags:</p> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span><span class="hll"><span class="kn">--langdef</span><span class="p">=</span><span class="nn">mojom</span>{base=C++}{bidirectional} +</span><span class="kd">--map-</span><span class="nn">mojom</span><span class="p">=+</span>.mojom +<span class="kd">--kinddef-</span><span class="nn">mojom</span><span class="p">=</span><span class="ni">f</span><span class="p">,</span><span class="ni">function</span><span class="p">,</span><span class="sd">functions</span> +<span class="kd">--regex-</span><span class="nn">mojom</span><span class="p">=</span>/^[ ]+([a-zA-Z]+)\(/\1/f/ +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>$ ctags --options=mojom-bidirectional.ctags --fields=+l -o - input.cc +<span class="hll">ABC input.cc /^ ABC();$/;" f language:mojom +</span>main input.cc /^int main(void)$/;" f language:C++ typeref:typename:int +</pre></div> +</div> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>$ ctags --options=mojom-bidirectional.ctags --fields=+l -o - input.mojom +<span class="hll">ABC input.cc /^ ABC();$/;" f language:mojom +</span><span class="hll">main input.cc /^int main(void)$/;" f language:C++ typeref:typename:int +</span></pre></div> +</div> +</section> +</section> +</section> +<section id="translating-an-option-file-into-c-source-code-optlib2c"> +<span id="optlib2c"></span><h2><a class="toc-backref" href="#id33">Translating an option file into C source code (optlib2c)</a><a class="headerlink" href="#translating-an-option-file-into-c-source-code-optlib2c" title="Permalink to this headline">¶</a></h2> +<p>Universal Ctags has an <code class="docutils literal notranslate"><span class="pre">optlib2c</span></code> script that translates an option file into C +source code. Your optlib parser can thus easily become a built-in parser.</p> +<p>To add your optlib file, <code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code>, into ctags do the following steps;</p> +<ul class="simple"> +<li><p>copy <code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code> file on <code class="docutils literal notranslate"><span class="pre">optlib/</span></code> directory</p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">foo.ctags</span></code> on <code class="docutils literal notranslate"><span class="pre">OPTLIB2C_INPUT</span></code> variable in <code class="docutils literal notranslate"><span class="pre">makefiles/optlib2c_input.mak</span></code></p></li> +<li><p>add <code class="docutils literal notranslate"><span class="pre">fooParser</span></code> on <code class="docutils literal notranslate"><span class="pre">PARSER_LIST</span></code> macro variable in <code class="docutils literal notranslate"><span class="pre">main/parser_p.h</span></code></p></li> +</ul> +<p>You are encouraged to submit your <code class="file docutils literal notranslate"><span class="pre">.ctags</span></code> file to our repository on +github through a pull request. See “<a class="reference internal" href="contributions.html#contributions"><span class="std std-ref">Contributions</span></a>” for more details.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Extending ctags with Regex parser (<em>optlib</em>)</a><ul> +<li><a class="reference internal" href="#regular-expression-regex-engine">Regular expression (regex) engine</a></li> +<li><a class="reference internal" href="#regex-option-argument-flags">Regex option argument flags</a><ul> +<li><a class="reference internal" href="#regex-control-flags">Regex control flags</a></li> +<li><a class="reference internal" href="#exclusive-flag-in-regex">Exclusive flag in regex</a></li> +<li><a class="reference internal" href="#experimental-flags">Experimental flags</a><ul> +<li><a class="reference internal" href="#conditional-tagging-with-extras">Conditional tagging with extras</a></li> +<li><a class="reference internal" href="#adding-custom-fields-to-the-tag-output">Adding custom fields to the tag output</a></li> +<li><a class="reference internal" href="#capturing-reference-tags">Capturing reference tags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#scope-tracking-in-a-regex-parser">Scope tracking in a regex parser</a></li> +</ul> +</li> +<li><a class="reference internal" href="#overriding-the-letter-for-file-kind">Overriding the letter for file kind</a></li> +<li><a class="reference internal" href="#generating-fully-qualified-tags-automatically-from-scope-information">Generating fully qualified tags automatically from scope information</a><ul> +<li><a class="reference internal" href="#customizing-scope-separators">Customizing scope separators</a></li> +</ul> +</li> +<li><a class="reference internal" href="#multi-line-pattern-match">Multi-line pattern match</a><ul> +<li><a class="reference internal" href="#multiline-pattern-flags">Multiline pattern flags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#advanced-pattern-matching-with-multiple-regex-tables">Advanced pattern matching with multiple regex tables</a><ul> +<li><a class="reference internal" href="#declaring-a-new-regex-table">Declaring a new regex table</a></li> +<li><a class="reference internal" href="#adding-a-regex-to-a-regex-table">Adding a regex to a regex table</a></li> +<li><a class="reference internal" href="#skipping-block-comments">Skipping block comments</a></li> +<li><a class="reference internal" href="#capturing-variables-in-a-sequence">Capturing variables in a sequence</a></li> +<li><a class="reference internal" href="#running-our-example">Running our example</a></li> +</ul> +</li> +<li><a class="reference internal" href="#scheduling-a-guest-parser-with-guest-regex-flag">Scheduling a guest parser with <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag</a><ul> +<li><a class="reference internal" href="#the-parser-field-of-guest-regex-flag">The <em><PARSER></em> field of <code class="docutils literal notranslate"><span class="pre">_guest</span></code> regex flag</a></li> +<li><a class="reference internal" href="#the-start-and-end-fields-of-guest-regex-flag">The <em><START></em> and <em><END></em> fields of <cite>_guest</cite> regex flag</a></li> +</ul> +</li> +<li><a class="reference internal" href="#defining-a-subparser">Defining a subparser</a><ul> +<li><a class="reference internal" href="#basic">Basic</a></li> +<li><a class="reference internal" href="#direction-flags">Direction flags</a><ul> +<li><a class="reference internal" href="#shared-combination">shared combination</a></li> +<li><a class="reference internal" href="#dedicated-combination">dedicated combination</a></li> +<li><a class="reference internal" href="#bidirectional-combination">bidirectional combination</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#translating-an-option-file-into-c-source-code-optlib2c">Translating an option file into C source code (optlib2c)</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="news.html" + title="previous chapter">Other changes</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="optscript.html" + title="next chapter">Optscript, a programming language for extending optlib parsers</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="optscript.html" title="Optscript, a programming language for extending optlib parsers" + >next</a> |</li> + <li class="right" > + <a href="news.html" title="Other changes" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Extending ctags with Regex parser (<em>optlib</em>)</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/optscript.html b/ctags/docs/optscript.html new file mode 100644 index 0000000..158f633 --- /dev/null +++ b/ctags/docs/optscript.html @@ -0,0 +1,425 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Optscript, a programming language for extending optlib parsers — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Extending ctags with a parser written in C" href="extending.html" /> + <link rel="prev" title="Extending ctags with Regex parser (optlib)" href="optlib.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="extending.html" title="Extending ctags with a parser written in C" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="optlib.html" title="Extending ctags with Regex parser (optlib)" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Optscript, a programming language for extending optlib parsers</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="optscript-a-programming-language-for-extending-optlib-parsers"> +<span id="optscript"></span><h1>Optscript, a programming language for extending optlib parsers<a class="headerlink" href="#optscript-a-programming-language-for-extending-optlib-parsers" title="Permalink to this headline">¶</a></h1> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#preparation-for-learning" id="id1">Preparation for learning</a></p></li> +<li><p><a class="reference internal" href="#syntax-extension" id="id2">Syntax extension</a></p></li> +<li><p><a class="reference internal" href="#the-optscript-command" id="id3">The <code class="docutils literal notranslate"><span class="pre">optscript</span></code> command</a></p></li> +<li><p><a class="reference internal" href="#optscript-in-ctags" id="id4">Optscript in ctags</a></p> +<ul> +<li><p><a class="reference internal" href="#related-options" id="id5">Related options</a></p></li> +<li><p><a class="reference internal" href="#operators" id="id6">Operators</a></p></li> +<li><p><a class="reference internal" href="#data-types" id="id7">Data types</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#recipes" id="id8">Recipes</a></p></li> +<li><p><a class="reference internal" href="#difference-between-optscript-and-postscript" id="id9">Difference between Optscript and PostScript</a></p></li> +</ul> +</div> +<section id="preparation-for-learning"> +<h2><a class="toc-backref" href="#id1">Preparation for learning</a><a class="headerlink" href="#preparation-for-learning" title="Permalink to this headline">¶</a></h2> +<p><strong>Optscript</strong> is an implementation of PostScript(tm) alike stack +oriented general purpose programming language. Developers of optlib +parsers can utilize the language for extending their parsers.</p> +<p>You may not be familiar with a stack oriented programming language. +Though there are some differences, the syntax and core non-graphical +operators of Optscript and PostScript are the same. You can get the +basic knowledge for using Optscript from the materials for learning +PostScript.</p> +<p>“PostScript Language Tutorial & Cookbook” published by Adobe Systems +Inc. The book is known as “blue book”. This is the best place to +start. PostScript is a language for controlling printers. So it has +many graphical operators. Optscript is for tagging, and doesn’t have +such graphical operators. So you can skip the sections about graphics +(but you may want to read them because the book is written well).</p> +<p>Ghostscript (<code class="docutils literal notranslate"><span class="pre">gs</span></code> or <code class="docutils literal notranslate"><span class="pre">gsnd</span></code>) is an interpreter for the PostScript +language and PDF files. Unlike Optscript, it implements the full-set of +PostScript features including graphical operators. It is available +under either the GNU GPL Affero license. You can Ghostscript while +reading the blue book. Do web searching to know about Ghostscript.</p> +<p><code class="docutils literal notranslate"><span class="pre">optscript</span></code> is an command that source files are included in +Universal Ctags source tree. You can use it as the replacement of +<code class="docutils literal notranslate"><span class="pre">gs</span></code>. However, I recommend you to have <code class="docutils literal notranslate"><span class="pre">gs</span></code> at hand because +<code class="docutils literal notranslate"><span class="pre">optscript</span></code> may have bugs. <code class="docutils literal notranslate"><span class="pre">gs</span></code> is much mature than <code class="docutils literal notranslate"><span class="pre">optscript</span></code>. +Having two interpreters helps you to know correct behavior.</p> +<p>Though <code class="docutils literal notranslate"><span class="pre">gs</span></code> has much higher qualities than <code class="docutils literal notranslate"><span class="pre">optscript</span></code>, eventually +you may have to build the <code class="docutils literal notranslate"><span class="pre">optscript</span></code> command to learn Optscript +specific operators. You can built the command with “<code class="docutils literal notranslate"><span class="pre">make</span> +<span class="pre">optscript</span></code>”.</p> +<ul> +<li><p>red book</p> +<p>TBW</p> +</li> +</ul> +</section> +<section id="syntax-extension"> +<h2><a class="toc-backref" href="#id2">Syntax extension</a><a class="headerlink" href="#syntax-extension" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">?</span></code> is a prefix for representing a character literal.</p> +<p>For an example, <code class="docutils literal notranslate"><span class="pre">?x</span></code> represents 120. This is a short cut for <code class="docutils literal notranslate"><span class="pre">(x)</span> <span class="pre">0</span> +<span class="pre">get</span></code>.</p> +<p>Some characters has special notation using <code class="docutils literal notranslate"><span class="pre">\</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">?\t</span></code></p> +<blockquote> +<div><p>tab</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">?\n</span></code></p> +<blockquote> +<div><p>newline</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">?\_</span></code></p> +<blockquote> +<div><p>space</p> +</div></blockquote> +</section> +<section id="the-optscript-command"> +<h2><a class="toc-backref" href="#id3">The <code class="docutils literal notranslate"><span class="pre">optscript</span></code> command</a><a class="headerlink" href="#the-optscript-command" title="Permalink to this headline">¶</a></h2> +<p>You can run optscript with no argument:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./optsript +<span class="go">OPT></span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">OPT></span></code> is the prompt of the interpreter. +You can stop it with <code class="docutils literal notranslate"><span class="pre">quit</span></code> operator:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>./optsript +<span class="go">OPT> quit</span> +<span class="gp">$</span> +</pre></div> +</div> +<p>Let’s see some example sessions. To help you understand the session +easily, Python sessions doing the same as Optscript are also written.</p> +<ul> +<li><p>hello world</p> +<p>Optscript:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">OPT> (hello, world) =</span> +<span class="go">hello, world</span> +</pre></div> +</div> +<p>Python:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">>>> print ('hello, world')</span> +<span class="go">hello, world</span> +</pre></div> +</div> +</li> +<li><p>Adding</p> +<p>Optscript:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">OPT> 2 3 add =</span> +<span class="go">5</span> +</pre></div> +</div> +<p>Python:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">>>> print (2 + 3)</span> +<span class="go">5</span> +</pre></div> +</div> +</li> +<li><p>Variables</p> +<p>Optscript:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">OPT> /x 2 def</span> +<span class="go">OPT> /y 3 def</span> +<span class="go">OPT> x y add =</span> +<span class="go">5</span> +</pre></div> +</div> +<p>Python:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">>>> x = 2</span> +<span class="go">>>> y = 3</span> +<span class="go">>>> print (x + y)</span> +<span class="go">5</span> +</pre></div> +</div> +</li> +<li><p>Procedures</p> +<p>Optscript:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">OPT> /add5_and_print { 5 add = } def</span> +<span class="go">OPT> 4 add5_and_print</span> +<span class="go">9</span> +</pre></div> +</div> +<p>Python:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">>>> def add5_and_print(x):</span> +<span class="go">... print(x + 5);</span> +<span class="go">>>> add5_and_print(4)</span> +<span class="go">9</span> +</pre></div> +</div> +</li> +<li><p>string manipulation</p> +<p>TBW</p> +</li> +<li><p>array manipulation</p> +<p>TBW</p> +</li> +<li><p>dict manipulation</p> +<p>TBW</p> +</li> +<li><p>control flow</p> +<p>TBW</p> +</li> +<li><p>operators for printing</p> +<p>TBW</p> +</li> +<li><p>reading script from file</p> +<p>TBW</p> +</li> +</ul> +</section> +<section id="optscript-in-ctags"> +<h2><a class="toc-backref" href="#id4">Optscript in ctags</a><a class="headerlink" href="#optscript-in-ctags" title="Permalink to this headline">¶</a></h2> +<section id="related-options"> +<h3><a class="toc-backref" href="#id5">Related options</a><a class="headerlink" href="#related-options" title="Permalink to this headline">¶</a></h3> +<div class="highlight-ctags notranslate"><div class="highlight"><pre><span></span>--_prelude-<LANG>={{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--_sequel-<LANG>={{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--regex-<LANG>=<PATTERN>/<NAME>/[<KIND>/]LONGFLAGS...{{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--regex-<LANG>=<PATTERN>//LONGFLAGS...{{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--mline-regex-<LANG>=<PATTERN>/<NAME>/[<KIND>/]LONGFLAGS...{{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--mline-regex-<LANG>=<PATTERN>//LONGFLAGS...{{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--_mtable-regex-<LANG>=<TABLE>/<PATTERN>/<NAME>/[<KIND>/]LONGFLAGS...{{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--_mtable-regex-<LANG>=<TABLE>/<PATTERN>//LONGFLAGS...{{ +<span class="w"> </span>OPTSCRIPT CODE FRAGMENTS +}} + +--_list-operators + +--list-fields +</pre></div> +</div> +<p>You can run optscript code fragments when pattern specified with +options matches successfully. The options are <code class="docutils literal notranslate"><span class="pre">--regex-<LANG></span></code>, +<code class="docutils literal notranslate"><span class="pre">--mline-regex-<LANG></span></code>, and <code class="docutils literal notranslate"><span class="pre">--_mtable-regex-<LANG></span></code> as you +expect. In addition, <code class="docutils literal notranslate"><span class="pre">--_prelude-<LANG></span></code> and <code class="docutils literal notranslate"><span class="pre">--_sequel-<LANG></span></code> +options also take code fragments.</p> +<p>TBW: two timings of evaluation</p> +<p>Put code fragments at the end of options with surrounding “<code class="docutils literal notranslate"><span class="pre">{{</span></code>” and +“<code class="docutils literal notranslate"><span class="pre">}}</span></code>”. Though it is not impossible, a command line is not suitable +place to put code fragments because the code fragments may be long. +Instead, you should write them to a .ctags file.</p> +<div class="admonition warning"> +<p class="admonition-title">Warning</p> +<p>An important rule in writing Optscript code in a file is +the start marker, <code class="docutils literal notranslate"><span class="pre">{{</span></code> must be at the end of line, and the end +marker <code class="docutils literal notranslate"><span class="pre">}}</span></code> must be at the beginning of line. If you break the +rule, the optlib loader of ctags fails to read your file.</p> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--_prelude-<LANG></span></code> is for specified code fragments run at the +beginning of parsing a source file. You can use this option for +defining the common code used in the parser.</p> +<p><code class="docutils literal notranslate"><span class="pre">--_sequel-<LANG></span></code> is for for specified code fragments run at the end +of parser a source file. You can use this option for debug-printing +the final state of parsing the source file. +e.g. <code class="docutils literal notranslate"><span class="pre">--_sequel-Foo={{</span> <span class="pre">_traced</span> <span class="pre">{</span> <span class="pre">pstack</span> <span class="pre">}</span> <span class="pre">if</span> <span class="pre">}}</span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">--_list-operators</span></code> lists all operators (and built-in procedures) +and exits. In additions to operators defined in <code class="docutils literal notranslate"><span class="pre">optscript</span></code>, +<code class="docutils literal notranslate"><span class="pre">ctags</span></code> provides operators for tagging.</p> +<p><code class="docutils literal notranslate"><span class="pre">OP</span></code> column of <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> represents the availability of +operators for accessing the field specified in the line. <code class="docutils literal notranslate"><span class="pre">r</span></code> +represents the field has an operator for reading +(<code class="docutils literal notranslate"><span class="pre">:fieldname</span></code>). <code class="docutils literal notranslate"><span class="pre">w</span></code> represents the field has an operator for +writing (<code class="docutils literal notranslate"><span class="pre">fieldname:</span></code>).</p> +</section> +<section id="operators"> +<h3><a class="toc-backref" href="#id6">Operators</a><a class="headerlink" href="#operators" title="Permalink to this headline">¶</a></h3> +<p><strong>.</strong> -> <code class="docutils literal notranslate"><span class="pre">-</span></code> <strong>.</strong> <code class="docutils literal notranslate"><span class="pre">corkIndex:int</span></code></p> +<blockquote> +<div><p>Push the cork index for the tag</p> +</div></blockquote> +<p><strong>\n</strong> -> <code class="docutils literal notranslate"><span class="pre">-</span></code> <strong>\n</strong> <code class="docutils literal notranslate"><span class="pre">matchedString:string</span></code></p> +<blockquote> +<div><p><code class="docutils literal notranslate"><span class="pre">n</span></code> is an integer (0…9) representing a group in a pattern. +Push the matched string for the group.</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">_matchloc</span></code></p> +<blockquote> +<div><p>TBW</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">:field</span></code> (See the output of <code class="docutils literal notranslate"><span class="pre">--_list-operators</span></code>)</p> +<blockquote> +<div><dl class="simple"> +<dt>Get the value for the specified field from a tag</dt><dd><p>and put it.</p> +</dd> +</dl> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">field:</span></code> (See the output of <code class="docutils literal notranslate"><span class="pre">--_list-operators</span></code>)</p> +<blockquote> +<div><p>Set a value at the stack to the specified field of a tag.</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">_tag</span></code></p> +<blockquote> +<div><p>TBW</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">_COMMIT</span></code></p> +<blockquote> +<div><p>TBW</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">_traced</span></code></p> +<blockquote> +<div><p>TBW</p> +</div></blockquote> +</section> +<section id="data-types"> +<h3><a class="toc-backref" href="#id7">Data types</a><a class="headerlink" href="#data-types" title="Permalink to this headline">¶</a></h3> +<p><code class="docutils literal notranslate"><span class="pre">MATCHLOC</span></code></p> +<blockquote> +<div><p>TBW</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">index:int</span></code></p> +<blockquote> +<div><p>TBW</p> +</div></blockquote> +<p><code class="docutils literal notranslate"><span class="pre">TAG</span></code></p> +<blockquote> +<div><p>TBW</p> +</div></blockquote> +</section> +</section> +<section id="recipes"> +<h2><a class="toc-backref" href="#id8">Recipes</a><a class="headerlink" href="#recipes" title="Permalink to this headline">¶</a></h2> +<p>TBW</p> +</section> +<section id="difference-between-optscript-and-postscript"> +<h2><a class="toc-backref" href="#id9">Difference between Optscript and PostScript</a><a class="headerlink" href="#difference-between-optscript-and-postscript" title="Permalink to this headline">¶</a></h2> +<ul class="simple"> +<li><p>Memory management</p></li> +<li><p>Dynamically extendable data type</p> +<ul> +<li><p>string</p></li> +<li><p>array</p></li> +</ul> +</li> +</ul> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Optscript, a programming language for extending optlib parsers</a><ul> +<li><a class="reference internal" href="#preparation-for-learning">Preparation for learning</a></li> +<li><a class="reference internal" href="#syntax-extension">Syntax extension</a></li> +<li><a class="reference internal" href="#the-optscript-command">The <code class="docutils literal notranslate"><span class="pre">optscript</span></code> command</a></li> +<li><a class="reference internal" href="#optscript-in-ctags">Optscript in ctags</a><ul> +<li><a class="reference internal" href="#related-options">Related options</a></li> +<li><a class="reference internal" href="#operators">Operators</a></li> +<li><a class="reference internal" href="#data-types">Data types</a></li> +</ul> +</li> +<li><a class="reference internal" href="#recipes">Recipes</a></li> +<li><a class="reference internal" href="#difference-between-optscript-and-postscript">Difference between Optscript and PostScript</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="optlib.html" + title="previous chapter">Extending ctags with Regex parser (<em>optlib</em>)</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="extending.html" + title="next chapter">Extending ctags with a parser written in C</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="extending.html" title="Extending ctags with a parser written in C" + >next</a> |</li> + <li class="right" > + <a href="optlib.html" title="Extending ctags with Regex parser (optlib)" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Optscript, a programming language for extending optlib parsers</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/osx.html b/ctags/docs/osx.html new file mode 100644 index 0000000..fb89401 --- /dev/null +++ b/ctags/docs/osx.html @@ -0,0 +1,165 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Building on Mac OS — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Man pages" href="man-pages.html" /> + <link rel="prev" title="Building/hacking/using on MS-Windows" href="windows.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="man-pages.html" title="Man pages" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="windows.html" title="Building/hacking/using on MS-Windows" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="building.html" accesskey="U">Building ctags</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building on Mac OS</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="building-on-mac-os"> +<h1>Building on Mac OS<a class="headerlink" href="#building-on-mac-os" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Cameron Eagans <<a class="reference external" href="mailto:me%40cweagans.net">me<span>@</span>cweagans<span>.</span>net</a>></p> +</dd> +</dl> +<hr class="docutils" /> +<p>This part of the documentation is written by Cameron Eagans, a co-maintainer of Universal Ctags and the maintainer of +the OSX packaging of this project.</p> +<section id="build-prerequisites"> +<h2>Build Prerequisites<a class="headerlink" href="#build-prerequisites" title="Permalink to this headline">¶</a></h2> +<p>Building ctags on OSX should be no different than building on GNU/Linux. The same toolchains are used, and the Mac OS +packaging scripts use autotools and make (as you’d expect).</p> +<p>You may need to install the xcode command line tools. You can install the entire xcode distribution from the App Store, +or for a lighter install, you can simply run <code class="docutils literal notranslate"><span class="pre">xcode-select</span> <span class="pre">--install</span></code> to <em>only</em> install the compilers and such. See +<a class="reference external" href="https://stackoverflow.com/a/9329325">https://stackoverflow.com/a/9329325</a> for more information. Once your build toolchain is installed, proceed to the next +section.</p> +<p>At this point, if you’d like to build from an IDE, you’ll have to figure it out. Building ctags is a pretty straightforward +process that matches many other projects and most decent IDEs should be able to handle it.</p> +<section id="building-manually-i-e-for-development"> +<h3>Building Manually (i.e. for development)<a class="headerlink" href="#building-manually-i-e-for-development" title="Permalink to this headline">¶</a></h3> +<p>You can simply run the build instructions in README.md.</p> +</section> +<section id="building-with-homebrew"> +<h3>Building with Homebrew<a class="headerlink" href="#building-with-homebrew" title="Permalink to this headline">¶</a></h3> +<p>Homebrew (<a class="reference external" href="https://brew.sh/">https://brew.sh/</a>) is the preferred method for installing Universal Ctags for end users. Currently, the process +for installing with Homebrew looks like this:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">brew</span> <span class="n">tap</span> <span class="n">universal</span><span class="o">-</span><span class="n">ctags</span><span class="o">/</span><span class="n">universal</span><span class="o">-</span><span class="n">ctags</span> +<span class="n">brew</span> <span class="n">install</span> <span class="o">--</span><span class="n">HEAD</span> <span class="n">universal</span><span class="o">-</span><span class="n">ctags</span> +</pre></div> +</div> +<p>Eventually, we hope to move the Universal-ctags formula to the main Homebrew repository, but since we don’t have any +tagged releases at this point, it’s a head-only formula and wouldn’t be accepted. When we have a tagged release, we’ll +submit a PR to Homebrew.</p> +<p>If you’d like to help with the Homebrew formula, you can find the repository here: +<a class="reference external" href="https://github.com/universal-ctags/homebrew-universal-ctags">https://github.com/universal-ctags/homebrew-universal-ctags</a></p> +</section> +</section> +<section id="differences-between-osx-and-gnu-linux"> +<h2>Differences between OSX and GNU/Linux<a class="headerlink" href="#differences-between-osx-and-gnu-linux" title="Permalink to this headline">¶</a></h2> +<p>There other things where building ctags on OSX differs from building on GNU/Linux.</p> +<ul class="simple"> +<li><p>Filenames on HFS+ (the Mac OS filesystem) are case-preserving, but not case-sensitive in 99% of configurations. If a +user manually formats their disk with a case sensitive version of HFS+, then the filesystem will behave like normal +GNU/Linux systems. Depending on users doing this is not a good thing.</p></li> +</ul> +</section> +<section id="contributing"> +<h2>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h2> +<p>This documentation is very much a work in progress. If you’d like to contribute, submit a PR and mention @cweagans for +review.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Building on Mac OS</a><ul> +<li><a class="reference internal" href="#build-prerequisites">Build Prerequisites</a><ul> +<li><a class="reference internal" href="#building-manually-i-e-for-development">Building Manually (i.e. for development)</a></li> +<li><a class="reference internal" href="#building-with-homebrew">Building with Homebrew</a></li> +</ul> +</li> +<li><a class="reference internal" href="#differences-between-osx-and-gnu-linux">Differences between OSX and GNU/Linux</a></li> +<li><a class="reference internal" href="#contributing">Contributing</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="windows.html" + title="previous chapter">Building/hacking/using on MS-Windows</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="man-pages.html" + title="next chapter">Man pages</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="man-pages.html" title="Man pages" + >next</a> |</li> + <li class="right" > + <a href="windows.html" title="Building/hacking/using on MS-Windows" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="building.html" >Building ctags</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building on Mac OS</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/other-projects.html b/ctags/docs/other-projects.html new file mode 100644 index 0000000..1eda28e --- /dev/null +++ b/ctags/docs/other-projects.html @@ -0,0 +1,811 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Relationship between other projects — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Who we are" href="developers.html" /> + <link rel="prev" title="Contributions" href="contributions.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="developers.html" title="Who we are" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="contributions.html" title="Contributions" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Relationship between other projects</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="relationship-between-other-projects"> +<h1>Relationship between other projects<a class="headerlink" href="#relationship-between-other-projects" title="Permalink to this headline">¶</a></h1> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#other-tagging-engines" id="id12">Other tagging engines</a></p> +<ul> +<li><p><a class="reference internal" href="#id1" id="id13">Exuberant Ctags</a></p></li> +<li><p><a class="reference internal" href="#id2" id="id14">Geany</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#software-using-ctags" id="id15">Software using ctags</a></p> +<ul> +<li><p><a class="reference internal" href="#id3" id="id16">Pygments</a></p></li> +<li><p><a class="reference internal" href="#id4" id="id17">GNU global</a></p></li> +<li><p><a class="reference internal" href="#id5" id="id18">GNU Source-highlight</a></p></li> +<li><p><a class="reference internal" href="#id6" id="id19">OpenGrok</a></p></li> +<li><p><a class="reference internal" href="#linux-kernel" id="id20">Linux kernel</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#other-interesting-ctags-repositories" id="id21">Other interesting ctags repositories</a></p> +<ul> +<li><p><a class="reference internal" href="#id7" id="id22">VIM-Japan</a></p></li> +<li><p><a class="reference internal" href="#id8" id="id23">Anjuta</a></p></li> +<li><p><a class="reference internal" href="#id9" id="id24">Tagbar</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#tracking-other-projects" id="id25">Tracking other projects</a></p> +<ul> +<li><p><a class="reference internal" href="#id10" id="id26">Exuberant Ctags</a></p> +<ul> +<li><p><a class="reference internal" href="#subversion" id="id27">subversion</a></p></li> +<li><p><a class="reference internal" href="#bugs" id="id28">bugs</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#id11" id="id29">patches</a></p></li> +<li><p><a class="reference internal" href="#devel-mailing-list-ctags-devel-sourceforge" id="id30">devel mailing list (ctags-devel@sourceforge)</a></p></li> +<li><p><a class="reference internal" href="#fedora" id="id31">Fedora</a></p></li> +<li><p><a class="reference internal" href="#debian" id="id32">Debian</a></p></li> +</ul> +</li> +</ul> +</div> +<section id="other-tagging-engines"> +<h2><a class="toc-backref" href="#id12">Other tagging engines</a><a class="headerlink" href="#other-tagging-engines" title="Permalink to this headline">¶</a></h2> +<section id="id1"> +<h3><a class="reference external" href="http://ctags.sourceforge.net/">Exuberant Ctags</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p>The origin of Universal Ctags.</p> +</section> +<section id="id2"> +<h3><a class="reference external" href="https://github.com/geany/geany">Geany</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p>Geany is a small and lightweight IDE. +Geany maintains their own tagging engine derived from ctags. +We are looking for the way to merge or share the source code each +other.</p> +<p>Repo</p> +<blockquote> +<div><p><a class="reference external" href="https://github.com/geany/geany/tree/master/ctags">https://github.com/geany/geany/tree/master/ctags</a></p> +</div></blockquote> +<p>Geany has created a library out of ctags</p> +<blockquote> +<div><p><a class="reference external" href="https://github.com/universal-ctags/ctags/issues/63">https://github.com/universal-ctags/ctags/issues/63</a></p> +</div></blockquote> +<p>Their language parsers have many improvements to various parsers. +Changes known by devs worth backporting:</p> +<ul class="simple"> +<li><p>Various fixes for D parser (c.c), but currently the code diverges +from ours to some extent.</p></li> +</ul> +<p>They have these additional language parsers:</p> +<ul class="simple"> +<li><p><a class="reference external" href="https://en.wikipedia.org/wiki/DocBook">DocBook</a></p></li> +<li><p><a class="reference external" href="https://en.wikipedia.org/wiki/Ferite">Ferite (c.c)</a></p></li> +<li><p><a class="reference external" href="https://en.wikipedia.org/wiki/OpenGL_Shading_Language">GLSL (c.c)</a></p></li> +<li><p><a class="reference external" href="https://en.wikipedia.org/wiki/Vala_%28programming_language%29">Vala (c.c)</a></p></li> +</ul> +</section> +</section> +<section id="software-using-ctags"> +<h2><a class="toc-backref" href="#id15">Software using ctags</a><a class="headerlink" href="#software-using-ctags" title="Permalink to this headline">¶</a></h2> +<section id="id3"> +<h3><a class="reference external" href="https://pygments.org/">Pygments</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>Pygments is a generic syntax highlighter.</p> +<p>It can utilize tags file +as input for making hyperlinks. However, Pygments just looks +at names and lines in tags file. scopes and kinds are not +used. See <a class="reference external" href="https://pygments-doc.readthedocs.io/en/latest/formatters/html.html">here</a> for +details.</p> +<p>As far as I (Masatake YAMATO) tried, using Pygments from ctags +is not so useful. There are critical gap between ctags and Pygments. +ctags focuses on identifiers. Pygments focuses on keywords.</p> +</div></blockquote> +</section> +<section id="id4"> +<h3><a class="reference external" href="https://www.gnu.org/software/global/">GNU global</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>GNU global is a source code tagging system.</p> +<p>I (Masatake YAMATO) don’t inspect this much but GNU global uses +ctags internally.</p> +<p>A person at GNU global project proposed an extension for the tags file +format: See <a class="reference external" href="https://sourceforge.net/p/ctags/mailman/message/30020186/">this ticket</a> for details.</p> +<p>See also <a class="reference external" href="https://www.gnu.org/software/global/links.html">‘Source code reading’ related sites</a>.</p> +</div></blockquote> +</section> +<section id="id5"> +<h3><a class="reference external" href="https://www.gnu.org/software/src-highlite/">GNU Source-highlight</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>GNU Source-highlight produces a document with syntax highlighting.</p> +<p>It can utilize tags file +as input for making hyperlinks. +See <a class="reference external" href="https://www.gnu.org/software/src-highlite/source-highlight.html#Generating-References">Generating References</a> +section for details.</p> +<p>I (Masatake YAMATO) have not tried the feature yet.</p> +</div></blockquote> +</section> +<section id="id6"> +<h3><a class="reference external" href="https://oracle.github.io/opengrok/">OpenGrok</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>OpenGrok is a fast and usable source +code search and cross reference engine.</p> +<p>I (Masatake YAMATO) don’t inspect this much but OpenGrok uses +ctags internally.</p> +</div></blockquote> +</section> +<section id="linux-kernel"> +<h3><a class="toc-backref" href="#id20">Linux kernel</a><a class="headerlink" href="#linux-kernel" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p>See <a class="reference external" href="https://elixir.bootlin.com/linux/v5.10.2/source/scripts/tags.sh">linux/scripts/tags.sh</a> +of Linux kernel source tree. +It utilizes c parser to the utmost limit.</p> +</div></blockquote> +</section> +</section> +<section id="other-interesting-ctags-repositories"> +<h2><a class="toc-backref" href="#id21">Other interesting ctags repositories</a><a class="headerlink" href="#other-interesting-ctags-repositories" title="Permalink to this headline">¶</a></h2> +<p>There are several interesting repo’s with ctags around. These are +interesting to integrate in the future.</p> +<section id="id7"> +<h3><a class="reference external" href="https://github.com/vim-jp/ctags/">VIM-Japan</a><a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3> +<p>VIM-Japan have some interesting things, especially regarding encoding.</p> +</section> +<section id="id8"> +<h3><a class="reference external" href="https://gitlab.gnome.org/GNOME/anjuta">Anjuta</a><a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h3> +<p>Anjuta DevStudio is a versatile Integrated Development Environment (IDE) +on GNOME Desktop Environment and features a number of advanced +programming facilities.</p> +<p>They did not fork Exuberant Ctags, but they did +natively <a class="reference external" href="https://git.gnome.org/browse/anjuta/tree/plugins/symbol-db/anjuta-tags">include it in Anjuta</a>. +They have made several additions to +their version of it including fairly extensive Vala language support.</p> +</section> +<section id="id9"> +<h3><a class="reference external" href="https://github.com/majutsushi/tagbar/">Tagbar</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h3> +<p>Tagbar is a Vim plugin that provides an easy way to browse the tags of the +current file and get an overview of its structure.</p> +<p>This is <a class="reference external" href="https://github.com/majutsushi/tagbar/wiki">a gold mine of optlibs</a>.</p> +<dl class="field-list simple"> +<dt class="field-odd">orphan</dt> +<dd class="field-odd"><p></p></dd> +</dl> +</section> +</section> +<section id="tracking-other-projects"> +<h2><a class="toc-backref" href="#id25">Tracking other projects</a><a class="headerlink" href="#tracking-other-projects" title="Permalink to this headline">¶</a></h2> +<p>This is working note for tracking activities other projects, +especially activity at Exuberant Ctags.</p> +<p>I(Masatake YAMATO) consider tracking activities as the first class +fruits of this project.</p> +<section id="id10"> +<h3><a class="toc-backref" href="#id26">Exuberant Ctags</a><a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h3> +<section id="subversion"> +<h4><a class="toc-backref" href="#id27">subversion</a><a class="headerlink" href="#subversion" title="Permalink to this headline">¶</a></h4> +<ul> +<li><p>status</p> +<p>Revisions up to <r815> are merged except:</p> +<blockquote> +<div><p>NOTHING HERE NOW</p> +</div></blockquote> +<p>(Mon Sep 22 12:41:32 2014 by yamato)</p> +</li> +<li><p>howto</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">svn</span><span class="o">></span> +<span class="o">=></span> <span class="o"><</span><span class="n">git</span><span class="p">:</span> <span class="n">local</span> <span class="n">Universal</span> <span class="n">Ctags</span> <span class="n">repo</span><span class="o">></span> +<span class="o">=></span> <span class="o"><</span><span class="n">git</span><span class="p">:</span> <span class="n">local</span> <span class="n">Universal</span> <span class="n">Ctags</span> <span class="n">repo</span><span class="o">></span> +</pre></div> +</div> +<ol class="arabic"> +<li><p>prepare your own Universal Ctags repo: a local git repo cloned from github. +You may know how to do it :)</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git clone https://github.com/universal-ctags/ctags.git +</pre></div> +</div> +</li> +<li><p>prepare Exuberant Ctags SVN repo: a local git repo clone from Exuberant Ctags svn tree.</p></li> +</ol> +<blockquote> +<div><p>The original clone is already part of Exuberant Ctags tree.</p> +<p>To initialize your git repository with the required subversion information do</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git svn init https://svn.code.sf.net/p/ctags/code/trunk +$ git update-ref refs/remotes/git-svn refs/remotes/origin/sourceforge +</pre></div> +</div> +<p>and then</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git svn fetch +$ git svn rebase +</pre></div> +</div> +<p>to get the latest changes and reflect it to the local copy.</p> +</div></blockquote> +<ol class="arabic simple" start="3"> +<li><p>merge</p></li> +</ol> +<blockquote> +<div><p>TODO</p> +</div></blockquote> +<ol class="arabic" start="4"> +<li><p>cherry-pick</p> +<p>4.1. Make a branch at local Universal Ctags repo and switch to it.</p> +<p>4.2. Do cherry-pick like:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git cherry-pick -s -x c81a8ce +</pre></div> +</div> +<p>You can find commit id on the another terminal +<git: local Universal Ctags repo>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git log +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git log --oneline +</pre></div> +</div> +<p>If conflicts are occurred in cherry-picking, you can +abort/reset cherry-picking with:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git reset --hard +</pre></div> +</div> +<dl class="simple"> +<dt><git: local Universal Ctags repo></dt><dd><p>at the branch for picking.</p> +</dd> +</dl> +</li> +</ol> +</li> +</ul> +</section> +<section id="bugs"> +<h4><a class="toc-backref" href="#id28">bugs</a><a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h4> +<blockquote> +<div><p><367> C++11 override makes a C++ member function declaration ignored</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d4fcbdd</span> +<span class="c1">#413</span> +<span class="c1">#405</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><366> --options=.ctags doesn’t work under Windows</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">15</span><span class="n">cedc6c94e95110cc319b5cdad7807caf3db1f4</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><365> Selecting Python kinds is broken</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">4</span><span class="n">a95e4a55f67230fc4eee91ffb31c18c422df6d3</span> +</pre></div> +</div> +</li> +<li><p>discussed at #324.</p></li> +</ul> +</div></blockquote> +<p><364> Ruby method on self is missing the trailing ? in the generated tag name</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d9ba5df9f4d54ddaa511bd5440a1a3decaa2dc28</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><363> Invalid C input file causes invalid read / heap overflow</p> +<blockquote> +<div><ul> +<li><p>it is not reproduced.</p></li> +<li><p>the test case is imported as parser-c.r/c-heapoverflow-sh-bug-363.d:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units UNITS=c-heapoverflow-sh-bug-363 VG=1 +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><361> Invalid C input file causes invalid read / heap overflow</p> +<blockquote> +<div><ul class="simple"> +<li><p>it is not reproduced.</p></li> +</ul> +</div></blockquote> +<p><360> Fails to parse annotation’s fields with default value</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">682</span><span class="n">a7f3b180c27c1196f8a1ae662d6e8ad142939</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><358> Vim parser: Segmentation fault when reading empty vim file</p> +<blockquote> +<div><ul> +<li><p>directly contributed by the original author of bug report and patch:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">e0f854f0100e7a3cb8b959a23d6036e43f6b6c85</span> +</pre></div> +</div> +</li> +<li><p>it is fixed in sf, too:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">5</span><span class="n">d774f6022a1af71fa5866994699aafce0253085</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><356> [python] mistakes module level attribute for class level attribute in module level if</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ab91e6e1ae84b80870a1e8712fc7f3133e4b5542</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><355> Error when parsing empty file (OCaml)</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">02</span><span class="n">ec2066b5be6b129eba49685bd0b17fef4acfa</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><341> Lua: “function f ()” whitespace</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">8590</span><span class="n">bbef5fcf70f6747d509808c29bf84342cd0d</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><341> Introducing ctags.conf.d</p> +<blockquote> +<div><ul> +<li><p>merged the improved version:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">216880</span><span class="n">c5287e0421d9c49898d983144db61c83aa</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><271> regex callback is broken; <320> [PATCH] fix regex callback match count</p> +<blockquote> +<div><ul> +<li><p>merged patch (with updated bug number):</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">a12b3a24b62d6535a968e076675f68bac9ad32ba</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><177> Lua: “function” results in function tag (includes patch)</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">5606</span><span class="n">f3f711afeac74587a249650a5f7b416f19be</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +</div></blockquote> +</section> +</section> +<section id="id11"> +<h3><a class="reference external" href="https://sourceforge.net/p/ctags/patches/%d">patches</a><a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h3> +<p>Tracking the tickets in patch tracker is quite fruitful. +Patches are always there. So it is easy to evaluate the value:)</p> +<blockquote> +<div><p>[(<]TICKET#[>)] TITLE</p> +<blockquote> +<div><ul class="simple"> +<li><p>STATUS</p> +<ul> +<li><p>MORE STATUS</p></li> +</ul> +</li> +</ul> +</div></blockquote> +<p><TICKET#></p> +<blockquote> +<div><p>means the ticket is closed from the view of Exuberant Ctags tree +developers. We don’t have to take time for this ticket.</p> +</div></blockquote> +<p>(TICKET#)</p> +<blockquote> +<div><p>means the ticket is still opened from the view of Exuberant Ctags +tree developers. We don’t have to take time for this ticket.</p> +</div></blockquote> +</div></blockquote> +<hr class="docutils" /> +<blockquote> +<div><p><85> Add --encoding option to make utf-8 encoded tags file</p> +<blockquote> +<div><ul> +<li><p>contributed by the original author:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">b3f670c7c4a3c3570b8d2d82756735586aafc0cb</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><84> C++11 new using semantics</p> +<blockquote> +<div><ul> +<li><p>solved by another implementation:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">c93e3bfa05b70d7fbc2539454c957eb2169e16b3</span> +<span class="mi">502355489</span><span class="n">b1ba748b1a235641bbd512ba6da315e</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><83> New full non-regex PHP parser</p> +<blockquote> +<div><ul class="simple"> +<li><p>contributed by the original author</p></li> +</ul> +</div></blockquote> +<p><82> Support for comments in .ctags files</p> +<blockquote> +<div><ul> +<li><p>contributed by the original author:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cab4735e4f99ce23c52b78dc879bc06af66796fd</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><81> ocaml parser segfaults on invalid files</p> +<blockquote> +<div><ul class="simple"> +<li><p>the bug is not reproduced</p></li> +</ul> +</div></blockquote> +<p><80> Add support for falcon pl</p> +<blockquote> +<div><ul class="simple"> +<li><p>contributed by the original author</p></li> +</ul> +</div></blockquote> +<p><74> protobuf parser</p> +<blockquote> +<div><ul class="simple"> +<li><p>Merged after getting approval from the original author</p></li> +</ul> +</div></blockquote> +<p><67> Objective C language parser</p> +<blockquote> +<div><ul class="simple"> +<li><p>This is the implementation we have in Universal Ctags tree.</p></li> +</ul> +</div></blockquote> +<p><65> absoluteFilename uses strcpy on overlapping strings</p> +<blockquote> +<div><ul> +<li><p>Fixed in Universal Ctags tree, however the ticket is still open:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d2bdf505abb7569deae2b50305ea1edce6208557</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><64> Fix strcpy() misuse</p> +<blockquote> +<div><ul> +<li><p>Fixed in Universal Ctags tree, however the ticket is still open:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d2bdf505abb7569deae2b50305ea1edce6208557</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><55> TTCN-3 support</p> +<blockquote> +<div><ul class="simple"> +<li><p>contributed by the original author</p></li> +</ul> +</div></blockquote> +<p><51> Ada support</p> +<blockquote> +<div><ul> +<li><p>Ada support is now available in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">4</span><span class="n">b6b4a72f3d2d4ef969d7c650de1829d79f0ea7c</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><38> Ada support</p> +<blockquote> +<div><ul> +<li><p>Ada support is now available in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">4</span><span class="n">b6b4a72f3d2d4ef969d7c650de1829d79f0ea7c</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><33> Add basic ObjC support</p> +<blockquote> +<div><ul class="simple"> +<li><p>This one is written in regexp.</p></li> +<li><p>we have better objc parser.</p></li> +</ul> +</div></blockquote> +<p>(1) bibtex parser</p> +<blockquote> +<div><ul> +<li><p>Reject because…</p> +<ul class="simple"> +<li><p>the owner of the ticket is anonymous.</p></li> +<li><p>the name of patch author is not written explicitly at +the header of patch.</p></li> +</ul> +</li> +<li><p>Alternative</p> +<p><a class="reference external" href="https://gist.github.com/ptrv/4576213">https://gist.github.com/ptrv/4576213</a></p> +</li> +</ul> +</div></blockquote> +</div></blockquote> +</section> +<section id="devel-mailing-list-ctags-devel-sourceforge"> +<h3>devel mailing list (<a class="reference external" href="mailto:ctags-devel%40sourceforge">ctags-devel<span>@</span>sourceforge</a>)<a class="headerlink" href="#devel-mailing-list-ctags-devel-sourceforge" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p><[Ctags] Shebang with python3 instead of python> +From: Martin Ueding <<a class="reference external" href="mailto:dev%40ma...">dev<span>@</span>ma…</a>> - 2013-01-26 18:36:32</p> +<blockquote> +<div><p>Added python, python2 and python3 as extensions of +python parser:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bb81485205c67617f1b34f61341e60b9e8030502</span> +</pre></div> +</div> +</div></blockquote> +<p><[Ctags-devel] Lack of fnmatch(3) in Windows> +From: Frank Fesevur <<a class="reference external" href="mailto:ffes%40us...">ffes<span>@</span>us…</a>> - 2013-08-24 20:25:47</p> +<blockquote> +<div><p>There is no fnmatch() in the Windows C library. Therefore +a string comparison is done in fileNameMatched() in +strlist.c and patterns are not recognized:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">698</span><span class="n">bf2f3db692946d2358892d228a864014abc4b</span> +</pre></div> +</div> +</div></blockquote> +<p><Re: [Ctags-devel] WindRes parser> +From: Frank Fesevur <<a class="reference external" href="mailto:ffes%40unns...">ffes<span>@</span>unns…</a>> - 2013-08-30 21:23:50</p> +<blockquote> +<div><p>A parser for Windows Resource files. +<a class="reference external" href="https://en.wikipedia.org/wiki/Resource_%28Windows%29">https://en.wikipedia.org/wiki/Resource_%28Windows%29</a></p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">95</span><span class="n">b4806ba6c006e4b7e72a006700e33c720ab9e7</span> +</pre></div> +</div> +</div></blockquote> +<p>([Ctags-devel] Skip repeat PATH_SEPARATORs in relativeFilename()) +From: Seth Dickson <<a class="reference external" href="mailto:whefxlr%40gm...">whefxlr<span>@</span>gm…</a>> - 2013-12-24 04:51:01</p> +<blockquote> +<div><p>Looks interesting.</p> +</div></blockquote> +</div></blockquote> +</section> +<section id="fedora"> +<h3><a class="toc-backref" href="#id31">Fedora</a><a class="headerlink" href="#fedora" title="Permalink to this headline">¶</a></h3> +<p>Some patches are maintained in ctags package of Fedora. +Inventory of patches are +<a class="reference external" href="http://pkgs.fedoraproject.org/cgit/ctags.git/tree/ctags.spec">http://pkgs.fedoraproject.org/cgit/ctags.git/tree/ctags.spec</a></p> +<p><ctags-5.7-destdir.patch></p> +<blockquote> +<div><p>This patch was merged in Universal Ctags git tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d4b5972427a46cbdcbfb050a944cf62b300676be</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.7-segment-fault.patch></p> +<blockquote> +<div><p>This patch was merged in Universal Ctags git tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">8</span><span class="n">cc2b482f6c7257c5151893a6d02b8c79851fedd</span> +</pre></div> +</div> +</div></blockquote> +<p>(ctags-5.8-cssparse.patch)</p> +<blockquote> +<div><p>Not in Universal Ctags tree.</p> +<p>The reproducer is attached to the following page: +<a class="reference external" href="https://bugzilla.redhat.com/show_bug.cgi?id=852101">https://bugzilla.redhat.com/show_bug.cgi?id=852101</a></p> +<p>However, Universal Ctags doesn’t reproduce with it.</p> +<p>I, Masatake YAMATO, read the patch. However, I don’t +understand the patch.</p> +</div></blockquote> +<p><ctags-5.8-css.patch></p> +<blockquote> +<div><p>This patch was merged in Universal Ctags git tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">80</span><span class="n">c1522a36df3ba52b8b7cd7f5c79d5c30437a63</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.8-memmove.patch></p> +<blockquote> +<div><p>This patch was merged in Exuberant Ctags svn tree. +As the result this patch is in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d2bdf505abb7569deae2b50305ea1edce6208557</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.8-ocaml-crash.patch></p> +<blockquote> +<div><p>This patch was merged in Exuberant Ctags svn tree. +As the result this patch is in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ddb29762b37d60a875252dcc401de0b7479527b1</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.8-format-security.patch></p> +<blockquote> +<div><p>This patch was merged in Exuberant Ctags svn tree. +As the result this patch is in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">2</span><span class="n">f7a78ce21e4156ec3e63c821827cf1d5680ace8</span> +</pre></div> +</div> +</div></blockquote> +</section> +<section id="debian"> +<h3><a class="toc-backref" href="#id32">Debian</a><a class="headerlink" href="#debian" title="Permalink to this headline">¶</a></h3> +<p>Some patches are maintained in ctags package of Debian. +Inventory of patches are +<a class="reference external" href="http://anonscm.debian.org/cgit/users/cjwatson/exuberant-ctags.git/tree/debian/patches/series">http://anonscm.debian.org/cgit/users/cjwatson/exuberant-ctags.git/tree/debian/patches/series</a></p> +<p><python-disable-imports.patch></p> +<blockquote> +<div><p>Universal Ctags tags Y in <cite>import X as Y</cite> and Z in <cite>from X import Y as Z</cite> +as definition tags. They are turned on by default. +The others are tagged as reference tags. reference tags are recorded only +when “r” extra tags are enabled. e.g. <cite>--extras=+r</cite>.</p> +</div></blockquote> +<p><vim-command-loop.patch></p> +<blockquote> +<div><p>This patch was merged as an alternative for +7fb36a2f4690374526e9e7ef4f1e24800b6914ec</p> +<p>Discussed on <a class="reference external" href="https://github.com/fishman/ctags/issues/74">https://github.com/fishman/ctags/issues/74</a></p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">e59325a576e38bc63b91abb05a5a22d2cef25ab7</span> +</pre></div> +</div> +</div></blockquote> +</section> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Relationship between other projects</a><ul> +<li><a class="reference internal" href="#other-tagging-engines">Other tagging engines</a><ul> +<li><a class="reference internal" href="#id1">Exuberant Ctags</a></li> +<li><a class="reference internal" href="#id2">Geany</a></li> +</ul> +</li> +<li><a class="reference internal" href="#software-using-ctags">Software using ctags</a><ul> +<li><a class="reference internal" href="#id3">Pygments</a></li> +<li><a class="reference internal" href="#id4">GNU global</a></li> +<li><a class="reference internal" href="#id5">GNU Source-highlight</a></li> +<li><a class="reference internal" href="#id6">OpenGrok</a></li> +<li><a class="reference internal" href="#linux-kernel">Linux kernel</a></li> +</ul> +</li> +<li><a class="reference internal" href="#other-interesting-ctags-repositories">Other interesting ctags repositories</a><ul> +<li><a class="reference internal" href="#id7">VIM-Japan</a></li> +<li><a class="reference internal" href="#id8">Anjuta</a></li> +<li><a class="reference internal" href="#id9">Tagbar</a></li> +</ul> +</li> +<li><a class="reference internal" href="#tracking-other-projects">Tracking other projects</a><ul> +<li><a class="reference internal" href="#id10">Exuberant Ctags</a><ul> +<li><a class="reference internal" href="#subversion">subversion</a></li> +<li><a class="reference internal" href="#bugs">bugs</a></li> +</ul> +</li> +<li><a class="reference internal" href="#id11">patches</a></li> +<li><a class="reference internal" href="#devel-mailing-list-ctags-devel-sourceforge">devel mailing list (ctags-devel@sourceforge)</a></li> +<li><a class="reference internal" href="#fedora">Fedora</a></li> +<li><a class="reference internal" href="#debian">Debian</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="contributions.html" + title="previous chapter">Contributions</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="developers.html" + title="next chapter">Who we are</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="developers.html" title="Who we are" + >next</a> |</li> + <li class="right" > + <a href="contributions.html" title="Contributions" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Relationship between other projects</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/output-format.html b/ctags/docs/output-format.html new file mode 100644 index 0000000..9a81a2e --- /dev/null +++ b/ctags/docs/output-format.html @@ -0,0 +1,144 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Output formats — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Changes to the tags file format" href="output-tags.html" /> + <link rel="prev" title="Option files" href="option-file.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="output-tags.html" title="Changes to the tags file format" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="option-file.html" title="Option files" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Output formats</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="output-formats"> +<span id="output-format"></span><h1>Output formats<a class="headerlink" href="#output-formats" title="Permalink to this headline">¶</a></h1> +<p>This section deals with individual output-format topics.</p> +<p>The command line option <code class="docutils literal notranslate"><span class="pre">--output-format=</span></code><em>format</em> chooses an output format. +Supported <em>format</em> are <code class="docutils literal notranslate"><span class="pre">u-ctags</span></code>, <code class="docutils literal notranslate"><span class="pre">e-ctags</span></code>, <code class="docutils literal notranslate"><span class="pre">etags</span></code>, <code class="docutils literal notranslate"><span class="pre">xref</span></code>, and <code class="docutils literal notranslate"><span class="pre">json</span></code>.</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">u-ctags</span></code>, <code class="docutils literal notranslate"><span class="pre">e-ctags</span></code></dt><dd><p><code class="docutils literal notranslate"><span class="pre">u-ctags</span></code> is the default output format extending the Exuberant Ctags +output format (<code class="docutils literal notranslate"><span class="pre">e-ctags</span></code>).</p> +<p><code class="docutils literal notranslate"><span class="pre">--format=1</span></code> and <code class="docutils literal notranslate"><span class="pre">--format=2</span></code> are same as <code class="docutils literal notranslate"><span class="pre">--output-format=e-ctags</span></code> +and <code class="docutils literal notranslate"><span class="pre">--output-format=u-ctags</span></code> respectively.</p> +<p>See man page <a class="reference internal" href="man/tags.5.html#tags-5"><span class="std std-ref">tags (5)</span></a> for details. The difference between +<code class="docutils literal notranslate"><span class="pre">u-ctags</span></code> and <code class="docutils literal notranslate"><span class="pre">e-ctags</span></code> are marked as “EXCEPTION”. +Additional changes in Universal Ctags are described in +<a class="reference internal" href="output-tags.html#changes-tags-file"><span class="std std-ref">Changes to the tags file format</span></a>.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">etags</span></code></dt><dd><p>Output format for Emacs etags. +<code class="docutils literal notranslate"><span class="pre">--output-format=etags</span></code> can be abbreviated as <code class="docutils literal notranslate"><span class="pre">-e</span></code>.</p> +<p>See <a class="reference external" href="https://git.savannah.gnu.org/cgit/emacs.git/tree/etc/ETAGS.EBNF">emacs git</a> for +details.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">xref</span></code></dt><dd><p>A tabular, human-readable cross reference (xref) format. +<code class="docutils literal notranslate"><span class="pre">--output-format=xref</span></code> can be abbreviated as <code class="docutils literal notranslate"><span class="pre">-x</span></code>.</p> +<p>See section <a class="reference internal" href="output-xref.html#output-xref"><span class="std std-ref">Xref output</span></a> for details.</p> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">json</span></code></dt><dd><p>JSON format.</p> +<p>See section <a class="reference internal" href="output-json.html#output-json"><span class="std std-ref">JSON output</span></a> for details.</p> +</dd> +</dl> +<hr class="docutils" /> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="output-tags.html">Changes to the tags file format</a><ul> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html#f-kind-usage"><code class="docutils literal notranslate"><span class="pre">F</span></code> kind usage</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html#reference-tags">Reference tags</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html#pseudo-tags">Pseudo-tags</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html#truncating-the-pattern-for-long-input-lines">Truncating the pattern for long input lines</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html#parser-specific-fields">Parser specific fields</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html#parser-specific-extras">Parser specific extras</a></li> +<li class="toctree-l2"><a class="reference internal" href="output-tags.html#parser-specific-parameter">Parser specific parameter</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="output-xref.html">Xref output</a><ul> +<li class="toctree-l2"><a class="reference internal" href="output-xref.html#customizing-xref-output">Customizing xref output</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="output-json.html">JSON output</a></li> +</ul> +</div> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="option-file.html" + title="previous chapter">Option files</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="output-tags.html" + title="next chapter">Changes to the tags file format</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="output-tags.html" title="Changes to the tags file format" + >next</a> |</li> + <li class="right" > + <a href="option-file.html" title="Option files" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Output formats</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/output-json.html b/ctags/docs/output-json.html new file mode 100644 index 0000000..6f349a1 --- /dev/null +++ b/ctags/docs/output-json.html @@ -0,0 +1,101 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>JSON output — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Running multiple parsers on an input file" href="running-multi-parsers.html" /> + <link rel="prev" title="Xref output" href="output-xref.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="running-multi-parsers.html" title="Running multiple parsers on an input file" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="output-xref.html" title="Xref output" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" accesskey="U">Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">JSON output</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="json-output"> +<span id="output-json"></span><h1>JSON output<a class="headerlink" href="#json-output" title="Permalink to this headline">¶</a></h1> +<p>See <a class="reference internal" href="man/ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a>.</p> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="output-xref.html" + title="previous chapter">Xref output</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="running-multi-parsers.html" + title="next chapter">Running multiple parsers on an input file</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="running-multi-parsers.html" title="Running multiple parsers on an input file" + >next</a> |</li> + <li class="right" > + <a href="output-xref.html" title="Xref output" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" >Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">JSON output</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/output-tags.html b/ctags/docs/output-tags.html new file mode 100644 index 0000000..7b58d4d --- /dev/null +++ b/ctags/docs/output-tags.html @@ -0,0 +1,551 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Changes to the tags file format — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Xref output" href="output-xref.html" /> + <link rel="prev" title="Output formats" href="output-format.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="output-xref.html" title="Xref output" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="output-format.html" title="Output formats" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" accesskey="U">Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">Changes to the tags file format</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="changes-to-the-tags-file-format"> +<span id="changes-tags-file"></span><h1>Changes to the tags file format<a class="headerlink" href="#changes-to-the-tags-file-format" title="Permalink to this headline">¶</a></h1> +<section id="f-kind-usage"> +<h2><code class="docutils literal notranslate"><span class="pre">F</span></code> kind usage<a class="headerlink" href="#f-kind-usage" title="Permalink to this headline">¶</a></h2> +<p>You cannot use <code class="docutils literal notranslate"><span class="pre">F</span></code> (<code class="docutils literal notranslate"><span class="pre">file</span></code>) kind in your .ctags because Universal Ctags +reserves it. See <a class="reference internal" href="man/ctags-incompatibilities.7.html#ctags-incompatibilities-7"><span class="std std-ref">ctags-incompatibilities(7)</span></a>.</p> +</section> +<section id="reference-tags"> +<h2>Reference tags<a class="headerlink" href="#reference-tags" title="Permalink to this headline">¶</a></h2> +<p>Traditionally ctags collects the information for locating where a +language object is DEFINED.</p> +<p>In addition Universal Ctags supports reference tags. If the extra-tag +<code class="docutils literal notranslate"><span class="pre">r</span></code> is enabled, Universal Ctags also collects the information for +locating where a language object is REFERENCED. This feature was +proposed by @shigio in <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/569">#569</a> for GNU GLOBAL.</p> +<p>Here are some examples. Here is the target input file named reftag.c.</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span> +<span class="cp">#include</span> <span class="cpf">"foo.h"</span><span class="cp"></span> +<span class="cp">#define TYPE point</span> +<span class="k">struct</span> <span class="nc">TYPE</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">;</span> <span class="p">};</span> +<span class="n">TYPE</span> <span class="n">p</span><span class="p">;</span> +<span class="cp">#undef TYPE</span> +</pre></div> +</div> +<p>Traditional output:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - reftag.c +<span class="go">TYPE reftag.c /^#define TYPE /;" d file:</span> +<span class="go">TYPE reftag.c /^struct TYPE { int x, y; };$/;" s file:</span> +<span class="go">p reftag.c /^TYPE p;$/;" v typeref:typename:TYPE</span> +<span class="go">x reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +<span class="go">y reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +</pre></div> +</div> +<p>Output with the extra-tag <code class="docutils literal notranslate"><span class="pre">r</span></code> enabled:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-extras <span class="p">|</span> grep ^r +<span class="go">r Include reference tags off</span> +<span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+r reftag.c +<span class="go">TYPE reftag.c /^#define TYPE /;" d file:</span> +<span class="go">TYPE reftag.c /^#undef TYPE$/;" d file:</span> +<span class="go">TYPE reftag.c /^struct TYPE { int x, y; };$/;" s file:</span> +<span class="go">foo.h reftag.c /^#include "foo.h"/;" h</span> +<span class="go">p reftag.c /^TYPE p;$/;" v typeref:typename:TYPE</span> +<span class="go">stdio.h reftag.c /^#include <stdio.h>/;" h</span> +<span class="go">x reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +<span class="go">y reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file:</span> +</pre></div> +</div> +<p><cite>#undef X</cite> and two <cite>#include</cite> are newly collected.</p> +<p>“roles” is a newly introduced field in Universal Ctags. The field +named is for recording how a tag is referenced. If a tag is definition +tag, the roles field has “def” as its value.</p> +<p>Universal Ctags prints the role information when the <cite>r</cite> +field is enabled with <code class="docutils literal notranslate"><span class="pre">--fields=+r</span></code>.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+r --fields<span class="o">=</span>+r reftag.c +<span class="go">TYPE reftag.c /^#define TYPE /;" d file:</span> +<span class="go">TYPE reftag.c /^#undef TYPE$/;" d file: roles:undef</span> +<span class="go">TYPE reftag.c /^struct TYPE { int x, y; };$/;" s file: roles:def</span> +<span class="go">foo.h reftag.c /^#include "foo.h"/;" h roles:local</span> +<span class="go">p reftag.c /^TYPE p;$/;" v typeref:typename:TYPE roles:def</span> +<span class="go">stdio.h reftag.c /^#include <stdio.h>/;" h roles:system</span> +<span class="go">x reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file: roles:def</span> +<span class="go">y reftag.c /^struct TYPE { int x, y; };$/;" m struct:TYPE typeref:typename:int file: roles:def</span> +</pre></div> +</div> +<p>The <cite>Reference tag marker</cite> field, <code class="docutils literal notranslate"><span class="pre">R</span></code>, is a specialized GNU global +requirement; D is used for the traditional definition tags, and R is +used for the new reference tags. The field can be used only with +<code class="docutils literal notranslate"><span class="pre">--_xformat</span></code>.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -x --_xformat<span class="o">=</span><span class="s2">"%R %-16N %4n %-16F %C"</span> --extras<span class="o">=</span>+r reftag.c +<span class="go">D TYPE 3 reftag.c #define TYPE point</span> +<span class="go">D TYPE 4 reftag.c struct TYPE { int x, y; };</span> +<span class="go">D p 5 reftag.c TYPE p;</span> +<span class="go">D x 4 reftag.c struct TYPE { int x, y; };</span> +<span class="go">D y 4 reftag.c struct TYPE { int x, y; };</span> +<span class="go">R TYPE 6 reftag.c #undef TYPE</span> +<span class="go">R foo.h 2 reftag.c #include "foo.h"</span> +<span class="go">R stdio.h 1 reftag.c #include <stdio.h></span> +</pre></div> +</div> +<p>See <a class="reference internal" href="output-xref.html#xformat"><span class="std std-ref">Customizing xref output</span></a> for more details about +<code class="docutils literal notranslate"><span class="pre">--_xformat</span></code>.</p> +<p>Although the facility for collecting reference tags is implemented, +only a few parsers currently utilize it. All available roles can be +listed with <code class="docutils literal notranslate"><span class="pre">--list-roles</span></code>:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-roles +<span class="gp">#</span>LANGUAGE KIND<span class="o">(</span>L/N<span class="o">)</span> NAME ENABLED DESCRIPTION +<span class="go">SystemdUnit u/unit Requires on referred in Requires key</span> +<span class="go">SystemdUnit u/unit Wants on referred in Wants key</span> +<span class="go">SystemdUnit u/unit After on referred in After key</span> +<span class="go">SystemdUnit u/unit Before on referred in Before key</span> +<span class="go">SystemdUnit u/unit RequiredBy on referred in RequiredBy key</span> +<span class="go">SystemdUnit u/unit WantedBy on referred in WantedBy key</span> +<span class="go">Yaml a/anchor alias on alias</span> +<span class="go">DTD e/element attOwner on attributes owner</span> +<span class="go">Automake c/condition branched on used for branching</span> +<span class="go">Cobol S/sourcefile copied on copied in source file</span> +<span class="go">Maven2 g/groupId dependency on dependency</span> +<span class="go">DTD p/parameterEntity elementName on element names</span> +<span class="go">DTD p/parameterEntity condition on conditions</span> +<span class="go">LdScript s/symbol entrypoint on entry points</span> +<span class="go">LdScript i/inputSection discarded on discarded when linking</span> +<span class="go">...</span> +</pre></div> +</div> +<p>The first column shows the name of the parser. +The second column shows the letter/name of the kind. +The third column shows the name of the role. +The fourth column shows whether the role is enabled or not. +The fifth column shows the description of the role.</p> +<p>You can define a role in an optlib parser for capturing reference +tags. See <a class="reference internal" href="optlib.html#roles"><span class="std std-ref">Capturing reference tags</span></a> for more +details.</p> +<p><code class="docutils literal notranslate"><span class="pre">--roles-<LANG>.<KIND></span></code> is the option for enabling/disabling +specified roles.</p> +</section> +<section id="pseudo-tags"> +<h2>Pseudo-tags<a class="headerlink" href="#pseudo-tags" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference internal" href="man/ctags-client-tools.7.html#ctags-client-tools-7"><span class="std std-ref">ctags-client-tools(7)</span></a> about the +concept of the pseudo-tags.</p> +<section id="tag-kind-description"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code><a class="headerlink" href="#tag-kind-description" title="Permalink to this headline">¶</a></h3> +<p>This is a newly introduced pseudo-tag. It is not emitted by default. +It is emitted only when <code class="docutils literal notranslate"><span class="pre">--pseudo-tags=+TAG_KIND_DESCRIPTION</span></code> is +given.</p> +<p>This is for describing kinds; their letter, name, and description are +enumerated in the tag.</p> +<p>ctags emits <code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code> with following format:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser} {letter},{name} /{description}/ +</pre></div> +</div> +<p>A backslash and a slash in {description} is escaped with a backslash.</p> +</section> +<section id="tag-kind-separator"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code><a class="headerlink" href="#tag-kind-separator" title="Permalink to this headline">¶</a></h3> +<p>This is a newly introduced pseudo-tag. It is not emitted by default. +It is emitted only when <code class="docutils literal notranslate"><span class="pre">--pseudo-tags=+TAG_KIND_SEPARATOR</span></code> is +given.</p> +<p>This is for describing separators placed between two kinds in a +language.</p> +<p>Tag entries including the separators are emitted when <code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code> +is given; fully qualified tags contain the separators. The separators +are used in scope information, too.</p> +<p>ctags emits <code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code> with following format:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser} {sep} /{upper}{lower}/ +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>!_TAG_KIND_SEPARATOR!{parser} {sep} /{lower}/ +</pre></div> +</div> +<p>Here {parser} is the name of language. e.g. PHP. +{lower} is the letter representing the kind of the lower item. +{upper} is the letter representing the kind of the upper item. +{sep} is the separator placed between the upper item and the lower +item.</p> +<p>The format without {upper} is for representing a root separator. The +root separator is used as prefix for an item which has no upper scope.</p> +<p><cite>*</cite> given as {upper} is a fallback wild card; if it is given, the +{sep} is used in combination with any upper item and the item +specified with {lower}.</p> +<p>Each backslash character used in {sep} is escaped with an extra +backslash character.</p> +<p>Example output:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+p --pseudo-tags<span class="o">=</span> --pseudo-tags<span class="o">=</span>+TAG_KIND_SEPARATOR input.php +<span class="go">!_TAG_KIND_SEPARATOR!PHP :: /*c/</span> +<span class="go">...</span> +<span class="go">!_TAG_KIND_SEPARATOR!PHP \\ /c/</span> +<span class="go">...</span> +<span class="go">!_TAG_KIND_SEPARATOR!PHP \\ /nc/</span> +<span class="go">...</span> +</pre></div> +</div> +<p>The first line means <code class="docutils literal notranslate"><span class="pre">::</span></code> is used when combining something with an +item of the class kind.</p> +<p>The second line means <code class="docutils literal notranslate"><span class="pre">\\</span></code> is used when a class item is at the top +level; no upper item is specified.</p> +<p>The third line means <code class="docutils literal notranslate"><span class="pre">\\</span></code> is used when for combining a namespace item +(upper) and a class item (lower).</p> +<p>Of course, ctags uses the more specific line when choosing a +separator; the third line has higher priority than the first.</p> +</section> +<section id="tag-output-filesep"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_FILESEP</span></code><a class="headerlink" href="#tag-output-filesep" title="Permalink to this headline">¶</a></h3> +<p>This pseudo-tag represents the separator used in file name: slash or +backslash. This is always ‘slash’ on Unix-like environments. +This is also ‘slash’ by default on Windows, however when +<code class="docutils literal notranslate"><span class="pre">--output-format=e-tags</span></code> or <code class="docutils literal notranslate"><span class="pre">--use-slash-as-filename-separator=no</span></code> +is specified, it becomes ‘backslash’.</p> +</section> +<section id="tag-output-mode"> +<h3><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code><a class="headerlink" href="#tag-output-mode" title="Permalink to this headline">¶</a></h3> +<p>This pseudo-tag represents output mode: u-ctags or e-ctags. +This is controlled by <code class="docutils literal notranslate"><span class="pre">--output-format</span></code> option.</p> +<p>See also <a class="reference internal" href="man/tags.5.html#compat-output"><span class="std std-ref">Compatible output and weakness</span></a>.</p> +</section> +</section> +<section id="truncating-the-pattern-for-long-input-lines"> +<h2>Truncating the pattern for long input lines<a class="headerlink" href="#truncating-the-pattern-for-long-input-lines" title="Permalink to this headline">¶</a></h2> +<p>See <code class="docutils literal notranslate"><span class="pre">--pattern-length-limit=N</span></code> option in <a class="reference internal" href="man/ctags.1.html#ctags-1"><span class="std std-ref">ctags(1)</span></a>.</p> +</section> +<section id="parser-specific-fields"> +<span id="id2"></span><h2>Parser specific fields<a class="headerlink" href="#parser-specific-fields" title="Permalink to this headline">¶</a></h2> +<p>A tag has a <cite>name</cite>, an <cite>input</cite> file name, and a <cite>pattern</cite> as basic +information. Some fields like <cite>language:</cite>, <cite>signature:</cite>, etc are +attached to the tag as optional information.</p> +<p>In Exuberant Ctags, fields are common to all languages. +Universal Ctags extends the concept of fields; a parser can define +its specific field. This extension was proposed by @pragmaware in +<a class="reference external" href="https://github.com/universal-ctags/ctags/issues/857">#857</a>.</p> +<p>For implementing the parser specific fields, the options for listing and +enabling/disabling fields are also extended.</p> +<p>In the output of <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code>, the owner of the field is printed +in the <cite>LANGUAGE</cite> column:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-fields +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE XFMT DESCRIPTION +<span class="go">...</span> +<span class="go">- end off C TRUE end lines of various constructs</span> +<span class="go">- properties off C TRUE properties (static, inline, mutable,...)</span> +<span class="go">- end off C++ TRUE end lines of various constructs</span> +<span class="go">- template off C++ TRUE template parameters</span> +<span class="go">- captures off C++ TRUE lambda capture list</span> +<span class="go">- properties off C++ TRUE properties (static, virtual, inline, mutable,...)</span> +<span class="go">- sectionMarker off reStructuredText TRUE character used for declaring section</span> +<span class="go">- version off Maven2 TRUE version of artifact</span> +</pre></div> +</div> +<p>e.g. reStructuredText is the owner of the sectionMarker field and +both C and C++ own the end field.</p> +<p><code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> takes one optional argument, <cite>LANGUAGE</cite>. If it is +given, <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> prints only the fields for that parser:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-fields<span class="o">=</span>Maven2 +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE XFMT DESCRIPTION +<span class="go">- version off Maven2 TRUE version of artifact</span> +</pre></div> +</div> +<p>A parser specific field only has a long name, no letter. For +enabling/disabling such fields, the name must be passed to +<code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code>.</p> +<p>e.g. for enabling the <cite>sectionMarker</cite> field owned by the +<cite>reStructuredText</cite> parser, use the following command line:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields-reStructuredText<span class="o">=</span>+<span class="o">{</span>sectionMarker<span class="o">}</span> ... +</pre></div> +</div> +<p>The wild card notation can be used for enabling/disabling parser specific +fields, too. The following example enables all fields owned by the +<cite>C++</cite> parser.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields-C++<span class="o">=</span><span class="s1">'*'</span> ... +</pre></div> +</div> +<p><cite>*</cite> can also be used for specifying languages.</p> +<p>The next example is for enabling <cite>end</cite> fields for all languages which +have such a field.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields-<span class="s1">'*'</span><span class="o">=</span>+<span class="s1">'{end}'</span> ... +<span class="go">...</span> +</pre></div> +</div> +<p>In this case, using wild card notation to specify the language, not +only fields owned by parsers but also common fields having the name +specified (<cite>end</cite> in this example) are enabled/disabled.</p> +<p>Using the wild card notation to specify the language is helpful to +avoid incompatibilities between versions of Universal Ctags itself +(SELF INCOMPATIBLY).</p> +<p>In Universal Ctags development, a parser developer may add a new +parser specific field for a certain language. Sometimes other developers +then recognize it is meaningful not only for the original language +but also other languages. In this case the field may be promoted to a +common field. Such a promotion will break the command line +compatibility for <code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code> usage. The wild card for +<cite><LANG></cite> will help in avoiding this unwanted effect of the promotion.</p> +<p>With respect to the tags file format, nothing is changed when +introducing parser specific fields; <cite><fieldname></cite>:<cite><value></cite> is used as +before and the name of field owner is never prefixed. The <cite>language:</cite> +field of the tag identifies the owner.</p> +</section> +<section id="parser-specific-extras"> +<h2>Parser specific extras<a class="headerlink" href="#parser-specific-extras" title="Permalink to this headline">¶</a></h2> +<p>As man page of Exuberant Ctags says, <code class="docutils literal notranslate"><span class="pre">--extras</span></code> option specifies +whether to include extra tag entries for certain kinds of information. +This option is available in Universal Ctags, too.</p> +<p>In Universal Ctags it is extended; a parser can define its specific +extra flags. They can be controlled with <code class="docutils literal notranslate"><span class="pre">--extras-<LANG>=[+|-]{...}</span></code>.</p> +<p>See some examples:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-extras +<span class="gp">#</span>LETTER NAME ENABLED LANGUAGE DESCRIPTION +<span class="go">F fileScope TRUE NONE Include tags ...</span> +<span class="go">f inputFile FALSE NONE Include an entry ...</span> +<span class="go">p pseudo FALSE NONE Include pseudo tags</span> +<span class="go">q qualified FALSE NONE Include an extra ...</span> +<span class="go">r reference FALSE NONE Include reference tags</span> +<span class="go">g guest FALSE NONE Include tags ...</span> +<span class="go">- whitespaceSwapped TRUE Robot Include tags swapping ...</span> +</pre></div> +</div> +<p>See the <cite>LANGUAGE</cite> column. NONE means the extra flags are language +independent (common). They can be enabled or disabled with <cite>--extras=</cite> as before.</p> +<p>Look at <cite>whitespaceSwapped</cite>. Its language is <cite>Robot</cite>. This flag is enabled +by default but can be disabled with <cite>--extras-Robot=-{whitespaceSwapped}</cite>.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.robot +<span class="go">*** Keywords ***</span> +<span class="go">it's ok to be correct</span> +<span class="go"> Python_keyword_2</span> + +<span class="gp">$ </span>ctags -o - input.robot +<span class="go">it's ok to be correct input.robot /^it's ok to be correct$/;" k</span> +<span class="go">it's_ok_to_be_correct input.robot /^it's ok to be correct$/;" k</span> + +<span class="gp">$ </span>ctags -o - --extras-Robot<span class="o">=</span>-<span class="s1">'{whitespaceSwapped}'</span> input.robot +<span class="go">it's ok to be correct input.robot /^it's ok to be correct$/;" k</span> +</pre></div> +</div> +<p>When disabled the name <cite>it’s_ok_to_be_correct</cite> is not included in the +tags output. In other words, the name <cite>it’s_ok_to_be_correct</cite> is +derived from the name <cite>it’s ok to be correct</cite> when the extra flag is +enabled.</p> +<section id="discussion"> +<h3>Discussion<a class="headerlink" href="#discussion" title="Permalink to this headline">¶</a></h3> +<p>(This subsection should move to somewhere for developers.)</p> +<p>The question is what are extra tag entries. As far as I know none has +answered explicitly. I have two ideas in Universal Ctags. I +write “ideas”, not “definitions” here because existing parsers don’t +follow the ideas. They are kept as is in variety reasons but the +ideas may be good guide for people who wants to write a new parser +or extend an exiting parser.</p> +<p>The first idea is that a tag entry whose name is appeared in the input +file as is, the entry is NOT an extra. (If you want to control the +inclusion of such entries, the classical <code class="docutils literal notranslate"><span class="pre">--kind-<LANG>=[+|-]...</span></code> is +what you want.)</p> +<p>Qualified tags, whose inclusion is controlled by <code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code>, is +explained well with this idea. +Let’s see an example:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.py +<span class="go">class Foo:</span> +<span class="go"> def func (self):</span> +<span class="go"> pass</span> + +<span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>+q --fields<span class="o">=</span>+E input.py +<span class="go">Foo input.py /^class Foo:$/;" c</span> +<span class="go">Foo.func input.py /^ def func (self):$/;" m class:Foo extra:qualified</span> +<span class="go">func input.py /^ def func (self):$/;" m class:Foo</span> +</pre></div> +</div> +<p><cite>Foo</cite> and <cite>func</cite> are in <cite>input.py</cite>. So they are no extra tags. In +other hand, <cite>Foo.func</cite> is not in <cite>input.py</cite> as is. The name is +generated by ctags as a qualified extra tag entry. +<cite>whitespaceSwapped</cite> extra flag of <cite>Robot</cite> parser is also aligned well +on the idea.</p> +<p>I don’t say all parsers follows this idea.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.cc +<span class="go">class A</span> +<span class="go">{</span> +<span class="go"> A operator+ (int);</span> +<span class="go">};</span> + +<span class="gp">$ </span>ctags --kinds-all<span class="o">=</span><span class="s1">'*'</span> --fields<span class="o">=</span> -o - input.cc +<span class="go">A input.cc /^class A$/</span> +<span class="go">operator + input.cc /^ A operator+ (int);$/</span> +</pre></div> +</div> +<p>In this example <cite>operator+</cite> is in <cite>input.cc</cite>. +In other hand, <cite>operator +</cite> is in the ctags output as non extra tag entry. +See a whitespace between the keyword <cite>operator</cite> and <cite>+</cite> operator. +This is an exception of the first idea.</p> +<p>The second idea is that if the <em>inclusion</em> of a tag cannot be +controlled well with <code class="docutils literal notranslate"><span class="pre">--kind-<LANG>=[+|-]...</span></code>, the tag may be an +extra.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.c +<span class="go">static int foo (void)</span> +<span class="go">{</span> +<span class="go"> return 0;</span> +<span class="go">}</span> +<span class="go">int bar (void)</span> +<span class="go">{</span> +<span class="go"> return 1;</span> +<span class="go">}</span> + +<span class="gp">$ </span>ctags --sort<span class="o">=</span>no -o - --extras<span class="o">=</span>+F input.c +<span class="go">foo input.c /^static int foo (void)$/;" f typeref:typename:int file:</span> +<span class="go">bar input.c /^int bar (void)$/;" f typeref:typename:int</span> + +<span class="gp">$ </span>ctags -o - --extras<span class="o">=</span>-F input.c +<span class="go">foo input.c /^static int foo (void)$/;" f typeref:typename:int file:</span> + +<span class="gp">$</span> +</pre></div> +</div> +<p>Function <cite>foo</cite> of C language is included only when <cite>F</cite> extra flag +is enabled. Both <cite>foo</cite> and <cite>bar</cite> are functions. Their inclusions +can be controlled with <cite>f</cite> kind of C language: <code class="docutils literal notranslate"><span class="pre">--kind-C=[+|-]f</span></code>.</p> +<p>The difference between static modifier or implicit extern modifier in +a function definition is handled by <cite>F</cite> extra flag.</p> +<p>Basically the concept kind is for handling the kinds of language +objects: functions, variables, macros, types, etc. The concept extra +can handle the other aspects like scope (static or extern).</p> +<p>However, a parser developer can take another approach instead of +introducing parser specific extra; one can prepare <cite>staticFunction</cite> and +<cite>exportedFunction</cite> as kinds of one’s parser. The second idea is a +just guide; the parser developer must decide suitable approach for the +target language.</p> +<p>Anyway, in the second idea, <code class="docutils literal notranslate"><span class="pre">--extras</span></code> is for controlling inclusion +of tags. If what you want is not about inclusion, <code class="docutils literal notranslate"><span class="pre">--param-<LANG></span></code> +can be used as the last resort.</p> +</section> +</section> +<section id="parser-specific-parameter"> +<h2>Parser specific parameter<a class="headerlink" href="#parser-specific-parameter" title="Permalink to this headline">¶</a></h2> +<p>To control the detail of a parser, <code class="docutils literal notranslate"><span class="pre">--param-<LANG></span></code> option is introduced. +<code class="docutils literal notranslate"><span class="pre">--kinds-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--fields-<LANG></span></code>, <code class="docutils literal notranslate"><span class="pre">--extras-<LANG></span></code> +can be used for customizing the behavior of a parser specified with <code class="docutils literal notranslate"><span class="pre"><LANG></span></code>.</p> +<p><code class="docutils literal notranslate"><span class="pre">--param-<LANG></span></code> should be used for aspects of the parser that +the options(kinds, fields, extras) cannot handle well.</p> +<p>A parser defines a set of parameters. Each parameter has name and +takes an argument. A user can set a parameter with following notation</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">param</span><span class="o">-<</span><span class="n">LANG</span><span class="o">></span><span class="p">:</span><span class="n">name</span><span class="o">=</span><span class="n">arg</span> +</pre></div> +</div> +<p>An example of specifying a parameter</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">param</span><span class="o">-</span><span class="n">CPreProcessor</span><span class="p">:</span><span class="n">if0</span><span class="o">=</span><span class="n">true</span> +</pre></div> +</div> +<p>Here <cite>if0</cite> is a name of parameter of CPreProcessor parser and +<cite>true</cite> is the value of it.</p> +<p>All available parameters can be listed with <code class="docutils literal notranslate"><span class="pre">--list-params</span></code> option.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --list-params +<span class="gp">#</span>PARSER NAME DESCRIPTION +<span class="go">CPreProcessor if0 examine code within "#if 0" branch (true or [false])</span> +<span class="go">CPreProcessor ignore a token to be specially handled</span> +</pre></div> +</div> +<p>(At this time only CPreProcessor parser has parameters.)</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Changes to the tags file format</a><ul> +<li><a class="reference internal" href="#f-kind-usage"><code class="docutils literal notranslate"><span class="pre">F</span></code> kind usage</a></li> +<li><a class="reference internal" href="#reference-tags">Reference tags</a></li> +<li><a class="reference internal" href="#pseudo-tags">Pseudo-tags</a><ul> +<li><a class="reference internal" href="#tag-kind-description"><code class="docutils literal notranslate"><span class="pre">TAG_KIND_DESCRIPTION</span></code></a></li> +<li><a class="reference internal" href="#tag-kind-separator"><code class="docutils literal notranslate"><span class="pre">TAG_KIND_SEPARATOR</span></code></a></li> +<li><a class="reference internal" href="#tag-output-filesep"><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_FILESEP</span></code></a></li> +<li><a class="reference internal" href="#tag-output-mode"><code class="docutils literal notranslate"><span class="pre">TAG_OUTPUT_MODE</span></code></a></li> +</ul> +</li> +<li><a class="reference internal" href="#truncating-the-pattern-for-long-input-lines">Truncating the pattern for long input lines</a></li> +<li><a class="reference internal" href="#parser-specific-fields">Parser specific fields</a></li> +<li><a class="reference internal" href="#parser-specific-extras">Parser specific extras</a><ul> +<li><a class="reference internal" href="#discussion">Discussion</a></li> +</ul> +</li> +<li><a class="reference internal" href="#parser-specific-parameter">Parser specific parameter</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="output-format.html" + title="previous chapter">Output formats</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="output-xref.html" + title="next chapter">Xref output</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="output-xref.html" title="Xref output" + >next</a> |</li> + <li class="right" > + <a href="output-format.html" title="Output formats" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" >Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">Changes to the tags file format</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/output-xref.html b/ctags/docs/output-xref.html new file mode 100644 index 0000000..4f9c67d --- /dev/null +++ b/ctags/docs/output-xref.html @@ -0,0 +1,236 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Xref output — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="JSON output" href="output-json.html" /> + <link rel="prev" title="Changes to the tags file format" href="output-tags.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="output-json.html" title="JSON output" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="output-tags.html" title="Changes to the tags file format" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" accesskey="U">Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">Xref output</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="xref-output"> +<span id="output-xref"></span><h1>Xref output<a class="headerlink" href="#xref-output" title="Permalink to this headline">¶</a></h1> +<p>Xref output is a tabular, human-readable cross reference (xref) format.</p> +<p>The default information contained in the output includes:</p> +<ul class="simple"> +<li><p>the tag name</p></li> +<li><p>the kind of tag</p></li> +<li><p>the line number</p></li> +<li><p>file name</p></li> +<li><p>source line (with extra white space condensed) of the file</p></li> +</ul> +<p><code class="docutils literal notranslate"><span class="pre">--_xformat</span></code> option allows a user to customize the output information. See +<a class="reference internal" href="#xformat"><span class="std std-ref">Customizing xref output</span></a> for more details.</p> +<p>Xref output goes to standard output by default.</p> +<p>Notes:</p> +<blockquote> +<div><ul class="simple"> +<li><p>Printing <cite>z`{kind} field in xref format doesn’t include `kind:</cite> prefix.</p></li> +<li><p>Printing <cite>Z`{scope} field in xref format doesn’t include `scope:</cite> prefix.</p></li> +</ul> +</div></blockquote> +<section id="customizing-xref-output"> +<span id="xformat"></span><h2>Customizing xref output<a class="headerlink" href="#customizing-xref-output" title="Permalink to this headline">¶</a></h2> +<p><code class="docutils literal notranslate"><span class="pre">--_xformat</span></code> option allows a user to customize the cross reference +(xref) output enabled with <code class="docutils literal notranslate"><span class="pre">-x</span></code>.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">_xformat</span><span class="o">=</span><span class="n">FORMAT</span> +</pre></div> +</div> +<p>The notation for FORMAT is similar to that employed by <cite>printf(3)</cite> in +the C language; <cite>%</cite> represents a slot which is substituted with a +field value when printing. You can specify multiple slots in FORMAT. +Here field means an item listed with <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> option.</p> +<p>The notation of a slot:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="p">[</span><span class="o">-</span><span class="p">][</span><span class="o">.</span><span class="p">][</span><span class="n">WIDTH</span><span class="o">-</span><span class="n">AND</span><span class="o">-</span><span class="n">ADJUSTMENT</span><span class="p">]</span><span class="n">FIELD</span><span class="o">-</span><span class="n">SPECIFIER</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">FIELD-SPECIFIER</span></code> specifies a field whose value is printed. +Short notation and long notation are available. They can be mixed +in a FORMAT. Specifying a field with either notation, one or more +fields are activated internally.</p> +<p>The short notation is just a letter listed in the LETTER column of +the <code class="docutils literal notranslate"><span class="pre">--list-fields</span></code> output.</p> +<p>The long notation is a name string surrounded by braces(<cite>{</cite> and +<cite>}</cite>). The name string is listed in the NAME column of the output of +the same option. To specify a field owned by a parser, prepend +the parser name to the name string with <cite>.</cite> as a separator.</p> +<p>Wild card (<cite>*</cite>) can be used where a parser name is specified. In this +case both common and parser specific fields are activated and printed. +If a common field and a parser specific field have the same name, +the common field has higher priority.</p> +<p><cite>WIDTH-AND-ADJUSTMENT</cite> is a positive number. +The value of the number is used as the width of +the column where a field is printed. The printing is +right adjusted by default, and left +adjusted when <cite>-</cite> is given as prefix. +The output is not truncated by default even if its field width is +specified and smaller than width of output value. For truncating +the output to the specified width, use <cite>.</cite> as prefix.</p> +<p>An example of specifying common fields:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -x --_xformat<span class="o">=</span><span class="s2">"%-20N %4n %-16{input}|"</span> main/main.c <span class="p">|</span> head +<span class="go">CLOCKS_PER_SEC 360 main/main.c |</span> +<span class="go">CLOCKS_PER_SEC 364 main/main.c |</span> +<span class="go">CLOCK_AVAILABLE 358 main/main.c |</span> +<span class="go">CLOCK_AVAILABLE 363 main/main.c |</span> +<span class="go">Totals 87 main/main.c |</span> +<span class="go">__anonae81ef0f0108 87 main/main.c |</span> +<span class="go">addTotals 100 main/main.c |</span> +<span class="go">batchMakeTags 436 main/main.c |</span> +<span class="go">bytes 87 main/main.c |</span> +<span class="go">clock 365 main/main.c |</span> +</pre></div> +</div> +<p>Here <cite>%-20N %4n %-16{input}|</cite> is a format string. Let’s look at the +elements of the format.</p> +<p><cite>%-20N</cite></p> +<blockquote> +<div><p>The short notation is used here. +The element means filling the slot with the name of the tag. +The width of the column is 20 characters and left adjusted.</p> +</div></blockquote> +<p><cite>%4n</cite></p> +<blockquote> +<div><p>The short notation is used here. +The element means filling the slot with the line number of +the tag. The width of the column is 4 characters and right +adjusted.</p> +</div></blockquote> +<p><cite>%-16{input}</cite></p> +<blockquote> +<div><p>The long notation is used here. +The element means filling the slot with the input file name +where the tag is defined. The width of column is 16 +characters and left adjusted.</p> +</div></blockquote> +<p><cite>|</cite></p> +<blockquote> +<div><p>Printed as is.</p> +</div></blockquote> +<p>Another example of specifying parser specific fields:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags -x --_xformat<span class="o">=</span><span class="s2">"%-20N [%10{C.properties}]"</span> main/main.c +<span class="go">CLOCKS_PER_SEC [ ]</span> +<span class="go">CLOCK_AVAILABLE [ ]</span> +<span class="go">Totals [ ]</span> +<span class="go">__anonae81ef0f0108 [ ]</span> +<span class="go">addTotals [ extern]</span> +<span class="go">batchMakeTags [ static]</span> +<span class="go">bytes [ ]</span> +<span class="go">clock [ ]</span> +<span class="go">clock [ static]</span> +<span class="go">...</span> +</pre></div> +</div> +<p>Here <cite>“%-20N [%10{C.properties}]”</cite> is a format string. Let’s look at +the elements of the format.</p> +<p><cite>%-20N</cite></p> +<blockquote> +<div><p>Already explained in the first example.</p> +</div></blockquote> +<p><cite>[</cite> and <cite>]</cite></p> +<blockquote> +<div><p>Printed as is.</p> +</div></blockquote> +<p><cite>%10{C.properties}</cite></p> +<blockquote> +<div><p>The long notation is used here. +The element means filling the slot with the value +of the properties field of the C parser. +The width of the column is 10 characters and right adjusted.</p> +</div></blockquote> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Xref output</a><ul> +<li><a class="reference internal" href="#customizing-xref-output">Customizing xref output</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="output-tags.html" + title="previous chapter">Changes to the tags file format</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="output-json.html" + title="next chapter">JSON output</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="output-json.html" title="JSON output" + >next</a> |</li> + <li class="right" > + <a href="output-tags.html" title="Changes to the tags file format" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="output-format.html" >Output formats</a> »</li> + <li class="nav-item nav-item-this"><a href="">Xref output</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-asm.html b/ctags/docs/parser-asm.html new file mode 100644 index 0000000..3e6d7f5 --- /dev/null +++ b/ctags/docs/parser-asm.html @@ -0,0 +1,119 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Asm parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="CMake parser" href="parser-cmake.html" /> + <link rel="prev" title="Parsers" href="parsers.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-cmake.html" title="CMake parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parsers.html" title="Parsers" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">Asm parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="asm-parser"> +<span id="asm"></span><h1>Asm parser<a class="headerlink" href="#asm-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<p>The original (Exuberant Ctags) parser handles #define C preprocessor directive and C +style comments by itself. In Universal Ctags Asm parser utilizes CPreProcessor meta +parser for handling them. So a language object defined with #define is tagged as +“defines” of CPreProcessor language, not Asm language.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat input.S +<span class="gp">#</span>define S <span class="m">1</span> + +<span class="gp">$ </span>e-ctags --fields<span class="o">=</span>+l -o - input.S +<span class="go">S input.S /^#define S 1$/;" d language:Asm</span> + +<span class="gp">$ </span>u-ctags --fields<span class="o">=</span>+l -o - input.S +<span class="go">S input.S /^#define S /;" d language:CPreProcessor file:</span> +</pre></div> +</div> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="parsers.html" + title="previous chapter">Parsers</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-cmake.html" + title="next chapter">CMake parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-cmake.html" title="CMake parser" + >next</a> |</li> + <li class="right" > + <a href="parsers.html" title="Parsers" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">Asm parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-cmake.html b/ctags/docs/parser-cmake.html new file mode 100644 index 0000000..b8158b4 --- /dev/null +++ b/ctags/docs/parser-cmake.html @@ -0,0 +1,128 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>CMake parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="The new C/C++ parser" href="parser-cxx.html" /> + <link rel="prev" title="Asm parser" href="parser-asm.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-cxx.html" title="The new C/C++ parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-asm.html" title="Asm parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">CMake parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="cmake-parser"> +<span id="cmake"></span><h1>CMake parser<a class="headerlink" href="#cmake-parser" title="Permalink to this headline">¶</a></h1> +<p>The CMake parser is used for <code class="docutils literal notranslate"><span class="pre">.cmake</span></code> and <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code> files. +It generates tags for the following items:</p> +<ul class="simple"> +<li><p>User-defined functions</p></li> +<li><p>User-defined macros</p></li> +<li><p>User-defined options created by <code class="docutils literal notranslate"><span class="pre">option()</span></code></p></li> +<li><p>Variables defined by <code class="docutils literal notranslate"><span class="pre">set()</span></code></p></li> +<li><p>Targets created by <code class="docutils literal notranslate"><span class="pre">add_custom_target()</span></code>, <code class="docutils literal notranslate"><span class="pre">add_executable()</span></code> and <code class="docutils literal notranslate"><span class="pre">add_library()</span></code></p></li> +</ul> +<p>The parser uses the experimental multi-table regex <code class="docutils literal notranslate"><span class="pre">ctags</span></code> options to +perform the parsing and tag generation.</p> +<p>Caveats:</p> +<blockquote> +<div><p>Names that are <code class="docutils literal notranslate"><span class="pre">${}</span></code> references to variables are not tagged.</p> +<p>For example, given the following:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>set(PROJECT_NAME_STR ${PROJECT_NAME}) +add_executable( ${PROJECT_NAME_STR} ... ) +add_custom_target( ${PROJECT_NAME_STR}_tests ... ) +add_library( sharedlib ... ) +</pre></div> +</div> +<p>…the variable <code class="docutils literal notranslate"><span class="pre">PROJECT_NAME_STR</span></code> and target <code class="docutils literal notranslate"><span class="pre">sharedlib</span></code> will both be tagged, +but the other targets will not be.</p> +</div></blockquote> +<p>References:</p> +<blockquote> +<div><p><a class="reference external" href="https://cmake.org/cmake/help/latest/manual/cmake-language.7.html">https://cmake.org/cmake/help/latest/manual/cmake-language.7.html</a></p> +</div></blockquote> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="parser-asm.html" + title="previous chapter">Asm parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-cxx.html" + title="next chapter">The new C/C++ parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-cxx.html" title="The new C/C++ parser" + >next</a> |</li> + <li class="right" > + <a href="parser-asm.html" title="Asm parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">CMake parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-cxx.html b/ctags/docs/parser-cxx.html new file mode 100644 index 0000000..5aa52b5 --- /dev/null +++ b/ctags/docs/parser-cxx.html @@ -0,0 +1,396 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>The new C/C++ parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="The new HTML parser" href="parser-html.html" /> + <link rel="prev" title="CMake parser" href="parser-cmake.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-html.html" title="The new HTML parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-cmake.html" title="CMake parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new C/C++ parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="the-new-c-c-parser"> +<span id="cxx"></span><h1>The new C/C++ parser<a class="headerlink" href="#the-new-c-c-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Szymon Tomasz Stefanek <<a class="reference external" href="mailto:s.stefanek%40gmail.com">s<span>.</span>stefanek<span>@</span>gmail<span>.</span>com</a>></p> +</dd> +</dl> +<section id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>The C++ language has strongly evolved since the old C/C++ parser was +written. The old parser was struggling with some of the new features +of the language and has shown signs of reaching its limits. For this +reason in February/March 2016 the C/C++ parser was rewritten from +scratch.</p> +<p>In the first release several outstanding bugs were fixed and some new +features were added. Among them:</p> +<ul class="simple"> +<li><p>Tagging of “using namespace” declarations</p></li> +<li><p>Tagging of function parameters</p></li> +<li><p>Extraction of function parameter types</p></li> +<li><p>Tagging of anonymous structures/unions/classes/enums</p></li> +<li><p>Support for C++11 lambdas (as anonymous functions)</p></li> +<li><p>Support for function-level scopes (for local variables and parameters)</p></li> +<li><p>Extraction of local variables which include calls to constructors</p></li> +<li><p>Extraction of local variables from within the for(), while(), if() +and switch() parentheses.</p></li> +<li><p>Support for function prototypes/declarations with trailing return type</p></li> +</ul> +<p>At the time of writing (March 2016) more features are planned.</p> +</section> +<section id="notable-new-features"> +<h2>Notable New Features<a class="headerlink" href="#notable-new-features" title="Permalink to this headline">¶</a></h2> +<p>Some of the notable new features are described below.</p> +<section id="properties"> +<h3>Properties<a class="headerlink" href="#properties" title="Permalink to this headline">¶</a></h3> +<p>Several properties of functions and variables can be extracted +and placed in a new field called <code class="docutils literal notranslate"><span class="pre">properties</span></code>. +The syntax to enable it is:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags ... --fields-c++<span class="o">=</span>+<span class="o">{</span>properties<span class="o">}</span> ... +</pre></div> +</div> +<p>At the time of writing the following properties are reported:</p> +<ul class="simple"> +<li><p><code class="docutils literal notranslate"><span class="pre">virtual</span></code>: a function is marked as virtual</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">static</span></code>: a function/variable is marked as static</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">inline</span></code>: a function implementation is marked as inline</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">explicit</span></code>: a function is marked as explicit</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">extern</span></code>: a function/variable is marked as extern</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">const</span></code>: a function is marked as const</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">pure</span></code>: a virtual function is pure (i.e = 0)</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">override</span></code>: a function is marked as override</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">default</span></code>: a function is marked as default</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">final</span></code>: a function is marked as final</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">delete</span></code>: a function is marked as delete</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">mutable</span></code>: a variable is marked as mutable</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">volatile</span></code>: a function is marked as volatile</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">specialization</span></code>: a function is a template specialization</p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">scopespecialization</span></code>: template specialization of scope <code class="docutils literal notranslate"><span class="pre">a<x>::b()</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">deprecated</span></code>: a function is marked as deprecated via <code class="docutils literal notranslate"><span class="pre">__attribute__</span></code></p></li> +<li><p><code class="docutils literal notranslate"><span class="pre">scopedenum</span></code>: a scoped enumeration (C++11)</p></li> +</ul> +</section> +<section id="preprocessor-macros"> +<h3>Preprocessor macros<a class="headerlink" href="#preprocessor-macros" title="Permalink to this headline">¶</a></h3> +<section id="defining-a-macro-from-command-line"> +<h4>Defining a macro from command line<a class="headerlink" href="#defining-a-macro-from-command-line" title="Permalink to this headline">¶</a></h4> +<p>The new parser supports the definition of real preprocessor macros +via the <code class="docutils literal notranslate"><span class="pre">-D</span></code> option. All types of macros are supported, +including the ones with parameters and variable arguments. +Stringification, token pasting and recursive macro expansion are also supported.</p> +<p>Option <code class="docutils literal notranslate"><span class="pre">-I</span></code> is now simply a backward-compatible syntax to define a +macro with no replacement.</p> +<p>The syntax is similar to the corresponding gcc <code class="docutils literal notranslate"><span class="pre">-D</span></code> option.</p> +<p>Some examples follow.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags ... -D IGNORE_THIS ... +</pre></div> +</div> +<p>With this commandline the following C/C++ input</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">IGNORE_THIS</span> <span class="n">a</span><span class="p">;</span> +</pre></div> +</div> +<p>will be processed as if it was</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">a</span><span class="p">;</span> +</pre></div> +</div> +<p>Defining a macro with parameters uses the following syntax:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags ... -D <span class="s2">"foreach(arg)=for(arg;;)"</span> ... +</pre></div> +</div> +<p>This example defines <code class="docutils literal notranslate"><span class="pre">for(arg;;)</span></code> as the replacement <code class="docutils literal notranslate"><span class="pre">foreach(arg)</span></code>. +So the following C/C++ input</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">foreach</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span> <span class="n">p</span><span class="p">,</span><span class="n">pointers</span><span class="p">)</span> +<span class="p">{</span> + +<span class="p">}</span> +</pre></div> +</div> +<p>is processed in new C/C++ parser as:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">for</span><span class="p">(</span><span class="kt">char</span> <span class="o">*</span> <span class="n">p</span><span class="p">;;)</span> +<span class="p">{</span> + +<span class="p">}</span> +</pre></div> +</div> +<p>and the p local variable can be extracted.</p> +<p>The previous commandline includes quotes since the macros generally contain +characters that are treated specially by the shells. You may need some escaping.</p> +<p>Token pasting is performed by the <code class="docutils literal notranslate"><span class="pre">##</span></code> operator, just like in the normal +C preprocessor.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags ... -D <span class="s2">"DECLARE_FUNCTION(prefix)=int prefix ## Call();"</span> +</pre></div> +</div> +<p>So the following code</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">DECLARE_FUNCTION</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> +<span class="n">DECLARE_FUNCTION</span><span class="p">(</span><span class="n">b</span><span class="p">)</span> +</pre></div> +</div> +<p>will be processed as</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">aCall</span><span class="p">();</span> +<span class="kt">int</span> <span class="nf">bCall</span><span class="p">();</span> +</pre></div> +</div> +<p>Macros with variable arguments use the gcc <code class="docutils literal notranslate"><span class="pre">__VA_ARGS__</span></code> syntax.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags ... -D <span class="s2">"DECLARE_FUNCTION(name,...)=int name(__VA_ARGS__);"</span> +</pre></div> +</div> +<p>So the following code</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">DECLARE_FUNCTION</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span><span class="kt">int</span> <span class="n">b</span><span class="p">)</span> +</pre></div> +</div> +<p>will be processed as</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">x</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span><span class="kt">int</span> <span class="n">b</span><span class="p">);</span> +</pre></div> +</div> +</section> +<section id="automatically-expanding-macros-defined-in-the-same-input-file-highly-experimental"> +<h4>Automatically expanding macros defined in the same input file (HIGHLY EXPERIMENTAL)<a class="headerlink" href="#automatically-expanding-macros-defined-in-the-same-input-file-highly-experimental" title="Permalink to this headline">¶</a></h4> +<p>If a CPreProcessor macro defined in a C/C++/CUDA file, the macro invocation in the +SAME file can be expanded with following options:</p> +<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>--param-CPreProcessor:_expand=1 +--fields-C=+{macrodef} +--fields-C++=+{macrodef} +--fields-CUDA=+{macrodef} +--fields=+{signature} +</pre></div> +</div> +<p>Let’s see an example.</p> +<p>input.c: +.. code-block:: C</p> +<blockquote> +<div><p>#define DEFUN(NAME) int NAME (int x, int y) +#define BEGIN { +#define END }</p> +<dl class="simple"> +<dt>DEFUN(myfunc)</dt><dd><p>BEGIN +return -1 +END</p> +</dd> +</dl> +</div></blockquote> +<p>The output without options: +.. code-block:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags -o - input.c +BEGIN input.c /^#define BEGIN /;" d language:C file: +DEFUN input.c /^#define DEFUN(/;" d language:C file: +END input.c /^#define END /;" d language:C file: +</pre></div> +</div> +<p>The output with options: +.. code-block:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --param-CPreProcessor:_expand=1 --fields-C=+'{macrodef}' --fields=+'{signature}' -o - input.c +BEGIN input.c /^#define BEGIN /;" d language:C file: macrodef:{ +DEFUN input.c /^#define DEFUN(/;" d language:C file: signature:(NAME) macrodef:int NAME (int x, int y) +END input.c /^#define END /;" d language:C file: macrodef:} +myfunc input.c /^DEFUN(myfunc)$/;" f language:C typeref:typename:int signature:(int x,int y) +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">myfunc</span></code> coded by <code class="docutils literal notranslate"><span class="pre">DEFUN</span></code> macro is captured well.</p> +<p>This feature is highly experimental. At least three limitations are known.</p> +<ul class="simple"> +<li><p>This feature doesn’t understand <code class="docutils literal notranslate"><span class="pre">#undef</span></code> yet. +Once a macro is defined, its invocation is always expanded even +after the parser sees <code class="docutils literal notranslate"><span class="pre">#undef</span></code> for the macro in the same input +file.</p></li> +<li><p>Macros are expanded incorrectly if the result of macro expansion +includes the macro invocation again.</p></li> +<li><p>Currently, ctags can expand a macro invocation only if its +definitions are in the same input file. ctags cannot expand a macro +defined in the header file included from the current input file.</p></li> +</ul> +<p>Enabling this macro expansion feature makes the parsing speed about +two times slower.</p> +</section> +</section> +</section> +<section id="incompatible-changes"> +<h2>Incompatible Changes<a class="headerlink" href="#incompatible-changes" title="Permalink to this headline">¶</a></h2> +<p>The parser is mostly compatible with the old one. There are some minor +incompatible changes which are described below.</p> +<section id="anonymous-structure-names"> +<h3>Anonymous structure names<a class="headerlink" href="#anonymous-structure-names" title="Permalink to this headline">¶</a></h3> +<p>The old parser produced structure names in the form <code class="docutils literal notranslate"><span class="pre">__anonN</span></code> where N +was a number starting at 1 in each file and increasing at each new +structure. This caused collisions in symbol names when ctags was run +on multiple files.</p> +<p>In the new parser the anonymous structure names depend on the file name +being processed and on the type of the structure itself. Collisions are +far less likely (though not impossible as hash functions are unavoidably +imperfect).</p> +<p>Pitfall: the file name used for hashing includes the path as passed to the +ctags executable. So the same file “seen” from different paths will produce +different structure names. This is unavoidable and is up to the user to +ensure that multiple ctags runs are started from a common directory root.</p> +</section> +<section id="file-scope"> +<h3>File scope<a class="headerlink" href="#file-scope" title="Permalink to this headline">¶</a></h3> +<p>The file scope information is not 100% reliable. It never was. +There are several cases in that compiler, linker or even source code +tricks can “unhide” file scope symbols (for instance *.c files can be +included into each other) and several other cases in that the limitation +of the scope of a symbol to a single file simply cannot be determined +with a single pass or without looking at a program as a whole.</p> +<p>The new parser defines a simple policy for file scope association +that tries to be as compatible as possible with the old parser and +should reflect the most common usages. The policy is the following:</p> +<ul class="simple"> +<li><p>Namespaces are in file scope if declared inside a .c or .cpp file</p></li> +<li><p>Function prototypes are in file scope if declared inside a .c or .cpp file</p></li> +<li><p>K&R style function definitions are in file scope if declared static +inside a .c file.</p></li> +<li><p>Function definitions appearing inside a namespace are in file scope only +if declared static inside a .c or .cpp file. +Note that this rule includes both global functions (global namespace) +and class/struct/union members defined outside of the class/struct/union +declaration.</p></li> +<li><p>Function definitions appearing inside a class/struct/union declaration +are in file scope only if declared static inside a .cpp file</p></li> +<li><p>Function parameters are always in file scope</p></li> +<li><p>Local variables are always in file scope</p></li> +<li><p>Variables appearing inside a namespace are in file scope only if +they are declared static inside a .c or .cpp file</p></li> +<li><p>Variables that are members of a class/struct/union are in file scope +only if declared in a .c or .cpp file</p></li> +<li><p>Typedefs are in file scope if appearing inside a .c or .cpp file</p></li> +</ul> +<p>Most of these rules are debatable in one way or the other. Just keep in mind +that this is not 100% reliable.</p> +</section> +<section id="inheritance-information"> +<h3>Inheritance information<a class="headerlink" href="#inheritance-information" title="Permalink to this headline">¶</a></h3> +<p>The new parser does not strip template names from base classes. +For a declaration like</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">template</span><span class="o"><</span><span class="n">typename</span> <span class="n">A</span><span class="o">></span> <span class="n">class</span> <span class="nl">B</span> <span class="p">:</span> <span class="n">public</span> <span class="n">C</span><span class="o"><</span><span class="n">A</span><span class="o">></span> +</pre></div> +</div> +<p>the old parser reported <code class="docutils literal notranslate"><span class="pre">C</span></code> as base class while the new one reports +<code class="docutils literal notranslate"><span class="pre">C<A></span></code>.</p> +</section> +<section id="typeref"> +<h3>Typeref<a class="headerlink" href="#typeref" title="Permalink to this headline">¶</a></h3> +<p>The syntax of the typeref field (<code class="docutils literal notranslate"><span class="pre">typeref:A:B</span></code>) was designed with only +struct/class/union/enum types in mind. Generic types don’t have <code class="docutils literal notranslate"><span class="pre">A</span></code> +information and the keywords became entirely optional in C++: +you just can’t tell. Furthermore, struct/class/union/enum types +share the same namespace and their names can’t collide, so the <code class="docutils literal notranslate"><span class="pre">A</span></code> +information is redundant for most purposes.</p> +<p>To accommodate generic types and preserve some degree of backward +compatibility the new parser uses struct/class/union/enum in place +of <code class="docutils literal notranslate"><span class="pre">A</span></code> where such keyword can be inferred. Where the information is +not available it uses the ‘typename’ keyword.</p> +<p>Generally, you should ignore the information in field <code class="docutils literal notranslate"><span class="pre">A</span></code> and use +only information in field <code class="docutils literal notranslate"><span class="pre">B</span></code>.</p> +</section> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">The new C/C++ parser</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +<li><a class="reference internal" href="#notable-new-features">Notable New Features</a><ul> +<li><a class="reference internal" href="#properties">Properties</a></li> +<li><a class="reference internal" href="#preprocessor-macros">Preprocessor macros</a><ul> +<li><a class="reference internal" href="#defining-a-macro-from-command-line">Defining a macro from command line</a></li> +<li><a class="reference internal" href="#automatically-expanding-macros-defined-in-the-same-input-file-highly-experimental">Automatically expanding macros defined in the same input file (HIGHLY EXPERIMENTAL)</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#incompatible-changes">Incompatible Changes</a><ul> +<li><a class="reference internal" href="#anonymous-structure-names">Anonymous structure names</a></li> +<li><a class="reference internal" href="#file-scope">File scope</a></li> +<li><a class="reference internal" href="#inheritance-information">Inheritance information</a></li> +<li><a class="reference internal" href="#typeref">Typeref</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="parser-cmake.html" + title="previous chapter">CMake parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-html.html" + title="next chapter">The new HTML parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-html.html" title="The new HTML parser" + >next</a> |</li> + <li class="right" > + <a href="parser-cmake.html" title="CMake parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new C/C++ parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-html.html b/ctags/docs/parser-html.html new file mode 100644 index 0000000..0e7f6f5 --- /dev/null +++ b/ctags/docs/parser-html.html @@ -0,0 +1,135 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>The new HTML parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="puppetManifest parser" href="parser-puppetManifest.html" /> + <link rel="prev" title="The new C/C++ parser" href="parser-cxx.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-puppetManifest.html" title="puppetManifest parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-cxx.html" title="The new C/C++ parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new HTML parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="the-new-html-parser"> +<span id="html"></span><h1>The new HTML parser<a class="headerlink" href="#the-new-html-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Jiri Techet <<a class="reference external" href="mailto:techet%40gmail.com">techet<span>@</span>gmail<span>.</span>com</a>></p> +</dd> +</dl> +<section id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>The old HTML parser was line-oriented based on regular expression matching. This +brought several limitations like the inability of the parser to deal with tags +spanning multiple lines and not respecting HTML comments. In addition, the speed +of the parser depended on the number of regular expressions - the more tag types +were extracted, the more regular expressions were needed and the slower the +parser became. Finally, parsing of embedded JavaScript was very limited, based +on regular expressions and detecting only function declarations.</p> +<p>The new parser is hand-written, using separated lexical analysis (dividing +the input into tokens) and syntax analysis. The parser has been profiled and +optimized for speed so it is one of the fastest parsers in Universal Ctags. +It handles HTML comments correctly and in addition to existing tags it extracts +also <h1>, <h2> and <h3> headings. It should be reasonably simple to add new +tag types.</p> +<p>Finally, the parser uses the new functionality of Universal Ctags to use another +parser for parsing other languages within a host language. This is used for +parsing JavaScript within <script> tags and CSS within <style> tags. This +simplifies the parser and generates much better results than having a simplified +JavaScript or CSS parser within the HTML parser. To run JavaScript and CSS parsers +from HTML parser, use <cite>--extras=+g</cite> option.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">The new HTML parser</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="parser-cxx.html" + title="previous chapter">The new C/C++ parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-puppetManifest.html" + title="next chapter">puppetManifest parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-puppetManifest.html" title="puppetManifest parser" + >next</a> |</li> + <li class="right" > + <a href="parser-cxx.html" title="The new C/C++ parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new HTML parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-in-c.html b/ctags/docs/parser-in-c.html new file mode 100644 index 0000000..a9dcbde --- /dev/null +++ b/ctags/docs/parser-in-c.html @@ -0,0 +1,199 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Writing a parser in C — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Input text stream" href="internal.html" /> + <link rel="prev" title="Extending ctags with a parser written in C" href="extending.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="internal.html" title="Input text stream" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="extending.html" title="Extending ctags with a parser written in C" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="extending.html" accesskey="U">Extending ctags with a parser written in C</a> »</li> + <li class="nav-item nav-item-this"><a href="">Writing a parser in C</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="writing-a-parser-in-c"> +<span id="writing-parser-in-c"></span><h1>Writing a parser in C<a class="headerlink" href="#writing-a-parser-in-c" title="Permalink to this headline">¶</a></h1> +<p>The section is based on the section “Integrating a new language parser” in “<a class="reference external" href="http://ctags.sourceforge.net/EXTENDING.html">How +to Add Support for a New Language to Exuberant Ctags (EXTENDING)</a>” of Exuberant Ctags documents.</p> +<p>Now suppose that I want to truly integrate compiled-in support for Swine into +ctags.</p> +<section id="registering-a-parser"> +<h2>Registering a parser<a class="headerlink" href="#registering-a-parser" title="Permalink to this headline">¶</a></h2> +<p>First, I create a new module, <code class="docutils literal notranslate"><span class="pre">swine.c</span></code>, and add one externally visible function +to it, <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">parserDefinition</span> <span class="pre">*SwineParser(void)</span></code>, and add its name to the +table in <code class="docutils literal notranslate"><span class="pre">parsers.h</span></code>. The job of this parser definition function is to create +an instance of the <code class="docutils literal notranslate"><span class="pre">parserDefinition</span></code> structure (using <code class="docutils literal notranslate"><span class="pre">parserNew()</span></code>) and +populate it with information defining how files of this language are recognized, +what kinds of tags it can locate, and the function used to invoke the parser on +the currently open file.</p> +<p>The structure <code class="docutils literal notranslate"><span class="pre">parserDefinition</span></code> allows assignment of the following fields:</p> +<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nc">sParserDefinition</span> <span class="p">{</span> + <span class="cm">/* defined by parser */</span> + <span class="kt">char</span><span class="o">*</span> <span class="n">name</span><span class="p">;</span> <span class="cm">/* name of language */</span> + <span class="n">kindDefinition</span><span class="o">*</span> <span class="n">kindTable</span><span class="p">;</span> <span class="cm">/* tag kinds handled by parser */</span> + <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">kindCount</span><span class="p">;</span> <span class="cm">/* size of 'kinds' list */</span> + <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="o">*</span><span class="n">extensions</span><span class="p">;</span> <span class="cm">/* list of default extensions */</span> + <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="o">*</span><span class="n">patterns</span><span class="p">;</span> <span class="cm">/* list of default file name patterns */</span> + <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="k">const</span> <span class="o">*</span><span class="n">aliases</span><span class="p">;</span> <span class="cm">/* list of default aliases (alternative names) */</span> + <span class="n">parserInitialize</span> <span class="n">initialize</span><span class="p">;</span> <span class="cm">/* initialization routine, if needed */</span> + <span class="n">parserFinalize</span> <span class="n">finalize</span><span class="p">;</span> <span class="cm">/* finalize routine, if needed */</span> + <span class="n">simpleParser</span> <span class="n">parser</span><span class="p">;</span> <span class="cm">/* simple parser (common case) */</span> + <span class="n">rescanParser</span> <span class="n">parser2</span><span class="p">;</span> <span class="cm">/* rescanning parser (unusual case) */</span> + <span class="n">selectLanguage</span><span class="o">*</span> <span class="n">selectLanguage</span><span class="p">;</span> <span class="cm">/* may be used to resolve conflicts */</span> + <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">method</span><span class="p">;</span> <span class="cm">/* See METHOD_ definitions above */</span> + <span class="kt">unsigned</span> <span class="kt">int</span> <span class="n">useCork</span><span class="p">;</span> <span class="cm">/* bit fields of corkUsage */</span> + <span class="p">...</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The <code class="docutils literal notranslate"><span class="pre">name</span></code> field must be set to a non-empty string. Also either <code class="docutils literal notranslate"><span class="pre">parser</span></code> or +<code class="docutils literal notranslate"><span class="pre">parser2</span></code> must set to point to a parsing routine which will generate the tag +entries. All other fields are optional.</p> +</section> +<section id="reading-input-file-stream"> +<h2>Reading input file stream<a class="headerlink" href="#reading-input-file-stream" title="Permalink to this headline">¶</a></h2> +<p>Now all that is left is to implement the parser. In order to do its job, the +parser should read the file stream using using one of the two I/O interfaces: +either the character-oriented <code class="docutils literal notranslate"><span class="pre">getcFromInputFile()</span></code>, or the line-oriented +<code class="docutils literal notranslate"><span class="pre">readLineFromInputFile()</span></code>.</p> +<p>See “<a class="reference internal" href="internal.html#input-text-stream"><span class="std std-ref">Input text stream</span></a>” for more details.</p> +</section> +<section id="parsing"> +<h2>Parsing<a class="headerlink" href="#parsing" title="Permalink to this headline">¶</a></h2> +<p>How our Swine parser actually parses the contents of the file is entirely up to +the writer of the parser--it can be as crude or elegant as desired. You will +note a variety of examples from the most complex (<code class="docutils literal notranslate"><span class="pre">parsers/cxx/*.[hc]</span></code>) to the +simplest (<code class="docutils literal notranslate"><span class="pre">parsers/make.[ch]</span></code>).</p> +</section> +<section id="adding-a-tag-to-the-tag-file"> +<h2>Adding a tag to the tag file<a class="headerlink" href="#adding-a-tag-to-the-tag-file" title="Permalink to this headline">¶</a></h2> +<p>When the Swine parser identifies an interesting token for which it wants to add +a tag to the tag file, it should create a <code class="docutils literal notranslate"><span class="pre">tagEntryInfo</span></code> structure and +initialize it by calling <code class="docutils literal notranslate"><span class="pre">initTagEntry()</span></code>, which initializes defaults and +fills information about the current line number and the file position of the +beginning of the line. After filling in information defining the current entry +(and possibly overriding the file position or other defaults), the parser passes +this structure to <code class="docutils literal notranslate"><span class="pre">makeTagEntry()</span></code>.</p> +<p>See “<a class="reference internal" href="internal.html#output-tag-stream"><span class="std std-ref">Output tag stream</span></a>” for more details.</p> +</section> +<section id="adding-the-parser-to-ctags"> +<h2>Adding the parser to <code class="docutils literal notranslate"><span class="pre">ctags</span></code><a class="headerlink" href="#adding-the-parser-to-ctags" title="Permalink to this headline">¶</a></h2> +<p>Lastly, be sure to add your the name of the file containing your parser (e.g. +<code class="docutils literal notranslate"><span class="pre">parsers/swine.c</span></code>) to the macro <code class="docutils literal notranslate"><span class="pre">PARSER_SRCS</span></code> in the file <code class="docutils literal notranslate"><span class="pre">source.mak</span></code>, so +that your new module will be compiled into the program.</p> +</section> +<section id="misc"> +<h2>Misc.<a class="headerlink" href="#misc" title="Permalink to this headline">¶</a></h2> +<p>This is all there is to it. All other details are specific to the parser and how +it wants to do its job.</p> +<p>There are some support functions which can take care of some commonly needed +parsing tasks, such as <em>keyword table lookups</em> (see <code class="docutils literal notranslate"><span class="pre">main/keyword.c</span></code>), which you +can make use of if desired (examples of its use can be found in <code class="docutils literal notranslate"><span class="pre">parsers/c.c</span></code>, +<code class="docutils literal notranslate"><span class="pre">parsers/eiffel.c</span></code>, and <code class="docutils literal notranslate"><span class="pre">parsers/fortran.c</span></code>).</p> +<p>Support functions can be found in <code class="docutils literal notranslate"><span class="pre">main/*.h</span></code> excluding <code class="docutils literal notranslate"><span class="pre">main/*_p.h</span></code>.</p> +<p>Almost everything is already taken care of automatically for you by the +infrastructure. Writing the actual parsing algorithm is the hardest part, but is +not constrained by any need to conform to anything in ctags other than that +mentioned above.</p> +<p>There are several different approaches used in the parsers inside Universal +Ctags and you can browse through these as examples of how to go about creating +your own.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Writing a parser in C</a><ul> +<li><a class="reference internal" href="#registering-a-parser">Registering a parser</a></li> +<li><a class="reference internal" href="#reading-input-file-stream">Reading input file stream</a></li> +<li><a class="reference internal" href="#parsing">Parsing</a></li> +<li><a class="reference internal" href="#adding-a-tag-to-the-tag-file">Adding a tag to the tag file</a></li> +<li><a class="reference internal" href="#adding-the-parser-to-ctags">Adding the parser to <code class="docutils literal notranslate"><span class="pre">ctags</span></code></a></li> +<li><a class="reference internal" href="#misc">Misc.</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="extending.html" + title="previous chapter">Extending ctags with a parser written in C</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="internal.html" + title="next chapter">Input text stream</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="internal.html" title="Input text stream" + >next</a> |</li> + <li class="right" > + <a href="extending.html" title="Extending ctags with a parser written in C" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="extending.html" >Extending ctags with a parser written in C</a> »</li> + <li class="nav-item nav-item-this"><a href="">Writing a parser in C</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-puppetManifest.html b/ctags/docs/parser-puppetManifest.html new file mode 100644 index 0000000..a6529f2 --- /dev/null +++ b/ctags/docs/parser-puppetManifest.html @@ -0,0 +1,116 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>puppetManifest parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="The new Python parser" href="parser-python.html" /> + <link rel="prev" title="The new HTML parser" href="parser-html.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-python.html" title="The new Python parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-html.html" title="The new HTML parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">puppetManifest parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="puppetmanifest-parser"> +<span id="puppetmanifest"></span><h1>puppetManifest parser<a class="headerlink" href="#puppetmanifest-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<p>puppetManifest is an experimental parser for testing multi tables +regex meta parser defined with <code class="docutils literal notranslate"><span class="pre">--_mtable-<LANG></span></code> option.</p> +<p>The parser has some bugs derived from the limit of the multi tables +regex meta parser.</p> +<p>Here document</p> +<blockquote> +<div><p>The parser cannot ignore the contents inside the area of +here document. The end marker of here document is defined +in the source code. Currently, ctags has no way to add a +regex pattern for detecting the end maker.</p> +</div></blockquote> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="parser-html.html" + title="previous chapter">The new HTML parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-python.html" + title="next chapter">The new Python parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-python.html" title="The new Python parser" + >next</a> |</li> + <li class="right" > + <a href="parser-html.html" title="The new HTML parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">puppetManifest parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-python.html b/ctags/docs/parser-python.html new file mode 100644 index 0000000..d09b433 --- /dev/null +++ b/ctags/docs/parser-python.html @@ -0,0 +1,142 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>The new Python parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="The new Tcl parser" href="parser-tcl.html" /> + <link rel="prev" title="puppetManifest parser" href="parser-puppetManifest.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-tcl.html" title="The new Tcl parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-puppetManifest.html" title="puppetManifest parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new Python parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="the-new-python-parser"> +<span id="python"></span><h1>The new Python parser<a class="headerlink" href="#the-new-python-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Colomban Wendling <<a class="reference external" href="mailto:ban%40herbesfolles.org">ban<span>@</span>herbesfolles<span>.</span>org</a>></p> +</dd> +</dl> +<section id="introduction"> +<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2> +<p>The old Python parser was a line-oriented parser that grew way beyond +its capabilities, and ended up riddled with hacks and easily fooled by +perfectly valid input. By design, it especially had problems dealing +with constructs spanning multiple lines, like triple-quoted strings +or implicitly continued lines; but several less tricky constructs were +also mishandled, and handling of lexical constructs was duplicated and +each clone evolved in its own direction, supporting different features +and having different bugs depending on the location.</p> +<p>All this made it very hard to fix some existing bugs, or add new +features. To fix this regrettable state of things, the parser has been +rewritten from scratch separating lexical analysis (generating tokens) +from syntactical analysis (understanding what the lexemes mean). +This moves understanding lexemes to a single location, making it +consistent and easier to extend with new lexemes, and lightens the +burden on the parsing code making it more concise, robust and clear.</p> +<p>This rewrite allowed to quite easily fix all known bugs of the old +parser, and add many new features, including:</p> +<ul class="simple"> +<li><p>Tagging function parameters</p></li> +<li><p>Extraction of decorators</p></li> +<li><p>Proper handling of semicolons</p></li> +<li><p>Extracting multiple variables in a combined declaration</p></li> +<li><p>More accurate support of mixed indentation</p></li> +<li><p>Tagging local variables</p></li> +</ul> +<p>The parser should be compatible with the old one.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">The new Python parser</a><ul> +<li><a class="reference internal" href="#introduction">Introduction</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="parser-puppetManifest.html" + title="previous chapter">puppetManifest parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-tcl.html" + title="next chapter">The new Tcl parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-tcl.html" title="The new Tcl parser" + >next</a> |</li> + <li class="right" > + <a href="parser-puppetManifest.html" title="puppetManifest parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new Python parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-tcl.html b/ctags/docs/parser-tcl.html new file mode 100644 index 0000000..a8a6c0e --- /dev/null +++ b/ctags/docs/parser-tcl.html @@ -0,0 +1,153 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>The new Tcl parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="The Vim parser" href="parser-vim.html" /> + <link rel="prev" title="The new Python parser" href="parser-python.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-vim.html" title="The Vim parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-python.html" title="The new Python parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new Tcl parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="the-new-tcl-parser"> +<span id="tcl"></span><h1>The new Tcl parser<a class="headerlink" href="#the-new-tcl-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<p>Tcl parser is rewritten as a token oriented parser to support +namespace. It was line oriented parser. Some incompatibility between +Exuberant Ctags is introduced in the rewriting.</p> +<p>The line oriented parser captures <cite>class</cite>, <cite>public|protected|private +method</cite>. They are definitions in ITcl and TclOO. The new token oriented Tcl +parser ignores them. Instead ITcl and TclOO subparser running on Tcl base +parser capture them.</p> +<section id="known-bugs"> +<h2>Known bugs<a class="headerlink" href="#known-bugs" title="Permalink to this headline">¶</a></h2> +<section id="full-qualified-tags"> +<h3>Full qualified tags<a class="headerlink" href="#full-qualified-tags" title="Permalink to this headline">¶</a></h3> +<p>The separator used in full qualified tags should be <cite>::</cite> but <cite>.</cite> is +used.</p> +<p>A ITcl or TclOO class <cite>C</cite> can be defined in a Tcl namespace <cite>N</cite>:</p> +<div class="highlight-Tcl notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> eval N <span class="k">{</span> + <span class="nv">oo</span><span class="o">::</span>class create C <span class="k">{</span> + <span class="k">}</span> +<span class="k">}</span> +</pre></div> +</div> +<p>When <code class="docutils literal notranslate"><span class="pre">--extras=+q</span></code> is given, currently ctags reports:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">N</span><span class="o">.</span><span class="n">C</span> <span class="o">...</span> +</pre></div> +</div> +<p>This should be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">N</span><span class="p">::</span><span class="n">C</span> <span class="o">...</span> +</pre></div> +</div> +<p>Much work is needed to fix this.</p> +</section> +<section id="nested-procs"> +<h3>Nested procs<a class="headerlink" href="#nested-procs" title="Permalink to this headline">¶</a></h3> +<p><cite>proc</cite> defined in a <cite>proc</cite> cannot be captured well. +This is a regression.</p> +</section> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">The new Tcl parser</a><ul> +<li><a class="reference internal" href="#known-bugs">Known bugs</a><ul> +<li><a class="reference internal" href="#full-qualified-tags">Full qualified tags</a></li> +<li><a class="reference internal" href="#nested-procs">Nested procs</a></li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="parser-python.html" + title="previous chapter">The new Python parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-vim.html" + title="next chapter">The Vim parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-vim.html" title="The Vim parser" + >next</a> |</li> + <li class="right" > + <a href="parser-python.html" title="The new Python parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The new Tcl parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-vim.html b/ctags/docs/parser-vim.html new file mode 100644 index 0000000..a41f490 --- /dev/null +++ b/ctags/docs/parser-vim.html @@ -0,0 +1,122 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>The Vim parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="XSLT parser" href="parser-xslt.html" /> + <link rel="prev" title="The new Tcl parser" href="parser-tcl.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-xslt.html" title="XSLT parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-tcl.html" title="The new Tcl parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The Vim parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="the-vim-parser"> +<span id="vim"></span><h1>The Vim parser<a class="headerlink" href="#the-vim-parser" title="Permalink to this headline">¶</a></h1> +<section id="incompatible-change"> +<h2>Incompatible change<a class="headerlink" href="#incompatible-change" title="Permalink to this headline">¶</a></h2> +<p>Quoted from <code class="docutils literal notranslate"><span class="pre">:help</span> <span class="pre">script-variable</span></code> in the Vim documentation:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">*</span><span class="n">script</span><span class="o">-</span><span class="n">variable</span><span class="o">*</span> <span class="o">*</span><span class="n">s</span><span class="p">:</span><span class="n">var</span><span class="o">*</span> +<span class="n">In</span> <span class="n">a</span> <span class="n">Vim</span> <span class="n">script</span> <span class="n">variables</span> <span class="n">starting</span> <span class="k">with</span> <span class="s2">"s:"</span> <span class="n">can</span> <span class="n">be</span> <span class="n">used</span><span class="o">.</span> <span class="n">They</span> +<span class="n">cannot</span> <span class="n">be</span> <span class="n">accessed</span> <span class="kn">from</span> <span class="nn">outside</span> <span class="n">of</span> <span class="n">the</span> <span class="n">scripts</span><span class="p">,</span> <span class="n">thus</span> <span class="n">are</span> <span class="n">local</span> <span class="n">to</span> +<span class="n">the</span> <span class="n">script</span><span class="o">.</span> +</pre></div> +</div> +<p>Exuberant Ctags records the prefix <cite>s:</cite> as part of a script-local +variable’s name. However, it is omitted from function names. As +requested in issue #852 on GitHub, Universal Ctags now also includes +the prefix in script-local function names.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">The Vim parser</a><ul> +<li><a class="reference internal" href="#incompatible-change">Incompatible change</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="parser-tcl.html" + title="previous chapter">The new Tcl parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-xslt.html" + title="next chapter">XSLT parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-xslt.html" title="XSLT parser" + >next</a> |</li> + <li class="right" > + <a href="parser-tcl.html" title="The new Tcl parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">The Vim parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parser-xslt.html b/ctags/docs/parser-xslt.html new file mode 100644 index 0000000..29adb79 --- /dev/null +++ b/ctags/docs/parser-xslt.html @@ -0,0 +1,117 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>XSLT parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Option files" href="option-file.html" /> + <link rel="prev" title="The Vim parser" href="parser-vim.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="option-file.html" title="Option files" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="parser-vim.html" title="The Vim parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" accesskey="U">Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">XSLT parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="xslt-parser"> +<span id="xslt"></span><h1>XSLT parser<a class="headerlink" href="#xslt-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<p>This parser only supports XSLT 1.0. +If a newer version (2.0 and 3.0) is specified in an input file, ctags +just skips the input. With <code class="docutils literal notranslate"><span class="pre">--verbose</span></code>, ctags prints the detected +version of the input file.</p> +<p>Scope information generated by the XSLT parser is a bit broken. +Currently a period (<cite>.</cite>) is used as the separator in nested scopes. +This is the default separator value in ctags.</p> +<p>When the XSLT parser captures a node <cite><xsl:template match=”…”></cite> the +value of the <cite>match</cite> attribute is tagged with kind <cite>matchedTemplate</cite>. +When a <cite>matchedTemplate</cite> name is stored as part of the scope information, +client tools may be confused because <cite>.</cite> is used both as the scope separator +and in the XPath match expression.</p> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="parser-vim.html" + title="previous chapter">The Vim parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="option-file.html" + title="next chapter">Option files</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="option-file.html" title="Option files" + >next</a> |</li> + <li class="right" > + <a href="parser-vim.html" title="The Vim parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="parsers.html" >Parsers</a> »</li> + <li class="nav-item nav-item-this"><a href="">XSLT parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/parsers.html b/ctags/docs/parsers.html new file mode 100644 index 0000000..33a64ca --- /dev/null +++ b/ctags/docs/parsers.html @@ -0,0 +1,129 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Parsers — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Asm parser" href="parser-asm.html" /> + <link rel="prev" title="readtags" href="man/readtags.1.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="parser-asm.html" title="Asm parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="man/readtags.1.html" title="readtags" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Parsers</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="parsers"> +<h1>Parsers<a class="headerlink" href="#parsers" title="Permalink to this headline">¶</a></h1> +<p>This section deals with individual parser topics.</p> +<div class="toctree-wrapper compound"> +<ul> +<li class="toctree-l1"><a class="reference internal" href="parser-asm.html">Asm parser</a></li> +<li class="toctree-l1"><a class="reference internal" href="parser-cmake.html">CMake parser</a></li> +<li class="toctree-l1"><a class="reference internal" href="parser-cxx.html">The new C/C++ parser</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-cxx.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-cxx.html#notable-new-features">Notable New Features</a></li> +<li class="toctree-l2"><a class="reference internal" href="parser-cxx.html#incompatible-changes">Incompatible Changes</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="parser-html.html">The new HTML parser</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-html.html#introduction">Introduction</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="parser-puppetManifest.html">puppetManifest parser</a></li> +<li class="toctree-l1"><a class="reference internal" href="parser-python.html">The new Python parser</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-python.html#introduction">Introduction</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="parser-tcl.html">The new Tcl parser</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-tcl.html#known-bugs">Known bugs</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="parser-vim.html">The Vim parser</a><ul> +<li class="toctree-l2"><a class="reference internal" href="parser-vim.html#incompatible-change">Incompatible change</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="parser-xslt.html">XSLT parser</a></li> +</ul> +</div> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h4>Previous topic</h4> + <p class="topless"><a href="man/readtags.1.html" + title="previous chapter">readtags</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="parser-asm.html" + title="next chapter">Asm parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="parser-asm.html" title="Asm parser" + >next</a> |</li> + <li class="right" > + <a href="man/readtags.1.html" title="readtags" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Parsers</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/reporting.html b/ctags/docs/reporting.html new file mode 100644 index 0000000..94b5475 --- /dev/null +++ b/ctags/docs/reporting.html @@ -0,0 +1,302 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Request for extending a parser (or Reporting a bug of parser) — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Contributions" href="contributions.html" /> + <link rel="prev" title="Testing a parser" href="testing.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="contributions.html" title="Contributions" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="testing.html" title="Testing a parser" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Request for extending a parser (or Reporting a bug of parser)</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="request-for-extending-a-parser-or-reporting-a-bug-of-parser"> +<h1>Request for extending a parser (or Reporting a bug of parser)<a class="headerlink" href="#request-for-extending-a-parser-or-reporting-a-bug-of-parser" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#before-reporting" id="id1">Before reporting</a></p></li> +<li><p><a class="reference internal" href="#the-content-of-report" id="id2">The content of report</a></p></li> +<li><p><a class="reference internal" href="#an-example-of-good-report" id="id3">An example of good report</a></p></li> +</ul> +</div> +<hr class="docutils" /> +<p>Sometimes you will find u-ctags doesn’t make a tag for a language +object unexpectedly. Writing a patch for making the tag is +appreciate. However, you may not have time to do so. In that case, you +can open an issue on the GitHub page of u-ctags.</p> +<p>This section tells you how to drive u-ctags developers effectively.</p> +<section id="before-reporting"> +<h2><a class="toc-backref" href="#id1">Before reporting</a><a class="headerlink" href="#before-reporting" title="Permalink to this headline">¶</a></h2> +<p>U-Ctags just captures the definitions of language objects. U-ctags +has an infrastructure for capturing references for language objects. +However, we implement reference tagging limited area. We will not +work on writing new code for capturing references for your favorite +language. About requests for capturing reference tags, we will say +“patches are welcome.”.</p> +<p>What kind of language objects u-ctags captures is controlled by +<cite>--kind-<LANG></cite> option. Some kinds are disabled by default because we +assume people don’t want too large <cite>tags</cite> file. When you cannot find a +language object you want in a tags file, it is worth for checking the +status of kinds. <cite>--list-kinds=<LANG></cite> or (<cite>--list-kinds-full=<LANG></cite>) +option lists the status of the given language.</p> +<p>Let’s see an example.</p> +<p>Consider following input (foo.h):</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nc">point</span> <span class="p">{</span> + <span class="kt">int</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">;</span> +<span class="p">};</span> + +<span class="k">struct</span> <span class="nc">point</span> <span class="o">*</span><span class="n">make_point</span><span class="p">(</span><span class="kt">int</span> <span class="n">x0</span><span class="p">,</span> <span class="kt">int</span> <span class="n">y0</span><span class="p">);</span> +</pre></div> +</div> +<p>tags output generated with <cite>u-ctags -o - /tmp/foo.h</cite> is as following.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>point foo.h /^struct point {$/;" s +x foo.h /^ int x, y;$/;" m struct:point typeref:typename:int +y foo.h /^ int x, y;$/;" m struct:point typeref:typename:int +</pre></div> +</div> +<p>Though <cite>point</cite>, <cite>x</cite> and <cite>y</cite> are tagged, the declaration <cite>make_point</cite> +is not tagged because <cite>prototype</cite> kind of C++ is disabled by default. +You can know it from the output of <cite>ctags --list-kinds-full=C++</cite>.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION</span> +<span class="n">A</span> <span class="n">alias</span> <span class="n">no</span> <span class="n">no</span> <span class="mi">0</span> <span class="n">NONE</span> <span class="n">namespace</span> <span class="n">aliases</span> +<span class="n">L</span> <span class="n">label</span> <span class="n">no</span> <span class="n">no</span> <span class="mi">0</span> <span class="n">C</span> <span class="n">goto</span> <span class="n">labels</span> +<span class="n">N</span> <span class="n">name</span> <span class="n">no</span> <span class="n">no</span> <span class="mi">0</span> <span class="n">NONE</span> <span class="n">names</span> <span class="n">imported</span> <span class="n">via</span> <span class="n">using</span> <span class="n">scope</span><span class="p">::</span><span class="n">symbol</span> +<span class="o">...</span> +<span class="n">p</span> <span class="n">prototype</span> <span class="n">no</span> <span class="n">no</span> <span class="mi">0</span> <span class="n">C</span> <span class="n">function</span> <span class="n">prototypes</span> +</pre></div> +</div> +<p>By turning on the kind with <cite>--kinds-C++=+p</cite>, u-ctags tags +<cite>make_point</cite>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>make_point foo.h /^struct point *make_point(int x0, int y0);$/;" p typeref:struct:point * +point foo.h /^struct point {$/;" s +x foo.h /^ int x, y;$/;" m struct:point typeref:typename:int +y foo.h /^ int x, y;$/;" m struct:point typeref:typename:int +</pre></div> +</div> +<p>Wildcard <cite>*</cite> is for enabling all kinds of a language at once. +<cite>--kinds-C++=*</cite> option enables all kinds of C++ parser. If you specify <cite>all</cite> +as the name of <cite><LANG></cite>, you can enable all kinds of all languages at once.</p> +</section> +<section id="the-content-of-report"> +<h2><a class="toc-backref" href="#id2">The content of report</a><a class="headerlink" href="#the-content-of-report" title="Permalink to this headline">¶</a></h2> +<p>Don’t assume following three things.</p> +<p>U-ctags developers know vi.</p> +<blockquote> +<div><p>If you explain the expectation about how tags related functions of vi +and its plugins, U-ctags developers don’t understand it. +The answer from them can be “it can be a bug of vi.”</p> +</div></blockquote> +<p>U-ctags developers know the programming language that you are talking.</p> +<blockquote> +<div><p>U-ctags developers need your help to understand the meaning of +language object you asked tagging especially about kind. A person +extending a parser have to decide a kind of newly tagging language +object: reusing an existing kind or introducing a new kind. +U-ctags developers expect a report know the concept kind, field, +and extra. ctags.1 man page of u-ctags explains them.</p> +</div></blockquote> +<p>English is the native language of the head maintainer.</p> +<blockquote> +<div><p>I don’t want to write this but I have to write this. +Following are my private request for reporters.</p> +<p>Instead of long explanation, showing code or output +examples make me understand what you want.</p> +<p>Don’t omit sentences. Please, write your sentence +in full.</p> +<p>Use pronounce fewer.</p> +</div></blockquote> +<p>U-ctags can generate something meaningful from a broken input.</p> +<blockquote> +<div><p>From garbage, u-ctags generates garbage. +For a syntactically broken input source file, U-ctags +does not work well. U-ctags developers will not work +on improving u-ctags for handing such input. +The exception is that macro related input. Well known +one is C and C++.</p> +</div></blockquote> +<p>Following a tuple with three items helps us to understand what you want.</p> +<ol class="arabic"> +<li><p>Input file</p> +<blockquote> +<div><p>A shorter input file is better. However, it must be syntactically +valid. Show the URL (or something) where you get the input +file. It is needed to incorporate the input file to the u-ctags +source tree as a test case.</p> +</div></blockquote> +</li> +<li><p>Command line running u-ctags</p></li> +<li><p>Expected output</p></li> +</ol> +<p>These three items should be rendered preformatted form on an issue +page of GitHub. Use triple backquotes notation of GitHub’s +markdown notation. I will close an issue with a bad notation +like this <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/1547">issue</a>.</p> +</section> +<section id="an-example-of-good-report"> +<h2><a class="toc-backref" href="#id3">An example of good report</a><a class="headerlink" href="#an-example-of-good-report" title="Permalink to this headline">¶</a></h2> +<p>For the following input file(input.f90), u-ctags reports incomplete pattern +for function <cite>f</cite> at the line 23.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>! input.f90, taken from https://github.com/universal-ctags/ctags/issues/1616 +module example_mod + + ! This module contains two interfaces: + ! 1. f_interface, which is an interface to the local f function + ! 2. g, which is implemented in the example_smod submodule + + interface f_interface + ! The function `f` is defined below, within the `contains` statement + module function f(x) result(y) + integer :: x, y + end function f + end interface f_interface + + interface + ! The function `g` is implemented in example_smod.f90 + module function g(x) result(y) + integer :: x,y + end function g + end interface + + contains + function f(x) result(y) + integer :: x, y + + y = x * 2 + end function f +end module example_mod +</pre></div> +</div> +<p>I run ctags with following command line:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">u</span><span class="o">-</span><span class="n">ctags</span> <span class="o">--</span><span class="n">fields</span><span class="o">=+</span><span class="n">n</span> <span class="o">-</span><span class="n">o</span> <span class="o">-</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="nb">input</span><span class="o">.</span><span class="n">f90</span> +</pre></div> +</div> +<p>What I got:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>example_mod /tmp/input.f90 /^module example_mod$/;" m line:2 +f /tmp/input.f90 /^ fu/;" f line:23 +f_interface /tmp/input.f90 /^ interface f_interface$/;" i line:8 module:example_mod +</pre></div> +</div> +<p>I think this should be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>example_mod /tmp/input.f90 /^module example_mod$/;" m line:2 +f /tmp/input.f90 /^ function f/;" f line:23 +f_interface /tmp/input.f90 /^ interface f_interface$/;" i line:8 module:example_mod +</pre></div> +</div> +<p>or:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>example_mod /tmp/input.f90 /^module example_mod$/;" m line:2 +f /tmp/input.f90 /^ function f(x) result(y)/;" f line:23 +f_interface /tmp/input.f90 /^ interface f_interface$/;" i line:8 module:example_mod +</pre></div> +</div> +<p>Either way, <cite>/^ fu/</cite> is too short as a pattern.</p> +<p>The version of u-ctags is <cite>83b0d1f6</cite>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ u-ctags --version +Universal Ctags 0.0.0(83b0d1f6), Copyright (C) 2015 Universal Ctags Team +Universal Ctags is derived from Exuberant Ctags. +Exuberant Ctags 5.8, Copyright (C) 1996-2009 Darren Hiebert + Compiled: Dec 15 2017, 08:07:36 + URL: https://ctags.io/ + Optional compiled features: +wildcards, +regex, +multibyte, +debug, +option-directory, +xpath, +json, +interactive, +sandbox, +yaml +</pre></div> +</div> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Request for extending a parser (or Reporting a bug of parser)</a><ul> +<li><a class="reference internal" href="#before-reporting">Before reporting</a></li> +<li><a class="reference internal" href="#the-content-of-report">The content of report</a></li> +<li><a class="reference internal" href="#an-example-of-good-report">An example of good report</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="testing.html" + title="previous chapter">Testing a parser</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="contributions.html" + title="next chapter">Contributions</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="contributions.html" title="Contributions" + >next</a> |</li> + <li class="right" > + <a href="testing.html" title="Testing a parser" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Request for extending a parser (or Reporting a bug of parser)</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/running-multi-parsers.html b/ctags/docs/running-multi-parsers.html new file mode 100644 index 0000000..7e1d620 --- /dev/null +++ b/ctags/docs/running-multi-parsers.html @@ -0,0 +1,548 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Running multiple parsers on an input file — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Interactive mode" href="interactive-mode.html" /> + <link rel="prev" title="JSON output" href="output-json.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="interactive-mode.html" title="Interactive mode" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="output-json.html" title="JSON output" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Running multiple parsers on an input file</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="running-multiple-parsers-on-an-input-file"> +<span id="multiple-parsers"></span><h1>Running multiple parsers on an input file<a class="headerlink" href="#running-multiple-parsers-on-an-input-file" title="Permalink to this headline">¶</a></h1> +<p>Universal Ctags provides parser developers two ways, <em>guest parser</em> (guest/host) +and <em>subparser</em> (sub/base), to run multiple parsers for an input file.</p> +<p>This section shows concepts behind the running multiple parsers and real +examples.</p> +<section id="guest-parser-applying-a-parser-to-specified-areas-of-input-file"> +<span id="host-guest-parsers"></span><h2>Guest parser: Applying a parser to specified areas of input file<a class="headerlink" href="#guest-parser-applying-a-parser-to-specified-areas-of-input-file" title="Permalink to this headline">¶</a></h2> +<p><em>Guest parser</em> (guest/host) considers the case that an input file has areas +written in languages different from the language for the input file.</p> +<p>A <em>host parser</em> parses the input file and detects the areas. +The host parser schedules <em>guest parsers</em> parsing the areas. +The guest parsers parse the areas.</p> +<figure class="align-default"> +<a class="reference internal image-reference" href="_images/area-and-parsers.svg"><img alt="_images/area-and-parsers.svg" src="_images/area-and-parsers.svg" /></a> +</figure> +<section id="command-line-interface"> +<h3>Command line interface<a class="headerlink" href="#command-line-interface" title="Permalink to this headline">¶</a></h3> +<p>Running guest parser can be controlled with guest (<code class="docutils literal notranslate"><span class="pre">g</span></code>) extras flag. +By default it is disabled. To turning on the feature running +guest parser, specify <code class="docutils literal notranslate"><span class="pre">--extras=+g</span></code>.</p> +<p>If <code class="docutils literal notranslate"><span class="pre">--fields=+E</span></code> is given, all tags generated by a guest parser is marked +<code class="docutils literal notranslate"><span class="pre">guest</span></code> in their <code class="docutils literal notranslate"><span class="pre">extras:</span></code> fields.</p> +</section> +<section id="examples-of-guest-parser"> +<h3>Examples of guest parser<a class="headerlink" href="#examples-of-guest-parser" title="Permalink to this headline">¶</a></h3> +<section id="css-javascript-html-parser-combination"> +<h4>{CSS,JavaScript}/HTML parser combination<a class="headerlink" href="#css-javascript-html-parser-combination" title="Permalink to this headline">¶</a></h4> +<p>For an 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?</p> +<p>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.</p> +<p>Here HTML parser is a <em>host parser</em>. CSS and JavaScript parsers +are <em>guest parsers</em>.</p> +<p>See “<a class="reference internal" href="parser-html.html#html"><span class="std std-ref">The new HTML parser</span></a>” and “<a class="reference external" href="https://github.com/universal-ctags/ctags/blob/master/parsers/html.c">parsers/html.c</a>”.</p> +</section> +<section id="c-yacc-parser-combination"> +<h4>C/Yacc parser combination<a class="headerlink" href="#c-yacc-parser-combination" title="Permalink to this headline">¶</a></h4> +<p>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.</p> +<p>Here YACC parser is a host parser. C parser is a guest parser. +See “<a class="reference external" href="https://github.com/universal-ctags/ctags/blob/master/parsers/yacc.c">parsers/yacc.c</a>”.</p> +</section> +<section id="pod-perl-parser-combination"> +<h4>Pod/Perl parser combination<a class="headerlink" href="#pod-perl-parser-combination" title="Permalink to this headline">¶</a></h4> +<p>Pod (Plain Old Documentation) is a language for documentation. The language +can be used not only in a stand alone file but also it can be +used inside a Perl script.</p> +<p>Universal Ctags has both parsers for Perl and Pod. +The Perl parser recognizes the area where Pod document is +embedded in a Perl script and schedules applying pod parser +as a guest parser on the area.</p> +</section> +</section> +</section> +<section id="subparser-tagging-definitions-of-higher-upper-level-language"> +<span id="base-sub-parsers"></span><h2>Subparser: Tagging definitions of higher (upper) level language<a class="headerlink" href="#subparser-tagging-definitions-of-higher-upper-level-language" title="Permalink to this headline">¶</a></h2> +<section id="background"> +<h3>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h3> +<p>Consider an application written in language X. The application has +its domain own concepts. Developers of the application may try to +express the concepts in the syntax of language X.</p> +<p>In language X level, the developer can define functions, variables, types, and +so on. Further more, if the syntax of X allows, the developers want to +define higher level (= application level) things for implementing the +domain own concepts.</p> +<p>Let me show the part of source code of SPY-WARS, an imaginary game application. +It is written in scheme language, a dialect of lisp. +(Here <a class="reference external" href="https://practical-scheme.net/gauche/index.html">gauche</a> is considered +as the implementation of scheme interpreter).</p> +<div class="highlight-scheme notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="k">define </span><span class="nv">agent-tables</span> <span class="p">(</span><span class="nf">make-hash-table</span><span class="p">))</span> +<span class="p">(</span><span class="nf">define-class</span> <span class="nv"><agent></span> <span class="p">()</span> + <span class="p">((</span><span class="nf">rights</span> <span class="nv">:init-keyword</span> <span class="nv">:rights</span><span class="p">)</span> + <span class="p">(</span><span class="nf">responsibilities</span> <span class="nv">:init-keyword</span> <span class="nv">:responsibilities</span><span class="p">)))</span> + +<span class="p">(</span><span class="nf">define-macro</span> <span class="p">(</span><span class="nf">define-agent</span> <span class="nv">name</span> <span class="nv">rights</span> <span class="nv">responsibilities</span><span class="p">)</span> + <span class="o">`</span><span class="p">(</span><span class="nf">hash-table-put!</span> <span class="nv">agent-tables</span> <span class="ss">',name</span> + <span class="p">(</span><span class="nf">make</span> <span class="nv"><agent></span> + <span class="nv">:rights</span> <span class="ss">',rights</span> + <span class="nv">:responsibilities</span> <span class="ss">',responsibilities</span><span class="p">)))</span> + +<span class="p">(</span><span class="nf">define-agent</span> <span class="nv">Bond</span> <span class="p">(</span><span class="nf">kill</span> <span class="o">...</span><span class="p">)</span> <span class="o">...</span><span class="p">)</span> +<span class="p">(</span><span class="nf">define-agent</span> <span class="nv">Bourne</span> <span class="o">...</span><span class="p">)</span> + +<span class="o">...</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">define</span></code>, <code class="docutils literal notranslate"><span class="pre">define-class</span></code>, and <code class="docutils literal notranslate"><span class="pre">define-macro</span></code> are keywords of scheme +for defining a variable, class and macro. Therefore scheme parser of +ctags should make tags for <code class="docutils literal notranslate"><span class="pre">agent-tables</span></code> with variable kind, +<code class="docutils literal notranslate"><span class="pre"><agent></span></code> with class kind, and <code class="docutils literal notranslate"><span class="pre">define-agent</span></code> with macro kind. +There is no discussion here.</p> +<blockquote> +<div><p>NOTE: To be exactly <code class="docutils literal notranslate"><span class="pre">define-class</span></code> and <code class="docutils literal notranslate"><span class="pre">define-macro</span></code> are not the part +of scheme language. They are part of gauche. That means three parsers +are stacked: scheme, gosh, and SPY-WARS.</p> +</div></blockquote> +<p>The interesting things here are <code class="docutils literal notranslate"><span class="pre">Bond</span></code> and <code class="docutils literal notranslate"><span class="pre">Bourne</span></code>.</p> +<div class="highlight-scheme notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="nf">define-agent</span> <span class="nv">Bond</span> <span class="p">(</span><span class="nf">kill</span> <span class="o">...</span><span class="p">)</span> <span class="o">...</span><span class="p">)</span> +<span class="p">(</span><span class="nf">define-agent</span> <span class="nv">Bourne</span> <span class="o">...</span><span class="p">)</span> +</pre></div> +</div> +<p>In scheme parser level, the two expressions define nothing; the two +expressions are just macro (<code class="docutils literal notranslate"><span class="pre">define-agent</span></code>) expansions.</p> +<p>However, in the application level, they define agents as the +macro name shown. In this level Universal Ctags should capture +<code class="docutils literal notranslate"><span class="pre">Bond</span></code> and <code class="docutils literal notranslate"><span class="pre">Bourne</span></code>. The question is which parser should +capture them? scheme parser should not; define-agent is not part of +scheme language. Newly defined SPY-WARS parser is the answer.</p> +<p>Though <code class="docutils literal notranslate"><span class="pre">define-agent</span></code> is just a macro in scheme parser level, +it is keyword in SPY-WARS parser. SPY-WARS parser makes a +tag for a token next to <code class="docutils literal notranslate"><span class="pre">define-agent</span></code>.</p> +<p>The above example illustrates levels of language in an input +file. scheme is used as the base language. With the base language we +can assume an imaginary higher level language named SPY-WARS is used +to write the application. To parse the source code of the application +written in two stacked language, ctags uses the two stacked parsers.</p> +<p>Making higher level language is very popular technique in the +languages of lisp family (see “<a class="reference external" href="http://www.paulgraham.com/onlisp.html">On Lisp</a>” for more details). +However, it is not special to lisp.</p> +<p>Following code is taken from linux kernel written in C:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">DEFINE_EVENT</span><span class="p">(</span><span class="n">mac80211_msg_event</span><span class="p">,</span> <span class="n">mac80211_info</span><span class="p">,</span> + <span class="n">TP_PROTO</span><span class="p">(</span><span class="k">struct</span> <span class="nc">va_format</span> <span class="o">*</span><span class="n">vaf</span><span class="p">),</span> + <span class="n">TP_ARGS</span><span class="p">(</span><span class="n">vaf</span><span class="p">)</span> +<span class="p">);</span> +</pre></div> +</div> +<p>There is no concept EVENT in C language, however it make sense in the +source tree of linux kernel. So we can consider linux parser, based on +C parser, which tags <code class="docutils literal notranslate"><span class="pre">mac80211_msg_event</span></code> as <code class="docutils literal notranslate"><span class="pre">event</span></code> kind.</p> +</section> +<section id="terms"> +<h3>Terms<a class="headerlink" href="#terms" title="Permalink to this headline">¶</a></h3> +<section id="base-parser-and-subparser"> +<h4>Base parser and subparser<a class="headerlink" href="#base-parser-and-subparser" title="Permalink to this headline">¶</a></h4> +<p>In the context of the SPY-WARS example, scheme parser is called a <em>base +parser</em>. The SPY-WARS is called a <em>subparser</em>. A base parser tags +definitions found in lower level view. A subparser on the base parser tags +definitions found in higher level view. This relationship can be nested. +A subparser can be a base parser for another subparser.</p> +<figure class="align-default"> +<a class="reference internal image-reference" href="_images/stack-and-parsers.svg"><img alt="_images/stack-and-parsers.svg" src="_images/stack-and-parsers.svg" /></a> +</figure> +<p>At a glance the relationship between two parsers are similar to the +relationship guest parser and host parser description in +“<a class="reference internal" href="#host-guest-parsers"><span class="std std-ref">Guest parser: Applying a parser to specified areas of input file</span></a>”. +However, they are different. Though a guest +parser can run stand-alone, a subparser cannot; a subparser needs help +from base parser to work.</p> +</section> +<section id="top-down-parser-choice-and-bottom-up-parser-choice"> +<h4>Top down parser choice and bottom up parser choice<a class="headerlink" href="#top-down-parser-choice-and-bottom-up-parser-choice" title="Permalink to this headline">¶</a></h4> +<p>There are two ways to run a subparser: <em>top down</em> or <em>bottom up</em> parser +choices.</p> +<p>Universal Ctags can chose a subparser <a class="reference internal" href="man/ctags.1.html#guessing"><span class="std std-ref">automatically</span></a>. +Matching file name patterns and extensions are the typical ways for +choosing. A user can choose a subparser with <code class="docutils literal notranslate"><span class="pre">--language-force=</span></code> option. +Choosing a parser in these deterministic way is called <em>top down</em>. +When a parser is chosen as a subparser in the top down way, the +subparser must call its base parser. The base parser may call methods +defined in the subparser.</p> +<p>Universal Ctags uses <em>bottom up</em> choice when the top down way +doesn’t work; a given file name doesn’t match any patterns and +extensions of subparsers and the user doesn’t specify +<code class="docutils literal notranslate"><span class="pre">--language-force=</span></code> explicitly. In choosing a subparser bottom up way +it is assumed that a base parser for the subparser can be chosen +by top down way. During a base parser running, the base parser tries +to detect use of higher level languages in the input file. As shown +later in this section, the base parser utilizes methods defined in its +subparsers for the detection. If the base parser detects the use of a +higher level language, a subparser for the higher level language is +chosen. Choosing a parser in this non-deterministic way (dynamic way) +is called <em>bottom up</em>.</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 64%" /> +<col style="width: 36%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>input file</p></th> +<th class="head"><p>subparser choices</p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><em><SUB_LANG></em> (<code class="docutils literal notranslate"><span class="pre">input.sub</span></code>)</p></td> +<td><p>top down</p></td> +</tr> +<tr class="row-odd"><td><p><em><BASE_LANG></em> (<code class="docutils literal notranslate"><span class="pre">input.base</span></code>)</p></td> +<td><p>bottom up</p></td> +</tr> +</tbody> +</table> +<p>Here is an example. Universal Ctags has both m4 parser and Autoconf +parser. The m4 parser is a base parser. The Autoconf parser is a +subparser based on the m4 parser. If <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code> is given as an +input file, Autoconf parser is chosen automatically because the +Autoconf parser has <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code> in its patterns list. Based on the +pattern matching, Universal Ctags chooses the Autoconf parser +automatically (top down choice).</p> +<p>If <code class="docutils literal notranslate"><span class="pre">input.m4</span></code> is given as an input file, the Autoconf parser is +not chosen. Instead the m4 parser is chosen automatically because +the m4 parser has <code class="docutils literal notranslate"><span class="pre">.m4</span></code> in its extension list. The m4 parser passes +every token finding in the input file to the +Autoconf parser. The Autoconf parser gets the chance to probe +whether the Autoconf parser itself can handle the input or not; if +a token name is started with <code class="docutils literal notranslate"><span class="pre">AC_</span></code>, the Autoconf parser +reports “this is Autoconf input though its file extension +is <code class="docutils literal notranslate"><span class="pre">.m4</span></code>” to the m4 parser. As the result the Autoconf parser is +chosen (bottom up choice).</p> +<p>Some subparsers can be chosen both top down and bottom up ways. Some +subparser can be chosen only top down way or bottom up ways.</p> +</section> +<section id="direction-flags"> +<span id="multiple-parsers-directions"></span><h4>Direction flags<a class="headerlink" href="#direction-flags" title="Permalink to this headline">¶</a></h4> +<p><em>Direction flags</em> specify how a base parser and a subparser work together. You +can choose directions by putting a long flag after +<code class="docutils literal notranslate"><span class="pre">--langdef=<SUB_LANG>{base=<BASE_LANG>}</span></code>.</p> +<p>The following three direction flags are available;</p> +<dl> +<dt><code class="docutils literal notranslate"><span class="pre">shared</span></code> (default):</dt><dd><p>For an input file of <em><BASE_LANG></em> (ex. <code class="docutils literal notranslate"><span class="pre">input.base</span></code>), tags captured by +both <em><BASE_LANG></em> and <em><SUB_LANG></em> parser are recorded to tags file.</p> +<p>For an input file of <em><SUB_LANG></em> (ex. <code class="docutils literal notranslate"><span class="pre">input.sub</span></code>), tags captured by only +<em><SUB_LANG></em> parser are recorded to tags file.</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 26%" /> +<col style="width: 36%" /> +<col style="width: 38%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>input file</p></th> +<th class="head"><p>tags of <em><BASE_LANG></em></p></th> +<th class="head"><p>tags of <em><SUB_LANG></em></p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">input.base</span></code></p></td> +<td><p>recorded</p></td> +<td><p>recorded</p></td> +</tr> +<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">input.sub</span></code></p></td> +<td><p>---</p></td> +<td><p>recorded</p></td> +</tr> +</tbody> +</table> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">dedicated</span></code>:</dt><dd><p>For an input file of <em><BASE_LANG></em> (ex. <code class="docutils literal notranslate"><span class="pre">input.base</span></code>), tags captured by +only <em><BASE_LANG></em> parser are recorded to tags file.</p> +<p>For an input file of <em><SUB_LANG></em> (ex. <code class="docutils literal notranslate"><span class="pre">input.sub</span></code>), tags captured by both +<em><BASE_LANG></em> and <em><SUB_LANG></em> parser are recorded to tags file.</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 26%" /> +<col style="width: 36%" /> +<col style="width: 38%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>input file</p></th> +<th class="head"><p>tags of <em><BASE_LANG></em></p></th> +<th class="head"><p>tags of <em><SUB_LANG></em></p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">input.base</span></code></p></td> +<td><p>recorded</p></td> +<td><p>---</p></td> +</tr> +<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">input.sub</span></code></p></td> +<td><p>recorded</p></td> +<td><p>recorded</p></td> +</tr> +</tbody> +</table> +</dd> +<dt><code class="docutils literal notranslate"><span class="pre">bidirectional</span></code>:</dt><dd><p>For an input file of both <em><BASE_LANG></em> (ex. <code class="docutils literal notranslate"><span class="pre">input.base</span></code>) and +<em><SUB_LANG></em> (ex. <code class="docutils literal notranslate"><span class="pre">input.sub</span></code>), tags captured by both <em><BASE_LANG></em> and +<SUB_LANG> parser are recorded to tags file.</p> +<table class="docutils align-default"> +<colgroup> +<col style="width: 26%" /> +<col style="width: 36%" /> +<col style="width: 38%" /> +</colgroup> +<thead> +<tr class="row-odd"><th class="head"><p>input file</p></th> +<th class="head"><p>tags of <em><BASE_LANG></em></p></th> +<th class="head"><p>tags of <em><SUB_LANG></em></p></th> +</tr> +</thead> +<tbody> +<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">input.base</span></code></p></td> +<td><p>recorded</p></td> +<td><p>recorded</p></td> +</tr> +<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">input.sub</span></code></p></td> +<td><p>recorded</p></td> +<td><p>recorded</p></td> +</tr> +</tbody> +</table> +</dd> +</dl> +<p>If no direction flag is specified, it implies <code class="docutils literal notranslate"><span class="pre">{shared}</span></code>.</p> +<p>See “<a class="reference internal" href="optlib.html#optlib-directions"><span class="std std-ref">Direction flags</span></a>” in “<a class="reference internal" href="optlib.html#optlib"><span class="std std-ref">Extending ctags with Regex parser (optlib)</span></a>” for examples of using the +direction flags.</p> +</section> +</section> +<section id="listing-subparsers"> +<h3>Listing subparsers<a class="headerlink" href="#listing-subparsers" title="Permalink to this headline">¶</a></h3> +<p>Subparsers can be listed with <code class="docutils literal notranslate"><span class="pre">--list-subparser</span></code>:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --options<span class="o">=</span>./linux.ctags --list-subparsers<span class="o">=</span>C +<span class="gp">#</span>NAME BASEPARSER DIRECTION +<span class="go">linux C base => sub {shared}</span> +</pre></div> +</div> +</section> +<section id="id1"> +<h3>Command line interface<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p>Running subparser can be controlled with subparser (<code class="docutils literal notranslate"><span class="pre">s</span></code>) extras flag. +By default it is enabled. To turning off the feature running +subparser, specify <code class="docutils literal notranslate"><span class="pre">--extras=-s</span></code>.</p> +</section> +<section id="examples-of-subparser"> +<h3>Examples of subparser<a class="headerlink" href="#examples-of-subparser" title="Permalink to this headline">¶</a></h3> +<section id="automake-make-parser-combination"> +<h4>Automake/Make parser combination<a class="headerlink" href="#automake-make-parser-combination" title="Permalink to this headline">¶</a></h4> +<p>Simply to say the syntax of Automake is the subset of Make. However, +the Automake parser has interests in Make macros having special +suffixes: <code class="docutils literal notranslate"><span class="pre">_PROGRAMS</span></code>, <code class="docutils literal notranslate"><span class="pre">_LTLIBRARIES</span></code>, and <code class="docutils literal notranslate"><span class="pre">_SCRIPTS</span></code> so on.</p> +<p>Here is an example of input for Automake:</p> +<div class="highlight-Make notranslate"><div class="highlight"><pre><span></span><span class="nv">bin_PROGRAMS</span> <span class="o">=</span> ctags +<span class="nv">ctags_CPPFLAGS</span> <span class="o">=</span> <span class="se">\</span> + -I. <span class="se">\</span> + -I<span class="k">$(</span>srcdir<span class="k">)</span> <span class="se">\</span> + -I<span class="k">$(</span>srcdir<span class="k">)</span>/main +</pre></div> +</div> +<p>From the point of the view of the Make parser, <code class="docutils literal notranslate"><span class="pre">bin_PROGRAMS</span></code> is a just +a macro; the Make parser tags <code class="docutils literal notranslate"><span class="pre">bin_PROGRAMS</span></code> as a macro. The Make parser +doesn’t tag <code class="docutils literal notranslate"><span class="pre">ctags</span></code> being right side of ‘<code class="docutils literal notranslate"><span class="pre">=</span></code>’ because it is not a new +name: just a value assigned to bin_PROGRAMS. However, for the Automake +parser <code class="docutils literal notranslate"><span class="pre">ctags</span></code> is a new name; the Automake parser tags <code class="docutils literal notranslate"><span class="pre">ctags</span></code> with +kind <code class="docutils literal notranslate"><span class="pre">Program</span></code>. The Automake parser can tag it with getting help from +the Make parser.</p> +<p>The Automake parser is an exclusive subparser. It is chosen in top +down way; an input file name <code class="docutils literal notranslate"><span class="pre">Makefile.am</span></code> gives enough information for +choosing the Automake parser.</p> +<p>To give chances to the Automake parser to capture Automake own +definitions, The Make parser provides following interface in +<code class="docutils literal notranslate"><span class="pre">parsers/make.h</span></code>:</p> +<div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nc">sMakeSubparser</span> <span class="p">{</span> + <span class="n">subparser</span> <span class="n">subparser</span><span class="p">;</span> + + <span class="kt">void</span> <span class="p">(</span><span class="o">*</span> <span class="n">valueNotify</span><span class="p">)</span> <span class="p">(</span><span class="n">makeSubparser</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">name</span><span class="p">);</span> + <span class="kt">void</span> <span class="p">(</span><span class="o">*</span> <span class="n">directiveNotify</span><span class="p">)</span> <span class="p">(</span><span class="n">makeSubparser</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> <span class="kt">char</span><span class="o">*</span> <span class="n">name</span><span class="p">);</span> + <span class="kt">void</span> <span class="p">(</span><span class="o">*</span> <span class="n">newMacroNotify</span><span class="p">)</span> <span class="p">(</span><span class="n">makeSubparser</span> <span class="o">*</span><span class="n">s</span><span class="p">,</span> + <span class="kt">char</span><span class="o">*</span> <span class="n">name</span><span class="p">,</span> + <span class="kt">bool</span> <span class="n">withDefineDirective</span><span class="p">,</span> + <span class="kt">bool</span> <span class="n">appending</span><span class="p">);</span> +<span class="p">};</span> +</pre></div> +</div> +<p>The Automake parser defines methods for tagging Automake own definitions +in a <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">sMakeSubparser</span></code> type variable, and runs the Make parser by +calling <code class="docutils literal notranslate"><span class="pre">scheduleRunningBaseparser</span></code> function.</p> +<p>The Make parser tags Make own definitions in an input file. In +addition Make parser calls the methods during parsing the input file.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --fields<span class="o">=</span>+lK --extras<span class="o">=</span>+r -o - Makefile.am +<span class="go">bin Makefile.am /^bin_PROGRAMS = ctags$/;" directory language:Automake</span> +<span class="go">bin_PROGRAMS Makefile.am /^bin_PROGRAMS = ctags$/;" macro language:Make</span> +<span class="go">ctags Makefile.am /^bin_PROGRAMS = ctags$/;" program language:Automake directory:bin</span> +<span class="go">ctags_CPPFLAGS Makefile.am /^ctags_CPPFLAGS = \\$/;" macro language:Make</span> +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">bin_PROGRAMS</span></code> and <code class="docutils literal notranslate"><span class="pre">ctags_CPPFLAGS</span></code> are tagged as macros of Make. +In addition <code class="docutils literal notranslate"><span class="pre">bin</span></code> is tagged as directory, and <code class="docutils literal notranslate"><span class="pre">ctags</span></code> as program of Automake.</p> +<p><code class="docutils literal notranslate"><span class="pre">bin</span></code> is tagged in a callback function assigned to <code class="docutils literal notranslate"><span class="pre">newMacroFound</span></code> method. +<code class="docutils literal notranslate"><span class="pre">ctags</span></code> is tagged in a callback function assigned to <code class="docutils literal notranslate"><span class="pre">valuesFound</span></code> method.</p> +<p><code class="docutils literal notranslate"><span class="pre">--extras=+r</span></code> is used in the example. Reference (<code class="docutils literal notranslate"><span class="pre">r</span></code>) extra is needed to +tag <code class="docutils literal notranslate"><span class="pre">bin</span></code>. <code class="docutils literal notranslate"><span class="pre">bin</span></code> is not defined in the line, <code class="docutils literal notranslate"><span class="pre">bin_PROGRAMS</span> <span class="pre">=</span></code>. +<code class="docutils literal notranslate"><span class="pre">bin</span></code> is referenced as a name of directory where programs are +stored. Therefore <code class="docutils literal notranslate"><span class="pre">r</span></code> is needed.</p> +<p>For tagging <code class="docutils literal notranslate"><span class="pre">ctags</span></code>, the Automake parser must recognize +<code class="docutils literal notranslate"><span class="pre">bin</span></code> in <code class="docutils literal notranslate"><span class="pre">bin_PROGRAMS</span></code> first. <code class="docutils literal notranslate"><span class="pre">ctags</span></code> is tagged +because it is specified as a value for <code class="docutils literal notranslate"><span class="pre">bin_PROGRAMS</span></code>. +As the result <code class="docutils literal notranslate"><span class="pre">r</span></code> is also needed to tag <code class="docutils literal notranslate"><span class="pre">ctags</span></code>.</p> +<p>Only Automake related tags are emitted if Make parser is +disabled.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>ctags --languages<span class="o">=</span>-Make --fields<span class="o">=</span>+lKr --extras<span class="o">=</span>+r -o - Makefile.am +<span class="go">bin Makefile.am /^bin_PROGRAMS = ctags$/;" directory language:Automake roles:program</span> +<span class="go">ctags Makefile.am /^bin_PROGRAMS = ctags$/;" program language:Automake directory:bin</span> +</pre></div> +</div> +</section> +<section id="autoconf-m4-parser-combination"> +<h4>Autoconf/M4 parser combination<a class="headerlink" href="#autoconf-m4-parser-combination" title="Permalink to this headline">¶</a></h4> +<p>Universal Ctags uses m4 parser as a base parser and Autoconf parse as +a subparser for <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code> input file.</p> +<div class="highlight-Autoconf notranslate"><div class="highlight"><pre><span></span>AC_DEFUN([PRETTY_VAR_EXPAND], + [$(eval "$as_echo_n" $(eval "$as_echo_n" "${$1}"))]) +</pre></div> +</div> +<p>The m4 parser finds no definition here. However, Autoconf parser finds +<code class="docutils literal notranslate"><span class="pre">PRETTY_VAR_EXPAND</span></code> as a macro definition. Syntax like <code class="docutils literal notranslate"><span class="pre">(...)</span></code> is part +of M4 language. So Autoconf parser is implemented as a subparser of +m4 parser. The most parts of tokens in input files are handled by +M4. Autoconf parser gives hints for parsing <code class="docutils literal notranslate"><span class="pre">configure.ac</span></code> and +registers callback functions to +Autoconf parser.</p> +</section> +</section> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Running multiple parsers on an input file</a><ul> +<li><a class="reference internal" href="#guest-parser-applying-a-parser-to-specified-areas-of-input-file">Guest parser: Applying a parser to specified areas of input file</a><ul> +<li><a class="reference internal" href="#command-line-interface">Command line interface</a></li> +<li><a class="reference internal" href="#examples-of-guest-parser">Examples of guest parser</a><ul> +<li><a class="reference internal" href="#css-javascript-html-parser-combination">{CSS,JavaScript}/HTML parser combination</a></li> +<li><a class="reference internal" href="#c-yacc-parser-combination">C/Yacc parser combination</a></li> +<li><a class="reference internal" href="#pod-perl-parser-combination">Pod/Perl parser combination</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#subparser-tagging-definitions-of-higher-upper-level-language">Subparser: Tagging definitions of higher (upper) level language</a><ul> +<li><a class="reference internal" href="#background">Background</a></li> +<li><a class="reference internal" href="#terms">Terms</a><ul> +<li><a class="reference internal" href="#base-parser-and-subparser">Base parser and subparser</a></li> +<li><a class="reference internal" href="#top-down-parser-choice-and-bottom-up-parser-choice">Top down parser choice and bottom up parser choice</a></li> +<li><a class="reference internal" href="#direction-flags">Direction flags</a></li> +</ul> +</li> +<li><a class="reference internal" href="#listing-subparsers">Listing subparsers</a></li> +<li><a class="reference internal" href="#id1">Command line interface</a></li> +<li><a class="reference internal" href="#examples-of-subparser">Examples of subparser</a><ul> +<li><a class="reference internal" href="#automake-make-parser-combination">Automake/Make parser combination</a></li> +<li><a class="reference internal" href="#autoconf-m4-parser-combination">Autoconf/M4 parser combination</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="output-json.html" + title="previous chapter">JSON output</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="interactive-mode.html" + title="next chapter">Interactive mode</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="interactive-mode.html" title="Interactive mode" + >next</a> |</li> + <li class="right" > + <a href="output-json.html" title="JSON output" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Running multiple parsers on an input file</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/search.html b/ctags/docs/search.html new file mode 100644 index 0000000..c2d1a7a --- /dev/null +++ b/ctags/docs/search.html @@ -0,0 +1,98 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <title>Search — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <script src="_static/searchtools.js"></script> + <script src="_static/language_data.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="#" /> + <script src="searchindex.js" defer></script> + + + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Search</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <h1 id="search-documentation">Search</h1> + + <div id="fallback" class="admonition warning"> + <script>$('#fallback').hide();</script> + <p> + Please activate JavaScript to enable the search + functionality. + </p> + </div> + + + <p> + Searching for multiple words only shows matches that contain + all words. + </p> + + + <form action="" method="get"> + <input type="text" name="q" aria-labelledby="search-documentation" value="" /> + <input type="submit" value="search" /> + <span id="search-progress" style="padding-left: 10px"></span> + </form> + + + + <div id="search-results"> + + </div> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Search</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/searchindex.js b/ctags/docs/searchindex.js new file mode 100644 index 0000000..d9745c2 --- /dev/null +++ b/ctags/docs/searchindex.js @@ -0,0 +1 @@ +Search.setIndex({docnames:["autotools","building","contributions","developers","extending","index","interactive-mode","internal","man-pages","man/ctags-client-tools.7","man/ctags-faq.7","man/ctags-incompatibilities.7","man/ctags-lang-iPythonCell.7","man/ctags-lang-inko.7","man/ctags-lang-julia.7","man/ctags-lang-python.7","man/ctags-lang-r.7","man/ctags-lang-sql.7","man/ctags-lang-verilog.7","man/ctags-optlib.7","man/ctags.1","man/readtags.1","man/tags.5","news","option-file","optlib","optscript","osx","other-projects","output-format","output-json","output-tags","output-xref","parser-asm","parser-cmake","parser-cxx","parser-html","parser-in-c","parser-puppetManifest","parser-python","parser-tcl","parser-vim","parser-xslt","parsers","reporting","running-multi-parsers","testing","tips","tracking","windows"],envversion:{"sphinx.domains.c":2,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":3,"sphinx.domains.index":1,"sphinx.domains.javascript":2,"sphinx.domains.math":2,"sphinx.domains.python":3,"sphinx.domains.rst":2,"sphinx.domains.std":2,sphinx:56},filenames:["autotools.rst","building.rst","contributions.rst","developers.rst","extending.rst","index.rst","interactive-mode.rst","internal.rst","man-pages.rst","man/ctags-client-tools.7.rst","man/ctags-faq.7.rst","man/ctags-incompatibilities.7.rst","man/ctags-lang-iPythonCell.7.rst","man/ctags-lang-inko.7.rst","man/ctags-lang-julia.7.rst","man/ctags-lang-python.7.rst","man/ctags-lang-r.7.rst","man/ctags-lang-sql.7.rst","man/ctags-lang-verilog.7.rst","man/ctags-optlib.7.rst","man/ctags.1.rst","man/readtags.1.rst","man/tags.5.rst","news.rst","option-file.rst","optlib.rst","optscript.rst","osx.rst","other-projects.rst","output-format.rst","output-json.rst","output-tags.rst","output-xref.rst","parser-asm.rst","parser-cmake.rst","parser-cxx.rst","parser-html.rst","parser-in-c.rst","parser-puppetManifest.rst","parser-python.rst","parser-tcl.rst","parser-vim.rst","parser-xslt.rst","parsers.rst","reporting.rst","running-multi-parsers.rst","testing.rst","tips.rst","tracking.rst","windows.rst"],objects:{},objnames:{},objtypes:{},terms:{"0":[2,6,7,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,25,26,31,35,42,44,46],"000":17,"01":[28,48],"02":2,"02ec2066b5be6b129eba49685bd0b17fef4acfa":[28,48],"04":[28,48],"06":22,"07":44,"08":[28,44,48],"0900":2,"0alpha":17,"0end":25,"0th":7,"0x01":22,"0x07":22,"0x08":22,"0x0b":22,"0x0c":22,"0x1f":22,"0x20":22,"0x21":22,"0x7f":22,"1":[2,5,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,25,28,29,31,33,35,42,44,45,46,47,48,49],"10":[2,3,9,10,25,32],"100":[22,32,35],"10k":25,"10l":25,"11":[28,35,48],"116":46,"12":[2,28,48],"120":26,"133":46,"1364":18,"1409":25,"15":[22,44],"154":46,"15cedc6c94e95110cc319b5cdad7807caf3db1f4":[28,48],"16":32,"1616":44,"1620780":18,"16f":31,"16n":31,"17":6,"170":46,"177":[28,48],"1795612":46,"18":[28,48],"1800":18,"1850914":46,"187":46,"1878155":46,"1880687":46,"19":2,"1903":10,"1996":44,"1998":22,"1end":25,"1st":25,"1start":25,"2":[2,7,9,10,11,16,17,19,20,21,22,25,26,28,29,31,42,44,46,47,48],"20":[28,32,48],"2005":18,"2008":3,"2009":[2,44],"2013":[28,48,49],"2014":[28,48],"2015":[3,44],"2016":[2,35],"2017":[18,44],"2019":2,"2023624":46,"20n":[25,32],"21":[28,48],"216880c5287e0421d9c49898d983144db61c83aa":[28,48],"219":25,"22":[28,48],"23":[28,44,48],"230":46,"24":[28,48],"25":[17,28,48],"255":7,"26":[28,48],"2674":18,"271":[28,48],"28window":[28,48],"29":[28,48],"2end":25,"2f7a78ce21e4156ec3e63c821827cf1d5680ace8":[28,48],"2nd":[9,10,25],"2start":25,"3":[2,7,10,16,19,20,21,23,24,25,26,28,31,32,42,46,47,48,49],"30":[28,48,49],"3000":20,"3006":17,"317":25,"3184782":46,"32":[28,48,49],"320":[28,48],"324":[28,48],"33":[28,48],"341":[28,48],"347":46,"355":[28,48],"356":[28,48],"358":[28,32,48],"36":[28,44,48],"360":[28,32,48],"361":[28,48],"363":[28,32,48],"364":[28,32,48],"365":[28,32,48],"366":[28,48],"367":[28,48],"37":2,"38":[28,48],"383":47,"389":22,"39":17,"393":2,"3rd":[7,9,25],"3start":25,"4":[7,10,16,19,20,25,26,28,31,32,46,48,49],"405":[28,48],"41":[28,48],"413":[28,48],"436":32,"45":9,"4576213":[28,48],"47":[28,48],"49":9,"4a95e4a55f67230fc4eee91ffb31c18c422df6d3":[28,48],"4b6b4a72f3d2d4ef969d7c650de1829d79f0ea7c":[28,48],"4n":[31,32],"4th":25,"5":[5,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,26,28,29,31,44,46,48,49],"50":[9,28,48],"502355489b1ba748b1a235641bbd512ba6da315":[28,48],"51":[28,46,48],"512":22,"55":[28,48],"5606f3f711afeac74587a249650a5f7b416f19b":[28,48],"569":31,"5d774f6022a1af71fa5866994699aafce0253085":[28,48],"5th":7,"6":[20,25,31],"63":28,"64":[17,28,48,49],"64a05963c108af4b7832a2215006ff5cafcaaebb":2,"65":[28,48],"67":[28,48],"682a7f3b180c27c1196f8a1ae662d6e8ad142939":[28,48],"698bf2f3db692946d2358892d228a864014abc4b":[28,48],"7":[2,4,5,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,28,30,31,34,46,48],"74":[28,48],"75":46,"77":[3,47],"7fb36a2f4690374526e9e7ef4f1e24800b6914ec":[28,48],"8":[19,20,22,28,44,48,49],"80":[28,48],"80c1522a36df3ba52b8b7cd7f5c79d5c30437a63":[28,48],"81":[28,48],"82":[28,48],"8299595":18,"83":[28,48],"83b0d1f6":44,"84":[28,48],"85":[28,48],"852":41,"852101":[28,48],"857":31,"8590bbef5fcf70f6747d509808c29bf84342cd0d":[28,48],"87":32,"89":22,"8cc2b482f6c7257c5151893a6d02b8c79851fedd":[28,48],"9":[9,10,11,12,13,14,15,16,17,18,19,20,21,25,26,46],"906459647":3,"93":46,"9329325":27,"95b4806ba6c006e4b7e72a006700e33c720ab9e7":[28,48],"96":[11,20],"99":27,"9_":19,"9a":25,"abstract":[11,20],"boolean":[9,20,21],"break":[2,7,22,25,26,31],"byte":[6,7,11,20,23,25,32],"case":[7,9,10,19,20,21,22,23,25,27,28,31,32,35,37,44,45,47,48,49],"char":[7,20,22,25,35,37,45],"class":[2,6,8,9,11,15,18,19,20,21,22,23,25,28,31,35,40,45,48],"const":[7,35,37],"default":[0,7,9,10,11,12,18,19,20,21,22,23,24,25,28,29,31,32,35,37,42,44,45,46,47,48,49],"do":[0,2,7,8,9,12,15,19,20,21,22,23,25,26,27,28,37,44,46,47,48,49],"enum":[7,18,22,35],"export":14,"final":[9,10,24,25,26,35,36,37],"function":[2,4,8,9,11,14,15,16,17,18,20,21,22,23,25,28,31,34,35,36,37,39,41,44,45,46,47,48],"goto":44,"import":[2,5,8,19,20,25,26,28,44,48],"int":[7,9,15,20,22,25,26,31,35,37,44],"long":[2,3,7,8,9,19,20,25,26,29,32,44,45,46],"new":[3,5,7,9,15,19,20,22,24,28,31,37,43,44,45,46,47,48],"null":7,"public":[2,7,20,25,35,40],"return":[2,7,9,15,16,17,20,21,23,25,31,35,46],"short":[9,20,22,24,25,26,32,44],"static":[0,2,7,10,20,22,24,25,31,32,35,47,49],"switch":[7,25,28,35,48],"throw":22,"true":[7,9,10,20,21,25,31],"try":[2,20,25,45,46],"var":[7,9,17,25,41,47],"void":[7,9,11,20,25,31,37,45],"while":[6,7,10,14,19,20,21,26,35,46,49],A:[2,7,9,10,14,15,18,19,20,21,22,23,25,28,29,31,35,40,44,45,46,47,48,49],AND:[8,21,32],AS:17,And:[10,24,25],As:[5,10,19,20,22,23,25,28,31,41,45,46,48,49],At:[2,24,25,27,31,35,45,46,47,49],Be:[19,22],But:[5,9,22,25,49],By:[7,9,10,20,21,23,24,25,39,44,45],FOR:[8,25,46],For:[2,6,7,9,10,11,14,15,17,19,20,21,22,23,24,25,26,31,32,34,35,44,45,46,49],IN:23,If:[0,2,3,6,7,9,10,12,15,16,18,19,20,21,24,25,26,27,28,31,32,35,42,44,45,46,47,48,49],In:[0,2,6,7,9,10,11,17,19,20,21,22,23,25,26,31,32,33,35,36,37,41,44,45,46,47,49],It:[0,7,9,10,12,14,19,20,21,22,23,24,25,26,28,31,34,35,36,40,44,45,46,47,49],Its:[7,20,31],NOT:[22,23,31],No:[9,11,20],Not:[25,28,48,49],OF:2,OR:17,Of:[7,10,31],On:[0,10,18,19,20,22,23,25,45],One:[7,10,20,25,49],Or:10,Such:[20,31,46,47],TO:8,That:[9,45],The:[0,2,3,4,5,6,9,10,12,13,14,15,17,18,19,20,21,22,23,24,27,28,29,31,32,33,34,37,38,43,45,46,47,48,49],Their:[28,31,49],Then:[7,9,10,21,49],There:[2,10,15,22,23,25,27,28,35,37,45,48,49],These:[2,7,9,10,20,21,22,23,24,25,28,44,46],To:[0,2,6,7,11,15,19,20,21,22,23,24,25,26,28,31,32,35,36,39,45,47,48],WITH:8,Will:25,With:[2,3,7,19,23,25,31,35,42,45,46],_:[9,19,26,46],__anon9f26d2460108:20,__anonae81ef0f0108:32,__anonn:35,__arg:20,__attribute__:35,__declspec:20,__main__:25,__name__:25,__va_args__:35,_advanceto:25,_anonym:25,_autofqtag:25,_commit:26,_echo:[2,19,20,24],_expand:35,_extra:25,_extradef:[23,25],_field:25,_fielddef:25,_forc:[19,24],_guest:5,_interact:[6,23],_list:26,_ltlibrari:45,_matchloc:26,_mtabl:[25,26,38],_p:37,_prelud:26,_program:45,_role:25,_roledef:25,_scopesep:25,_script:45,_sequel:26,_tabledef:25,_tag:26,_tag_:22,_tag_extra_descript:9,_tag_field_descript:9,_tag_file_format:[20,22],_tag_file_sort:[20,22],_tag_kind_descript:9,_tag_kind_separ:31,_tag_proc_cwd:9,_tag_program_author:22,_tag_program_nam:[9,22],_tag_program_url:22,_tag_program_vers:22,_tag_role_descript:9,_test:34,_trace:26,_type:[6,9],_xformat:[20,25,31,32],a12b3a24b62d6535a968e076675f68bac9ad32ba:[28,48],aaa:24,aarch64:0,ab91e6e1ae84b80870a1e8712fc7f3133e4b5542:[28,48],abaqu:23,abbrevi:[5,29],abc2:17,abc:[17,23,25],abil:[5,10,23],abl:[3,20,22,25,27,46],abort:[10,23,28,48],about:[0,2,7,8,10,14,15,16,18,19,20,21,22,23,25,26,31,35,37,44,46,49],abov:[0,2,7,9,10,11,17,20,21,22,24,25,37,45,46],absenc:[3,20],absolut:[9,10,20,24],absolutefilenam:[28,48],abstractclass:11,ac:[2,7,45,46],ac_:[7,45],ac_config_fil:2,ac_defun:45,acal:35,accept:[19,20,22,23,25,27],access:[3,7,15,20,21,23,25,26,41],accesson:22,accessor:23,accommod:35,accomplish:[10,25],accord:9,account:[2,10,49],accur:39,achiev:[3,6],act:47,action:[8,20,25],activ:[5,6,7,19,28,32,46,48],actual:[7,9,19,20,21,22,25,37,46],ad:[2,4,9,10,18,19,20,22,23,24,26,28,35,46,48,49],ada:[23,28,46,48],add5_and_print:26,add:[0,3,4,10,18,20,21,22,24,25,26,28,31,36,37,38,39,46,48],add_custom_target:34,add_execut:34,add_librari:34,addit:[0,5,7,9,10,11,19,20,22,23,24,25,26,28,29,31,36,45],address:[20,22],addtot:32,adjust:[2,7,20,22,32],adob:26,advanc:[2,5,28,49],advantag:[10,20],affect:[0,20,25,49],affero:26,after:[0,2,6,7,9,11,17,20,21,22,24,25,28,31,35,37,45,46,47,48,49],again:[25,35],against:[3,20,23,25],agent:45,ah_:7,ah_verbatim:7,ahead:25,aim:[22,46],akefil:20,algorithm:[20,37],alia:[17,20,21,31,44],alias:[9,20,37,44],align:[2,20,23,31],alik:26,all:[2,3,7,8,9,11,14,19,20,21,22,23,24,25,26,31,35,37,39,44,45,46,47,49],allow:[2,6,7,10,17,20,21,22,23,25,32,37,39,45,49],almost:[3,37,49],alnum:25,alon:45,alongsid:0,alpha:25,alphabet:[3,19,20,21,22,24],alphanumer:19,alreadi:[0,7,10,20,25,28,32,37,48,49],also:[0,2,3,4,5,6,7,8,23,24,25,26,28,31,35,36,37,39,41,45,46,47,49],alter:[10,20],altern:[2,20,28,37,48],although:[20,22,31],alwai:[9,10,20,22,25,28,31,35,46,48,49],am:[2,3,45],am_:7,ambigu:20,among:35,amount:22,an:[0,2,3,5,6,7,8,10,11,12,15,16,17,18,19,20,21,22,26,27,28,29,31,32,35,37,38,42,48,49],analysi:[7,36,39,47],analyz:[7,15,25,46],ancestor:[5,19],anchor:[25,31],andreicristianpetcu:25,android:0,androideabi21:0,androideabi:0,ani:[2,3,7,9,10,11,19,20,22,24,25,27,31,37,45,46,49],annot:[25,28,48],announc:6,anonfunc84011d2c0101:15,anonfuncn:15,anonscm:[28,48],anonym:[9,15,20,25,28,48],anoth:[0,7,9,10,14,15,20,22,25,28,31,32,36,45,46,48,49],ansibleplaybook:23,answer:[2,31,44,45],ant:[11,23],anti:49,antun:3,anymor:49,anynam:10,anyth:[25,37],anywai:[7,9,31],api:[4,5,45,49],app:27,appar:46,appear:[6,7,9,10,16,20,21,22,24,25,31,35,49],append:[8,9,20,45,46],appl:2,appli:[2,5,7,9,11,19,20,22,25],applic:[2,3,7,20,45,49],appreci:44,approach:[7,10,31,37,46],appropri:[20,23],approv:[19,28,48],appveyor:[2,3],apt:0,ar:[0,2,5,6,7,8,9,11,13,14,17,18,19,20,21,22,23,24,25,26,27,28,29,31,32,34,35,37,40,41,44,45,46,47,48,49],arbitrari:22,archiv:49,area:[2,5,7,20,25,38,44,47],aren:25,arg:[22,31,35,46,47],argc:[20,22,25],argdecl4:20,argument:[0,5,6,7,9,10,19,20,21,22,24,26,31,35,46,47],argv:[20,22,25],arihiro:7,aris:20,arithi:7,arithmet:10,ariti:22,arm:0,armeabi:0,armv7a:0,around:[9,10,20,22,28],arrai:[7,26],arrang:8,array_s:7,array_spec:46,artifact:31,as_:7,as_echo_n:45,ascii:19,asciidoc:23,asdf:22,ask:[7,10,22,44],asm:[5,43],aspect:[2,24,31,47],assembl:9,assert:18,assign:[7,15,20,23,25,37,45],associ:[9,16,20,23,25,35],assum:[7,9,10,18,20,23,44,45,47],assumpt:[11,20],asterisk:25,atom:25,attach:[9,15,16,19,20,25,28,31,48],attempt:[10,23],attown:31,attribut:[11,13,28,31,42,48],au:22,author:[2,5,8,22,28,48],auto:[18,20],autoconf:[0,7,23,46,49],autoconfpars:7,autoconfsubpars:7,autogen:[0,49],autoit:23,autoload:20,automak:[0,23,31],automat:[2,4,5,10,20,24,37,45,46],autoreconf:0,autotool:[0,27,49],avail:[2,7,9,10,20,23,26,28,31,32,35,45,46,47,48,49],avid:3,avoid:[8,9,12,19,20,21,22,31],awai:22,awar:[20,49],awk:2,b3f670c7c4a3c3570b8d2d82756735586aafc0cb:[28,48],b4n:7,b:[9,10,11,14,16,18,19,20,21,22,25,35,46],back:[19,20,25],backend:[7,46],background:[3,4,20],backport:[2,28],backquot:44,backslash:[9,10,19,20,22,25,31,46,49],backtrack:25,backward:[8,9,10,20,35],bad:[2,44],badinput:3,bagl:17,baha:20,ban:39,bar:[20,22,23,25,31],bare:[9,10],base:[0,2,3,4,10,20,21,23,25,35,36,37,40,46,49],base_lang:45,baselang:20,basemethodt:7,basenam:46,basepars:45,bash:[2,46,47,49],basi:[10,20],basic:[5,19,20,21,26,28,31,48],batch:[3,7],batchmaketag:32,baz:[20,25],bb81485205c67617f1b34f61341e60b9e8030502:[28,48],bcall:35,becam:[35,36],becaus:[0,2,3,6,7,10,11,12,14,15,18,19,20,22,23,24,25,26,28,31,42,44,45,48],becom:[2,20,21,23,24,25,31],been:[3,6,9,10,19,20,22,23,25,36,39,49],beer:49,befor:[0,4,5,7,9,11,17,19,20,21,22,23,24,25,31,46,47],begin0:21,begin:[6,7,8,9,17,18,20,21,24,25,26,35,37],begin_c:25,behalf:7,behav:[10,20,22,27],behavior:[2,8,10,20,22,25,26,31,47],behaviour:23,behind:[7,25,45],being:[0,7,9,10,20,22,23,25,35,45],bel:22,bell:7,belong:20,below:[9,10,20,21,22,35,44,46,49],benefit:20,besid:[17,46],best:[9,10,20,22,26],better:[5,9,19,20,28,36,44,48],between:[1,2,5,7,8,11,15,20,22,23,25,29,31,40,45],beyond:39,bibtex:[23,28,48],bidirect:[7,45],big:10,biggest:20,bin:[0,10,20,45,46,49],bin_program:45,binari:[0,10,20,21,22,23,46,49],bisect:2,bit:[0,7,8,9,15,37,42,49],blank:25,blob:[12,17],block:[2,9,18,20,35,46],blue:26,bond:45,book:26,bool:[7,45],bore:2,borrow:49,bostic:22,both:[2,7,9,10,19,20,21,22,23,25,31,32,34,35,42,45,46,49],bottleneck:5,bottom:[7,19],boundari:25,bourn:45,bpf:6,brace:[9,19,20,23,32],bracket:25,bram:[20,22],branch:[20,28,31,48],breakag:2,brew:27,brief:20,briefli:20,broken:[9,28,42,44,46,48],brought:[14,36],brows:[28,37],bs:22,bsd:0,bsdi:22,buffer:[2,6],bug1856363:46,bug:[2,5,8,26,35,38,39,43],bugfix:2,bugzilla:[28,48],build:[5,6,7,8,10,11,21,23,25,26,47],builddir:47,built:[6,9,10,19,20,24,25,26,46,49],bunch:21,bundl:0,burden:39,bust:20,bypass:4,c11:49,c81a8c:[28,48],c93e3bfa05b70d7fbc2539454c957eb2169e16b3:[28,48],c99:49,c:[0,3,5,7,8,9,10,11,12,16,17,18,19,21,22,23,24,28,31,32,33,40,43,44,46,47,48,49],c_end:7,ca:22,cab4735e4f99ce23c52b78dc879bc06af66796fd:[28,48],call:[4,5,6,9,10,20,21,22,24,25,35,37,45,46,47],callabl:[15,20],callback:[7,28,45,48],caller:2,cameron:[3,27],can:[0,2,3,4,5,6,7,8,9,11,12,15,17,18,19,20,21,22,23,24,25,26,27,28,29,31,32,35,37,40,41,44,45,46,47,48,49],candid:[17,25],cannot:[2,7,9,10,11,14,15,18,20,22,23,25,31,35,38,40,41,44,45,46,47,49],capabl:[3,10,20,22,39],capit:19,captur:[2,19,31,35,40,42,44,45,47],card:[31,32],care:[3,37],cat:[9,25,31,33,46],catchev:25,categor:20,caus:[8,9,20,22,28,35,46,48],caveat:[8,10,34],cc:[0,2,22,25,31,47,49],cc_for_build:0,cd:[0,2,10],cell:12,centric:23,certain:[0,9,20,21,22,25,31],cfg:2,cfgentrylist:7,cfgfile:7,cflag:0,cflags_for_build:0,cflow:10,cgcc:47,cgcc_cflag:47,cgi:[28,48],cgit:[28,48],ch:[2,10,37],chain:21,chanc:[7,19,45],chang:[1,5,7,9,10,11,20,22,25,28,29,43,46,47,48],chapter:[4,17,19,25],charact:[2,7,9,19,20,21,22,23,24,25,26,31,32,35,37,46],check:[2,5,7,9,20,22,24,25,44,46],checker:18,cherri:[28,48],child:25,choic:[7,10],choos:[7,10,11,17,19,25,29,31,45],chooseexclusivesubpars:7,chop:[2,5],chose:45,chosen:[7,22,23,45],ci:[2,46],circl:0,circumst:10,cite:10,cjwatson:[28,48],clang:0,clark:22,class_method:19,classic:[9,10,25,31],classnam:20,clean:[46,47,49],cleanup:2,clear:[2,19,20,24,25,39],client:[5,8,10,12,13,14,15,17,18,20,21,22,23,30,31,42],clock:[18,32],clock_avail:32,clocks_per_sec:32,clojur:[7,23],clojurekind:7,clojurepars:7,clone:[0,20,28,39,48],close:[7,9,20,28,44,48],clumsi:22,cmake:[5,23,43],cmakelist:34,cmd:49,cmdline:46,cnf:24,co:[22,27,49],cobol:[11,31],code:[0,2,3,5,6,7,9,10,13,14,15,16,17,18,20,21,22,23,24,26,28,31,35,38,39,44,45,46,47,48],codeblock:49,coexist:7,collect:[2,20,31,49],collid:35,collis:35,colomban:[3,7,39],colon:[20,22,25],column:[9,20,22,23,26,31,32],com:[0,2,3,5,7,12,17,18,19,20,21,22,23,25,27,28,33,35,36,38,40,42,44,46,47,48,49],combin:[2,3,9,19,20,22,23,31,39],combinev2:9,come:[2,17,19,20,46,49],comma:[2,20,21,25,46],command:[1,3,5,6,7,8,9,10,12,19,21,22,24,25,27,28,29,31,44,47,48],commandlin:35,comment:[2,10,17,19,20,22,23,24,28,33,36,46,48],commit:[5,7,28,48],common:[2,5,9,10,20,21,25,26,31,32,35,37],commonli:[20,37],commun:[6,49],compar:[20,21,24,46,47],comparison:[20,28,48],compat:[8,10,19,20,23,31,35,39],compdef:20,compil:[1,4,5,18,20,24,25,27,35,37,44,47],complet:[0,2,3,6,10,11,20,49],complex:[2,20,23,37],compli:22,compliant:22,complic:[0,15,20,25,46],compon:[10,19,20],compos:20,comprehens:3,comput:[6,25],concaten:[20,22],concept:[7,19,20,23,25,31,44,45],conceptu:10,concern:[20,25],concis:39,concret:20,condens:[20,32],condit:[10,20,23,31,46],conduct:20,conf:[20,24,28,48],config:[0,20,23,24,49],configur:[1,2,5,7,10,19,20,23,27,45,47,49],conflict:[11,19,20,25,28,37,48],conform:37,confus:[2,17,19,20,42,49],connect:7,consensu:21,consid:[2,4,7,15,20,21,23,25,28,44,45,46,48],consist:[2,19,20,22,23,39],constant:[13,14,18],constrain:[25,37],constraint:18,construct:[10,20,31,39],constructor:[16,35],consult:[5,10],contain:[2,9,10,19,20,21,22,24,31,32,35,37,44,46,49],content:[5,6,8,19,22,37,38],context:[7,9,16,22,25,45],contextu:25,continu:[5,23,25,39,46,49],contrari:[21,24],contribut:[1,3,5,25,28,48],contributor:[2,3,46],control:[2,6,8,19,20,23,26,31,44,45],convei:22,convent:[11,19,20,46],convers:[20,22],convert:[7,9,20,22,23,25,46,49],cookbook:26,copi:[22,25,28,31,48,49],copyright:[2,44],core:[2,21,26],cork:[4,26],cork_nil:7,cork_queu:7,corkindex:26,corkusag:37,correct:[9,20,26,31,46],correctli:[9,36],correspond:[6,20,23,35],cosmet:2,cost:46,could:[3,9,10,20,21,22,25,49],count:[7,22,28,48],counter:[7,46],coupl:49,cours:[2,7,20,31,45],cover:[18,47],coverag:5,covergroup:18,cp932:23,cp:49,cpp:[0,35],cppcheck:5,cppflag:0,cppflags_for_build:0,cpreprocessor:[31,33,35],cpu:19,cr:[10,22],crash:[2,7,28,48],creat:[0,2,5,7,15,17,20,25,28,34,37,40,49],credit:8,crisp:22,criteria:2,critic:[20,23,28],crlf:49,cron:10,cross:[1,10,20,28,29,32,46,49],crude:37,cs:[20,22],csc:3,cscope:10,css:[23,28,36,46,48],csspars:[28,48],cstart:7,ct:21,ctag:[0,2,3,6,7,8,21,27,29,30,31,32,33,34,35,36,38,40,41,42,44,45,46],ctagd:12,ctags_attr_unus:7,ctags_cppflag:45,ctags_vs2013:[2,49],ctagswrit:7,ctrl:20,cuda:[23,35],cumul:[10,20],current:[2,3,6,7,9,10,14,16,19,20,22,23,25,27,28,31,35,37,38,40,42],cursor:[20,22,23],custom:[8,10,19,20,24,29,31],cut:[20,26],cweagan:[3,27],cxx:37,cycl:7,cygwin1:49,cygwin:[3,10,49],d2bdf505abb7569deae2b50305ea1edce6208557:[28,48],d4b5972427a46cbdcbfb050a944cf62b300676b:[28,48],d4fcbdd:[28,48],d9ba5df9f4d54ddaa511bd5440a1a3decaa2dc28:[28,48],d:[7,10,12,16,20,21,22,24,25,27,28,31,33,35,46,47,48],dai:[2,49],damag:6,darren:[5,10,19,20,21,22,44],darrenhiebert:[19,20,21],darwin:0,dash:[20,25],data:[7,8,10,16,18,20,22,23,25,46],datafram:16,date:[2,10,22],dbusintrospect:23,ddb29762b37d60a875252dcc401de0b7479527b1:[28,48],deal:[2,7,10,11,20,21,23,29,36,39,43],debat:35,debian:[0,23],debug:[19,20,21,22,23,24,26,44,46,49],debugg:[2,49],dec:44,decent:[27,49],decid:[2,5,9,21,25,31,44],decim:22,declar:[2,7,11,17,18,19,20,28,31,35,36,39,44,48],declare_funct:35,decor:39,dedic:[5,7,45],deem:10,deeper:[15,19],def:[6,7,9,12,15,19,20,25,26,31],defici:49,defin:[5,7,8,10,12,14,15,17,18,20,22,24,26,31,32,33,34,37,38,40,44,45,46],define_ev:45,definit:[2,5,7,8,9,15,20,23,24,25,28,31,35,37,40,44,48],defun:[25,35],degre:35,delai:[10,45],delet:[35,46],delimit:[9,20],demon:22,demonstr:[16,20],deni:9,depend:[0,7,10,14,16,20,21,22,23,27,31,35,36,39,46,49],dependencycount:7,deploi:3,deprec:35,depth:20,deptype_subpars:7,deriv:[9,17,19,20,21,28,31,38,44,46],descend:[10,20,22],describ:[2,4,9,11,13,18,20,21,22,23,24,25,29,31,35,46],descript:[2,7,8,23,25,31,44,45],design:[2,4,9,18,19,20,25,35,39],desir:[10,20,22,37],desktop:[28,49],despit:20,destdir:[28,48],detail:[2,4,7,8,11,19,21,22,23,24,25,28,29,31,32,37,45,47],detect:[2,20,21,23,36,38,42,45,46],determin:[8,19,22,23,35],determinist:45,dev:[0,23,28,48],devel:[0,10,49],develop:[3,5,7,9,20,25,26,28,31,44,45,46,47,48,49],developd:21,devot:20,devstudio:28,dfseeko:0,dftello:0,dhiebert:[19,20,21,22],dialect:[17,45],dickei:22,dickson:[28,48],dict:26,did:28,didn:25,diff:[2,23,46,49],differ:[1,5,7,8,9,11,14,15,20,22,23,25,29,31,35,37,39,45,46],difficult:[20,25,46],dilemma:20,dir:[2,19,20,24],direct:[3,7,9,20,33,39],directivenotifi:45,directli:[3,7,9,20,28,48],directori:[2,7,8,9,11,19,20,22,25,35,44,45,47,49],dirtag:10,disabl:[0,7,9,12,18,19,20,22,24,25,28,31,44,45,46,47,48,49],disadvantag:10,disallow:19,discard:31,discuss:[9,21,25,28,45,48],disk:27,dispatch:3,displai:[20,23],distinguish:[9,20,22],distract:10,distribut:[1,2,22,27,49],diverg:28,divid:36,dll:49,dllexport:20,dnf:0,do_someth:25,doc:[2,17,20],docbook:28,document:[5,11,17,18,19,20,22,25,27,28,37,38,41,45,49],docutil:0,doe:[7,8,11,15,19,20,23,24,25,35,44,46,47],doeslinecommentstart:7,doesn:[2,7,9,10,11,15,16,17,19,20,21,23,24,25,26,28,32,35,44,45,46,48],doesstringliteralstart:7,dollar:17,domain:45,don:[2,3,7,9,15,19,20,22,24,25,27,28,31,35,44,45,46,48],done:[7,10,21,22,25,28,48,49],dont_capture_m:25,dot:25,doubl:[10,20,22],doublequot:22,doublesharp:12,down:[7,49],downcas:21,download:49,draft:[5,22],drawback:[20,49],drive:[20,44,49],drop:[20,25],dt:[7,23],dtd:[2,23,31],dtsi:7,dtsparser:7,due:[9,20,25,49],duplic:[10,20,22,39],durat:46,dure:[0,7,9,20,24,25,45,46,49],dynam:[26,45],e0f854f0100e7a3cb8b959a23d6036e43f6b6c85:[28,48],e59325a576e38bc63b91abb05a5a22d2cef25ab7:[28,48],e:[0,2,5,7,9,10,11,14,16,18,19,20,21,22,24,25,26,28,29,31,33,35,37,45,46,48,49],each:[2,6,7,9,10,19,20,21,22,23,24,25,28,31,35,39,46],eagan:[3,27],eagerli:20,earli:9,earlier:[9,25],easi:[5,7,9,23,28,48,49],easier:[2,7,19,20,22,23,24,39],easili:[10,20,24,25,26,39],echo:[6,46],ecosystem:49,ed:15,edel:22,edit:[6,20,22,49],editor:[2,3,5,10,18,20,22],editorconfig:2,edu:[20,22],edv:3,effect:[7,9,19,20,25,31,44,46],effici:10,effort:20,eg:19,egrep:19,eiffel:[10,20,37],either:[9,10,19,20,25,26,32,37,44],ek:19,ekr:20,el:[2,25],eleg:37,element:[7,19,31,32],elementnam:31,elimin:20,elisp:[3,9],elixir:23,elm:23,els:[20,22],elsewher:22,elvi:[20,22],emac:[3,5,8,29],emacslisp:9,email:22,embed:[7,20,22,36,45],emerg:49,emit:[6,7,9,15,19,20,25,31,45],emphas:7,emphasi:25,emploi:32,empti:[2,19,20,22,24,25,28,37,48],emul:[20,23],en:[28,48],enabeld:12,enabl:[0,7,9,12,14,15,17,18,19,20,22,25,28,31,32,35,44,45,46,47,48,49],enclos:[20,22],encod:[10,20,22,28,48],encount:[10,20,25],encourag:25,end:[2,3,6,7,8,9,17,19,20,21,22,26,27,31,35,38,39,44,46,49],end_c:25,end_of_fil:7,endif:20,endmodul:18,energi:20,engin:[2,5,11],english:44,enhanc:25,enjoi:46,enough:[2,7,21,22,45,46,47,49],ensur:[21,22,35],enter:[2,6,25,46],enter_c_prologu:7,entersubpars:7,entir:[10,20,25,27,35,37],entitl:20,entri:[2,7,8,9,10,19,21,22,25,31,37],entrypoint:31,enumer:[18,20,22,23,31,35,46],env:20,environ:[3,8,10,24,25,28,31,49],eof:[20,25,46],eq:[9,21],equal:[7,20,21],equival:[20,21,25],er:25,error:[2,7,8,9,19,20,21,23,25,28,46,47,48,49],escap:[9,10,17,19,20,21,22,25,31,35],esoter:20,especi:[2,23,28,39,44,46,48,49],essenti:[7,20],esubparserrundirect:7,etag:[0,9,11,19,20,29,46],etagswrit:7,etc:[5,10,14,20,22,24,25,31,47],eval:[25,40,45],evalu:[2,19,21,23,26,28,46,48],even:[2,9,10,11,20,21,22,25,32,35,46,49],event:[18,25,45],eventu:[25,26,27],ever:[10,24,25],everi:[8,20,45],everyth:37,evolv:[35,39],ex:[0,9,10,20,22,45,49],ex_cmd:20,exactli:[20,21,22,24,25,45],examin:[10,20,31],exampl:[0,5,6,7,8,9,10,11,12,16,20,22,23,24,26,31,32,34,35,37,47],example_mod:44,example_smod:44,exce:11,except:[2,3,8,9,11,19,20,25,28,29,31,44,46,48],excess:20,excit:[20,25],exclud:[10,20,21,24,37],exclus:[7,10,19,20,23,45],exclusivesubparserchosencallback:7,exclusivesubparserchosennotifi:7,excmd:[9,10,20,23],exctag:0,exec:10,execut:[1,9,10,19,20,22,23,35,46],exercis:20,exert:20,exhibit:20,exist:[2,7,10,20,23,24,25,31,36,39,44,46,47,49],exit:[19,20,25,26,31,46,47],exp:21,expand:[19,20],expans:[20,22,35,45],expect:[2,7,9,10,13,20,23,24,26,27,44,46,47],expens:[10,20],experiment:[2,5,10,19,20,34,38],explain:[2,12,19,20,22,24,25,31,32,44,46],explan:[2,44],explicit:35,explicitli:[7,19,20,25,28,31,45,47,48],exploit:6,exportedfunct:31,expr:21,express:[2,4,5,8,19,20,22,23,36,42,45,49],ext:[20,46],extend:[2,5,8,9,19,20,21,24,29,31,37,39,45],extens:[2,4,5,7,8,10,18,19,21,22,23,25,28,31,37,45,48],extension_field:20,extensionfield:7,extent:28,extern:[7,18,20,31,32,35,37,49],extra:[0,7,8,9,10,11,14,15,17,19,21,22,28,29,32,36,40,44,45,46,48],extract:[9,12,17,25,35,36,39,49],extrem:10,exuber:[2,5,7,8,9,11,19,20,22,25,29,31,33,37,40,41,44,46],f90:[44,46],f:[2,9,12,16,17,18,19,20,21,22,23,25,28,29,35,44,48,49],f_interfac:44,facil:[2,3,5,10,28,31],fact:[20,25],factor:10,fail:[2,10,20,25,26,28,46,48],failur:[20,46],fairli:[20,28],falcon:[23,28,48],fall:20,fallback:[25,31],fals:[7,9,20,21,31],famili:45,familiar:[26,46],faq:[2,5,8],far:[2,10,25,28,31,35,49],fast:[10,20,25,28],faster:21,fastest:36,fatal:[19,23],fault:[28,48],favor:10,favorit:[8,12,20,44],featur:[2,5,6,10,19,20,22,23,24,25,26,28,31,39,43,44,45,46,49],feb:22,februari:35,fedora:[0,3,23],fedoraproject:[28,48],feel:49,ferit:28,fesevur:[3,28,48,49],fetch:[28,48],few:[2,3,9,10,20,31],fewer:[20,44],ff:22,ffe:[3,28,48,49],fget:22,field:[3,4,6,8,10,11,14,15,16,19,21,22,26,28,29,32,33,35,37,44,45,46,48],fieldnam:[25,26,31],fifth:31,figur:27,file:[2,4,5,6,7,8,13,14,15,16,18,21,26,28,29,32,33,34,42,44,47,48,49],file_nam:20,filedesc:11,fileencod:23,filenam:[6,20,22,27,31,49],filenamematch:[28,48],filescop:[9,11,20,31],filesystem:[6,27],filetyp:20,fill:[7,15,19,20,25,32,37],filter:[2,6,8,20,22,46,49],find:[2,5,7,9,10,17,19,20,21,23,25,27,28,44,45,48],findautoconftag:7,fine:[20,25,47,49],finer:23,finish:[7,20],first:[2,5,7,9,10,16,19,20,21,22,24,25,28,31,32,35,37,45,46,48],fishman:[20,28,48],fit:[10,20],fix:[2,3,7,9,18,20,28,35,39,40,46,48],flag:[5,7,8,9,10,20,31],flavor:[25,49],flex:2,flexibl:7,flip:21,flow:[2,26],flush:7,fnmatch:[28,48,49],focu:[19,25],focus:[19,28],fold:[9,20,21],foldcas:[9,20,21],follow:[0,2,6,7,8,9,11,15,18,19,20,22,23,24,25,28,31,34,35,37,44,45,46,47,48,49],foo:[0,2,7,9,10,11,20,22,23,25,26,31,44],foo_for_build:0,foo_t:22,foobar:[6,25],foobaz:6,fool:[20,39],foopars:[2,25],forc:[2,7,9,13,14,15,16,20,45],foreach:35,foreachsubpars:7,forget:[2,25],fork:[2,5,10,11,18,28,49],form:[2,10,11,19,20,25,35,44,46],formal:20,format:[2,3,5,6,8,10,19,21,23,25,27,28,32,46,48],former:11,formula:27,forth:20,fortran:[3,9,20,37],forward:[9,20,25,49],found:[0,5,7,8,9,19,20,23,25,37,45,46,49],four:[7,20,25],fourth:31,fox:22,fp:7,fprintf:7,fq:7,fragment:26,frame:16,framework:[7,25],frank:[3,28,48,49],free:[2,7,49],freed:7,freedom:22,frequent:[2,10,25],fri:22,friendli:11,from:[1,2,3,4,5,8,9,10,11,15,16,17,19,20,21,26,27,28,31,36,37,38,39,41,44,45,47,48],front:25,frrrwww:46,fruit:[7,28,48],fseek:0,ft:20,fte:22,ftell:0,ftp:10,fu:44,full:[4,18,19,20,23,25,26,28,44,48,49],fulli:[5,6,31],fun1:17,fun2:17,func1:22,func2:22,func3:22,func:[25,31],functionparamet:23,functionvar:16,further:[20,21,45],furthermor:[20,35],fussi:5,futur:[2,3,9,11,19,20,22,23,28],fuzz:[2,5],fyi:2,g:[2,7,9,16,19,20,21,22,25,26,28,31,36,37,44,45,48,49],game:45,gap:28,gar:25,garbag:[20,44],gather:[2,9,14,15,16,20,23],gauch:45,gawk:49,gaz:25,gcc:[0,20,23,35,47],gcda:47,gcno:47,gcov:47,gdb:[25,49],gdbinit:[23,25],geani:[2,3,20],gear:49,gener:[0,2,3,4,5,9,10,11,12,13,19,20,21,22,23,26,28,31,34,35,36,37,39,42,44,45,46,47,48,49],get:[2,3,7,9,16,25,26,28,44,45,48,49],getcfrominputfil:[7,37],getflag:22,getinputlanguag:7,getinputlinenumb:7,getinputlineoffset:7,getsourcelinenumb:7,gfm:25,gh3006:17,ghost:[4,5],ghostscript:26,gigo:20,gist:[28,48],git:[0,2,21,23,25,28,29,48],github:[0,2,5,7,12,17,18,21,25,27,28,41,44,48],gitreadi:2,give:[7,9,10,19,20,21,22,25,45,46,49],given:[7,9,11,19,20,23,25,31,32,34,40,44,45,46,47],glade:23,glanc:45,glibc:[25,49],glob:10,global:[2,10,20,23,25,31,35],globalvar:16,glsl:28,gm:[28,48],gmail:[3,5,35,36,46],gnome:28,gnu:[1,5,8,10,19,23,25,26,31],go:[0,9,10,23,25,37,47,49],goal:[3,5,8],goe:[7,9,21,25,32],gold:28,goo:25,good:[2,3,5,9,10,23,25,27,31,46,49],gosh:45,got:44,gperftool:47,gpl:[26,49],grab:[20,25],graft:7,grain:[20,25],grammar:[7,20],granular:23,graph:19,graphic:26,great:3,greedi:25,grep:[6,20,23,31,49],grew:[5,39],group:[4,9,10,11,12,13,14,15,16,17,18,19,20,21,22,25,26],groupid:31,grow:10,gs:26,gsnd:26,guarante:20,guess:[4,5],guest:[4,5,17,31],gui:49,guid:[2,3,31],guidelin:2,h1:[9,36],h2:36,h3:36,h:[2,7,9,10,18,20,21,22,25,31,37,44,45,46],ha:[3,5,6,7,9,10,15,17,19,20,21,22,23,24,25,26,28,31,32,35,36,38,39,44,45,46,49],hack:[1,2,3,39],had:[23,24,39],hand:[7,19,20,22,23,25,26,31,36,44,45],handl:[3,6,7,9,10,11,20,22,25,27,31,33,36,37,39,45],handler:23,hanschen:12,happen:[19,20],happi:2,har:[2,46],hard:[9,28,39,48],harder:2,hardest:37,hardwar:18,hash:[20,35,45],haskel:[3,23],hat:2,have:[0,2,3,7,8,9,11,14,15,17,19,20,21,22,23,24,25,26,27,28,31,32,35,36,39,44,45,46,48,49],haven:25,hax:23,hc:37,hda:3,hdr:10,he:[3,46],head1:[19,25],head2:19,head3:19,head4:19,head:[2,23,27,32,36,44,46],header:[2,20,23,28,35,48],heading1:11,heading2:11,heading3:11,heap:[28,48],heapoverflow:[28,48],heart:20,heaviest:3,hello:[20,26],help:[2,3,9,11,19,20,21,22,23,25,26,27,31,34,41,44,45,46,49],helper:2,henc:3,herbesfol:39,here:[0,2,3,7,9,10,12,14,15,16,20,21,23,25,27,28,31,32,38,45,46,47,48,49],hereinaft:20,hexadecim:22,hf:27,hh:20,hi:[9,20,22],hidden:20,hiebert:[5,10,19,20,21,22,44],hierarchi:8,higher:[5,7,20,25,26,31,32],highest:20,highli:25,highlight:20,himself:22,hint:[8,9,45],histori:[2,9],hit:10,hoc:19,hold:[7,20,22,23],home:[3,10,20,24],homedr:[20,24],homepath:[20,24],honest:25,hook:2,hope:[22,27],hors:22,host:[0,7,10,20,25,36,45,49],how:[0,4,8,9,12,19,21,23,25,28,31,37,44,45,48,49],howev:[2,7,9,10,11,15,17,19,20,22,23,25,26,28,31,41,44,45,46,47,48],howto:[28,48],hpp:20,html:[2,5,9,10,11,17,19,23,34,43],http:[0,2,5,7,10,12,17,18,19,20,21,27,28,34,44,48,49],human:[20,21,29,32,47],hxx:20,hyperlink:28,i686:49,i:[0,2,3,7,8,9,11,14,17,18,19,20,21,22,23,24,25,26,28,31,35,37,44,45,46,47,48,49],ibiblio:10,icas:[19,21,25],iconv:[23,49],iconv_dir:49,iconvlib:49,id:[1,2,3,6,10,15,18,22,27,28,48],id_t:15,idea:[2,4,9,23,24,31,46,49],ident:[9,20],identifi:[10,20,22,23,25,28,31,37,46],idutil:10,ieee:18,ieeexplor:18,if0:[20,31],ifclass:18,ifdef:20,ignor:[10,11,13,19,20,23,24,25,28,31,35,38,40,46,48],ignore_thi:35,ignorecas:20,illustr:[20,45],imagin:10,imaginari:[25,45],imbal:20,immedi:[19,20,24,25],immut:17,impact:[2,7,10],imperfect:35,impl:21,implement:[2,4,5,7,10,20,22,25,26,28,31,35,37,44,45,48],impli:[2,7,10,19,20,25,45],implicit:31,implicitli:[20,39],impos:20,imposs:[2,26,35],impract:25,improperli:20,improv:[2,3,5,22,28,44,46,48],in_source_fil:2,inabl:36,inappropri:20,inc:[20,22,26],includ:[1,2,5,6,7,9,11,17,19,20,21,22,24,25,26,28,31,32,35,39,41,48,49],inclus:31,incompat:[2,5,8,9,10,20,22,31,40,43],incomplet:44,inconsist:20,inconveni:[0,10],incorpor:44,incorrect:20,incorrectli:[20,35],increas:[10,22,35],increment:[25,46],inde:[20,25],indent:[2,24,39],independ:[2,20,22,31],index:[5,7,20,26],indic:[9,20,21,24,25],indirectlyimport:15,individu:[9,20,29,43],ineffici:25,infer:[20,35],infinit:[2,46],influenc:10,info:[19,20],inform:[5,7,9,10,18,19,20,22,23,27,28,31,32,37,42,45,48],infrastructur:[37,44],inherit:[20,21],inhibit:20,iniconf:7,init:[28,45,48],initi:[5,7,10,11,15,22,25,28,37,48],inittagentri:[7,37],inject:9,inko:[5,8,23],inlin:[6,22,31,35],inner:25,input:[2,3,4,5,8,12,13,14,15,16,17,18,19,21,25,28,29,32,33,36,39,42,44,47,48],inputend:7,inputfil:[4,11,20,31],inputfileinfo:7,inputsect:31,inputstart:7,inquir:[20,25],inquiri:25,insensit:[19,20,21,25],insert:[2,46],insid:[9,22,25,35,37,38,45],insight:3,insist:10,inspect:[8,20,28,46],inspir:[20,23,25],instal:[0,2,5,6,23,27,49],instanc:[18,20,35,37,49],instanti:[18,25],instead:[2,8,11,15,20,23,24,25,26,28,31,40,44,45,46,48],instruct:[20,27],integ:[7,9,17,21,26,44],integr:[7,28,37,49],intellig:10,intend:[19,25,49],intent:[2,7,20,24,46],interact:[3,5,20,21,44,46],interest:[3,5,7,20,25,37,45,47,48],interfac:[8,18,37,44],intern:[0,3,4,19,20,25,28,32,49],interpret:[10,19,20,23,26,45],interpretconfig:7,interrupt:46,introduc:[2,3,7,9,11,15,19,20,22,23,24,25,28,31,40,44,46,47,48],introduct:[8,43],invalid:[20,25,28,46,48],inventori:[28,48],invert:46,investig:49,invit:2,invoc:[10,20,35,45],invok:[6,10,20,37,46],io:[2,5,10,19,20,21,44],ipython:12,ipythoncel:[5,8,15,23],irrespect:20,is_runn:46,isn:15,iso:49,isol:10,issu:[3,8,10,17,20,23,25,28,41,44,46,48],itcl:[23,40],item:[5,9,20,21,22,25,31,32,34,44],iter:[7,25],its:[2,4,6,9,10,11,15,17,19,20,21,22,23,25,28,31,32,35,37,39,44,45,46],itself:[2,7,9,12,15,19,25,31,33,35,45],iuliano:22,j:20,jai:22,jame:22,jansson:[0,49],java:[10,20,25],javaproperti:23,javascript:[2,9,17,20,22,25,36,46],javaspr:25,jelveh:[5,20],jiri:36,jl:14,job:[3,7,10,37,49],join:2,jp:3,jq:46,js:46,json:[5,6,8,17,20,23,29,44,46],json_output_vers:9,jsonwrit:7,jstype:[9,18,20],julia:[5,8,23,46],jump:[2,8,9,20,25],jumppanen:22,jussi:22,jussij:22,just:[2,7,9,19,20,21,23,25,28,31,32,35,42,44,45,46],k:[2,18,19,20,31,35],k_namespac:7,karol:3,kconfig:23,keep:[2,3,9,10,19,20,21,22,25,35,46,47],kei:[9,10,17,20,31],keith:22,ken:3,kentkt:3,kept:[20,31,46],ker:20,kernel:[45,47],keystrok:10,keyword:[2,7,17,18,20,25,28,31,35,37,45],keyword_init:7,keyword_non:7,kill:45,kind:[4,5,6,8,14,15,19,21,22,26,28,29,32,37,42,44,45,46,48],kindcount:37,kinddef:[19,20,25],kinddefinit:37,kindlett:25,kindspec:20,kindtabl:37,kindx:20,kirkenda:[20,22],kirkendal:[20,22],klass:9,know:[2,7,9,14,15,19,20,21,23,25,26,28,31,44,46,48,49],knowledg:[25,26],known:[2,7,8,9,16,20,22,25,26,28,35,39,43,44,49],kotlin:23,ks:15,ksh:10,kz:16,l1:18,l2:18,l3:18,l4:18,l5:18,l6:18,l7:18,l:[0,9,10,16,18,20,21,23,25,31,33,44],label:[20,23,44],lack:[28,48],lambda:[2,8,9,20,25,31,35],lang1:46,lang2:46,lang:[2,5,8,9,10,20,24,25,26,31,38,44,46],langdef:[19,20,23,24,25,45],langmap:[18,20,23,25],languag:[0,3,5,7,8,12,13,14,15,16,17,19,21,22,23,24,25,28,31,32,33,34,35,36,37,44,48],larg:[2,3,10,11,20,44],last:[3,7,9,20,21,22,25,31],lastli:37,later:[2,9,10,19,20,22,25,45,49],latest:[20,28,34,48],latin1:23,launch:23,layer:49,layout:47,lazi:25,ldflag:0,ldflags_for_build:0,ldscript:[23,31],le4679d360100:25,lead:[20,22,25,46],leaf:10,leak:[3,22],learn:[5,20,46],least:[2,35,49],leav:[20,25],leave_c_prologu:7,leavesubpars:7,left:[2,7,20,32,37],legaci:[9,20,23],leleliu008:0,lemmi:22,length:[11,17,20,22,31],less:[2,10,23,35,39],let:[7,9,10,15,19,21,23,25,26,31,32,35,44,45,46],letter:[5,8,9,18,19,22,23,31,32,44,49],level:[5,7,8,16,19,20,23,24,25,28,31,35,48],lex:25,lexem:39,lexic:[25,36,39],lf:22,lgtm:2,lib:[0,10,19],liber:22,libiconv:[0,23,49],libjansson:[0,6,9,20,49],librari:[0,3,20,21,23,28,48,49],libreadtag:21,libseccomp:[0,6],libxml2:[0,23,49],libxml:23,libyaml:[0,23,49],licens:[20,26,49],life:7,lighten:39,lighter:27,lightweight:[3,28],like:[0,2,3,7,9,10,11,15,20,21,22,23,24,25,27,28,31,35,36,39,44,45,46,47,48,49],limit:[6,9,11,20,22,28,31,35,36,38,44,46],line:[1,5,6,7,8,9,12,19,21,22,24,26,27,28,29,32,36,37,39,40,44,46,47],line_pattern:[19,20],linefe:22,linenum:7,link:[20,23,31,49],linker:[23,35],linux:[1,2,5,6,10,25,45,47],lisp:[3,9,21,45],list:[2,3,6,7,8,10,11,16,18,19,21,22,25,26,31,32,37,44,46],liter:[7,9,13,17,25,26],lj:22,lk:45,lkr:45,ll:[9,25,27],llvm:0,ln:25,load:[2,5,7,8,14,19,20,23],loader:26,local:[0,2,10,20,22,24,28,31,35,39,41,44,46,48],localparam:18,locat:[5,8,9,19,20,22,25,31,37,39],log:[23,28,48],logic:[2,7,21,22],longer:[10,20],longflag:[25,26],look:[2,9,10,17,20,21,22,24,25,27,28,31,32,35,46,48],lookup:[10,37],lookupkeyword:7,loop:[2,6,28,46,48],lot:[22,25],love:46,lower:[20,22,31,45],lowercas:19,lrm:18,ls:[0,20],ltx:22,lua:[28,48],lvalu:25,m4:[7,23,25],m4_:7,m4_defin:25,m4found:7,m4subpars:7,m4tmp:7,m:[3,9,16,18,19,20,22,25,31,44,46],ma:[28,48],mac80211_info:45,mac80211_msg_ev:45,mac:[1,5],macek:22,machin:[0,20,21,23],macintosh:22,maco:10,macro:[2,7,9,10,14,20,25,31,34,37,44,45,46],macrodef:[9,35],made:[7,22,28,39],magic:[20,22],mai:[0,2,3,7,9,10,11,15,17,19,20,21,22,23,25,26,27,28,31,35,37,42,44,45,46,47,48,49],main:[2,5,7,9,11,20,22,25,27,32,37,45,46],mainli:[3,7,23],maintain:[2,3,5,7,19,21,23,25,27,28,33,35,36,38,39,40,42,44,46,47,48,49],mainten:[2,24],major:[5,11,20,49],mak:[2,20,23,25,37,49],make:[0,2,3,4,5,8,10,11,16,17,19,20,21,22,23,24,25,26,27,28,35,37,39,44,46,47,48,49],make_point:44,makeautoconftag:7,makefil:[2,20,25,45,49],makepromis:7,maker:38,makesubpars:45,maketagentri:[7,37],man:[5,9,10,11,12,13,14,15,16,17,18,19,20,23,24,25,29,31,44],man_man:2,manag:[4,5,20,25,26],mani:[2,7,8,20,21,22,23,25,26,27,28,39,46,49],manifest:25,manipul:[19,23,26],manner:[10,19,20,23],manual:[9,10,11,12,13,14,15,16,17,18,19,20,21,22,25,34],map:[8,9,10,11,13,14,15,16,18,19,25],mar:2,march:35,mark:[20,21,22,23,25,29,35,45,46],markdown:[23,25,44],marker:[2,7,20,22,24,25,26,31,38],marko:22,martin:[28,48],masatak:[2,3,7,23,25,28,33,38,40,42,44,46,47,48],master:[12,18,20,28,44],match:[5,7,8,9,19,20,21,23,26,27,28,36,42,45,48],matchedstr:26,matchedtempl:42,matchloc:26,materi:26,matlab:20,matter:[9,22],matur:26,maven2:[23,31],maxdepth:20,maxim:46,mayb:[3,19,20,46],mayswitchlanguag:7,mb:10,mbyte:22,md:[12,27],me:[2,3,27,44,45],mean:[0,2,7,9,10,20,21,22,25,28,31,32,39,44,45,46,48],meaning:[31,44],measur:47,meet:[20,46],member:[2,7,8,9,18,20,22,28,35,48],memmov:[28,48],memori:[2,3,7,26,46],mention:[22,27,37,49],menu:49,mere:[9,20],merg:[2,28,46,48],meson:[2,23],mesonbuild:23,mesonopt:23,messag:[2,19,20,46],met:46,meta:[9,19,20,23,33,38],method:[4,6,9,10,13,19,21,22,25,27,28,37,40,45,46,48],method_:37,methoda:19,methodb:19,mgroup:25,microsoft:1,middl:20,might:[2,6,10,22,25],mind:[25,35],mine:28,mingw32:[23,49],mingw:[23,49],minifi:20,minim:10,minimum:10,minor:[2,35],minu:[7,9,20],mio:7,misc:[2,4,7,46,47],misccomp:10,miscellan:[8,23],mishandl:39,mislead:10,miss:[9,20,21,22,28,48],mistak:[28,48],mistakenli:20,misus:[28,48],mix:[2,20,32,39],mk_mingw:[23,49],mk_mvc:49,mkdir:0,mkstemp:[20,49],mline:[19,20,25,26],mm:20,mode:[2,5,10,20,24,31],modelin:20,modern:[10,25],modif:[2,7],modifi:[2,19,20,25,31],modport:18,modul:[2,14,15,18,20,25,28,37,44,46,48],module_vers:20,mojom:25,moment:[3,49],mon:[28,48],moolenaar:[20,22],moos:23,more:[2,3,5,7,10,11,18,19,20,21,22,23,24,25,27,28,31,32,35,36,37,39,45,46,47,48,49],most:[0,2,3,4,9,10,11,19,20,22,23,25,27,35,37,45,46,49],mostli:[3,22,25,35],motiv:[2,8],move:[2,5,23,25,27,31,39],ms:[1,5,20,22],msbuild:49,msdo:24,msg:[19,20,24],mswindow:24,msy:49,msys2:[10,23,49],much:[7,20,21,23,24,25,26,27,28,36,40,49],multi:[5,8,19,20,34,38],multibyt:[20,44],multilanguag:3,multilin:20,multipl:[2,3,4,5,8,10,19,20,21,22,23,24,32,35,36,39,46],must:[2,7,11,19,20,22,23,25,26,31,37,44,45,46,47,49],mutabl:[31,35],mv:49,my:[2,3,7,8,21,44],my_ctag:0,myemacs_tag:0,myfunc:[21,35],mymethod:21,myrddin:23,mystruct:20,myvar:21,n:[2,7,11,12,14,15,16,18,20,21,22,25,26,31,35,40,44,46],naiv:20,name:[1,2,3,6,7,8,9,14,15,17,18,19,22,25,26,28,31,32,34,37,41,42,44,45,46,48,49],name_pattern:[19,20],nameattr:16,nameref:15,namespac:[14,15,20,25,31,35,40,44],narrow:7,nativ:[0,23,28,44,49],natur:[20,25],navig:2,nbyte:20,nc:31,ndk:0,ne:21,nearer:9,nearest:9,necessari:[5,22,25],necessarili:10,neck:20,nedit:[8,22],need:[0,6,7,9,10,14,19,20,21,22,23,25,27,35,36,37,40,44,45,46,47,49],neither:20,nest:[7,21,22,25,42,45,46],net:[3,10,18,19,20,21,22,27,28,48,49],nettyp:18,never:[7,10,20,25,31,35,46],new_field:22,newer:[42,46],newli:[2,9,19,20,23,24,25,31,44,45],newlin:[6,20,25,26,46],newmacrocallback:7,newmacrofound:45,newmacronotifi:[7,45],next:[7,9,10,20,22,24,25,27,31,45,46],nice:10,nicev:25,nil:9,nix:[1,5],nl:22,nmake:49,nmap:10,no_nomatch:10,no_parameter_port_list:18,node:[10,42],nois:5,non:[2,9,10,19,20,22,23,25,26,28,31,37,45,46,48],none:[9,12,14,15,16,17,18,20,24,31,44,46],nonomatch:10,nor:[20,25],normal:[9,20,22,27,35,49],notabl:[8,10,43],notat:[9,19,20,25,26,31,32,44],note:[8,9,10,12,14,15,16,18,19,21,22,23,24,25,28,32,35,37,45,48,49],notepad:3,noth:[7,19,20,23,25,28,31,45,46,48],notic:[2,9,14,15,21],notifi:[10,23],notori:25,now:[0,3,7,9,10,11,21,22,25,28,35,37,41,48],nowadai:23,nrole:[18,20,44],nsi:23,num:[19,24],number:[5,6,7,9,10,19,20,21,22,25,28,32,35,36,37,48],numer:[20,22],nvi:22,o:[2,9,11,12,14,15,16,17,18,19,20,25,31,33,35,37,44,45,46,47],obei:15,objc:[28,48],object:[2,5,6,7,9,13,15,17,20,25,28,31,33,44,48],objection:10,objectivec:[20,23],observ:20,obsolet:[8,24],obtain:[7,46],obviou:[2,22,25],obvious:49,ocaml:[28,48],occasion:[3,19],occur:[9,20,22,23,28,48],occurr:20,odd:25,off:[20,23,31,45],offer:21,offici:[10,19,20,21],offset:7,often:[10,20,22,25],ok:[31,46],old:[9,22,35,36,39,45,46,49],older:[10,20,25,46,49],omit:[19,20,22,25,41,44],omni:3,onc:[2,6,10,19,20,22,24,25,27,35,44,46],one:[0,2,3,6,7,8,9,11,16,17,19,20,21,22,23,24,25,28,31,32,35,36,37,39,44,46,48],onelin:[28,48],ones:[9,11,18,20,21,25,35],onli:[2,6,7,9,10,11,12,19,20,21,22,23,24,25,27,28,31,35,36,42,45,46,48,49],onto:25,oo:40,op:[20,26],opaqu:7,open:[6,9,11,20,28,37,44,48],oper:[2,8,9,10,21,25,31,35],opposit:9,opt:[0,19,26],optim:[22,36],option:[5,6,7,8,12,14,15,16,17,18,22,28,29,31,32,34,35,36,37,38,44,45,46,47,48,49],optlib2c:[2,5,24],optlib2c_input:[2,25],optlib:[2,3,4,5,7,8,11,23,28,31,45],optscript:[5,20],optsript:26,order:[3,5,10,20,21,37],ordinari:24,org:[3,10,17,18,19,20,22,28,34,39,48,49],orient:[0,20,26,36,37,39,40],origin:[7,9,10,20,22,23,28,31,33,47,48,49],orphan:[20,28],os:[1,5],osx:1,other:[1,2,3,5,7,9,10,14,15,17,19,20,21,22,24,25,27,31,34,35,36,37,45,46,47],otherwis:[9,13,20,24],our:[2,28,37],out:[0,2,3,20,22,23,27,28,46],outer:25,outlin:4,output:[2,4,5,6,8,11,12,13,14,15,16,17,19,24,26,31,35,37,44,46,47],outsid:[20,35,41],outstand:35,over:[6,20,22,25],overcom:20,overflow:[6,28,48],overhaul:7,overlap:[25,28,48],overli:[11,25],overload:20,overrid:[5,20,21,23,24,28,35,37,48],overridden:[18,46],overview:[8,28],overwrit:20,overwritten:20,own:[3,7,9,10,20,22,23,25,28,31,32,37,39,45,46,48],owner:[20,28,31,48],p1:18,p2:18,p3:18,p:[9,10,18,20,21,22,23,25,28,31,35,44,48,49],pacemak:49,packag:[0,10,18,20,27,28,48,49],package_kind:7,packcc:[0,4,5,23],page:[5,9,10,11,12,13,14,15,16,17,18,19,20,23,24,25,28,29,31,44,48],pai:25,pair:[7,19,20,21,23,46],parallel:10,param:[20,31,35],paramet:[2,7,9,19,20,24,25,29,35,39,46],parameter:11,parameterent:31,parent:[7,25],parenthes:[20,35],parenthesi:[20,21],pars:[2,4,7,8,11,19,20,22,23,25,26,28,34,35,36,39,45,48],parser2:37,parser:[3,5,8,9,11,12,13,16,17,18,21,22,24,28,29,32,47,48,49],parser_list:[2,25],parser_p:[2,25],parser_src:[2,37],parserdefinit:[7,37],parserdepend:7,parserfin:37,parseriniti:37,parsernew:[7,37],part:[0,2,5,7,9,10,22,23,25,27,28,37,41,42,45,46,48,49],partial:[19,20],particip:5,particular:[10,20,25],particularli:10,partit:20,partli:10,pascal:22,pass:[2,6,7,9,10,12,20,23,24,25,31,35,37,45,46,47],passwd:[23,25],past:[20,35],pat:9,patch:[2,44,46],path:[6,9,10,11,20,21,22,35,47,49],path_separ:[28,48],pathnam:[5,19,20],pattern:[5,6,7,8,10,12,19,20,21,22,26,28,29,37,38,44,45,46,48],paul:22,pdb:49,pdf:26,pdx:[20,22],peg:[7,23],peopl:[2,5,9,19,22,23,31,44],per:[6,7,20],perfect:20,perfectli:39,perform:[2,5,10,21,25,34,35,49],perhap:10,period:[10,20,42,49],perl6:23,perl:[8,20,23],perldoc:19,perlpod:19,permit:20,person:[2,3,5,19,20,24,28,44],perspect:25,php:[3,20,23,28,31,46,48],pick:[28,48],pipe:20,pipebuf:22,pitfal:[9,35],pkg:[0,28,48,49],pkg_config_libdir:0,pkg_config_path:0,pkgconfig:0,pl:[17,28,48],place:[20,25,26,31,35],placehold:[19,20,25],placement:25,plain:45,plan:35,platform:[2,3,10,20,23],pleas:[0,2,3,20,44,49],plist:23,pll:20,plpgsql:17,plpythonu:17,plu:[7,9,20],plug:3,plugin:[2,3,18,28,44],plural:23,plv8:17,pod:[8,23,25],point:[7,20,25,27,31,37,44,45,46],pointer:35,pointless:25,polici:[25,35],poor:49,pop:[19,20,25],popul:37,popular:[0,2,24,25,45],port:[18,49],portabl:22,portion:20,posit:[9,20,22,25,32,37,45,46],posix:[11,19,20,21,22,25,49],possess:25,possibl:[2,19,20,22,23,24,25,35,37,47],post:[21,25],postgresql:17,postscript:5,potenti:[2,10,20,22,25],power:[24,25,49],powershel:23,pp:25,pr0:25,pr1:25,pr:27,pragmawar:31,prebuilt:0,preced:[9,20],predic:21,prefer:[20,25,27],prefix:[0,2,7,9,19,20,21,22,25,26,31,32,35,41,46],preformat:44,preload:[8,19,20,24],prepar:[2,5,7,28,31,48],prepend:[20,32],preprocessor:[20,23,33],prerequisit:1,presenc:[10,20],present:[6,9,10,20,22,49],preserv:[27,35,49],press:20,pretti:27,pretty_var_expand:45,prevent:[9,11,20],previou:[8,20,25,35],previous:[20,24,25],primari:[2,3,5,25],primarili:[5,10],prin1:9,print:[10,19,20,21,25,26,31,32,42,47],printabl:19,printer:26,printf:32,prioriti:[31,32],privat:[7,19,20,25,40,44],privileg:0,probabl:9,probe:[7,45],probelanguag:7,problem:[3,9,10,20,21,22,39,49],proc:25,proce:27,procedur:[17,25,26],process:[2,6,7,9,10,19,20,23,24,25,27,35,46,49],processor:21,produc:[9,20,21,22,24,25,28,35,49],profession:49,profil:[36,47],program:[0,3,5,6,7,18,19,20,21,22,25,28,35,37,44,45,47,49],programm:24,programmat:[6,23],progress:[2,27,49],project:[0,2,3,5,9,10,19,20,21,22,23,24,27,49],project_nam:34,project_name_str:34,promis:[4,45],promot:31,prompt:[20,26,49],pronounc:44,proof:3,proofread:5,proper:[9,17,19,20,25,39,49],properli:[20,25,49],properti:[2,18,31,32],propertylist:[2,23],propos:[8,9,28,31],protect:[20,25,40,46],protobuf:[23,28,48],prototyp:[2,4,7,18,20,22,35,44],provid:[0,2,3,5,7,9,10,19,20,22,23,24,25,26,28,45,49],prune:10,pseudo:[8,20,21,22,29],pstack:26,ptag:9,pthon:23,ptr:20,ptrv:[28,48],pub:10,publish:26,pull:[5,25],puppet:[25,46],puppetmanifest:[5,23,25,43,46],purchas:49,pure:[18,20,35],purpos:[2,7,9,20,22,23,25,26,35,46],pursu:20,push:[2,19,25,26],put:[2,7,10,12,19,20,21,22,24,25,26,45,46],pwd:[0,10],px:20,py:[9,12,15,25,31,46],pygment:25,python2:[28,48],python3:[0,28,48],python:[5,8,9,12,16,17,20,21,23,25,26,28,43,46,48,49],python_keyword_2:31,pythonloggingconfig:23,q:[7,10,18,20,21,23,25,31,40],qemuhx:23,qingm:3,qq:3,qtmoc:23,qualifi:[4,5,10,20,31],qualiti:[3,26],quantifi:25,queri:[2,21],question:[10,31,45],queue:7,quick:[2,10,21],quickli:[10,19,20],quiet:[19,20,24,25],quirk:25,quit:[10,19,20,22,24,25,26,28,39,46,48],qunus:0,quot:[2,7,9,10,17,20,22,23,24,25,35,39,41],r3:17,r6class:23,r815:[28,48],r:[2,5,8,10,14,15,18,20,22,23,25,26,28,31,35,45,46,48],race:20,rais:[9,21],random:[2,14,15,16,46],randomli:2,rang:[22,25],ranlib:0,rare:[20,22,24,25],raspbian:3,rather:20,raw:4,rb:6,rc:20,re:[9,25,28,48],reach:[19,25,35],read:[2,4,6,7,8,9,10,11,19,20,22,23,24,25,26,28,46,48],readabl:[20,21,22,25,29,32,47],readcmd:47,reader:19,readi:[2,46,47],readili:3,readlinefrombypass:7,readlinefrombypassslow:7,readlinefrominputfil:[7,37],readlineraw:7,readlinerawwithnoseek:7,readm:[12,27],readtag:[0,5,8,20,22,47],real:[7,20,22,24,35,45],realist:25,realli:[10,20,22,25],rearrang:46,reason:[2,9,10,15,20,23,25,31,35,36,46,47],rebas:[2,28,48],rebuild:10,receiv:[2,6,7,20],recent:49,recip:5,recogn:[7,9,19,20,22,23,25,28,31,37,45,46,48,49],recognit:46,recommend:[10,19,22,23,26,49],record:[2,7,14,15,20,25,28,31,41,45,46,48],recov:[20,25],recurs:[10,20,35],red:[2,26],redhat:[2,3,23,25,28,33,38,40,42,44,46,47,48],reduc:[2,19,20,22],redund:[8,19,35],ref:[19,25,28,48],refactor:2,refect:23,refer:[7,8,9,14,15,18,19,20,21,23,28,29,32,34,44,45,46,48],referenc:[2,20,31,45],refin:[2,19,20],reflect:[28,35,48],refonli:[18,20,44],reftag:31,refus:20,reg_newlin:25,regard:[20,22,23,28],regardless:16,regener:10,regex:[2,4,5,8,9,11,12,20,23,24,26,28,34,38,44,45,48,49],regexlex:25,regexmatch:7,regexp:[9,19,21,28,48],regist:[4,18,23,45],registr:7,regress:[3,40,46],regrett:39,regular:[4,5,9,19,20,21,22,36],reject:[9,11,28,48],rel:[9,10,20,22,24,25],relat:[5,15,20,25,28,44,45],relationship:[5,15,45],relativefilenam:[28,48],relaxng:23,releas:[2,3,20,27,35,49],relev:25,reli:[9,20],reliabl:[35,47],remain:[9,10,20,49],remark:[8,22],rememb:[0,7,10,21,25,46],remot:[10,28,48],remov:[2,9,19,20,23,46,47],renam:[0,2,11,20,23],render:[20,44],repeat:[28,48],repeatedli:12,repl:[6,23],replac:[9,10,11,17,19,20,22,23,26,35],repo:[25,28,48],report:[2,5,19,20,28,35,40,45,46,48],repositori:[2,5,7,20,21,22,25,27,48,49],repres:[2,6,7,9,10,15,19,20,21,23,25,26,31,32,46],represent:[10,19,20],reproduc:[28,46,48],request:[5,6,7,25,41],requestautomaticfqtag:7,requir:[0,2,6,7,9,11,20,22,23,25,28,31,46,48,49],requiredbi:31,requisit:46,rescan:37,rescanpars:37,resembl:9,reserv:[11,19,22,31],reset:[20,28,48],resist:[10,20],resolv:[20,37],resort:31,resourc:[20,28,46,48],resource_:[28,48],respect:[20,25,29,31,36],respons:[2,6,45],rest:[7,9,11,19,20,25],restor:20,restrict:[9,11,18,22],restructuredtext:[22,23,31],result:[0,3,5,9,10,11,20,21,23,25,28,35,36,44,45,47,48],ret:20,retain:20,retri:20,reus:[7,11,44],review:[5,23,27],revis:[20,28,48],reviv:46,rewrit:[39,40],rewritten:[23,35,39,40],reza:[5,20],rge:23,rget:23,rich:10,riddl:39,right:[3,7,20,22,25,32,45],risk:[25,49],rm:49,robot:[23,31],robust:[3,39],role:[9,14,15,19,25,31,45,46],roledesc:25,root:[10,24,25,31,35,46],rough:2,roughli:19,routin:[10,20,37],rpmspec:23,rspec:23,rst:[2,46],rubi:[11,19,28,48],rule:[5,11,15,19,20,22,25,26,35,46],run:[0,2,3,4,5,6,9,10,17,20,21,22,23,24,26,27,35,36,40,44,49],runnabl:46,runtim:[20,49],rust:23,rzk:[14,15,46],rzkz:[14,15],s4class:23,s:[1,3,6,7,8,9,10,11,14,17,18,19,20,21,22,23,25,26,27,28,31,32,33,35,41,44,45,46,48,49],s_ok_to_be_correct:31,safe:[21,25],sai:[9,10,31,44,45],said:24,samborski:3,same:[0,2,7,8,9,19,20,21,22,25,26,27,29,32,46,49],sampl:[7,46],sandbox:[5,44],sap:22,satisfi:[10,21],save:[20,25],saw:25,scan:[7,10,20,25],scandir:49,scanfil:7,scanstr:7,schedul:[2,4,5,45],schedulerunningbasepars:[7,45],schedulerunningbasepas:7,scheme:[3,9,21,45],scope:[5,6,7,8,9,10,14,15,16,18,20,22,23,28,31,32,42,44],scopedenum:35,scopeindex:7,scopekind:[6,9,20],scopespeci:35,scratch:[35,39],script:[7,9,10,20,21,23,24,25,26,27,28,36,41,45],scss:23,sdk:0,search:[5,9,10,19,20,21,22,23,25,26,28],sec:10,seccomp:[0,6],second:[7,10,20,22,25,31,46],secondari:[2,3],section:[2,7,9,10,11,12,13,14,15,16,17,18,19,20,21,22,24,25,26,27,28,29,31,37,43,44,45],sectionmark:31,secur:[6,8,28,48],sed:[19,49],see:[0,2,4,7,8,23,24,25,26,27,28,29,30,31,32,35,37,44,45,46,47,49],seem:[9,20],seen:[20,22,25,35],segfault:[28,48],segment:[28,48],select:[8,10,22,23,27,28,46,48],selectlanguag:37,self:[2,9,10,28,31,48],semant:[2,28,47,48],semi:[5,22,25],semicolon:[9,10,20,22,39],send:[6,10,46],sens:[20,25,45],sensit:[19,27,49],sent:20,sentenc:44,sep:[25,28,31,48],separ:[2,9,10,19,20,21,22,23,24,31,32,36,39,40,42,46,49],sequenc:[2,9,17,18,20,22,23],seri:[28,48],seriou:25,server:10,servic:20,session:26,set:[0,2,3,7,8,9,19,20,22,23,24,25,26,31,34,37,46,49],set_one_prio:25,seth:[28,48],setm4quot:7,setopt:10,setprior:25,setuid:20,setup:49,sever:[10,22,25,28,35,36,37,39],sf:[2,28,48],sgraham:25,sh:[0,10,11,20,25,27,28,46,47,48,49],shamelessli:20,share:[7,28,35,45],sharedlib:34,shebang:[28,48],shell:[9,10,11,19,20,23,24,25,35,46,49],shift:[2,9],shigio:31,shortcut:49,shorten:25,shorter:[21,44],shortest:46,shorthand:25,shortli:25,should:[0,5,7,8,9,11,15,19,20,21,22,25,26,27,31,35,36,37,39,40,44,45,46,49],show:[0,2,9,20,21,23,31,44,45,46],show_bug:[28,48],shown:[0,7,19,20,24,25,35,45,47],shrink:46,shrunk:46,si:22,side:[7,9,19,45],sign:[20,35],signal:6,signatur:[15,20,25,31,35],signifi:20,signific:[10,20,24],significantli:[20,49],silent:20,similar:[2,10,15,19,25,32,35,45],simpl:[2,7,10,20,25,35,36,37,46],simplepars:37,simpler:[0,9],simplest:[6,37],simpli:[2,9,20,25,27,35,45],simplifi:[7,21,36],sinc:[9,10,14,19,20,21,22,24,25,27,35],singl:[6,9,10,19,20,22,24,25,35,39,49],singlequot:46,singletonmethod:11,site:[2,10,19,20,21,24,28,49],situat:[11,20,21],size:[6,10,11,20,22,37],sketch:2,skill:3,skip:[2,19,20,22,26,28,42,46,47,48],slap:5,slash:[20,25,31,49],slightli:25,sln:49,slot:32,slow:[25,49],slower:[22,35,36],sm4subpars:7,smakesubpars:45,small:[2,19,28,46],smaller:[21,32],smart:[20,22],snet:22,snippet:[2,25],so:[0,2,3,4,7,8,9,11,15,17,19,20,21,22,23,24,25,26,28,31,33,35,36,37,44,45,46,47,48,49],softwar:[5,10,20,49],sole:[9,22],solid:7,solut:[10,49],solv:[9,22,28,48],some:[0,2,3,5,7,9,10,11,19,20,22,23,25,26,28,31,35,37,38,39,40,44,45,46,48,49],someev:25,someon:10,someth:[19,20,22,25,31,44,47],sometim:[2,10,21,23,31,44,49],somewhat:0,somewher:[2,31],soon:[46,49],sort:[8,9,10,12,15,16,17,20,22,31,49],sorter:[8,21],sought:20,sourc:[0,2,3,5,7,9,10,11,13,14,15,16,17,18,19,20,22,23,24,26,31,32,35,37,38,44,45,46,47,49],source_fil:[11,20],sourcefil:31,sourceforg:[2,3,10,19,20,21,22,49],space:[5,19,20,21,22,24,25,26,32,49],span:[20,36,39],spars:47,sparserdefinit:37,speak:9,spec:[11,19,20,23,25,28,48],special:[19,20,22,25,26,31,35,45,46,49],specif:[2,5,7,8,9,11,12,21,22,25,26,29,32,37,49],specifi:[2,5,6,7,8,9,11,12,15,19,20,21,22,23,25,26,31,32,42,44,46,47,49],specparam:18,speech:49,speed:[3,35,36],split:9,spot:46,spring:25,spy:45,sql:[2,5,8,11,46],srb:19,src:10,srcdir:45,ssubpars:7,stabl:[2,19],stack:[12,19,25,26,45],stackoverflow:27,stage:[0,9,20,23],stall:[5,49],stand:[7,22,45],standard:[3,8,9,10,11,18,19,20,32,47],stare:12,start:[4,5,6,7,8,9,17,19,20,21,22,23,24,26,35,41,45,46,47,49],startup:20,state:[25,26,39],statement:[8,18,20,25,44],staticfunct:31,station:20,statist:20,statu:[19,28,44,46,47,48],std:18,stderr:[7,47],stdin:[6,46],stdio:[6,20,31],stdout:[6,46,47],steadili:3,stefanek:[3,35],step:[2,9,10,19,25,49],steve:[20,22],steveno:2,still:[7,9,10,11,22,23,25,28,46,47,48,49],stolen:20,stop:[25,26,46],store:[7,8,9,23,25,27,42,45],straightforward:27,strang:8,strategi:23,strcmp:[21,24],strcpy:[28,48],stream:[4,5,19,25],strict:17,stricter:19,strictli:9,string:[7,9,13,17,19,20,21,23,25,26,28,32,37,39,48],stringif:[20,35],stringifi:17,strip:[20,35],strlist:[28,48],strncmp:7,strongli:35,struct:[7,9,18,20,22,25,31,35,37,44,45],structur:[7,20,22,23,28,37],struggl:35,stubbornli:20,studi:7,style:[2,5,9,19,20,21,33,35,36],sub:[7,19,22,45,46],sub_lang:45,subdirectori:[46,49],subject:20,submit:[5,17,25,27],submod:5,submodul:44,subpars:[4,5,9,12,20,23,40],subparser_base_runs_sub:7,subparser_bi_direct:7,subparser_sub_runs_bas:7,subparserrundirect:7,subrubi:19,subscrib:25,subscript:25,subsect:[2,9,19,20,31],subsequ:[25,46],subset:[19,20,45],subshel:47,substitut:[19,32],substr:[21,23,25],subsubsect:19,subtl:[25,46],subvers:22,succe:25,successfulli:[25,26],sudo:0,suffer:22,suffici:25,suffix:[9,20,21,23,25,45,46],suggest:[9,46],suitabl:[2,4,20,22,23,25,26,31],summar:[2,10],summari:[8,20,22,46,49],supplement:49,suppli:[10,20],supplier:10,support:[2,3,5,6,8,9,12,17,19,20,22,23,25,28,29,31,35,37,39,40,42,46,48],suppos:37,suppress:[23,25],sure:[2,20,21,37,49],surround:[9,19,20,23,25,26,32],sv:18,svalu:22,svg:23,svh:18,svi:18,svn:[28,48],svr4:20,swap:[20,31],swine:37,swinepars:37,symbol:[2,7,14,20,23,25,31,35,44],synchron:20,synonym:[18,20],synopsi:8,syntact:[20,39,44],syntax:[5,7,20,25,28,35,36,45,46,49],syscal:25,syscall_defin:25,syscall_define3:25,sysint:10,sysroot:0,system:[0,6,9,10,20,22,25,26,27,28,31,46,49],systemd:7,systemdunit:[7,23,31],systemtap:23,systemverilog:[18,23],szymon:[3,35],t:[2,3,7,8,9,11,12,15,16,17,18,19,20,21,22,23,24,25,26,27,28,31,32,35,44,45,46,48],ta:[20,23],tab:[9,19,20,21,22,23,26],tabl:[5,20,34,37,38,45],tabular:[20,29,32],tag:[4,5,8,12,13,16,17,19,26,27,29,32,33,34,35,36,39,42,44,46,47,48,49],tag_extra_descript:9,tag_field_descript:9,tag_file_encod:[9,20,23],tag_file_format:9,tag_file_sort:9,tag_kind_descript:9,tag_kind_separ:9,tag_nam:20,tag_output_excmd:9,tag_output_filesep:9,tag_output_mod:[9,22],tag_pattern_length_limit:9,tag_proc_cwd:9,tag_program_author:9,tag_program_nam:9,tag_role_descript:9,tagaddress:22,tagbar:3,tagentryinfo:[7,37],tagfield:22,tagfil:[20,21,22],tagmanag:20,tagnam:22,tagrel:10,tail:[20,46],tailor:20,takata:3,take:[2,3,6,7,9,10,19,20,23,26,28,31,37,46,48],taken:[7,20,25,37,44,45,46,49],talk:44,tap:27,target:[2,19,20,23,31,34,46,47,49],task:[2,3,18,37,49],task_struct:25,tbw:[2,4,5,9,26],tcl:[5,23,25,43],tcloo:[23,40],tdm:49,tdragon:49,team:[2,44],techet:36,technic:25,techniqu:[21,45],tell:[21,22,35,44],templat:[2,20,25,31,35,42],temporari:[7,20],temporarili:49,tend:[10,20],tenter:25,term:[2,9,23],termin:[6,9,20,28,48,49],test1_var1:17,test1_var2:17,test1_var3:17,test2_var1:17,test2_var2:17,test2_var3:17,test:[3,5,6,7,10,11,17,19,20,23,25,28,38,44,48,49],test_var3:17,tex:22,text:[3,4,5,8,17,20,22,25,37],textual:20,th:25,than:[2,7,9,19,20,21,22,23,24,25,26,27,31,32,36,37,46,49],the_name_of_languag:25,thei:[2,3,7,9,10,14,18,19,20,21,22,25,28,31,32,35,40,41,45,46,48,49],them:[2,7,9,10,17,19,20,21,22,23,24,25,26,33,35,40,44,45,46,47,49],themselv:14,theoret:7,theori:25,therefor:[3,7,19,20,22,24,25,28,45,48,49],thi:[2,4,5,6,7,9,10,11,13,14,15,16,18,19,20,21,22,23,24,25,26,27,28,29,31,32,35,36,37,39,40,42,43,44,45,46,47,48,49],thing:[2,9,24,25,27,28,39,44,45,49],think:[2,7,15,19,20,25,44,45,46],third:[10,25,31],those:[3,10,20,21,24],though:[7,10,11,19,20,23,25,26,35,44,45],thoughtfulli:2,thousand:22,three:[10,19,20,23,25,35,44,45,49],through:[3,19,20,24,25,37],thu:[10,20,24,25,41],ticket:[28,48],till:[2,7],time:[2,3,6,7,8,16,19,20,22,24,25,26,28,31,35,44,46,47,48],tinst:[2,5,24],tip:[5,8,21,23],titl:[7,9,28,48],tjump:25,tleav:25,tm:26,tmain:[2,5,23,24,46],tmain_compar:47,tmain_run:47,tmp:[7,9,25,44,46],tmpdir:20,to_char:17,toctre:2,todai:25,todo:[7,23,28,48],togeth:[5,14,20,25,45,49],token:[7,17,20,31,35,36,37,39,40,45],tokeninfo:[4,5],toler:9,tom:22,tomasz:[3,35],too:[0,2,7,9,12,20,28,31,44,46,48,49],tool:[0,2,5,7,8,12,13,14,15,17,18,20,21,22,23,25,27,30,31,42,47,49],toolchain:[0,27,49],top:[2,7,12,16,19,20,23,25,31],topic:[2,9,20,29,43],toplevel:25,total:[20,32],touch:7,toward:49,tp_arg:45,tp_proto:45,tquit:25,track:[2,5,7,19,23,46],tracker:[2,28,48],tradit:[5,22,31,49],tradition:[22,31],trail:[20,22,28,35,48],trait:13,transform:[0,2],transit:25,translat:[2,5,7,9,21,24],travi:46,treat:[9,19,20,22,24,25,35],tree:[0,2,7,10,20,26,28,44,45,46,48],treset:25,tri:[20,23,24,25,28,35,45,46],trial:49,trick:[35,49],tricki:39,trigger:[25,46],trim:[9,17],tripl:[39,44],trivial:10,trojan:22,troubl:20,truli:37,truncat:[20,29,32,46],trunk:[28,48],ttcn:[2,23,28,48],tue:2,tupl:44,turn:[9,20,21,23,28,44,45,48],tutori:26,tweak:21,twice:[11,22],two:[0,2,6,7,9,10,19,20,21,22,23,24,25,26,31,35,37,44,45,46,49],two_altern:20,txt2tag:23,txt:[34,47],type:[2,4,8,10,18,19,20,22,25,31,35,36,45,46],typedef:[7,9,18,20,22,35],typenam:[9,11,15,20,25,31,35,44],typeref:[9,11,15,20,25,31,44],typescript:[2,3,23],typic:[2,10,20,25,45],u:[2,5,11,17,20,22,25,29,31,33,44],ubuntu:[0,3],uctag:20,uctagsend:20,ued:[28,48],uganda:20,ugli:20,uk:22,ultim:25,ultra:25,unabl:[20,46],unavail:46,unavoid:35,unbalanc:20,uncertain:21,unconstrain:20,uncov:10,uncrustifi:2,undef:[20,31,35],undefin:[13,20,22,25],under:[2,10,20,24,25,26,28,47,48,49],underscor:[2,20],understand:[2,19,20,23,25,26,28,35,39,44,48,49],understood:20,unescap:9,unexpect:46,unexpectedli:44,unfair:46,unfortun:[5,22],unhid:35,uni:22,unicod:8,unifi:[5,18,24],unintend:9,unintuit:25,union:[9,18,20,22,35],uniqu:[11,19,20,22],unit:[2,3,5,7,18,24,28,31,47,48,49],univers:[0,2,3,4,6,7,8,9,11,12,13,14,15,16,17,18,19,20,21,23,24,25,26,27,28,29,31,33,36,37,41,44,45,48,49],unix:[10,20,22,25,31,49],unknown:[7,14,15,20,25],unless:[19,20],unlik:[15,20,25,26],unmap:20,unmatch:10,unn:[28,48],unnam:19,unnecessari:2,unoffici:10,unpredict:22,unrecogn:9,unsav:6,unset:7,unsign:[7,37],unsort:[9,20,21,22],until:[20,21,25],unus:2,unusu:37,unwant:[12,31],uo:[18,20],up:[3,7,8,19,20,24,25,28,35,37,39,46,48],upcas:21,updat:[2,7,9,28,48],upon:[10,20],upper:[5,7,20,22,23,25,31],url:[2,22,44],us:[0,1,2,3,4,5,6,8,10,15,18,21,22,23,25,26,27,31,32,34,35,36,37,40,41,42,44,45,46,47,48],usabl:[22,25,28],usag:[4,16,20,22,23,25,29,35,46],usecork:[7,37],useless:20,user:[0,3,5,6,10,11,17,19,20,21,22,23,25,27,28,31,32,34,35,45,48,49],usr:[0,20,24],usual:[7,19,20,25,46],utf:[20,28,48],util:[2,7,8,10,19,20,21,26,28,31,33,45,49],utmost:28,v1:23,v7a:0,v8:17,v:[0,9,12,16,17,18,20,22,23,25,31],va_format:45,vaf:45,val:17,vala:28,valgrind:[2,47],valid:[5,9,13,20,21,39,44],valink:7,valu:[7,9,15,16,18,19,20,21,22,23,25,26,28,31,32,42,45,46,48],valuenotifi:45,valuesfound:45,var0:15,var1:15,varchar:17,variabl:[0,2,7,8,9,15,16,18,21,22,24,26,31,34,35,39,41,45,46],variant:46,variat:46,varieti:[3,20,23,31,37,46],variou:[2,3,9,17,20,28,31],varlink:23,vberthoux:10,vcxproj:[2,49],ve:[2,3,25],vector:16,vendor:49,verbos:[20,23,42],veri:[7,19,20,24,25,27,36,39,45,46,49],verif:18,verifi:[11,47],verilog:[3,5,8,23,46],versa:24,versatil:28,version:[2,3,5,6,7,9,10,11,12,13,14,15,16,17,18,19,20,21,22,24,25,27,28,31,42,44,46,48,49],vfm:9,vg:[2,28,46,48],vhd:46,vi:[8,10,44],via:[7,15,23,35,44,46],vice:24,view:[28,45,48],vile:22,vim:[3,5,10,12,20,22,23,43,46,48],violat:[19,22],virtual:[20,31,35],viru:49,visibl:[20,37],visit:[19,20,24],visual:10,visualstudio:49,vitor:3,volatil:35,vs2012:49,vs2013:49,vs:20,vstring:7,vstringlength:7,vstringvalu:7,vt:22,w64:49,w:[16,18,20,26],wa:[5,6,7,10,20,22,23,24,25,28,31,35,36,39,40,46,47,48,49],wai:[0,2,6,7,9,10,15,19,20,22,23,24,25,28,35,38,39,44,45,46,49],wait:2,wall:47,want:[0,2,6,8,11,15,18,19,20,21,25,26,31,37,44,45,46,49],wantedbi:31,war:45,warm:25,warn:[11,19,22,23,25,47],warning_cflag:47,we:[0,2,5,7,9,10,14,15,19,21,22,23,24,25,27,28,44,45,46,48],weak:[8,20,31],wealth:20,web:[2,5,10,19,20,21,26],websit:3,welcom:[2,5,44],well:[2,3,7,16,25,26,31,35,40,44,46,47,49],wendl:[3,7,39],were:[7,20,23,24,25,35,36,39,46],wextra:47,what:[7,8,9,19,20,21,22,24,25,31,37,39,44,46,49],whefxlr:[28,48],when:[0,2,3,6,7,8,9,11,12,19,20,21,22,23,24,25,26,27,28,31,32,35,37,40,42,44,45,46,47,48,49],where:[0,2,3,5,6,7,9,10,19,20,21,22,25,27,31,32,35,44,45,47,49],wherea:20,wherev:19,whether:[2,7,9,10,14,15,16,20,21,23,25,31,45,46],which:[0,3,5,6,7,8,9,11,18,19,20,21,22,23,24,25,31,32,35,37,44,45,46,49],whichev:19,white:[19,20,22,32],whitespac:[2,11,24,25,28,31,48],whitespaceswap:31,who:[0,2,5,9,19,20,21,25,31,46],whole:[10,19,21,25,35],whose:[10,18,20,31,32],why:[7,8,14,15],wide:[20,23,25],width:32,wiki:[28,48],wikipedia:[28,48],wild:[31,32],wildcard:[20,25,44],win32:[2,3,20,49],window:[1,3,5,10,20,23,24,28,31,48],windr:[3,23,28,48],wip:2,wireshark:23,wish:10,with_empty_parameter_port_list:18,with_iconv:[23,49],with_parameter_port_list:18,withdefinedirect:45,within:[10,19,20,25,31,35,36,44,46,49],without:[2,7,9,10,19,20,22,23,25,31,35,46,49],won:[9,25],wonder:19,word:[9,19,20,25,31],work:[2,3,5,7,9,10,11,12,20,21,22,23,24,25,27,28,40,44,45,46,47,48,49],workaround:[10,20],world:26,wors:20,worship:20,worth:[28,44],would:[2,10,20,21,22,24,25,49],wouldn:27,wrap:[9,21],write:[3,4,5,7,9,10,19,20,21,22,23,25,26,31,35,44,45,47],writeentri:7,writer:[7,37],writert:7,writerwritetag:7,writetagentri:7,written:[0,5,7,9,17,20,22,24,25,26,27,28,35,36,45,46,48,49],wrong:[8,20,25,46],wrote:[2,3],wspars:47,www:[2,10,17,20,49],x0:[14,15,44,46],x1:[14,15],x20:22,x21:22,x2:[14,15],x3:[14,15],x4:15,x64:49,x86_64:[0,49],x:[9,12,14,15,19,20,22,25,26,28,29,31,32,35,44,45,46,47,48],xbb:23,xbf:23,xcode:27,xdg_config_hom:[20,24],xef:23,xfmt:31,xml:[11,49],xname:25,xpath:[42,44],xplang:17,xref:[5,20,29,31],xrefwrit:7,xsl:42,xslt:[5,23,43],xxx:22,xyz2:17,xyz:[17,22],xz:49,y0:44,y1:15,y3:15,y4:15,y:[7,14,15,20,25,26,28,31,35,44,48],yacc:[7,23],yamato:[2,3,7,23,25,28,33,38,40,42,44,46,47,48],yaml:[23,31,44],ye:[9,10,11,18,20,23,49],year:3,yet:[3,20,25,28,35],yml:0,yoshida:7,you:[0,3,4,5,7,9,10,11,12,15,18,19,20,21,23,24,25,26,27,28,31,32,35,37,44,45,46,47,48,49],young:2,your:[3,7,9,10,12,19,20,21,23,24,25,26,27,28,31,37,44,48,49],yumrepo:[7,23],yyerror:7,z0:[19,25],z4:15,z:[10,11,15,19,20,23,25,28,32,48],z_0:25,z_:25,za:[19,25],zephir:23,zero:46,zeu:22,zip:49,zk:20,zsh:[2,8,20],zshrc:10,zzz:24},titles:["Building with configure (*nix including GNU/Linux)","Building ctags","Contributions","Who we are","Extending ctags with a parser written in C","Universal Ctags Hacking Guide","Interactive mode","Input text stream","Man pages","ctags-client-tools","ctags-faq","ctags-incompatibilities","ctags-lang-iPythonCell","ctags-lang-inko","ctags-lang-julia","ctags-lang-python","ctags-lang-r","ctags-lang-sql","ctags-lang-verilog","ctags-optlib","ctags","readtags","tags","Other changes","Option files","Extending ctags with Regex parser (<em>optlib</em>)","Optscript, a programming language for extending optlib parsers","Building on Mac OS","Relationship between other projects","Output formats","JSON output","Changes to the tags file format","Xref output","Asm parser","CMake parser","The new C/C++ parser","The new HTML parser","Writing a parser in C","puppetManifest parser","The new Python parser","The new Tcl parser","The Vim parser","XSLT parser","Parsers","Request for extending a parser (or Reporting a bug of parser)","Running multiple parsers on an input file","Testing a parser","Testing ctags","Tracking other projects","Building/hacking/using on MS-Windows"],titleterms:{"8":23,"case":[2,46],"class":10,"do":10,"function":[7,10],"import":[14,15,23,46],"long":[10,11,23,31],"new":[2,23,25,35,36,39,40],A:11,AND:[14,15],FOR:[9,19],No:24,TO:20,The:[7,11,25,26,35,36,39,40,41,44],WITH:20,_guest:25,about:9,accept:11,acknowledg:46,action:21,ad:[25,37],add:2,advanc:25,all:10,alphabet:11,also:[9,10,11,12,13,14,15,16,17,18,19,20,21,22],alwai:23,an:[9,23,24,25,44,45,46],anjuta:28,anonym:35,api:7,append:10,appli:45,applic:11,ar:[3,10],area:45,argument:[23,25],arrang:11,asm:33,author:[10,19,20],autoconf:45,automak:45,automat:[7,23,25,35],avoid:[10,24],background:[7,45],backward:22,bad:46,base:[7,45],basic:[2,25],befor:[2,44],begin:10,behavior:21,between:[10,26,27,28,49],bidirect:25,bit:10,block:[25,49],bom:23,bottleneck:47,bottom:45,bug:[17,20,28,40,44,46,48],build:[0,1,2,9,27,49],bypass:7,c:[2,4,20,25,35,37,45],call:7,can:10,captur:25,categori:46,caus:10,caveat:20,chang:[0,2,23,31,35,41],charact:11,check:47,choic:45,chop:46,client:9,cmake:34,code:[25,49],codebas:2,combin:[11,25,45],command:[2,11,20,23,26,35,45,46,49],comment:25,commit:2,compat:[2,22],compil:[0,7,49],complement:23,condit:25,configur:[0,24],content:[2,10,20,23,25,26,28,44,46,47],contribut:[2,27],control:[21,25],cork:7,coverag:47,cppcheck:47,cpreprocessor:23,credit:[20,21],cross:0,css:45,ctag:[1,4,5,9,10,11,12,13,14,15,16,17,18,19,20,22,23,24,25,26,28,37,47,48,49],custom:[12,25,32],d:23,data:[9,26],debian:[28,48],declar:25,dedic:25,defin:[2,11,19,23,25,35],definit:[11,19,45],descript:[9,10,11,12,13,14,15,16,17,18,19,20,21,22],design:7,detail:20,determin:20,devel:[28,48],develop:[2,27],differ:[10,24,26,27,49],direct:[25,45],directori:[10,24,46],disabl:23,disallow:11,discuss:31,distribut:0,document:2,doe:10,down:45,e:27,emac:[2,20],enabl:23,encod:23,end:[10,25],engin:[25,28],entri:[20,23],environ:[11,20],error:10,everi:10,exampl:[2,14,15,17,19,21,25,44,45,46],except:[22,23],exclud:23,exclus:25,execut:0,expand:[23,35],experiment:[23,25,35],express:[7,9,14,15,21,25],extend:[4,7,22,23,25,26,44],extens:[11,20,24,26],extra:[12,20,23,25,31],exuber:[10,23,24,28,48],f:[11,31],facil:[46,47],faq:10,favorit:10,featur:35,fedora:[28,48],field:[7,9,18,20,23,25,31],file:[9,10,11,19,20,22,23,24,25,31,35,37,45,46],filter:[9,21,23],find:[46,47],flag:[19,25,45],follow:10,format:[9,11,20,22,29,31],found:10,from:[7,22,23,24,25,35,46,49],full:[2,7,40],fulli:[23,25],fussi:47,fuzz:46,g:23,gather:46,gcc:49,geani:28,gener:[6,7,25],ghost:7,global:28,gnu:[0,2,20,27,28,49],goal:22,good:44,group:7,guess:[7,20,23],guest:[7,25,45],guid:5,hack:[5,49],have:10,heurist:20,hierarchi:10,higher:45,highli:[23,35],highlight:28,hint:15,homebrew:27,how:[2,7,10,20,46],html:[36,45],i:[10,27],id:49,idea:7,improv:23,includ:[0,23],incompat:[11,23,24,35,41],inform:[2,25,35],inherit:35,inko:13,input:[7,9,11,20,23,31,35,37,45,46],inputfil:7,inspect:[21,23],instal:47,instead:10,interact:[6,23],interest:28,interfac:[11,20,45],intern:[7,23],introduct:[22,35,36,39],ipythoncel:12,issu:[18,24],its:7,japan:28,javascript:45,json:[9,30],julia:14,jump:10,kernel:28,kind:[2,7,9,11,12,16,18,20,23,25,31],known:[17,18,40,46],lambda:15,lang:[11,12,13,14,15,16,17,18,19,23],langdef:11,langmap:11,languag:[2,9,11,18,20,26,45,46],learn:26,letter:[11,20,25],level:[10,45],licens:2,line:[2,10,11,20,23,25,31,35,45,49],linux:[0,27,28,49],list:[9,20,23,24,28,45,48],load:[11,24],locat:10,log:2,m4:45,mac:27,macro:[23,35],mail:[28,48],main:47,make:[7,9,45],man:[2,8,46],manag:[7,24],mani:10,manual:27,map:[20,23],match:[10,25],maxdepth:23,member:10,messag:23,method:7,microsoft:49,minim:46,misc:37,miscellan:20,mode:[6,23],motiv:20,ms:49,multi:[10,25],multilin:25,multipl:[7,9,25,45],my:10,n:23,name:[0,10,11,20,21,23,35],nedit:20,nest:40,never:23,nix:0,nois:46,notabl:[9,35],note:[2,20,46],notic:23,number:23,numer:11,obsolet:[11,20],one:10,opengrok:28,oper:[20,26],option:[2,9,10,11,19,20,21,23,24,25,26],optlib2c:25,optlib:[19,20,24,25,26],optscript:26,order:[11,24],orient:24,origin:2,os:27,osx:27,other:[11,23,28,48,49],our:25,outlin:7,output:[7,9,20,21,22,23,25,29,30,32],overrid:25,overview:19,packcc:7,page:[2,8,46],paramet:[18,31],pars:[9,37],parser:[2,4,7,19,20,23,25,26,31,33,34,35,36,37,38,39,40,41,42,43,44,45,46],part:[11,47],patch:[28,48],path:24,pathnam:24,pattern:[9,11,23,25,31],perform:47,perl:[19,45],pod:[19,45],postscript:26,prefix:23,preload:11,prepar:26,preprocessor:35,prerequisit:27,previou:9,print:23,proc:40,program:26,project:[28,48],promis:7,properti:35,propos:22,pseudo:[9,23,31],pull:2,puppetmanifest:38,put:23,pygment:28,python:[15,39],qualifi:[2,7,25,40],quiet:23,r:16,raw:7,read:[21,37],readtag:[9,21,23],realist:2,recip:26,redund:9,refer:[2,10,17,25,31],regex:[7,19,25],regist:[7,37],regular:[7,25],rel:23,relat:[23,26],relationship:28,remark:9,remov:11,report:44,repositori:28,request:[2,44],result:46,review:[2,46],role:[2,20],rule:2,run:[7,25,45,46,47],s:[0,12],same:[10,23,35],sandbox:6,schedul:[7,25],scope:[2,11,19,25,35],script:2,secur:22,see:[9,10,11,12,13,14,15,16,17,18,19,20,21,22],select:20,semi:46,separ:25,sequenc:25,session:46,set:10,share:25,should:[2,10],skip:[23,25],slap:46,so:10,softwar:28,sort:[21,23],sorter:9,sourc:[25,28],sourceforg:[28,48],specif:[10,18,20,23,31,46],specifi:[10,24,45],sql:17,squash:2,standard:22,start:[2,11,25],statement:15,store:19,strang:10,stream:[7,37],structur:35,studio:49,submit:2,submod:6,subpars:[7,25,45],subvers:[28,48],summari:[14,15],support:[10,18],synchron:23,synopsi:[9,11,12,13,14,15,16,17,18,19,20,21],syntax:[26,47],system:24,t:10,tabl:[2,23,25,26,28,44,46,47],tag:[2,6,7,9,10,11,14,15,20,21,22,23,25,28,31,37,40,45],tag_kind_descript:31,tag_kind_separ:31,tag_output_filesep:31,tag_output_mod:31,tagbar:28,tagfield:11,tbw:7,tcl:40,term:45,test:[2,46,47],text:[7,10],than:11,time:[10,11],timeout:46,tinst:47,tip:[18,24],titl:2,tmain:47,todo:47,tokeninfo:7,tool:9,top:45,track:[25,28,48],translat:25,truncat:[11,31],type:[7,9,15,26],typeref:35,under:46,unicod:10,unit:46,univers:[5,10,22],up:[10,11,45],upper:45,us:[7,9,11,14,19,20,24,28,49],usag:[7,31],user:2,utf:23,util:9,valgrind:46,valid:46,variabl:[10,11,20,25],verilog:18,vi:[20,22],vim:[28,41],visual:49,want:10,we:3,weak:22,what:[2,10],when:10,which:10,who:3,why:10,wide:24,wildcard:23,window:49,write:[2,24,37,46],written:4,wrong:10,xref:32,xslt:42,yacc:45,you:2,your:2,zsh:10}})
\ No newline at end of file diff --git a/ctags/docs/testing.html b/ctags/docs/testing.html new file mode 100644 index 0000000..83b5d5f --- /dev/null +++ b/ctags/docs/testing.html @@ -0,0 +1,754 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Testing a parser — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Request for extending a parser (or Reporting a bug of parser)" href="reporting.html" /> + <link rel="prev" title="Testing ctags" href="tips.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="reporting.html" title="Request for extending a parser (or Reporting a bug of parser)" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="tips.html" title="Testing ctags" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Testing a parser</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="testing-a-parser"> +<span id="testing-parser"></span><h1>Testing a parser<a class="headerlink" href="#testing-a-parser" title="Permalink to this headline">¶</a></h1> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#units-test-facility" id="id1"><em>Units</em> test facility</a></p> +<ul> +<li><p><a class="reference internal" href="#how-to-write-a-test-case" id="id2">How to write a test case</a></p></li> +<li><p><a class="reference internal" href="#note-for-importing-a-test-case-from-test-directory" id="id3">Note for importing a test case from Test directory</a></p></li> +<li><p><a class="reference internal" href="#example-of-files" id="id4">Example of files</a></p></li> +<li><p><a class="reference internal" href="#how-to-run-unit-tests" id="id5">How to run unit tests</a></p></li> +<li><p><a class="reference internal" href="#example-of-running" id="id6">Example of running</a></p></li> +<li><p><a class="reference internal" href="#running-unit-tests-for-specific-languages" id="id7">Running unit tests for specific languages</a></p></li> +<li><p><a class="reference internal" href="#gathering-test-cases-for-known-bugs" id="id8">Gathering test cases for known bugs</a></p></li> +<li><p><a class="reference internal" href="#running-under-valgrind-and-timeout" id="id9">Running under valgrind and timeout</a></p></li> +<li><p><a class="reference internal" href="#categories" id="id10">Categories</a></p></li> +<li><p><a class="reference internal" href="#finding-minimal-bad-input" id="id11">Finding minimal bad input</a></p></li> +<li><p><a class="reference internal" href="#acknowledgments" id="id12">Acknowledgments</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#reviewing-the-result-of-units-test" id="id13">Reviewing the result of Units test</a></p></li> +<li><p><a class="reference internal" href="#semi-fuzz-fuzz-testing" id="id14">Semi-fuzz(<em>Fuzz</em>) testing</a></p></li> +<li><p><a class="reference internal" href="#noise-testing" id="id15"><em>Noise</em> testing</a></p></li> +<li><p><a class="reference internal" href="#chop-and-slap-testing" id="id16"><em>Chop</em> and <em>slap</em> testing</a></p></li> +<li><p><a class="reference internal" href="#input-validation-for-units" id="id17">Input validation for <em>Units</em></a></p> +<ul> +<li><p><a class="reference internal" href="#how-to-run-an-example-session-of-input-validation" id="id18">How to run an example session of input validation</a></p></li> +<li><p><a class="reference internal" href="#validator-file" id="id19"><em>validator</em> file</a></p></li> +<li><p><a class="reference internal" href="#validator-command" id="id20">validator command</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#testing-examples-in-language-specific-man-pages" id="id21">Testing examples in language specific man pages</a></p></li> +</ul> +</div> +<p>It is difficult for us to know syntax of all languages supported in ctags. Test +facility and test cases are quite important for maintaining ctags with limited +resources.</p> +<section id="units-test-facility"> +<span id="units"></span><h2><a class="toc-backref" href="#id1"><em>Units</em> test facility</a><a class="headerlink" href="#units-test-facility" title="Permalink to this headline">¶</a></h2> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<hr class="docutils" /> +<p><strong>Test facility</strong></p> +<p>Exuberant Ctags has a test facility. The test case were <em>Test</em> +directory. So Here I call it <em>Test</em>.</p> +<p>Main aim of the facility is detecting regression. All files under Test +directory are given as input for old and new version of ctags +commands. The output tags files of both versions are compared. If any +difference is found the check fails. <em>Test</em> expects the older ctags +binary to be correct.</p> +<p>This expectation is not always met. Consider that a parser for a new +language is added. You may want to add a sample source code for that +language to <em>Test</em>. An older ctags version is unable to generate a +tags file for that sample code, but the newer ctags version does. At +this point a difference is found and <em>Test</em> reports failure.</p> +<p><strong>Units facility</strong></p> +<p>The units test facility (<em>Units</em>) I describe here takes a different +approach. An input file and an expected output file are given by a +contributor of a language parser. The units test facility runs ctags +command with the input file and compares its output and the expected +output file. The expected output doesn’t depend on ctags.</p> +<p>If a contributor sends a patch which may improve a language parser, +and if a reviewer is not familiar with that language, s/he cannot +evaluate it.</p> +<p><em>Unit</em> test files, the pair of input file and expected output file may +be able to explain the intent of patch well; and may help the +reviewer.</p> +<section id="how-to-write-a-test-case"> +<h3><a class="toc-backref" href="#id2">How to write a test case</a><a class="headerlink" href="#how-to-write-a-test-case" title="Permalink to this headline">¶</a></h3> +<p>The test facility recognizes an input file and an expected +output file by patterns of file name. Each test case should +have its own directory under Units directory.</p> +<p><em>Units/TEST/input.*</em> <strong>requisite</strong></p> +<blockquote> +<div><p>Input file name must have a <em>input</em> as basename. <em>TEST</em> +part should explain the test case well.</p> +</div></blockquote> +<p><em>Units/TEST/input[-_][0-9].*</em> <em>Units/TEST/input[-_][0-9][-_]*.*</em> <strong>optional</strong></p> +<blockquote> +<div><p>Optional input file names. They are put next to <em>input.*</em> in +testing command line.</p> +</div></blockquote> +<p><em>Units/TEST/expected.tags</em> <strong>optional</strong></p> +<blockquote> +<div><p>Expected output file must have a name <em>expected.tags</em>. It +should be the same directory of the input file.</p> +<p>If this file is not given, the exit status of ctags process +is just checked; the output is ignored.</p> +<p>If you want to test etags output (specified with <code class="docutils literal notranslate"><span class="pre">-e</span></code> ), +Use <strong>.tags-e</strong> as suffix instead of <strong>.tags</strong>. +In such a case you don’t have to write <code class="docutils literal notranslate"><span class="pre">-e</span></code> to <code class="docutils literal notranslate"><span class="pre">args.ctags</span></code>. +The test facility sets <code class="docutils literal notranslate"><span class="pre">-e</span></code> automatically.</p> +<p>If you want to test cross reference output (specified with <code class="docutils literal notranslate"><span class="pre">-x</span></code> ), +Use <strong>.tags-x</strong> as suffix instead of <strong>.tags</strong>. +In such a case you don’t have to write <code class="docutils literal notranslate"><span class="pre">-x</span></code> to <code class="docutils literal notranslate"><span class="pre">args.ctags</span></code>. +The test facility sets <code class="docutils literal notranslate"><span class="pre">-x</span></code> automatically.</p> +<p>If you want to test json output (specified with <code class="docutils literal notranslate"><span class="pre">--output-format=json</span></code> ), +Use <strong>.tags-json</strong> as suffix instead of <strong>.tags</strong>. +In such a case you don’t have to write <code class="docutils literal notranslate"><span class="pre">--output-format=json</span></code> to <code class="docutils literal notranslate"><span class="pre">args.ctags</span></code>, +and add <code class="docutils literal notranslate"><span class="pre">json</span></code> to <code class="docutils literal notranslate"><span class="pre">features</span></code> as described below. +The test facility sets the option and the feature automatically.</p> +</div></blockquote> +<p><em>Units/TEST/args.ctags</em> <strong>optional</strong></p> +<blockquote> +<div><p><code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">-</span></code> is used as default optional argument when running a +unit test ctags. If you want to add more options, enumerate +options in <strong>args.ctags</strong> file.</p> +<p>Remember you have to put one option in one line; don’t +put multiple options to one line. Multiple options in +one line doesn’t work.</p> +</div></blockquote> +<p><em>Units/TEST/filter</em> <strong>optional</strong></p> +<blockquote> +<div><p>You can rearrange the output of ctags with this command +before comparing with <em>executed.tags</em>. +This command is invoked with no argument. The output +ctags is given via stdin. Rearrange data should be +written to stdout.</p> +</div></blockquote> +<p><em>Units/TEST/features</em> <strong>optional</strong></p> +<blockquote> +<div><p>If a unit test case requires special features of ctags, +enumerate them in this file line by line. If a target ctags +doesn’t have one of the features, the test is skipped.</p> +<p>If a file line is started with <code class="docutils literal notranslate"><span class="pre">!</span></code>, the effect is inverted; +if a target ctags has the feature specified with <code class="docutils literal notranslate"><span class="pre">!</span></code>, the +test is skipped.</p> +<p>All features built-in can be listed with passing +<code class="docutils literal notranslate"><span class="pre">--list-features</span></code> to ctags.</p> +</div></blockquote> +<p><em>Units/TEST/languages</em> <strong>optional</strong></p> +<blockquote> +<div><p>If a unit test case requires that language parsers are enabled/available, +enumerate them in this file line by line. If one of them is +disabled/unavailable, the test is skipped.</p> +<p>language parsers enabled/available can be checked with passing +<code class="docutils literal notranslate"><span class="pre">--list-languages</span></code> to ctags.</p> +</div></blockquote> +</section> +<section id="note-for-importing-a-test-case-from-test-directory"> +<h3><a class="toc-backref" href="#id3">Note for importing a test case from Test directory</a><a class="headerlink" href="#note-for-importing-a-test-case-from-test-directory" title="Permalink to this headline">¶</a></h3> +<p>I think all test cases under Test directory should be converted to +Units.</p> +<p>If you convert use following TEST name convention.</p> +<ul class="simple"> +<li><p>use <em>.t</em> instead of <em>.d</em> as suffix for the name</p></li> +</ul> +<p>Here is an example:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Test</span><span class="o">/</span><span class="n">simple</span><span class="o">.</span><span class="n">sh</span> +</pre></div> +</div> +<p>This should be:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Units</span><span class="o">/</span><span class="n">simple</span><span class="o">.</span><span class="n">sh</span><span class="o">.</span><span class="n">t</span> +</pre></div> +</div> +<p>With this name convention we can track which test case is converted or +not.</p> +</section> +<section id="example-of-files"> +<h3><a class="toc-backref" href="#id4">Example of files</a><a class="headerlink" href="#example-of-files" title="Permalink to this headline">¶</a></h3> +<p>See <a class="reference external" href="https://github.com/universal-ctags/ctags/tree/master/Units/parser-c.r/c-sample.d">Units/parser-c.r/c-sample.d</a>.</p> +</section> +<section id="how-to-run-unit-tests"> +<h3><a class="toc-backref" href="#id5">How to run unit tests</a><a class="headerlink" href="#how-to-run-unit-tests" title="Permalink to this headline">¶</a></h3> +<p><em>test</em> make target:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units +</pre></div> +</div> +<p>The result of unit tests is reported by lines. You can specify +test cases with <code class="docutils literal notranslate"><span class="pre">UNITS=</span></code>.</p> +<p>An example to run <em>vim-command.d</em> only:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units UNITS=vim-command +</pre></div> +</div> +<p>Another example to run <em>vim-command.d</em> and <em>parser-python.r/bug1856363.py.d</em>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units UNITS=vim-command,bug1856363.py +</pre></div> +</div> +<p>During testing <em>OUTPUT.tmp</em>, <em>EXPECTED.tmp</em> and <em>DIFF.tmp</em> files are +generated for each test case directory. These are removed when the +unit test is <strong>passed</strong>. If the result is <strong>FAILED</strong>, it is kept for +debugging. Following command line can clean up these generated files +at once:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make clean-units +</pre></div> +</div> +<p>Other than <strong>FAILED</strong> and <strong>passed</strong> two types of result are +defined.</p> +<p><strong>skipped</strong></p> +<blockquote> +<div><p>means running the test case is skipped in some reason.</p> +</div></blockquote> +<p><strong>failed (KNOWN bug)</strong></p> +<blockquote> +<div><p>means the result was failed but the failure is expected. +See “<a class="reference internal" href="#gathering-test"><span class="std std-ref">Gathering test cases for known bugs</span></a>”.</p> +</div></blockquote> +</section> +<section id="example-of-running"> +<h3><a class="toc-backref" href="#id6">Example of running</a><a class="headerlink" href="#example-of-running" title="Permalink to this headline">¶</a></h3> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units +Category: ROOT +------------------------------------------------------------------------- +Testing 1795612.js as JavaScript passed +Testing 1850914.js as JavaScript passed +Testing 1878155.js as JavaScript passed +Testing 1880687.js as JavaScript passed +Testing 2023624.js as JavaScript passed +Testing 3184782.sql as SQL passed +... +</pre></div> +</div> +</section> +<section id="running-unit-tests-for-specific-languages"> +<h3><a class="toc-backref" href="#id7">Running unit tests for specific languages</a><a class="headerlink" href="#running-unit-tests-for-specific-languages" title="Permalink to this headline">¶</a></h3> +<p>You can run only the tests for specific languages by setting +<code class="docutils literal notranslate"><span class="pre">LANGUAGES</span></code> to parsers as reported by +<code class="docutils literal notranslate"><span class="pre">ctags</span> <span class="pre">--list-languages</span></code>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">units</span> <span class="n">LANGUAGES</span><span class="o">=</span><span class="n">PHP</span><span class="p">,</span><span class="n">C</span> +</pre></div> +</div> +<p>Multiple languages can be selected using a comma separated list.</p> +</section> +<section id="gathering-test-cases-for-known-bugs"> +<span id="gathering-test"></span><h3><a class="toc-backref" href="#id8">Gathering test cases for known bugs</a><a class="headerlink" href="#gathering-test-cases-for-known-bugs" title="Permalink to this headline">¶</a></h3> +<p>When we meet a bug, it is an important development activity to make a small test +case that triggers the bug. +Even the bug cannot be fixed in soon, +the test case is an important result of work. Such result should +be merged to the source tree. However, we don’t love <strong>FAILED</strong> +message, too. What we should do?</p> +<p>In such a case, merge as usually but use <em>.b</em> as suffix for +the directory of test case instead of <em>.d</em>.</p> +<p><code class="docutils literal notranslate"><span class="pre">parser-autoconf.r/nested-block.ac.b/</span></code> is an example +of <code class="docutils literal notranslate"><span class="pre">.b``*</span></code> suffix usage.</p> +<p>When you run test.units target, you will see:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Testing</span> <span class="n">c</span><span class="o">-</span><span class="n">sample</span> <span class="k">as</span> <span class="n">C</span> <span class="n">passed</span> +<span class="n">Testing</span> <span class="n">css</span><span class="o">-</span><span class="n">singlequote</span><span class="o">-</span><span class="ow">in</span><span class="o">-</span><span class="n">comment</span> <span class="k">as</span> <span class="n">CSS</span> <span class="n">failed</span> <span class="p">(</span><span class="n">KNOWN</span> <span class="n">bug</span><span class="p">)</span> +<span class="n">Testing</span> <span class="n">ctags</span><span class="o">-</span><span class="n">simple</span> <span class="k">as</span> <span class="n">ctags</span> <span class="n">passed</span> +</pre></div> +</div> +<p>Suffix <em>.i</em> is a variant of <em>.b</em>. <em>.i</em> is for merging/gathering input +which lets ctags process enter an infinite loop. Different from <em>.b</em>, +test cases marked as <em>.i</em> are never executed. They are just skipped +but reported the skips:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Testing</span> <span class="n">ada</span><span class="o">-</span><span class="n">ads</span> <span class="k">as</span> <span class="n">Ada</span> <span class="n">passed</span> +<span class="n">Testing</span> <span class="n">ada</span><span class="o">-</span><span class="n">function</span> <span class="k">as</span> <span class="n">Ada</span> <span class="n">skipped</span> <span class="p">(</span><span class="n">may</span> <span class="n">cause</span> <span class="n">an</span> <span class="n">infinite</span> <span class="n">loop</span><span class="p">)</span> +<span class="n">Testing</span> <span class="n">ada</span><span class="o">-</span><span class="n">protected</span> <span class="k">as</span> <span class="n">Ada</span> <span class="n">passed</span> +<span class="o">...</span> + +<span class="n">Summary</span> <span class="p">(</span><span class="n">see</span> <span class="n">CMDLINE</span><span class="o">.</span><span class="n">tmp</span> <span class="n">to</span> <span class="n">reproduce</span> <span class="n">without</span> <span class="n">test</span> <span class="n">harness</span><span class="p">)</span> +<span class="o">------------------------------------------------------------</span> + <span class="c1">#passed: 347</span> + <span class="c1">#FIXED: 0</span> + <span class="c1">#FAILED (unexpected-exit-status): 0</span> + <span class="c1">#FAILED (unexpected-output): 0</span> + <span class="c1">#skipped (features): 0</span> + <span class="c1">#skipped (languages): 0</span> + <span class="c1">#skipped (infinite-loop): 1</span> + <span class="n">ada</span><span class="o">-</span><span class="n">protected</span> + <span class="o">...</span> +</pre></div> +</div> +</section> +<section id="running-under-valgrind-and-timeout"> +<h3><a class="toc-backref" href="#id9">Running under valgrind and timeout</a><a class="headerlink" href="#running-under-valgrind-and-timeout" title="Permalink to this headline">¶</a></h3> +<p>If <code class="docutils literal notranslate"><span class="pre">VG=1</span></code> is given, each test cases are run under valgrind. +If valgrind detects an error, it is reported as:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units VG=1 +Testing css-singlequote-in-comment as CSS failed (valgrind-error) +... +Summary (see CMDLINE.tmp to reproduce without test harness) +------------------------------------------------------------ +... +#valgrind-error: 1 + css-singlequote-in-comment +... +</pre></div> +</div> +<p>In this case the report of valgrind is recorded to +<code class="docutils literal notranslate"><span class="pre">Units/css-singlequote-in-comment/VALGRIND-CSS.tmp</span></code>.</p> +<p>NOTE: <code class="docutils literal notranslate"><span class="pre">/bin/bash</span></code> is needed to report the result. You can specify a shell +running test with SHELL macro like:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units VG=1 SHELL=/bin/bash +</pre></div> +</div> +<p>If <code class="docutils literal notranslate"><span class="pre">TIMEOUT=N</span></code> is given, each test cases are run under timeout +command. If ctags doesn’t stop in <code class="docutils literal notranslate"><span class="pre">N</span></code> second, it is stopped +by timeout command and reported as:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units TIMEOUT=1 +Testing css-singlequote-in-comment as CSS failed (TIMED OUT) +... +Summary (see CMDLINE.tmp to reproduce without test harness) +------------------------------------------------------------ +... +#TIMED-OUT: 1 + css-singlequote-in-comment +... +</pre></div> +</div> +<p>If <code class="docutils literal notranslate"><span class="pre">TIMEOUT=N</span></code> is given, <em>.i</em> test cases are run. They will be +reported as <em>TIMED-OUT</em>.</p> +</section> +<section id="categories"> +<h3><a class="toc-backref" href="#id10">Categories</a><a class="headerlink" href="#categories" title="Permalink to this headline">¶</a></h3> +<p>With <em>.r</em> suffix, you can put test cases under a sub directory +of <em>Units</em>. <code class="docutils literal notranslate"><span class="pre">Units/parser-ada.r</span></code> is an example. If <em>misc/units</em> +test harness, the sub directory is called a category. <code class="docutils literal notranslate"><span class="pre">parser-ada.r</span></code> +is the name category in the above example.</p> +<p><em>CATEGORIES</em> macro of make is for running units in specified categories. +Following command line is for running units in +<code class="docutils literal notranslate"><span class="pre">Units/parser-sh.r</span></code> and <code class="docutils literal notranslate"><span class="pre">Units/parser-ada.r</span></code>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units CATEGORIES='parser-sh,parser-ada' +</pre></div> +</div> +</section> +<section id="finding-minimal-bad-input"> +<h3><a class="toc-backref" href="#id11">Finding minimal bad input</a><a class="headerlink" href="#finding-minimal-bad-input" title="Permalink to this headline">¶</a></h3> +<p>When a test case is failed, the input causing <code class="docutils literal notranslate"><span class="pre">FAILED</span></code> result is +passed to <em>misc/units shrink</em>. <em>misc/units shrink</em> tries to make the +shortest input which makes ctags exits with non-zero status. The +result is reported to <code class="docutils literal notranslate"><span class="pre">Units/\*/SHRINK-${language}.tmp</span></code>. Maybe +useful to debug.</p> +</section> +<section id="acknowledgments"> +<h3><a class="toc-backref" href="#id12">Acknowledgments</a><a class="headerlink" href="#acknowledgments" title="Permalink to this headline">¶</a></h3> +<p>The file name rule is suggested by Maxime Coste <<a class="reference external" href="mailto:frrrwww%40gmail.com">frrrwww<span>@</span>gmail<span>.</span>com</a>>.</p> +</section> +</section> +<section id="reviewing-the-result-of-units-test"> +<h2><a class="toc-backref" href="#id13">Reviewing the result of Units test</a><a class="headerlink" href="#reviewing-the-result-of-units-test" title="Permalink to this headline">¶</a></h2> +<p>Try misc/review.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>misc/review --help +<span class="go">Usage:</span> +<span class="go"> misc/review help|--help|-h show this message</span> +<span class="go"> misc/review [list] [-b] list failed Units and Tmain</span> +<span class="go"> -b list .b (known bug) marked cases</span> +<span class="go"> misc/review inspect [-b] inspect difference interactively</span> +<span class="go"> -b inspect .b (known bug) marked cases</span> +<span class="gp">$</span> +</pre></div> +</div> +</section> +<section id="semi-fuzz-fuzz-testing"> +<h2><a class="toc-backref" href="#id14">Semi-fuzz(<em>Fuzz</em>) testing</a><a class="headerlink" href="#semi-fuzz-fuzz-testing" title="Permalink to this headline">¶</a></h2> +<p>Unexpected input can lead ctags to enter an infinite loop. The fuzz +target tries to identify these conditions by passing +semi-random (semi-broken) input to ctags.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make fuzz LANGUAGES=LANG1[,LANG2,...] +</pre></div> +</div> +<p>With this command line, ctags is run for random variations of all test +inputs under <em>Units/*/input.*</em> of languages defined by <code class="docutils literal notranslate"><span class="pre">LANGUAGES</span></code> +macro variable. In this target, the output of ctags is ignored and +only the exit status is analyzed. The ctags binary is also run under +timeout command, such that if an infinite loop is found it will exit +with a non-zero status. The timeout will be reported as following:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">timeout</span> <span class="n">C</span><span class="p">]</span> <span class="n">Units</span><span class="o">/</span><span class="n">test</span><span class="o">.</span><span class="n">vhd</span><span class="o">.</span><span class="n">t</span><span class="o">/</span><span class="nb">input</span><span class="o">.</span><span class="n">vhd</span> +</pre></div> +</div> +<p>This means that if C parser doesn’t stop within N seconds when +<em>Units/test.vhd.t/input.vhd</em> is given as an input, timeout will +interrupt ctags. The default duration can be changed using +<code class="docutils literal notranslate"><span class="pre">TIMEOUT=N</span></code> argument in <em>make</em> command. If there is no timeout but +the exit status is non-zero, the target reports it as following:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">unexpected</span><span class="o">-</span><span class="n">status</span><span class="p">(</span><span class="n">N</span><span class="p">)</span> <span class="n">C</span><span class="p">]</span> <span class="n">Units</span><span class="o">/</span><span class="n">test</span><span class="o">.</span><span class="n">vhd</span><span class="o">.</span><span class="n">t</span><span class="o">/</span><span class="nb">input</span><span class="o">.</span><span class="n">vhd</span> +</pre></div> +</div> +<p>The list of parsers which can be used as a value for <code class="docutils literal notranslate"><span class="pre">LANGUAGES</span></code> can +be obtained with following command line</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ctags --list-languages +</pre></div> +</div> +<p>Besides <code class="docutils literal notranslate"><span class="pre">LANGUAGES</span></code> and <code class="docutils literal notranslate"><span class="pre">TIMEOUT</span></code>, fuzz target also takes the +following parameters:</p> +<blockquote> +<div><p><code class="docutils literal notranslate"><span class="pre">VG=1</span></code></p> +<blockquote> +<div><p>Run ctags under valgrind. If valgrind finds a memory +error it is reported as:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">valgrind</span><span class="o">-</span><span class="n">error</span> <span class="n">Verilog</span><span class="p">]</span> <span class="n">Units</span><span class="o">/</span><span class="n">array_spec</span><span class="o">.</span><span class="n">f90</span><span class="o">.</span><span class="n">t</span><span class="o">/</span><span class="nb">input</span><span class="o">.</span><span class="n">f90</span> +</pre></div> +</div> +<p>The valgrind report is recorded at +<code class="docutils literal notranslate"><span class="pre">Units/\*/VALGRIND-${language}.tmp</span></code>.</p> +</div></blockquote> +</div></blockquote> +<p>As the same as units target, this semi-fuzz test target also calls +<em>misc/units shrink</em> when a test case is failed. See “<em>Units</em> test facility” +about the shrunk result.</p> +</section> +<section id="noise-testing"> +<h2><a class="toc-backref" href="#id15"><em>Noise</em> testing</a><a class="headerlink" href="#noise-testing" title="Permalink to this headline">¶</a></h2> +<p>After enjoying developing Semi-fuzz testing, I’m looking for a more unfair +approach. Run</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make noise LANGUAGES=LANG1[,LANG2,...] +</pre></div> +</div> +<p>The noise target generates test cases by inserting or deleting one +character to the test cases of <em>Units</em>.</p> +<p>It takes a long time, even without <code class="docutils literal notranslate"><span class="pre">VG=1</span></code>, so this cannot be run +under Travis CI. However, it is a good idea to run it locally.</p> +</section> +<section id="chop-and-slap-testing"> +<h2><a class="toc-backref" href="#id16"><em>Chop</em> and <em>slap</em> testing</a><a class="headerlink" href="#chop-and-slap-testing" title="Permalink to this headline">¶</a></h2> +<p>After reviving many bug reports, we recognized some of them spot +unexpected EOF. The chop target was developed based on this recognition.</p> +<p>The chop target generates many input files from an existing input file +under <em>Units</em> by truncating the existing input file at variety file +positions.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make chop LANGUAGES=LANG1[,LANG2,...] +</pre></div> +</div> +<p>It takes a long time, especially with <code class="docutils literal notranslate"><span class="pre">VG=1</span></code>, so this cannot be run +under Travis CI. However, it is a good idea to run it locally.</p> +<p>slap target is derived from chop target. While chop target truncates +the existing input files from tail, the slap target does the same +from head.</p> +</section> +<section id="input-validation-for-units"> +<span id="input-validation"></span><h2><a class="toc-backref" href="#id17">Input validation for <em>Units</em></a><a class="headerlink" href="#input-validation-for-units" title="Permalink to this headline">¶</a></h2> +<p>We have to maintain parsers for languages that we don’t know well. We +don’t have enough time to learn the languages.</p> +<p><em>Units</em> test cases help us not introduce wrong changes to a parser.</p> +<p>However, there is still an issue; a developer who doesn’t know a +target language well may write a broken test input file for the +language. Here comes “Input validation.”</p> +<section id="how-to-run-an-example-session-of-input-validation"> +<h3><a class="toc-backref" href="#id18">How to run an example session of input validation</a><a class="headerlink" href="#how-to-run-an-example-session-of-input-validation" title="Permalink to this headline">¶</a></h3> +<p>You can validate the test input files of <em>Units</em> with <em>validate-input</em> +make target if a validator or a language is defined.</p> +<p>Here is an example validating an input file for JSON.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make validate-input <span class="nv">VALIDATORS</span><span class="o">=</span>jq +<span class="go">...</span> +<span class="go">Category: ROOT</span> +<span class="go">------------------------------------------------------------</span> +<span class="go">simple-json.d/input.json with jq valid</span> + +<span class="go">Summary</span> +<span class="go">------------------------------------------------------------</span> +<span class="gp"> #</span>valid: <span class="m">1</span> +<span class="gp"> #</span>invalid: <span class="m">0</span> +<span class="gp"> #</span>skipped <span class="o">(</span>known invalidation<span class="o">)</span> <span class="m">0</span> +<span class="gp"> #</span>skipped <span class="o">(</span>validator unavailable<span class="o">)</span> <span class="m">0</span> +</pre></div> +</div> +<p>This example shows validating <em>simple-json.d/input.json</em> as an input +file with <em>jq</em> validator. With VALIDATORS variable passed via +command-line, you can specify validators to run. Multiple validators +can be specified using a comma-separated list. If you don’t give +VALIDATORS, the make target tries to use all available validators.</p> +<p>The meanings of “valid” and “invalid” in “Summary” are apparent. In +two cases, the target skips validating input files:</p> +<p>#skipped (known invalidation)</p> +<blockquote> +<div><p>A test case specifies KNOWN-INVALIDATION in its <em>validator</em> file.</p> +</div></blockquote> +<p>#skipped (validator unavailable)</p> +<blockquote> +<div><p>A command for a validator is not available.</p> +</div></blockquote> +</section> +<section id="validator-file"> +<h3><a class="toc-backref" href="#id19"><em>validator</em> file</a><a class="headerlink" href="#validator-file" title="Permalink to this headline">¶</a></h3> +<p><em>validator</em> file in a <em>Units</em> test directory specifies which +validator the make target should use.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat Units/simple-json.d/validator +<span class="go">jq</span> +</pre></div> +</div> +<p>If you put <em>validator</em> file to a category directory (a directory +having <em>.r</em> suffix), the make target uses the validator specified in +the file as default. The default validator can be overridden with a +<em>validator</em> file in a subdirectory.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>cat Units/parser-puppetManifest.r/validator +<span class="go">puppet</span> +<span class="gp"># </span>cat Units/parser-puppetManifest.r/puppet-append.d/validator +<span class="go">KNOWN-INVALIDATION</span> +</pre></div> +</div> +<p>In the example, the make target uses <em>puppet</em> validator for validating +the most of all input files under <em>Units/parser-puppetManifest.r</em> +directory. An exception is an input file under +<em>Units/parser-puppetManifest.r/puppet-append.d</em> directory. The +directory has its specific <em>validator</em> file.</p> +<p>If a <em>Unit</em> test case doesn’t have <em>expected.tags</em> file, the make +target doesn’t run the validator on the file even if a default +validator is given in its category directory.</p> +<p>If a <em>Unit</em> test case specifies KNOWN-INVALIDATION in its <em>validator</em> +file, the make target just increments “#skipped (known invalidation)” +counter. The target reports the counter at the end of execution.</p> +</section> +<section id="validator-command"> +<h3><a class="toc-backref" href="#id20">validator command</a><a class="headerlink" href="#validator-command" title="Permalink to this headline">¶</a></h3> +<p>A validator specified in a <em>validator</em> file is a command file put +under <em>misc/validators</em> directory. The command must have “validator-” +as prefix in its file name. For an example, +<em>misc/validators/validator-jq</em> is the command for “jq”.</p> +<p>The command file must be an executable. <em>validate-input</em> make target +runs the command in two ways.</p> +<p><em>is_runnable</em> method</p> +<blockquote> +<div><p>Before running the command as a validator, the target runs +the command with “is_runnable” as the first argument. +A validator command can let the target know whether the +validator command is runnable or not with exit status. +0 means ready to run. Non-zero means not ready to run.</p> +<p>The make target never runs the validator command for +validation purpose if the exit status is non-zero.</p> +<p>For an example, <em>misc/validators/validator-jq</em> command uses <em>jq</em> +command as its backend. If <em>jq</em> command is not available on a +system, <em>validator-jq</em> can do nothing. If such case, +<em>is_runnable</em> method of <em>validator-jq</em> command should exit with +non-zero value.</p> +</div></blockquote> +<p><em>validate</em> method</p> +<blockquote> +<div><p>The make target runs the command with “validate* and an input +file name for validating the input file. The command exits +non-zero if the input file contains invalid syntax. This method +will never run if <em>is_runnable</em> method of the command exits with +non-zero.</p> +</div></blockquote> +</section> +</section> +<section id="testing-examples-in-language-specific-man-pages"> +<span id="man-test"></span><h2><a class="toc-backref" href="#id21">Testing examples in language specific man pages</a><a class="headerlink" href="#testing-examples-in-language-specific-man-pages" title="Permalink to this headline">¶</a></h2> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<hr class="docutils" /> +<p><cite>man-test</cite> is a target for testing the examples in the language +specific man pages (<code class="docutils literal notranslate"><span class="pre">man/ctags-lang-<LANG>.7.rst.in</span></code>). The command +line for running the target is:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make man-test +</pre></div> +</div> +<p>An example for testing must have following form:</p> +<div class="highlight-ReStructuredText notranslate"><div class="highlight"><pre><span></span>"input.<EXT>" + +<span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> <span class="k"><LANG></span> + +<span class="s"> <INPUT LINES></span> + +"output.tags" +with "<OPTIONS FOR CTAGS>" + +<span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> tags + + <TAGS OUTPUT LINES> +</pre></div> +</div> +<p>The man-test target recognizes the form and does the same as +the following shell code for each example in the man page:</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">echo</span> <INPUT LINES> > input.<EXT> +<span class="gp">$ </span><span class="nb">echo</span> <TAGS OUTPUT LINES> > output.tags +<span class="gp">$ </span>ctags <OPTIONS FOR CTAGS> > actual.tags +<span class="gp">$ </span>diff output.tags actual.tags +</pre></div> +</div> +<p>A backslash character at the end of <code class="docutils literal notranslate"><span class="pre"><INPUT</span> <span class="pre">LINES></span></code> or +<code class="docutils literal notranslate"><span class="pre"><TAGS</span> <span class="pre">OUTPUT</span> <span class="pre">LINES></span></code> represents the continuation of lines; +a subsequent newline is ignored.</p> +<div class="highlight-ReStructuredText notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> <span class="k">tags</span> + +<span class="s"> very long\</span> +<span class="s"> line</span> +</pre></div> +</div> +<p>is read as:</p> +<div class="highlight-ReStructuredText notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> tags + + very long line +</pre></div> +</div> +<p>Here is an example of a test case taken from +<code class="docutils literal notranslate"><span class="pre">ctags-lang-python.7.rst.in</span></code>:</p> +<div class="highlight-ReStructuredText notranslate"><div class="highlight"><pre><span></span>"input.py" + +<span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> <span class="k">Python</span> + + <span class="kn">import</span> <span class="nn">X0</span> + +"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK input.py" + +<span class="p">..</span> <span class="ow">code-block</span><span class="p">::</span> tags + + X0 input.py /^import X0$/;" kind:module roles:imported +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">man-test</span></code> returns 0 if the all test cases in the all language +specific man pages are passed.</p> +<p>Here is an example output of the man-test target.</p> +<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make man-test +<span class="go"> RUN man-test</span> +<span class="gp"># </span>Run <span class="nb">test</span> cases <span class="k">in</span> ./man/ctags-lang-julia.7.rst.in +<span class="go">```</span> +<span class="go">./man/ctags-lang-julia.7.rst.in[0]:75...passed</span> +<span class="go">./man/ctags-lang-julia.7.rst.in[1]:93...passed</span> +<span class="go">```</span> +<span class="gp"># </span>Run <span class="nb">test</span> cases <span class="k">in</span> ./man/ctags-lang-python.7.rst.in +<span class="go">```</span> +<span class="go">./man/ctags-lang-python.7.rst.in[0]:116...passed</span> +<span class="go">./man/ctags-lang-python.7.rst.in[1]:133...passed</span> +<span class="go">./man/ctags-lang-python.7.rst.in[2]:154...passed</span> +<span class="go">./man/ctags-lang-python.7.rst.in[3]:170...passed</span> +<span class="go">./man/ctags-lang-python.7.rst.in[4]:187...passed</span> +<span class="go">./man/ctags-lang-python.7.rst.in[5]:230...passed</span> +<span class="go">```</span> +<span class="gp"># </span>Run <span class="nb">test</span> cases <span class="k">in</span> ./man/ctags-lang-verilog.7.rst.in +<span class="go">```</span> +<span class="go">./man/ctags-lang-verilog.7.rst.in[0]:51...passed</span> +<span class="go">```</span> +<span class="go">OK</span> +</pre></div> +</div> +<p>NOTE: keep examples in the man pages simple. If you want to test ctags +complicated (and or subtle) input, use the units target. The main +purpose of the examples is for explaining the parser.</p> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Testing a parser</a><ul> +<li><a class="reference internal" href="#units-test-facility"><em>Units</em> test facility</a><ul> +<li><a class="reference internal" href="#how-to-write-a-test-case">How to write a test case</a></li> +<li><a class="reference internal" href="#note-for-importing-a-test-case-from-test-directory">Note for importing a test case from Test directory</a></li> +<li><a class="reference internal" href="#example-of-files">Example of files</a></li> +<li><a class="reference internal" href="#how-to-run-unit-tests">How to run unit tests</a></li> +<li><a class="reference internal" href="#example-of-running">Example of running</a></li> +<li><a class="reference internal" href="#running-unit-tests-for-specific-languages">Running unit tests for specific languages</a></li> +<li><a class="reference internal" href="#gathering-test-cases-for-known-bugs">Gathering test cases for known bugs</a></li> +<li><a class="reference internal" href="#running-under-valgrind-and-timeout">Running under valgrind and timeout</a></li> +<li><a class="reference internal" href="#categories">Categories</a></li> +<li><a class="reference internal" href="#finding-minimal-bad-input">Finding minimal bad input</a></li> +<li><a class="reference internal" href="#acknowledgments">Acknowledgments</a></li> +</ul> +</li> +<li><a class="reference internal" href="#reviewing-the-result-of-units-test">Reviewing the result of Units test</a></li> +<li><a class="reference internal" href="#semi-fuzz-fuzz-testing">Semi-fuzz(<em>Fuzz</em>) testing</a></li> +<li><a class="reference internal" href="#noise-testing"><em>Noise</em> testing</a></li> +<li><a class="reference internal" href="#chop-and-slap-testing"><em>Chop</em> and <em>slap</em> testing</a></li> +<li><a class="reference internal" href="#input-validation-for-units">Input validation for <em>Units</em></a><ul> +<li><a class="reference internal" href="#how-to-run-an-example-session-of-input-validation">How to run an example session of input validation</a></li> +<li><a class="reference internal" href="#validator-file"><em>validator</em> file</a></li> +<li><a class="reference internal" href="#validator-command">validator command</a></li> +</ul> +</li> +<li><a class="reference internal" href="#testing-examples-in-language-specific-man-pages">Testing examples in language specific man pages</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="tips.html" + title="previous chapter">Testing ctags</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="reporting.html" + title="next chapter">Request for extending a parser (or Reporting a bug of parser)</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="reporting.html" title="Request for extending a parser (or Reporting a bug of parser)" + >next</a> |</li> + <li class="right" > + <a href="tips.html" title="Testing ctags" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Testing a parser</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/tips.html b/ctags/docs/tips.html new file mode 100644 index 0000000..f394313 --- /dev/null +++ b/ctags/docs/tips.html @@ -0,0 +1,247 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Testing ctags — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Testing a parser" href="testing.html" /> + <link rel="prev" title="Input text stream" href="internal.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="testing.html" title="Testing a parser" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="internal.html" title="Input text stream" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Testing ctags</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="testing-ctags"> +<span id="id1"></span><h1>Testing ctags<a class="headerlink" href="#testing-ctags" title="Permalink to this headline">¶</a></h1> +<div class="contents local topic" id="table-of-contents"> +<p class="topic-title"><cite>Table of contents</cite></p> +<ul class="simple"> +<li><p><a class="reference internal" href="#tmain-a-facility-for-testing-main-part" id="id3"><em>Tmain</em>: a facility for testing main part</a></p></li> +<li><p><a class="reference internal" href="#tinst-installation-test" id="id4"><em>Tinst</em>: installation test</a></p></li> +<li><p><a class="reference internal" href="#fussy-syntax-checking" id="id5">Fussy syntax checking</a></p></li> +<li><p><a class="reference internal" href="#finding-performance-bottleneck" id="id6">Finding performance bottleneck</a></p></li> +<li><p><a class="reference internal" href="#checking-coverage" id="id7">Checking coverage</a></p></li> +<li><p><a class="reference internal" href="#running-cppcheck" id="id8">Running cppcheck</a></p></li> +</ul> +</div> +<section id="tmain-a-facility-for-testing-main-part"> +<h2><a class="toc-backref" href="#id3"><em>Tmain</em>: a facility for testing main part</a><a class="headerlink" href="#tmain-a-facility-for-testing-main-part" title="Permalink to this headline">¶</a></h2> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<hr class="docutils" /> +<p><em>Tmain</em> is introduced to test the area where <em>Units</em> +does not cover well.</p> +<p><em>Units</em> works fine for testing parsers. However, it +assumes something input is given to ctags command, +and a <cite>tags</cite> file is generated from ctags command.</p> +<p>Other aspects cannot be tested. Such areas are files +and directories layout after installation, standard +error output, exit status, etc.</p> +<p>You can run test cases with following command line:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make tmain +</pre></div> +</div> +<p><em>Tmain</em> is still under development so I will not write +the details here.</p> +<p>To write a test case, see files under <cite>Tmain/tmain-example.d</cite>. +In the example, <em>Tmain</em> does:</p> +<ol class="arabic simple"> +<li><p>runs new subshell and change the working directory to <cite>Tmain/tmain-example.d</cite>,</p></li> +<li><p>runs <cite>run.sh</cite> with <cite>bash</cite>,</p></li> +<li><p>captures stdout, stderr and exit status, and</p></li> +<li><p>compares them with <cite>stdout-expected.txt</cite>, <cite>stderr-expected.txt</cite>, +and <cite>exit-expected.txt</cite>.</p></li> +<li><p>compares it with <cite>tags-expected.txt</cite> if run.sh generates <cite>tags</cite> file.</p></li> +</ol> +<p><cite>run.sh</cite> is run with following 3 arguments:</p> +<ol class="arabic simple"> +<li><p>the path for the target ctags</p></li> +<li><p>the path for <cite>builddir</cite> directory</p></li> +<li><p>the path for the target readtags</p></li> +</ol> +<p>The path for readtags is not reliable; readtags command is not +available if --disable-readcmd was given in configure time. A case, +testing the behavior of readtags, must verify the command existence +with <cite>test -x $3</cite> before going into the main part of the test.</p> +<p>When comparing <cite>tags</cite> file with <cite>tags-expected.txt</cite>, you +must specify the path of <cite>tags</cite> explicitly with -o option +in ctags command line like:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>CTAGS=$1 +BUILDDIR=$2 +${CTAGS} ... -o $BUILDDIR/tags ... +</pre></div> +</div> +<p>This makes it possible to keep the original source directory clean.</p> +<p>See also <cite>tmain_run</cite> and <cite>tmain_compare</cite> functions in <cite>misc/units</cite>.</p> +<p>If run.sh exits with code 77, the test case is skipped. +The output to stdout is captured and printed as the reason +of skipping.</p> +<section id="todo"> +<h3>TODO<a class="headerlink" href="#todo" title="Permalink to this headline">¶</a></h3> +<ul class="simple"> +<li><p>Run under valgrind</p></li> +</ul> +</section> +</section> +<section id="tinst-installation-test"> +<h2><a class="toc-backref" href="#id4"><em>Tinst</em>: installation test</a><a class="headerlink" href="#tinst-installation-test" title="Permalink to this headline">¶</a></h2> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Masatake YAMATO <<a class="reference external" href="mailto:yamato%40redhat.com">yamato<span>@</span>redhat<span>.</span>com</a>></p> +</dd> +</dl> +<hr class="docutils" /> +<p>tinst target is for testing the result of <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code>.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make tinst +</pre></div> +</div> +</section> +<section id="fussy-syntax-checking"> +<h2><a class="toc-backref" href="#id5">Fussy syntax checking</a><a class="headerlink" href="#fussy-syntax-checking" title="Permalink to this headline">¶</a></h2> +<p>If <code class="docutils literal notranslate"><span class="pre">-Wall</span></code> of gcc is not enough, you may be interested in this.</p> +<p>You can change C compiler warning options with ‘WARNING_CFLAGS’ +configure arg-var option.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./configure WARNING_CFLAGS='-Wall -Wextra' +</pre></div> +</div> +<p>If configure option ‘--with-sparse-cgcc’ is specified, +cgcc is used as CC. cgcc is part of <a class="reference external" href="https://sparse.docs.kernel.org/en/latest/">Sparse, Semantic Parser for C</a>. +It is used in development of Linux kernel for finding programming error. +cgcc acts as a c compiler but more fussy. ‘-Wsparse-all’ is used as +default option passed to cgcc but you can change with ‘CGCC_CFLAGS’ +configure arg-var option.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./configure --with-sparse-cgcc [CGCC_CFLAGS='-Wsparse-all'] +</pre></div> +</div> +</section> +<section id="finding-performance-bottleneck"> +<h2><a class="toc-backref" href="#id6">Finding performance bottleneck</a><a class="headerlink" href="#finding-performance-bottleneck" title="Permalink to this headline">¶</a></h2> +<p>See <a class="reference external" href="https://wiki.geany.org/howtos/profiling/gperftools">Profiling with gperftools</a> and <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/383">#383</a>.</p> +</section> +<section id="checking-coverage"> +<h2><a class="toc-backref" href="#id7">Checking coverage</a><a class="headerlink" href="#checking-coverage" title="Permalink to this headline">¶</a></h2> +<p>Before starting coverage measuring, you need to specify +‘--enable-coverage-gcov’ configure option.</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./configure --enable-coverage-gcov +</pre></div> +</div> +<p>After doing <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean</span></code>, you can build coverage measuring ready +ctags by <code class="docutils literal notranslate"><span class="pre">make</span></code>. At this time <em>*.gcno</em> files are generated +by the compiler. <em>*.gcno</em> files can be removed with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean</span></code>.</p> +<p>After building ctags, you can run run-gcov target. When running +<em>*.gcda</em> files. The target runs ctags with all input files under +<em>Units/**/input.*</em>; and call <code class="docutils literal notranslate"><span class="pre">gcov</span></code>. Human readable result is +printed. The detail can be shown in <em>*.gcov</em>. files. <em>*.gcda</em> files +and <em>*.gcov</em> files can be removed with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean-gcov</span></code>.</p> +</section> +<section id="running-cppcheck"> +<h2><a class="toc-backref" href="#id8">Running cppcheck</a><a class="headerlink" href="#running-cppcheck" title="Permalink to this headline">¶</a></h2> +<p><a class="reference external" href="http://cppcheck.sourceforge.net/">cppcheck</a> is a tool for static C/C++ code +analysis.</p> +<p>To run it do as following after install cppcheck:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make cppcheck +</pre></div> +</div> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Testing ctags</a><ul> +<li><a class="reference internal" href="#tmain-a-facility-for-testing-main-part"><em>Tmain</em>: a facility for testing main part</a><ul> +<li><a class="reference internal" href="#todo">TODO</a></li> +</ul> +</li> +<li><a class="reference internal" href="#tinst-installation-test"><em>Tinst</em>: installation test</a></li> +<li><a class="reference internal" href="#fussy-syntax-checking">Fussy syntax checking</a></li> +<li><a class="reference internal" href="#finding-performance-bottleneck">Finding performance bottleneck</a></li> +<li><a class="reference internal" href="#checking-coverage">Checking coverage</a></li> +<li><a class="reference internal" href="#running-cppcheck">Running cppcheck</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="internal.html" + title="previous chapter">Input text stream</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="testing.html" + title="next chapter">Testing a parser</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="testing.html" title="Testing a parser" + >next</a> |</li> + <li class="right" > + <a href="internal.html" title="Input text stream" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Testing ctags</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/tracking.html b/ctags/docs/tracking.html new file mode 100644 index 0000000..6dcd884 --- /dev/null +++ b/ctags/docs/tracking.html @@ -0,0 +1,605 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Tracking other projects — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Tracking other projects</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="tracking-other-projects"> +<h1>Tracking other projects<a class="headerlink" href="#tracking-other-projects" title="Permalink to this headline">¶</a></h1> +<p>This is working note for tracking activities other projects, +especially activity at Exuberant Ctags.</p> +<p>I(Masatake YAMATO) consider tracking activities as the first class +fruits of this project.</p> +<section id="exuberant-ctags"> +<h2>Exuberant Ctags<a class="headerlink" href="#exuberant-ctags" title="Permalink to this headline">¶</a></h2> +<section id="subversion"> +<h3>subversion<a class="headerlink" href="#subversion" title="Permalink to this headline">¶</a></h3> +<ul> +<li><p>status</p> +<p>Revisions up to <r815> are merged except:</p> +<blockquote> +<div><p>NOTHING HERE NOW</p> +</div></blockquote> +<p>(Mon Sep 22 12:41:32 2014 by yamato)</p> +</li> +<li><p>howto</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">svn</span><span class="o">></span> +<span class="o">=></span> <span class="o"><</span><span class="n">git</span><span class="p">:</span> <span class="n">local</span> <span class="n">Universal</span> <span class="n">Ctags</span> <span class="n">repo</span><span class="o">></span> +<span class="o">=></span> <span class="o"><</span><span class="n">git</span><span class="p">:</span> <span class="n">local</span> <span class="n">Universal</span> <span class="n">Ctags</span> <span class="n">repo</span><span class="o">></span> +</pre></div> +</div> +<ol class="arabic"> +<li><p>prepare your own Universal Ctags repo: a local git repo cloned from github. +You may know how to do it :)</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git clone https://github.com/universal-ctags/ctags.git +</pre></div> +</div> +</li> +<li><p>prepare Exuberant Ctags SVN repo: a local git repo clone from Exuberant Ctags svn tree.</p></li> +</ol> +<blockquote> +<div><p>The original clone is already part of Exuberant Ctags tree.</p> +<p>To initialize your git repository with the required subversion information do</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git svn init https://svn.code.sf.net/p/ctags/code/trunk +$ git update-ref refs/remotes/git-svn refs/remotes/origin/sourceforge +</pre></div> +</div> +<p>and then</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git svn fetch +$ git svn rebase +</pre></div> +</div> +<p>to get the latest changes and reflect it to the local copy.</p> +</div></blockquote> +<ol class="arabic simple" start="3"> +<li><p>merge</p></li> +</ol> +<blockquote> +<div><p>TODO</p> +</div></blockquote> +<ol class="arabic" start="4"> +<li><p>cherry-pick</p> +<p>4.1. Make a branch at local Universal Ctags repo and switch to it.</p> +<p>4.2. Do cherry-pick like:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git cherry-pick -s -x c81a8ce +</pre></div> +</div> +<p>You can find commit id on the another terminal +<git: local Universal Ctags repo>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git log +</pre></div> +</div> +<p>or</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git log --oneline +</pre></div> +</div> +<p>If conflicts are occurred in cherry-picking, you can +abort/reset cherry-picking with:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ git reset --hard +</pre></div> +</div> +<dl class="simple"> +<dt><git: local Universal Ctags repo></dt><dd><p>at the branch for picking.</p> +</dd> +</dl> +</li> +</ol> +</li> +</ul> +</section> +<section id="bugs"> +<h3>bugs<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h3> +<blockquote> +<div><p><367> C++11 override makes a C++ member function declaration ignored</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d4fcbdd</span> +<span class="c1">#413</span> +<span class="c1">#405</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><366> --options=.ctags doesn’t work under Windows</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">15</span><span class="n">cedc6c94e95110cc319b5cdad7807caf3db1f4</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><365> Selecting Python kinds is broken</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">4</span><span class="n">a95e4a55f67230fc4eee91ffb31c18c422df6d3</span> +</pre></div> +</div> +</li> +<li><p>discussed at #324.</p></li> +</ul> +</div></blockquote> +<p><364> Ruby method on self is missing the trailing ? in the generated tag name</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d9ba5df9f4d54ddaa511bd5440a1a3decaa2dc28</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><363> Invalid C input file causes invalid read / heap overflow</p> +<blockquote> +<div><ul> +<li><p>it is not reproduced.</p></li> +<li><p>the test case is imported as parser-c.r/c-heapoverflow-sh-bug-363.d:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ make units UNITS=c-heapoverflow-sh-bug-363 VG=1 +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><361> Invalid C input file causes invalid read / heap overflow</p> +<blockquote> +<div><ul class="simple"> +<li><p>it is not reproduced.</p></li> +</ul> +</div></blockquote> +<p><360> Fails to parse annotation’s fields with default value</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">682</span><span class="n">a7f3b180c27c1196f8a1ae662d6e8ad142939</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><358> Vim parser: Segmentation fault when reading empty vim file</p> +<blockquote> +<div><ul> +<li><p>directly contributed by the original author of bug report and patch:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">e0f854f0100e7a3cb8b959a23d6036e43f6b6c85</span> +</pre></div> +</div> +</li> +<li><p>it is fixed in sf, too:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">5</span><span class="n">d774f6022a1af71fa5866994699aafce0253085</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><356> [python] mistakes module level attribute for class level attribute in module level if</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ab91e6e1ae84b80870a1e8712fc7f3133e4b5542</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><355> Error when parsing empty file (OCaml)</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">02</span><span class="n">ec2066b5be6b129eba49685bd0b17fef4acfa</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><341> Lua: “function f ()” whitespace</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">8590</span><span class="n">bbef5fcf70f6747d509808c29bf84342cd0d</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><341> Introducing ctags.conf.d</p> +<blockquote> +<div><ul> +<li><p>merged the improved version:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">216880</span><span class="n">c5287e0421d9c49898d983144db61c83aa</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><271> regex callback is broken; <320> [PATCH] fix regex callback match count</p> +<blockquote> +<div><ul> +<li><p>merged patch (with updated bug number):</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">a12b3a24b62d6535a968e076675f68bac9ad32ba</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><177> Lua: “function” results in function tag (includes patch)</p> +<blockquote> +<div><ul> +<li><p>fixed in:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">5606</span><span class="n">f3f711afeac74587a249650a5f7b416f19be</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +</div></blockquote> +</section> +</section> +<section id="id1"> +<h2><a class="reference external" href="https://sourceforge.net/p/ctags/patches/%d">patches</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2> +<p>Tracking the tickets in patch tracker is quite fruitful. +Patches are always there. So it is easy to evaluate the value:)</p> +<blockquote> +<div><p>[(<]TICKET#[>)] TITLE</p> +<blockquote> +<div><ul class="simple"> +<li><p>STATUS</p> +<ul> +<li><p>MORE STATUS</p></li> +</ul> +</li> +</ul> +</div></blockquote> +<p><TICKET#></p> +<blockquote> +<div><p>means the ticket is closed from the view of Exuberant Ctags tree +developers. We don’t have to take time for this ticket.</p> +</div></blockquote> +<p>(TICKET#)</p> +<blockquote> +<div><p>means the ticket is still opened from the view of Exuberant Ctags +tree developers. We don’t have to take time for this ticket.</p> +</div></blockquote> +</div></blockquote> +<hr class="docutils" /> +<blockquote> +<div><p><85> Add --encoding option to make utf-8 encoded tags file</p> +<blockquote> +<div><ul> +<li><p>contributed by the original author:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">b3f670c7c4a3c3570b8d2d82756735586aafc0cb</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><84> C++11 new using semantics</p> +<blockquote> +<div><ul> +<li><p>solved by another implementation:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">c93e3bfa05b70d7fbc2539454c957eb2169e16b3</span> +<span class="mi">502355489</span><span class="n">b1ba748b1a235641bbd512ba6da315e</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><83> New full non-regex PHP parser</p> +<blockquote> +<div><ul class="simple"> +<li><p>contributed by the original author</p></li> +</ul> +</div></blockquote> +<p><82> Support for comments in .ctags files</p> +<blockquote> +<div><ul> +<li><p>contributed by the original author:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cab4735e4f99ce23c52b78dc879bc06af66796fd</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><81> ocaml parser segfaults on invalid files</p> +<blockquote> +<div><ul class="simple"> +<li><p>the bug is not reproduced</p></li> +</ul> +</div></blockquote> +<p><80> Add support for falcon pl</p> +<blockquote> +<div><ul class="simple"> +<li><p>contributed by the original author</p></li> +</ul> +</div></blockquote> +<p><74> protobuf parser</p> +<blockquote> +<div><ul class="simple"> +<li><p>Merged after getting approval from the original author</p></li> +</ul> +</div></blockquote> +<p><67> Objective C language parser</p> +<blockquote> +<div><ul class="simple"> +<li><p>This is the implementation we have in Universal Ctags tree.</p></li> +</ul> +</div></blockquote> +<p><65> absoluteFilename uses strcpy on overlapping strings</p> +<blockquote> +<div><ul> +<li><p>Fixed in Universal Ctags tree, however the ticket is still open:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d2bdf505abb7569deae2b50305ea1edce6208557</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><64> Fix strcpy() misuse</p> +<blockquote> +<div><ul> +<li><p>Fixed in Universal Ctags tree, however the ticket is still open:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d2bdf505abb7569deae2b50305ea1edce6208557</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><55> TTCN-3 support</p> +<blockquote> +<div><ul class="simple"> +<li><p>contributed by the original author</p></li> +</ul> +</div></blockquote> +<p><51> Ada support</p> +<blockquote> +<div><ul> +<li><p>Ada support is now available in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">4</span><span class="n">b6b4a72f3d2d4ef969d7c650de1829d79f0ea7c</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><38> Ada support</p> +<blockquote> +<div><ul> +<li><p>Ada support is now available in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">4</span><span class="n">b6b4a72f3d2d4ef969d7c650de1829d79f0ea7c</span> +</pre></div> +</div> +</li> +</ul> +</div></blockquote> +<p><33> Add basic ObjC support</p> +<blockquote> +<div><ul class="simple"> +<li><p>This one is written in regexp.</p></li> +<li><p>we have better objc parser.</p></li> +</ul> +</div></blockquote> +<p>(1) bibtex parser</p> +<blockquote> +<div><ul> +<li><p>Reject because…</p> +<ul class="simple"> +<li><p>the owner of the ticket is anonymous.</p></li> +<li><p>the name of patch author is not written explicitly at +the header of patch.</p></li> +</ul> +</li> +<li><p>Alternative</p> +<p><a class="reference external" href="https://gist.github.com/ptrv/4576213">https://gist.github.com/ptrv/4576213</a></p> +</li> +</ul> +</div></blockquote> +</div></blockquote> +</section> +<section id="devel-mailing-list-ctags-devel-sourceforge"> +<h2>devel mailing list (<a class="reference external" href="mailto:ctags-devel%40sourceforge">ctags-devel<span>@</span>sourceforge</a>)<a class="headerlink" href="#devel-mailing-list-ctags-devel-sourceforge" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div><p><[Ctags] Shebang with python3 instead of python> +From: Martin Ueding <<a class="reference external" href="mailto:dev%40ma...">dev<span>@</span>ma…</a>> - 2013-01-26 18:36:32</p> +<blockquote> +<div><p>Added python, python2 and python3 as extensions of +python parser:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">bb81485205c67617f1b34f61341e60b9e8030502</span> +</pre></div> +</div> +</div></blockquote> +<p><[Ctags-devel] Lack of fnmatch(3) in Windows> +From: Frank Fesevur <<a class="reference external" href="mailto:ffes%40us...">ffes<span>@</span>us…</a>> - 2013-08-24 20:25:47</p> +<blockquote> +<div><p>There is no fnmatch() in the Windows C library. Therefore +a string comparison is done in fileNameMatched() in +strlist.c and patterns are not recognized:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">698</span><span class="n">bf2f3db692946d2358892d228a864014abc4b</span> +</pre></div> +</div> +</div></blockquote> +<p><Re: [Ctags-devel] WindRes parser> +From: Frank Fesevur <<a class="reference external" href="mailto:ffes%40unns...">ffes<span>@</span>unns…</a>> - 2013-08-30 21:23:50</p> +<blockquote> +<div><p>A parser for Windows Resource files. +<a class="reference external" href="https://en.wikipedia.org/wiki/Resource_%28Windows%29">https://en.wikipedia.org/wiki/Resource_%28Windows%29</a></p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">95</span><span class="n">b4806ba6c006e4b7e72a006700e33c720ab9e7</span> +</pre></div> +</div> +</div></blockquote> +<p>([Ctags-devel] Skip repeat PATH_SEPARATORs in relativeFilename()) +From: Seth Dickson <<a class="reference external" href="mailto:whefxlr%40gm...">whefxlr<span>@</span>gm…</a>> - 2013-12-24 04:51:01</p> +<blockquote> +<div><p>Looks interesting.</p> +</div></blockquote> +</div></blockquote> +</section> +<section id="fedora"> +<h2>Fedora<a class="headerlink" href="#fedora" title="Permalink to this headline">¶</a></h2> +<p>Some patches are maintained in ctags package of Fedora. +Inventory of patches are +<a class="reference external" href="http://pkgs.fedoraproject.org/cgit/ctags.git/tree/ctags.spec">http://pkgs.fedoraproject.org/cgit/ctags.git/tree/ctags.spec</a></p> +<p><ctags-5.7-destdir.patch></p> +<blockquote> +<div><p>This patch was merged in Universal Ctags git tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d4b5972427a46cbdcbfb050a944cf62b300676be</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.7-segment-fault.patch></p> +<blockquote> +<div><p>This patch was merged in Universal Ctags git tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">8</span><span class="n">cc2b482f6c7257c5151893a6d02b8c79851fedd</span> +</pre></div> +</div> +</div></blockquote> +<p>(ctags-5.8-cssparse.patch)</p> +<blockquote> +<div><p>Not in Universal Ctags tree.</p> +<p>The reproducer is attached to the following page: +<a class="reference external" href="https://bugzilla.redhat.com/show_bug.cgi?id=852101">https://bugzilla.redhat.com/show_bug.cgi?id=852101</a></p> +<p>However, Universal Ctags doesn’t reproduce with it.</p> +<p>I, Masatake YAMATO, read the patch. However, I don’t +understand the patch.</p> +</div></blockquote> +<p><ctags-5.8-css.patch></p> +<blockquote> +<div><p>This patch was merged in Universal Ctags git tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">80</span><span class="n">c1522a36df3ba52b8b7cd7f5c79d5c30437a63</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.8-memmove.patch></p> +<blockquote> +<div><p>This patch was merged in Exuberant Ctags svn tree. +As the result this patch is in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d2bdf505abb7569deae2b50305ea1edce6208557</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.8-ocaml-crash.patch></p> +<blockquote> +<div><p>This patch was merged in Exuberant Ctags svn tree. +As the result this patch is in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ddb29762b37d60a875252dcc401de0b7479527b1</span> +</pre></div> +</div> +</div></blockquote> +<p><ctags-5.8-format-security.patch></p> +<blockquote> +<div><p>This patch was merged in Exuberant Ctags svn tree. +As the result this patch is in Universal Ctags tree:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">2</span><span class="n">f7a78ce21e4156ec3e63c821827cf1d5680ace8</span> +</pre></div> +</div> +</div></blockquote> +</section> +<section id="debian"> +<h2>Debian<a class="headerlink" href="#debian" title="Permalink to this headline">¶</a></h2> +<p>Some patches are maintained in ctags package of Debian. +Inventory of patches are +<a class="reference external" href="http://anonscm.debian.org/cgit/users/cjwatson/exuberant-ctags.git/tree/debian/patches/series">http://anonscm.debian.org/cgit/users/cjwatson/exuberant-ctags.git/tree/debian/patches/series</a></p> +<p><python-disable-imports.patch></p> +<blockquote> +<div><p>Universal Ctags tags Y in <cite>import X as Y</cite> and Z in <cite>from X import Y as Z</cite> +as definition tags. They are turned on by default. +The others are tagged as reference tags. reference tags are recorded only +when “r” extra tags are enabled. e.g. <cite>--extras=+r</cite>.</p> +</div></blockquote> +<p><vim-command-loop.patch></p> +<blockquote> +<div><p>This patch was merged as an alternative for +7fb36a2f4690374526e9e7ef4f1e24800b6914ec</p> +<p>Discussed on <a class="reference external" href="https://github.com/fishman/ctags/issues/74">https://github.com/fishman/ctags/issues/74</a></p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">e59325a576e38bc63b91abb05a5a22d2cef25ab7</span> +</pre></div> +</div> +</div></blockquote> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Tracking other projects</a><ul> +<li><a class="reference internal" href="#exuberant-ctags">Exuberant Ctags</a><ul> +<li><a class="reference internal" href="#subversion">subversion</a></li> +<li><a class="reference internal" href="#bugs">bugs</a></li> +</ul> +</li> +<li><a class="reference internal" href="#id1">patches</a></li> +<li><a class="reference internal" href="#devel-mailing-list-ctags-devel-sourceforge">devel mailing list (ctags-devel@sourceforge)</a></li> +<li><a class="reference internal" href="#fedora">Fedora</a></li> +<li><a class="reference internal" href="#debian">Debian</a></li> +</ul> +</li> +</ul> + +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-this"><a href="">Tracking other projects</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/docs/windows.html b/ctags/docs/windows.html new file mode 100644 index 0000000..e68cb2d --- /dev/null +++ b/ctags/docs/windows.html @@ -0,0 +1,257 @@ + +<!DOCTYPE html> + +<html> + <head> + <meta charset="utf-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + + <title>Building/hacking/using on MS-Windows — Universal Ctags 0.3.0 documentation</title> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/classic.css" /> + + <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Building on Mac OS" href="osx.html" /> + <link rel="prev" title="Building with configure (*nix including GNU/Linux)" href="autotools.html" /> + </head><body> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + accesskey="I">index</a></li> + <li class="right" > + <a href="osx.html" title="Building on Mac OS" + accesskey="N">next</a> |</li> + <li class="right" > + <a href="autotools.html" title="Building with configure (*nix including GNU/Linux)" + accesskey="P">previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="building.html" accesskey="U">Building ctags</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building/hacking/using on MS-Windows</a></li> + </ul> + </div> + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + <div class="body" role="main"> + + <section id="building-hacking-using-on-ms-windows"> +<h1>Building/hacking/using on MS-Windows<a class="headerlink" href="#building-hacking-using-on-ms-windows" title="Permalink to this headline">¶</a></h1> +<dl class="field-list simple"> +<dt class="field-odd">Maintainer</dt> +<dd class="field-odd"><p>Frank Fesevur <<a class="reference external" href="mailto:ffes%40users.sourceforge.net">ffes<span>@</span>users<span>.</span>sourceforge<span>.</span>net</a>></p> +</dd> +</dl> +<hr class="docutils" /> +<p>This part of the documentation is written by Frank Fesevur, co-maintainer of Universal Ctags and the maintainer of the Windows port of this project. It is still very much a work in progress. Things still need to be written down, tested or even investigated. When building for Windows you should be aware that there are many compilers and build environments available. This is a summary of available options and things that have been tested so far.</p> +<section id="compilers"> +<h2>Compilers<a class="headerlink" href="#compilers" title="Permalink to this headline">¶</a></h2> +<p>There are many compilers for Windows. Compilers not mentioned here may work but are not tested.</p> +<section id="microsoft-visual-studio"> +<h3>Microsoft Visual Studio<a class="headerlink" href="#microsoft-visual-studio" title="Permalink to this headline">¶</a></h3> +<p><a class="reference external" href="https://www.visualstudio.com/">https://www.visualstudio.com/</a></p> +<p>Obviously there is Microsoft Visual Studio 2013. Many professional developers targeting Windows use Visual Studio. Visual Studio comes in a couple of different editions. Their Express and Community editions are free to use, but a Microsoft-account is required to download the .iso and when you want to continue using it after a 30-days trial period. Other editions of Visual Studio must be purchased.</p> +<p>Installing Visual Studio will give you the IDE, the command line compilers and the MS-version of make named nmake.</p> +<p>Note that ctags cannot be built with Visual Studio older than 2013 anymore. There is C99 (or C11) coding used that generates syntax errors with VS2012 and older. This could affect compilers from other vendors as well.</p> +</section> +<section id="gcc"> +<h3>GCC<a class="headerlink" href="#gcc" title="Permalink to this headline">¶</a></h3> +<p>There are three flavors of GCC for Windows:</p> +<ul class="simple"> +<li><p>MinGW <a class="reference external" href="http://www.mingw.org">http://www.mingw.org</a></p></li> +<li><p>MinGW-w64 <a class="reference external" href="http://mingw-w64.sourceforge.net">http://mingw-w64.sourceforge.net</a></p></li> +<li><p>TDM-GCC <a class="reference external" href="http://tdm-gcc.tdragon.net">http://tdm-gcc.tdragon.net</a></p></li> +</ul> +<p>MinGW started it all, but development stalled for a while and no x64 was available. Then the MinGW-w64 fork emerged. It started as a 64-bit compiler, but soon they included both a 32-bit and a 64-bit compiler. But the name remained, a bit confusing. Another fork of MinGW is TDM-GCC. It also provides both 32-bit and 64-bit compilers. All have at least GCC 4.8. MinGW-w64 appears to be the most used flavor of MinGW at this moment. Many well known programs that originate from GNU/Linux use MinGW-w64 to compile their Windows port.</p> +</section> +</section> +<section id="building-ctags-from-the-command-line"> +<h2>Building ctags from the command line<a class="headerlink" href="#building-ctags-from-the-command-line" title="Permalink to this headline">¶</a></h2> +<section id="id1"> +<h3>Microsoft Visual Studio<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3> +<p>Most users of Visual Studio will use the IDE and not the command line to compile a project. But by default a shortcut to the command prompt that sets the proper path is installed in the Start Menu. When this command prompt is used <code class="docutils literal notranslate"><span class="pre">nmake</span> <span class="pre">-f</span> <span class="pre">mk_mvc.mak</span></code> will compile ctags. You can also go into the <code class="docutils literal notranslate"><span class="pre">win32</span></code> subdirectory and run <code class="docutils literal notranslate"><span class="pre">msbuild</span> <span class="pre">ctags_vs2013.sln</span></code> for the default build. Use <code class="docutils literal notranslate"><span class="pre">msbuild</span> <span class="pre">ctags_vs2013.sln</span> <span class="pre">/p:Configuration=Release</span></code> to specifically build a release build. MSBuild is what the IDE uses internally and therefore will produce the same files as the IDE.</p> +<p>If you want to build an iconv enabled version, you must specify <code class="docutils literal notranslate"><span class="pre">WITH_ICONV=yes</span></code> and <code class="docutils literal notranslate"><span class="pre">ICONV_DIR</span></code> like below:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nmake</span> <span class="o">-</span><span class="n">f</span> <span class="n">mk_mvc</span><span class="o">.</span><span class="n">mak</span> <span class="n">WITH_ICONV</span><span class="o">=</span><span class="n">yes</span> <span class="n">ICONV_DIR</span><span class="o">=</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">iconvlib</span> +</pre></div> +</div> +<p>If you want to build a debug version using <code class="docutils literal notranslate"><span class="pre">mk_mvc.mak</span></code>, you must specify <code class="docutils literal notranslate"><span class="pre">DEBUG=1</span></code> like below:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nmake</span> <span class="o">-</span><span class="n">f</span> <span class="n">mk_mvc</span><span class="o">.</span><span class="n">mak</span> <span class="n">DEBUG</span><span class="o">=</span><span class="mi">1</span> +</pre></div> +</div> +<p>If you want to create PDB files for debugging even for a release version, you must specify <code class="docutils literal notranslate"><span class="pre">PDB=1</span></code> like below:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nmake</span> <span class="o">-</span><span class="n">f</span> <span class="n">mk_mvc</span><span class="o">.</span><span class="n">mak</span> <span class="n">PDB</span><span class="o">=</span><span class="mi">1</span> +</pre></div> +</div> +</section> +<section id="id2"> +<h3>GCC<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3> +<p><strong>General</strong></p> +<p>All the GCC’s come with installers or with zipped archives. Install or extract them in a directory without spaces.</p> +<p>GNU Make builds for Win32 are available as well, and sometimes are included with the compilers. Make sure it is in your path, for instance by copying the make.exe in the bin directory of your compiler.</p> +<p>Native win32 versions of the GNU/Linux commands cp, rm and mv can be useful. rm is almost always used in by the <code class="docutils literal notranslate"><span class="pre">clean</span></code> target of a makefile.</p> +<p><strong>CMD</strong></p> +<p>Any Windows includes a command prompt. Not the most advanced, but it is enough to do the build tasks. Make sure the path is set properly and <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-f</span> <span class="pre">mk_mingw.mak</span></code> should do the trick.</p> +<p>If you want to build an iconv enabled version, you must specify <code class="docutils literal notranslate"><span class="pre">WITH_ICONV=yes</span></code> like below:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="o">-</span><span class="n">f</span> <span class="n">mk_mingw</span><span class="o">.</span><span class="n">mak</span> <span class="n">WITH_ICONV</span><span class="o">=</span><span class="n">yes</span> +</pre></div> +</div> +<p>If you want to build a debug version, you must specify <code class="docutils literal notranslate"><span class="pre">DEBUG=1</span></code> like below:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="o">-</span><span class="n">f</span> <span class="n">mk_mingw</span><span class="o">.</span><span class="n">mak</span> <span class="n">DEBUG</span><span class="o">=</span><span class="mi">1</span> +</pre></div> +</div> +<p><strong>MSYS / MSYS2</strong></p> +<p>From their site: MSYS is a collection of GNU utilities such as bash, make, gawk and grep to allow building of applications and programs which depend on traditional UNIX tools to be present. It is intended to supplement MinGW and the deficiencies of the cmd shell.</p> +<p>MSYS comes in two flavors; the original from MinGW and MSYS2. +See <a class="reference external" href="https://www.msys2.org/">https://www.msys2.org/</a> about MSYS2.</p> +<p>MSYS is old but still works. You can build ctags with it using <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-f</span> <span class="pre">mk_mingw.mak</span></code>. The Autotools are too old on MSYS so you cannot use them.</p> +<p>MSYS2 is a more maintained version of MSYS, but specially geared towards MinGW-w64. You can also use Autotools to build ctags. +If you use Autotools you can enable parsers which require jansson, libxml2 or libyaml, and can also do the Units testing with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">units</span></code>.</p> +<p>The following packages are needed to build a full-featured version:</p> +<ul class="simple"> +<li><p>base-devel (make, autoconf)</p></li> +<li><p>mingw-w64-{i686,x86_64}-toolchain (mingw-w64-{i686,x86_64}-gcc, mingw-w64-{i686,x86_64}-pkg-config)</p></li> +<li><p>mingw-w64-{i686,x86_64}-jansson</p></li> +<li><p>mingw-w64-{i686,x86_64}-libxml2</p></li> +<li><p>mingw-w64-{i686,x86_64}-libyaml</p></li> +<li><p>mingw-w64-{i686,x86_64}-xz</p></li> +</ul> +<p>If you want to build a single static-linked binary, you can use the following command:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>./autogen.sh +./configure --disable-external-sort --enable-static +make +</pre></div> +</div> +<p><code class="docutils literal notranslate"><span class="pre">--disable-external-sort</span></code> is a recommended option for Windows builds.</p> +<p><strong>Cygwin</strong></p> +<p>Cygwin provides ports of many GNU/Linux tools and a POSIX API layer. This is the most complete way to get the GNU/Linux terminal feel under Windows. Cygwin has a setup that helps you install all the tools you need. One drawback of Cygwin is that it has poor performance.</p> +<p>It is easy to build a Cygwin version of ctags using the normal GNU/Linux build steps. This ctags.exe will depend on cygwin1.dll and should only be used within the Cygwin ecosystem.</p> +<p>The following packages are needed to build a full-featured version:</p> +<ul class="simple"> +<li><p>libiconv-devel</p></li> +<li><p>libjansson-devel</p></li> +<li><p>libxml2-devel</p></li> +<li><p>libyaml-devel</p></li> +</ul> +<p>Cygwin has packages with a recent version of MinGW-w64 as well. This way it is easy to cross-compile a native Windows application with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">-f</span> <span class="pre">mk_mingw.mak</span>  <span class="pre">CC=i686-w64-mingw32-gcc</span></code>.</p> +<p>You can also build a native Windows version using Autotools.</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>./autogen.sh +./configure --host<span class="o">=</span>i686-w64-mingw32 --disable-external-sort +make +</pre></div> +</div> +<p>If you use Autotools you can also do the Units testing with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">units</span></code>.</p> +<p>Some anti-virus software slows down the build and test process significantly, especially when <code class="docutils literal notranslate"><span class="pre">./configure</span></code> is running and during the Units tests. In that case it could help to temporarily disable them. But be aware of the risks when you disable your anti-virus software.</p> +<p><strong>Cross-compile from GNU/Linux</strong></p> +<p>All major distributions have both MinGW and MinGW-w64 packages. Cross-compiling works the same way as with Cygwin. You cannot do the Windows based Units tests on GNU/Linux.</p> +</section> +</section> +<section id="building-ctags-with-ides"> +<h2>Building ctags with IDEs<a class="headerlink" href="#building-ctags-with-ides" title="Permalink to this headline">¶</a></h2> +<p>I have no idea how things work for most GNU/Linux developers, but most Windows developers are used to IDEs. Not many use a command prompt and running the debugger from the command line is not a thing a Windows developers would normally do. Many IDEs exist for Windows, I use the two below.</p> +<section id="id3"> +<h3>Microsoft Visual Studio<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3> +<p>As already mentioned Microsoft Visual Studio 2013 has the free Express and Community editions. For ctags the Windows Desktop Express Edition is enough to get the job done. The IDE has a proper debugger. Project files for VS2013 can be found in the win32 directory.</p> +<p>Please know that when files are added to the sources.mak, these files need to be added to the .vcxproj and .vcxproj.filters files as well. The XML of these files should not be a problem.</p> +</section> +<section id="code-blocks"> +<h3>Code::Blocks<a class="headerlink" href="#code-blocks" title="Permalink to this headline">¶</a></h3> +<p><a class="reference external" href="http://www.codeblocks.org/">http://www.codeblocks.org/</a></p> +<p>Code::Blocks is a decent GPL-licensed IDE that has good gcc and gdb integration. The TDM-GCC that can be installed together with Code::Blocks works fine and I can provide a project file. This is an easy way to have a free - free as in beer as well as in speech - solution and to have the debugger within the GUI as well.</p> +</section> +</section> +<section id="other-differences-between-microsoft-windows-and-gnu-linux"> +<h2>Other differences between Microsoft Windows and GNU/Linux<a class="headerlink" href="#other-differences-between-microsoft-windows-and-gnu-linux" title="Permalink to this headline">¶</a></h2> +<p>There other things where building ctags on Microsoft Windows differs from building on GNU/Linux.</p> +<ul class="simple"> +<li><p>Filenames on Windows file systems are case-preserving, but not case-sensitive.</p></li> +<li><p>Windows file systems use backslashes <code class="docutils literal notranslate"><span class="pre">"\"</span></code> as path separators, but paths with forward slashes <code class="docutils literal notranslate"><span class="pre">"/"</span></code> are no problem for a Windows program to recognize, even when a full path (include drive letter) is used.</p></li> +<li><p>The default line-ending on Windows is CRLF. A tags file generated by the Windows build of ctags will contain CRLF.</p></li> +<li><p>The tools used to build ctags do understand Unix-line endings without problems. There is no need to convert the line-ending of existing files in the repository.</p></li> +<li><p>Due to the differences between the GNU/Linux and Windows C runtime library there are some things that need to be added to ctags to make the program as powerful as it is on GNU/Linux. At this moment regex and fnmatch are borrowed from glibc. mkstemp() is taken from MinGW-w64’s runtime library. scandir() is taken from <a class="reference external" href="https://github.com/ClusterLabs/pacemaker/blob/master/replace/scandir.c">Pacemaker</a>.</p></li> +<li><p>Units testing needs a decent <code class="docutils literal notranslate"><span class="pre">bash</span></code> shell, some unix-like tools (e.g. <code class="docutils literal notranslate"><span class="pre">diff</span></code>, <code class="docutils literal notranslate"><span class="pre">sed</span></code>) and Python 3.5 or later. It is only tested using Cygwin or MSYS2.</p></li> +</ul> +</section> +</section> + + + <div class="clearer"></div> + </div> + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> + <h3><a href="index.html">Table of Contents</a></h3> + <ul> +<li><a class="reference internal" href="#">Building/hacking/using on MS-Windows</a><ul> +<li><a class="reference internal" href="#compilers">Compilers</a><ul> +<li><a class="reference internal" href="#microsoft-visual-studio">Microsoft Visual Studio</a></li> +<li><a class="reference internal" href="#gcc">GCC</a></li> +</ul> +</li> +<li><a class="reference internal" href="#building-ctags-from-the-command-line">Building ctags from the command line</a><ul> +<li><a class="reference internal" href="#id1">Microsoft Visual Studio</a></li> +<li><a class="reference internal" href="#id2">GCC</a></li> +</ul> +</li> +<li><a class="reference internal" href="#building-ctags-with-ides">Building ctags with IDEs</a><ul> +<li><a class="reference internal" href="#id3">Microsoft Visual Studio</a></li> +<li><a class="reference internal" href="#code-blocks">Code::Blocks</a></li> +</ul> +</li> +<li><a class="reference internal" href="#other-differences-between-microsoft-windows-and-gnu-linux">Other differences between Microsoft Windows and GNU/Linux</a></li> +</ul> +</li> +</ul> + + <h4>Previous topic</h4> + <p class="topless"><a href="autotools.html" + title="previous chapter">Building with configure (*nix including GNU/Linux)</a></p> + <h4>Next topic</h4> + <p class="topless"><a href="osx.html" + title="next chapter">Building on Mac OS</a></p> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script>$('#searchbox').show(0);</script> + </div> + </div> + <div class="clearer"></div> + </div> + <div class="related" role="navigation" aria-label="related navigation"> + <h3>Navigation</h3> + <ul> + <li class="right" style="margin-right: 10px"> + <a href="genindex.html" title="General Index" + >index</a></li> + <li class="right" > + <a href="osx.html" title="Building on Mac OS" + >next</a> |</li> + <li class="right" > + <a href="autotools.html" title="Building with configure (*nix including GNU/Linux)" + >previous</a> |</li> + <li class="nav-item nav-item-0"><a href="index.html">Universal Ctags 0.3.0 documentation</a> »</li> + <li class="nav-item nav-item-1"><a href="building.html" >Building ctags</a> »</li> + <li class="nav-item nav-item-this"><a href="">Building/hacking/using on MS-Windows</a></li> + </ul> + </div> + <div class="footer" role="contentinfo"> + © Copyright 2015, Universal Ctags Team. + Last updated on 11 Jun 2021. + Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.2. + </div> + </body> +</html>
\ No newline at end of file diff --git a/ctags/license/COPYING b/ctags/license/COPYING new file mode 100644 index 0000000..60549be --- /dev/null +++ b/ctags/license/COPYING @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) 19yy <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/ctags/license/COPYING.MinGW-w64-runtime.txt b/ctags/license/COPYING.MinGW-w64-runtime.txt new file mode 100644 index 0000000..ca6a077 --- /dev/null +++ b/ctags/license/COPYING.MinGW-w64-runtime.txt @@ -0,0 +1,240 @@ +MinGW-w64 runtime licensing +*************************** + +This program or library was built using MinGW-w64 and statically +linked against the MinGW-w64 runtime. Some parts of the runtime +are under licenses which require that the copyright and license +notices are included when distributing the code in binary form. +These notices are listed below. + + +======================== +Overall copyright notice +======================== + +Copyright (c) 2009, 2010, 2011, 2012, 2013 by the mingw-w64 project + +This license has been certified as open source. It has also been designated +as GPL compatible by the Free Software Foundation (FSF). + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + 1. Redistributions in source code must retain the accompanying copyright + notice, this list of conditions, and the following disclaimer. + 2. Redistributions in binary form must reproduce the accompanying + copyright notice, this list of conditions, and the following disclaimer + in the documentation and/or other materials provided with the + distribution. + 3. Names of the copyright holders must not be used to endorse or promote + products derived from this software without prior written permission + from the copyright holders. + 4. The right to distribute this software or to use it for any purpose does + not give you the right to use Servicemarks (sm) or Trademarks (tm) of + the copyright holders. Use of them is covered by separate agreement + with the copyright holders. + 5. If any files are modified, you must cause the modified files to carry + prominent notices stating that you changed the files and the date of + any change. + +Disclaimer + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY EXPRESSED +OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO +EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +======================================== +getopt, getopt_long, and getop_long_only +======================================== + +Copyright (c) 2002 Todd C. Miller <Todd.Miller@courtesan.com> + +Permission to use, copy, modify, and distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +Sponsored in part by the Defense Advanced Research Projects +Agency (DARPA) and Air Force Research Laboratory, Air Force +Materiel Command, USAF, under agreement number F39502-99-1-0512. + + * * * * * * * + +Copyright (c) 2000 The NetBSD Foundation, Inc. +All rights reserved. + +This code is derived from software contributed to The NetBSD Foundation +by Dieter Baron and Thomas Klausner. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. + + +=============================================================== +gdtoa: Converting between IEEE floating point numbers and ASCII +=============================================================== + +The author of this software is David M. Gay. + +Copyright (C) 1997, 1998, 1999, 2000, 2001 by Lucent Technologies +All Rights Reserved + +Permission to use, copy, modify, and distribute this software and +its documentation for any purpose and without fee is hereby +granted, provided that the above copyright notice appear in all +copies and that both that the copyright notice and this +permission notice and warranty disclaimer appear in supporting +documentation, and that the name of Lucent or any of its entities +not be used in advertising or publicity pertaining to +distribution of the software without specific, written prior +permission. + +LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. +IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY +SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER +IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF +THIS SOFTWARE. + + * * * * * * * + +The author of this software is David M. Gay. + +Copyright (C) 2005 by David M. Gay +All Rights Reserved + +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that the copyright notice and this permission notice and warranty +disclaimer appear in supporting documentation, and that the name of +the author or any of his current or former employers not be used in +advertising or publicity pertaining to distribution of the software +without specific, written prior permission. + +THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN +NO EVENT SHALL THE AUTHOR OR ANY OF HIS CURRENT OR FORMER EMPLOYERS BE +LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY +DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS +SOFTWARE. + + * * * * * * * + +The author of this software is David M. Gay. + +Copyright (C) 2004 by David M. Gay. +All Rights Reserved +Based on material in the rest of /netlib/fp/gdota.tar.gz, +which is copyright (C) 1998, 2000 by Lucent Technologies. + +Permission to use, copy, modify, and distribute this software and +its documentation for any purpose and without fee is hereby +granted, provided that the above copyright notice appear in all +copies and that both that the copyright notice and this +permission notice and warranty disclaimer appear in supporting +documentation, and that the name of Lucent or any of its entities +not be used in advertising or publicity pertaining to +distribution of the software without specific, written prior +permission. + +LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. +IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY +SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER +IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF +THIS SOFTWARE. + + +========================= +Parts of the math library +========================= + +Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved. + +Developed at SunSoft, a Sun Microsystems, Inc. business. +Permission to use, copy, modify, and distribute this +software is freely granted, provided that this notice +is preserved. + + * * * * * * * + +Copyright (C) 1993 by Sun Microsystems, Inc. All rights reserved. + +Developed at SunPro, a Sun Microsystems, Inc. business. +Permission to use, copy, modify, and distribute this +software is freely granted, provided that this notice +is preserved. + + * * * * * * * + +FIXME: Cephes math lib +Copyright (C) 1984-1998 Stephen L. Moshier + +It sounds vague, but as to be found at +<http://lists.debian.org/debian-legal/2004/12/msg00295.html>, it gives an +impression that the author could be willing to give an explicit +permission to distribute those files e.g. under a BSD style license. So +probably there is no problem here, although it could be good to get a +permission from the author and then add a license into the Cephes files +in MinGW runtime. At least on follow-up it is marked that debian sees the +version a-like BSD one. As MinGW.org (where those cephes parts are coming +from) distributes them now over 6 years, it should be fine. + +=================================== +Headers and IDLs imported from Wine +=================================== + +Some header and IDL files were imported from the Wine project. These files +are prominent maked in source. Their copyright belongs to contributors and +they are distributed under LGPL license. + +Disclaimer + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. diff --git a/ctags/license/Copyright.libxml2 b/ctags/license/Copyright.libxml2 new file mode 100644 index 0000000..d613185 --- /dev/null +++ b/ctags/license/Copyright.libxml2 @@ -0,0 +1,23 @@ +Except where otherwise noted in the source code (e.g. the files hash.c, +list.c and the trio files, which are covered by a similar licence but +with different Copyright notices) all the files are: + + Copyright (C) 1998-2012 Daniel Veillard. All Rights Reserved. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is fur- +nished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FIT- +NESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/ctags/license/LICENSE.janssen b/ctags/license/LICENSE.janssen new file mode 100644 index 0000000..eb63b93 --- /dev/null +++ b/ctags/license/LICENSE.janssen @@ -0,0 +1,19 @@ +Copyright (c) 2009-2016 Petri Lehtinen <petri@digip.org> + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/ctags/license/LICENSE.libyaml b/ctags/license/LICENSE.libyaml new file mode 100644 index 0000000..050ced2 --- /dev/null +++ b/ctags/license/LICENSE.libyaml @@ -0,0 +1,19 @@ +Copyright (c) 2006 Kirill Simonov + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies +of the Software, and to permit persons to whom the Software is furnished to do +so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/ctags/man/ctags-client-tools.7.html b/ctags/man/ctags-client-tools.7.html new file mode 100644 index 0000000..1ddb80c --- /dev/null +++ b/ctags/man/ctags-client-tools.7.html @@ -0,0 +1,869 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-client-tools</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-client-tools"> +<span id="ctags-client-tools-7"></span> +<h1 class="title">ctags-client-tools</h1> +<h2 class="subtitle" id="hints-for-developing-a-tool-using-ctags-command-and-tags-output">Hints for developing a tool using ctags command and tags output</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [options] [file(s)]</div> +<div class="line"><strong>etags</strong> [options] [file(s)]</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p><strong>Client tool</strong> means a tool running the ctags command +and/or reading a tags file generated by ctags command. +This man page gathers hints for people who develop client tools.</p> +</div> +<div class="section" id="pseudo-tags"> +<h1>PSEUDO-TAGS</h1> +<p><strong>Pseudo-tags</strong>, stored in a tag file, indicate how +ctags generated the tags file: whether the +tags file is sorted or not, which version of tags file format is used, +the name of tags generator, and so on. The opposite term for +pseudo-tags is <strong>regular-tags</strong>. A regular-tag is for a language +object in an input file. A pseudo-tag is for the tags file +itself. Client tools may use pseudo-tags as reference for processing +regular-tags.</p> +<p>A pseudo-tag is stored in a tags file in the same format as +regular-tags as described in tags(5), except that pseudo-tag names +are prefixed with "!_". For the general information about +pseudo-tags, see "TAG FILE INFORMATION" in tags(5).</p> +<p>An example of a pseudo tag:</p> +<pre class="literal-block"> +!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ +</pre> +<p>The value, "2", associated with the pseudo tag "TAG_PROGRAM_NAME", is +used in the field for input file. The description, "Derived from +Exuberant Ctags", is used in the field for pattern.</p> +<p>Universal Ctags extends the naming scheme of the classical pseudo-tags +available in Exuberant Ctags for emitting language specific +information as pseudo tags:</p> +<pre class="literal-block"> +!_{pseudo-tag-name}!{language-name} {associated-value} /{description}/ +</pre> +<p>The language-name is appended to the pseudo-tag name with a separator, "!".</p> +<p>An example of pseudo tag with a language suffix:</p> +<pre class="literal-block"> +!_TAG_KIND_DESCRIPTION!C f,function /function definitions/ +</pre> +<p>This pseudo-tag says "the function kind of C language is enabled +when generating this tags file." <tt class="docutils literal"><span class="pre">--pseudo-tags</span></tt> is the option for +enabling/disabling individual pseudo-tags. When enabling/disabling a +pseudo tag with the option, specify the tag name only +"TAG_KIND_DESCRIPTION", without the prefix ("!_") or the suffix ("!C").</p> +<div class="section" id="options-for-pseudo-tags"> +<h2>Options for Pseudo-tags</h2> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--extras=+p</span></tt> (or <tt class="docutils literal"><span class="pre">--extras=+{pseudo}</span></tt>)</dt> +<dd><p class="first">Forces writing pseudo-tags.</p> +<p class="last">ctags emits pseudo-tags by default when writing tags +to a regular file (e.g. "tags'.) However, when specifying <tt class="docutils literal"><span class="pre">-o</span> -</tt> +or <tt class="docutils literal"><span class="pre">-f</span> -</tt> for writing tags to standard output, +ctags doesn't emit pseudo-tags. <tt class="docutils literal"><span class="pre">--extras=+p</span></tt> or +<tt class="docutils literal"><span class="pre">--extras=+{pseudo}</span></tt> will force pseudo-tags to be written.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-pseudo-tags</span></tt></dt> +<dd><p class="first">Lists available types of pseudo-tags and shows whether they are enabled or disabled.</p> +<p class="last">Running ctags with <tt class="docutils literal"><span class="pre">--list-pseudo-tags</span></tt> option +lists available pseudo-tags. Some of pseudo-tags newly introduced +in Universal Ctags project are disabled by default. Use +<tt class="docutils literal"><span class="pre">--pseudo-tags=...</span></tt> to enable them.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--pseudo-tags=[+|-]names|*</span></tt></dt> +<dd><p class="first">Specifies a list of pseudo-tag types to include in the output.</p> +<p>The parameters are a set of pseudo tag names. Valid pseudo tag names +can be listed with <tt class="docutils literal"><span class="pre">--list-pseudo-tags</span></tt>. Surround each name in the set +with braces, like "{TAG_PROGRAM_AUTHOR}". You don't have to include the "!_" +pseudo tag prefix when specifying a name in the option argument for <tt class="docutils literal"><span class="pre">--pseudo-tags=</span></tt> +option.</p> +<p>pseudo-tags don't have a notation using one-letter flags.</p> +<p class="last">If a name is preceded by either the '+' or '-' characters, that +tags's effect has been added or removed. Otherwise the names replace +any current settings. All entries are included if '*' is given.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--fields=+E</span></tt> (or <tt class="docutils literal"><span class="pre">--fields=+{extras}</span></tt>)</dt> +<dd><p class="first">Attach "extras:pseudo" field to pseudo-tags.</p> +<p>An example of pseudo tags with the field:</p> +<pre class="literal-block"> +!_TAG_PROGRAM_NAME Universal Ctags /Derived from Exuberant Ctags/ extras:pseudo +</pre> +<p class="last">If the name of a normal tag in a tag file starts with "!_", a +client tool cannot distinguish whether the tag is a regular-tag or +pseudo-tag. The fields attached with this option help the tool +distinguish them.</p> +</dd> +</dl> +</div> +<div class="section" id="list-of-notable-pseudo-tags"> +<h2>List of notable pseudo-tags</h2> +<p>Running ctags with <tt class="docutils literal"><span class="pre">--list-pseudo-tags</span></tt> option lists available types +of pseudo-tags with short descriptions. This subsection shows hints +for using notable ones.</p> +<dl class="docutils"> +<dt><tt class="docutils literal">TAG_EXTRA_DESCRIPTION</tt> (new in Universal Ctags)</dt> +<dd><p class="first">Indicates the names and descriptions of enabled extras:</p> +<pre class="literal-block"> +!_TAG_EXTRA_DESCRIPTION {extra-name} /description/ +!_TAG_EXTRA_DESCRIPTION!{language-name} {extra-name} /description/ +</pre> +<p>If your tool relies on some extra tags (extras), refer to +the pseudo-tags of this type. A tool can reject the tags file that +doesn't include expected extras, and raise an error in an early +stage of processing.</p> +<p>An example of the pseudo-tags:</p> +<pre class="literal-block"> +$ ctags --extras=+p --pseudo-tags='{TAG_EXTRA_DESCRIPTION}' -o - input.c +!_TAG_EXTRA_DESCRIPTION anonymous /Include tags for non-named objects like lambda/ +!_TAG_EXTRA_DESCRIPTION fileScope /Include tags of file scope/ +!_TAG_EXTRA_DESCRIPTION pseudo /Include pseudo tags/ +!_TAG_EXTRA_DESCRIPTION subparser /Include tags generated by subparsers/ +... +</pre> +<p class="last">A client tool can know "{anonymous}", "{fileScope}", "{pseudo}", +and "{subparser}" extras are enabled from the output.</p> +</dd> +<dt><tt class="docutils literal">TAG_FIELD_DESCRIPTION</tt> (new in Universal Ctags)</dt> +<dd><p class="first">Indicates the names and descriptions of enabled fields:</p> +<pre class="literal-block"> +!_TAG_FIELD_DESCRIPTION {field-name} /description/ +!_TAG_FIELD_DESCRIPTION!{language-name} {field-name} /description/ +</pre> +<p>If your tool relies on some fields, refer to the pseudo-tags of +this type. A tool can reject a tags file that doesn't include +expected fields, and raise an error in an early stage of +processing.</p> +<p>An example of the pseudo-tags:</p> +<pre class="literal-block"> +$ ctags --fields-C=+'{macrodef}' --extras=+p --pseudo-tags='{TAG_FIELD_DESCRIPTION}' -o - input.c +!_TAG_FIELD_DESCRIPTION file /File-restricted scoping/ +!_TAG_FIELD_DESCRIPTION input /input file/ +!_TAG_FIELD_DESCRIPTION name /tag name/ +!_TAG_FIELD_DESCRIPTION pattern /pattern/ +!_TAG_FIELD_DESCRIPTION typeref /Type and name of a variable or typedef/ +!_TAG_FIELD_DESCRIPTION!C macrodef /macro definition/ +... +</pre> +<p class="last">A client tool can know "{file}", "{input}", "{name}", "{pattern}", +and "{typeref}" fields are enabled from the output. +The fields are common in languages. In addition to the common fields, +the tool can known "{macrodef}" field of C language is also enabled.</p> +</dd> +<dt><tt class="docutils literal">TAG_FILE_ENCODING</tt> (new in Universal Ctags)</dt> +<dd>TBW</dd> +<dt><tt class="docutils literal">TAG_FILE_FORMAT</tt></dt> +<dd>See also tags(5).</dd> +<dt><tt class="docutils literal">TAG_FILE_SORTED</tt></dt> +<dd>See also tags(5).</dd> +<dt><tt class="docutils literal">TAG_KIND_DESCRIPTION</tt> (new in Universal Ctags)</dt> +<dd><p class="first">Indicates the names and descriptions of enabled kinds:</p> +<pre class="literal-block"> +!_TAG_KIND_DESCRIPTION!{language-name} {kind-letter},{kind-name} /description/ +</pre> +<p>If your tool relies on some kinds, refer to the pseudo-tags of +this type. A tool can reject the tags file that doesn't include +expected kinds, and raise an error in an early stage of +processing.</p> +<p>Kinds are language specific, so a language name is always +appended to the tag name as suffix.</p> +<p>An example of the pseudo-tags:</p> +<pre class="literal-block"> +$ ctags --extras=+p --kinds-C=vfm --pseudo-tags='{TAG_KIND_DESCRIPTION}' -o - input.c +!_TAG_KIND_DESCRIPTION!C f,function /function definitions/ +!_TAG_KIND_DESCRIPTION!C m,member /struct, and union members/ +!_TAG_KIND_DESCRIPTION!C v,variable /variable definitions/ +... +</pre> +<p class="last">A client tool can know "{function}", "{member}", and "{variable}" +kinds of C language are enabled from the output.</p> +</dd> +<dt><tt class="docutils literal">TAG_KIND_SEPARATOR</tt> (new in Universal Ctags)</dt> +<dd>TBW</dd> +<dt><tt class="docutils literal">TAG_OUTPUT_EXCMD</tt> (new in Universal Ctags)</dt> +<dd>Indicates the specified type of EX command with <tt class="docutils literal"><span class="pre">--excmd</span></tt> option.</dd> +<dt><tt class="docutils literal">TAG_OUTPUT_FILESEP</tt> (new in Universal Ctags)</dt> +<dd>TBW</dd> +<dt><tt class="docutils literal">TAG_OUTPUT_MODE</tt> (new in Universal Ctags)</dt> +<dd>TBW</dd> +<dt><tt class="docutils literal">TAG_PATTERN_LENGTH_LIMIT</tt> (new in Universal Ctags)</dt> +<dd>TBW</dd> +<dt><tt class="docutils literal">TAG_PROC_CWD</tt> (new in Universal Ctags)</dt> +<dd><p class="first">Indicates the working directory of ctags during processing.</p> +<p>This pseudo-tag helps a client tool solve the absolute paths for +the input files for tag entries even when they are tagged with +relative paths.</p> +<p>An example of the pseudo-tags:</p> +<pre class="literal-block"> +$ cat tags +!_TAG_PROC_CWD /tmp/ // +main input.c /^int main (void) { return 0; }$/;" f typeref:typename:int +... +</pre> +<p class="last">From the regular tag for "main", the client tool can know the +"main" is at "input.c". However, it is a relative path. So if the +directory where ctags run and the directory +where the client tool runs are different, the client tool cannot +find "input.c" from the file system. In that case, +<tt class="docutils literal">TAG_PROC_CWD</tt> gives the tool a hint; "input.c" may be at "/tmp".</p> +</dd> +<dt><tt class="docutils literal">TAG_PROGRAM_NAME</tt></dt> +<dd>TBW</dd> +<dt><tt class="docutils literal">TAG_ROLE_DESCRIPTION</tt> (new in Universal Ctags)</dt> +<dd><p class="first">Indicates the names and descriptions of enabled roles:</p> +<pre class="literal-block"> +!_TAG_ROLE_DESCRIPTION!{language-name}!{kind-name} {role-name} /description/ +</pre> +<p class="last">If your tool relies on some roles, refer to the pseudo-tags of +this type. Note that a role owned by a disabled kind is not listed +even if the role itself is enabled.</p> +</dd> +</dl> +</div> +</div> +<div class="section" id="redundant-kinds"> +<h1>REDUNDANT-KINDS</h1> +<p>TBW</p> +</div> +<div class="section" id="multiple-languages-for-an-input-file"> +<h1>MULTIPLE-LANGUAGES FOR AN INPUT FILE</h1> +<p>Universal ctags can run multiple parsers. +That means a parser, which supports multiple parsers, may output tags for +different languages. <tt class="docutils literal">language</tt>/<tt class="docutils literal">l</tt> field can be used to show the language +for each tag.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>cat /tmp/foo.html +<span class="generic output"><html> +<script>var x = 1</script> +<h1>title</h1> +</html> +</span><span class="generic prompt">$ </span>./ctags -o - --extras<span class="operator">=</span>+g /tmp/foo.html +<span class="generic output">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h +x /tmp/foo.html /var x = 1/;" v +</span><span class="generic prompt">$ </span>./ctags -o - --extras<span class="operator">=</span>+g --fields<span class="operator">=</span>+l /tmp/foo.html +<span class="generic output">title /tmp/foo.html /^ <h1>title<\/h1>$/;" h language:HTML +x /tmp/foo.html /var x = 1/;" v language:JavaScript</span> +</pre> +</div> +<div class="section" id="utilizing-readtags"> +<h1>UTILIZING READTAGS</h1> +<p>See readtags(1) to know how to use readtags. This section is for discussing +some notable topics for client tools.</p> +<div class="section" id="build-filter-sorter-expressions"> +<h2>Build Filter/Sorter Expressions</h2> +<p>Certain escape sequences in expressions are recognized by readtags. For +example, when searching for a tag that matches <tt class="docutils literal"><span class="pre">a\?b</span></tt>, if using a filter +expression like <tt class="docutils literal">'(eq? $name <span class="pre">"a\?b")'</span></tt>, since <tt class="docutils literal">\?</tt> is translated into a +single <tt class="docutils literal">?</tt> by readtags, it actually searches for <tt class="docutils literal"><span class="pre">a?b</span></tt>.</p> +<p>Another problem is if a single quote appear in filter expressions (which is +also wrapped by single quotes), it terminates the expression, producing broken +expressions, and may even cause unintended shell injection. Single quotes can +be escaped using <tt class="docutils literal"><span class="pre">'"'"'</span></tt>.</p> +<p>So, client tools need to:</p> +<ul class="simple"> +<li>Replace <tt class="docutils literal">\</tt> by <tt class="docutils literal">\\</tt></li> +<li>Replace <tt class="docutils literal">'</tt> by <tt class="docutils literal"><span class="pre">'"'"'</span></tt></li> +</ul> +<p>inside the expressions. If the expression also contains strings, <tt class="docutils literal">"</tt> in the +strings needs to be replaced by <tt class="docutils literal">\"</tt>.</p> +<p>Client tools written in Lisp could build the expression using lists. <tt class="docutils literal">prin1</tt> +(in Common Lisp style Lisps) and <tt class="docutils literal">write</tt> (in Scheme style Lisps) can +translate the list into a string that can be directly used. For example, in +EmacsLisp:</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-client-tools.7.rst</tt>, line 308)</p> +<p>Cannot analyze code. No Pygments lexer found for "EmacsLisp".</p> +<pre class="literal-block"> +.. code-block:: EmacsLisp + + (let ((name "hi")) + (prin1 `(eq? $name ,name))) + => "(eq\\? $name "hi")" + +</pre> +</div> +<p>The "?" is escaped, and readtags can handle it. Scheme style Lisps should do +proper escaping so the expression readtags gets is just the expression passed +into <tt class="docutils literal">write</tt>. Common Lisp style Lisps may produce unrecognized escape +sequences by readtags, like <tt class="docutils literal">\#</tt>. Readtags provides some aliases for these +Lisps:</p> +<ul class="simple"> +<li>Use <tt class="docutils literal">true</tt> for <tt class="docutils literal">#t</tt>.</li> +<li>Use <tt class="docutils literal">false</tt> for <tt class="docutils literal">#f</tt>.</li> +<li>Use <tt class="docutils literal">nil</tt> or <tt class="docutils literal">()</tt> for <tt class="docutils literal">()</tt>.</li> +<li>Use <tt class="docutils literal"><span class="pre">(string->regexp</span> "PATTERN")</tt> for <tt class="docutils literal">#/PATTERN/</tt>. Use +<tt class="docutils literal"><span class="pre">(string->regexp</span> "PATTERN" <span class="pre">:case-fold</span> true)</tt> for <tt class="docutils literal">#/PATTERN/i</tt>. Notice +that <tt class="docutils literal"><span class="pre">string->regexp</span></tt> doesn't require escaping "/" in the pattern.</li> +</ul> +<p>Notice that even when the client tool uses this method, <tt class="docutils literal">'</tt> still needs to be +replaced by <tt class="docutils literal"><span class="pre">'"'"'</span></tt> to prevent broken expressions and shell injection.</p> +<p>Another thing to notice is that missing fields are represented by <tt class="docutils literal">#f</tt>, and +applying string operators to them will produce an error. You should always +check if a field is missing before applying string operators. See the +"Filtering" section in readtags(1) to know how to do this. Run "readtags -H +filter" to see which operators take string arguments.</p> +</div> +<div class="section" id="parse-readtags-output"> +<h2>Parse Readtags Output</h2> +<p>In the output of readtags, tabs can appear in all field values (e.g., the tag +name itself could contain tabs), which makes it hard to split the line into +fields. Client tools should use the <tt class="docutils literal"><span class="pre">-E</span></tt> option, which keeps the escape +sequences in the tags file, so the only field that could contain tabs is the +pattern field.</p> +<p>The pattern field could:</p> +<ul class="simple"> +<li>Use a line number. It will look like <tt class="docutils literal">number;"</tt> (e.g. <tt class="docutils literal">10;"</tt>).</li> +<li>Use a search pattern. It will look like <tt class="docutils literal"><span class="pre">/pattern/;"</span></tt> or <tt class="docutils literal"><span class="pre">?pattern?;"</span></tt>. +Notice that the search pattern could contain tabs.</li> +<li>Combine these two, like <tt class="docutils literal"><span class="pre">number;/pattern/;"</span></tt> or <tt class="docutils literal"><span class="pre">number;?pattern?;"</span></tt>.</li> +</ul> +<p>These are true for tags files using extended format, which is the default one. +The legacy format (i.e. <tt class="docutils literal"><span class="pre">--format=1</span></tt>) doesn't include the semicolons. It's +old and barely used, so we won't discuss it here.</p> +<p>Client tools could split the line using the following steps:</p> +<ul class="simple"> +<li>Find the first 2 tabs in the line, so we get the name and input field.</li> +<li>From the 2nd tab:<ul> +<li>If a <tt class="docutils literal">/</tt> follows, then the pattern delimiter is <tt class="docutils literal">/</tt>.</li> +<li>If a <tt class="docutils literal">?</tt> follows, then the pattern delimiter is <tt class="docutils literal">?</tt>.</li> +<li>If a number follows, then:<ul> +<li>If a <tt class="docutils literal">;/</tt> follows the number, then the delimiter is <tt class="docutils literal">/</tt>.</li> +<li>If a <tt class="docutils literal">;?</tt> follows the number, then the delimiter is <tt class="docutils literal">?</tt>.</li> +<li>If a <tt class="docutils literal">;"</tt> follows the number, then the field uses only line number, and +there's no pattern delimiter (since there's no regex pattern). In this +case the pattern field ends at the 3rd tab.</li> +</ul> +</li> +</ul> +</li> +<li>After the opening delimiter, find the next unescaped pattern delimiter, and +that's the closing delimiter. It will be followed by <tt class="docutils literal">;"</tt> and then a tab. +That's the end of the pattern field. By "unescaped pattern delimiter", we +mean there's an even number (including 0) of backslashes before it.</li> +<li>From here, split the rest of the line into fields by tabs.</li> +</ul> +<p>Then, the escape sequences in fields other than the pattern field should be +translated. See "Proposal" in tags(5) to know about all the escape sequences.</p> +</div> +<div class="section" id="make-use-of-the-pattern-field"> +<h2>Make Use of the Pattern Field</h2> +<p>The pattern field specifies how to find a tag in its source file. The code +generating this field seems to have a long history, so there are some pitfalls +and it's a bit hard to handle. A client tool could simply require the <tt class="docutils literal">line:</tt> +field and jump to the line it specifies, to avoid using the pattern field. But +anyway, we'll discuss how to make the best use of it here.</p> +<p>You should take the words here merely as suggestions, and not standards. A +client tool could definitely develop better (or simpler) ways to use the +pattern field.</p> +<p>From the last section, we know the pattern field could contain a line number +and a search pattern. When it only contains the line number, handling it is +easy: you simply go to that line.</p> +<p>The search pattern resembles an EX command, but as we'll see later, it's +actually not a valid one, so some manual work are required to process it.</p> +<p>The search pattern could look like <tt class="docutils literal">/pat/</tt>, called "forward search pattern", +or <tt class="docutils literal"><span class="pre">?pat?</span></tt>, called "backward search pattern". Using a search pattern means +even if the source file is updated, as long as the part containing the tag +doesn't change, we could still locate the tag correctly by searching.</p> +<p>When the pattern field only contains the search pattern, you just search for +it. The search direction (forward/backward) doesn't matter, as it's decided +solely by whether the <tt class="docutils literal"><span class="pre">-B</span></tt> option is enabled, and not the actual context. You +could always start the search from say the beginning of the file.</p> +<p>When both the search pattern and the line number are presented, you could make +good use of the line number, by going to the line first, then searching for the +nearest occurence of the pattern. A way to do this is to search both forward +and backward for the pattern, and when there is a occurence on both sides, go +to the nearer one.</p> +<p>What's good about this is when there are multiple identical lines in the source +file (e.g. the COMMON block in Fortran), this could help us find the correct +one, even after the source file is updated and the tag position is shifted by a +few lines.</p> +<p>Now let's discuss how to search for the pattern. After you trim the <tt class="docutils literal">/</tt> or +<tt class="docutils literal">?</tt> around it, the pattern resembles a regex pattern. It should be a regex +pattern, as required by being a valid EX command, but it's actually not, as +you'll see below.</p> +<p>It could begin with a <tt class="docutils literal">^</tt>, which means the pattern starts from the beginning +of a line. It could also end with an <em>unescaped</em> <tt class="docutils literal">$</tt> which means the pattern +ends at the end of a line. Let's keep this information, and trim them too.</p> +<p>Now the remaining part is the actual string containing the tag. Some characters +are escaped:</p> +<ul class="simple"> +<li><tt class="docutils literal">\</tt>.</li> +<li><tt class="docutils literal">$</tt>, but only at the end of the string.</li> +<li><tt class="docutils literal">/</tt>, but only in forward search patterns.</li> +<li><tt class="docutils literal">?</tt>, but only in backward search patterns.</li> +</ul> +<p>You need to unescape these to get the literal string. Now you could convert +this literal string to a regexp that matches it (by escaping, like +<tt class="docutils literal">re.escape</tt> in Python or <tt class="docutils literal"><span class="pre">regexp-quote</span></tt> in Elisp), and assemble it with +<tt class="docutils literal">^</tt> or <tt class="docutils literal">$</tt> if the pattern originally has it, and finally search for the tag +using this regexp.</p> +</div> +<div class="section" id="remark-about-a-previous-format-of-the-pattern-field"> +<h2>Remark: About a Previous Format of the Pattern Field</h2> +<p>In some earlier versions of Universal Ctags, the line number in the pattern +field is the actual line number minus one, for forward search patterns; or plus +one, for backward search patterns. The idea is to resemble an EX command: you +go to the line, then search forward/backward for the pattern, and you can +always find the correct one. But this denies the purpose of using a search +pattern: to tolerate file updates. For example, the tag is at line 50, +according to this scheme, the pattern field should be:</p> +<pre class="literal-block"> +49;/pat/;" +</pre> +<p>Then let's assume that some code above are removed, and the tag is now at +line 45. Now you can't find it if you search forward from line 49.</p> +<p>Due to this reason, Universal Ctags turns to use the actual line number. A +client tool could distinguish them by the <tt class="docutils literal">TAG_OUTPUT_EXCMD</tt> pseudo tag, it's +"combine" for the old scheme, and "combineV2" for the present scheme. But +probably there's no need to treat them differently, since "search for the +nearest occurence from the line" gives good result on both schemes.</p> +</div> +</div> +<div class="section" id="json-output"> +<h1>JSON OUTPUT</h1> +<p>Universal Ctags supports <a class="reference external" href="https://www.json.org/">JSON</a> (strictly +speaking <a class="reference external" href="https://jsonlines.org/">JSON Lines</a>) output format if the +ctags executable is built with <tt class="docutils literal">libjansson</tt>. JSON output goes to +standard output by default.</p> +<div class="section" id="format"> +<h2>Format</h2> +<p>Each JSON line represents a tag.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --extras<span class="operator">=</span>+p --output-format<span class="operator">=</span>json --fields<span class="operator">=</span>-s input.py +<span class="generic output">{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "0.0", "pattern": "in development"} +{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"} +... +{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"} +{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^ def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"} +...</span> +</pre> +<p>A key not starting with <tt class="docutils literal">_</tt> is mapped to a field of ctags. +"<tt class="docutils literal"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></tt>" options list the fields.</p> +<p>A key starting with <tt class="docutils literal">_</tt> represents meta information of the JSON +line. Currently only <tt class="docutils literal">_type</tt> key is used. If the value for the key +is <tt class="docutils literal">tag</tt>, the JSON line represents a normal tag. If the value is +<tt class="docutils literal">ptag</tt>, the line represents a pseudo-tag.</p> +<p>The output format can be changed in the +future. <tt class="docutils literal">JSON_OUTPUT_VERSION</tt> pseudo-tag provides a change +client-tools to handle the changes. Current version is "0.0". A +client-tool can extract the version with <tt class="docutils literal">path</tt> key from the +pseudo-tag.</p> +<p>The JSON output format is newly designed and has no limitation found +in the default tags file format.</p> +<ul class="simple"> +<li>The values for <tt class="docutils literal">kind</tt> key are represented in long-name flags. +No one-letter is here.</li> +<li>Scope names and scope kinds have distinguished keys: <tt class="docutils literal">scope</tt> and <tt class="docutils literal">scopeKind</tt>. +They are combined in the default tags file format.</li> +</ul> +</div> +<div class="section" id="data-type-used-in-a-field"> +<h2>Data type used in a field</h2> +<p>Values for the most of all keys are represented in JSON string type. +However, some of them are represented in string, integer, and/or boolean type.</p> +<p>"<tt class="docutils literal"><span class="pre">--output-format=json</span> <span class="pre">--list-fields</span></tt>" options show What kind of data type +used in a field of JSON.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --output-format<span class="operator">=</span>json --list-fields +<span class="generic prompt">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="generic output">F input yes NONE s-- no input file +... +P pattern yes NONE s-b no pattern +... +f file yes NONE --b no File-restricted scoping +... +e end no NONE -i- no end lines of various items +...</span> +</pre> +<p><tt class="docutils literal">JSTYPE</tt> column shows the data types.</p> +<dl class="docutils"> +<dt>'<tt class="docutils literal">s</tt>'</dt> +<dd>string</dd> +<dt>'<tt class="docutils literal">i</tt>'</dt> +<dd>integer</dd> +<dt>'<tt class="docutils literal">b</tt>'</dt> +<dd>boolean (true or false)</dd> +</dl> +<p>For an example, the value for <tt class="docutils literal">pattern</tt> field of ctags takes a string or a boolean value.</p> +</div> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-lang-python(7), ctags-incompatibilities(7), tags(5), readtags(1)</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-faq.7.html b/ctags/man/ctags-faq.7.html new file mode 100644 index 0000000..65d4f71 --- /dev/null +++ b/ctags/man/ctags-faq.7.html @@ -0,0 +1,757 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-faq</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-faq"> +<span id="ctags-faq-7"></span> +<h1 class="title">ctags-faq</h1> +<h2 class="subtitle" id="universal-ctags-faq">Universal Ctags FAQ</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<p>This is the Universal Ctags FAQ (Frequently-Asked Questions). +It is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a></p> +<div class="contents topic" id="contents"> +<p class="topic-title">Contents</p> +<ul class="simple"> +<li><a class="reference internal" href="#description" id="id2">DESCRIPTION</a><ul> +<li><a class="reference internal" href="#what-is-the-difference-between-universal-ctags-and-exuberant-ctags" id="id3">What is the difference between Universal Ctags and Exuberant Ctags?</a></li> +<li><a class="reference internal" href="#how-can-i-avoid-having-to-specify-my-favorite-option-every-time" id="id4">How can I avoid having to specify my favorite option every time?</a></li> +<li><a class="reference internal" href="#what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file" id="id5">What are these strange bits of text beginning with <tt class="docutils literal">;"</tt> which follow many of the lines in the tag file?</a></li> +<li><a class="reference internal" href="#why-can-t-i-jump-to-class-member" id="id6">Why can't I jump to <tt class="docutils literal"><span class="pre">class::member</span></tt>?</a></li> +<li><a class="reference internal" href="#why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag" id="id7">Why do I end up on the wrong line when I jump to a tag?</a></li> +<li><a class="reference internal" href="#how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name" id="id8">How do I jump to the tag I want instead of the wrong one by the same name?</a></li> +<li><a class="reference internal" href="#how-can-i-locate-all-references-to-a-specific-function-or-variable" id="id9">How can I locate all references to a specific function or variable?</a></li> +<li><a class="reference internal" href="#why-does-appending-tags-to-a-tag-file-tag-so-long" id="id10">Why does appending tags to a tag file tag so long?</a></li> +<li><a class="reference internal" href="#how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy" id="id11">How should I set up tag files for a multi-level directory hierarchy?</a></li> +<li><a class="reference internal" href="#does-universal-ctags-support-unicode-file-names" id="id12">Does Universal Ctags support Unicode file names?</a></li> +<li><a class="reference internal" href="#why-does-zsh-cause-zsh-no-matches-found-error" id="id13">Why does zsh cause "zsh: no matches found" error?</a></li> +</ul> +</li> +<li><a class="reference internal" href="#see-also" id="id14">SEE ALSO</a></li> +<li><a class="reference internal" href="#author" id="id15">AUTHOR</a></li> +</ul> +</div> +<div class="section" id="description"> +<h1><a class="toc-backref" href="#id2">DESCRIPTION</a></h1> +<!-- TODO: https://github.com/universal-ctags/ctags/issues/2312 +#1421: feature: clean up stale tags when appending (`-a`) +#2356: can't pre-process the macro but it works with Exuberant Ctags 5.8 +#2540: C/C++：conditional compilation like #ifdef will cause parse errror --> +<div class="section" id="what-is-the-difference-between-universal-ctags-and-exuberant-ctags"> +<h2><a class="toc-backref" href="#id3">What is the difference between Universal Ctags and Exuberant Ctags?</a></h2> +<p>Universal Ctags is an unofficial fork of Exuberant Ctags. +The differences are summarized in ctags-incompatibilities(7) man page.</p> +<p>The most notable one is that Universal Ctags doesn't read <tt class="docutils literal"><span class="pre">~/.ctags</span></tt> file. +Instead, it reads <tt class="docutils literal">*.ctags</tt> under <tt class="docutils literal"><span class="pre">~/.ctags.d</span></tt> directory.</p> +</div> +<div class="section" id="how-can-i-avoid-having-to-specify-my-favorite-option-every-time"> +<h2><a class="toc-backref" href="#id4">How can I avoid having to specify my favorite option every time?</a></h2> +<p>Either by setting the environment variable <tt class="docutils literal">CTAGS</tt> to your custom +options, or putting them into a <tt class="docutils literal"><span class="pre">~/.ctags.d/anyname.ctags</span></tt> file in your home +directory.</p> +</div> +<div class="section" id="what-are-these-strange-bits-of-text-beginning-with-which-follow-many-of-the-lines-in-the-tag-file"> +<h2><a class="toc-backref" href="#id5">What are these strange bits of text beginning with <tt class="docutils literal">;"</tt> which follow many of the lines in the tag file?</a></h2> +<p>These are <em>extension flags</em>. They are added in order to provide extra +information about the tag that may be utilized by the editor in order to +more intelligently handle tags. They are appended to the EX command part of +the tag line in a manner that provides backwards compatibility with existing +implementations of the Vi editor. The semicolon is an EX command separator +and the double quote begins an EX comment. Thus, the extension flags appear +as an EX comment and should be ignored by the editor when it processes the +EX command.</p> +<p>Some non-vi editors, however, implement only the bare minimum of EX commands +in order to process the search command or line number in the third field of +the tag file. If you encounter this problem, use the option <tt class="docutils literal"><span class="pre">--format=1</span></tt> to +generate a tag file without these extensions (remember that you can set the +CTAGS environment variable to any default arguments you wish to supply). Then +ask the supplier of your editor to implement handling of this feature of EX +commands.</p> +</div> +<div class="section" id="why-can-t-i-jump-to-class-member"> +<h2><a class="toc-backref" href="#id6">Why can't I jump to <tt class="docutils literal"><span class="pre">class::member</span></tt>?</a></h2> +<p>Because, by default, ctags only generates tags for the separate identifiers +found in the source files. If you specify the <tt class="docutils literal"><span class="pre">--extra=+q</span></tt> option, then +ctags will also generate a second, class-qualified tag for each class member +(data and function/method) in the form <tt class="docutils literal"><span class="pre">class::member</span></tt> for C++, and in the form +<tt class="docutils literal">class.method</tt> for Eiffel and Java.</p> +</div> +<div class="section" id="why-do-i-end-up-on-the-wrong-line-when-i-jump-to-a-tag"> +<h2><a class="toc-backref" href="#id7">Why do I end up on the wrong line when I jump to a tag?</a></h2> +<p>By default, ctags encodes the line number in the file where macro (<tt class="docutils literal">#define</tt>) +tags are found. This was done to remain compatible with the original UNIX +version of ctags. If you change the file containing the tag without +rebuilding the tag file, the location of tag in the tag file may no longer +match the current location.</p> +<p>In order to avoid this problem, you can specify the option <tt class="docutils literal"><span class="pre">--excmd=p</span></tt>, +which causes ctags to use a search pattern to locate macro tags. I have +never uncovered the reason why the original UNIX ctags used line numbers +exclusively for macro tags, but have so far resisted changing the default +behavior of Exuberant (and Universal) Ctags to behave differently.</p> +</div> +<div class="section" id="how-do-i-jump-to-the-tag-i-want-instead-of-the-wrong-one-by-the-same-name"> +<h2><a class="toc-backref" href="#id8">How do I jump to the tag I want instead of the wrong one by the same name?</a></h2> +<p>A tag file is simple a list of tag names and where to find them. If there +are duplicate entries, you often end up going to the wrong one because the +tag file is sorted and your editor locates the first one in the tag file.</p> +<p>Standard Vi provides no facilities to alter this behavior. However, Vim +has some nice features to minimize this problem, primarily by examining all +matches and choosing the best one under the circumstances. Vim also provides +commands which allow for selection of the desired matching tag.</p> +</div> +<div class="section" id="how-can-i-locate-all-references-to-a-specific-function-or-variable"> +<h2><a class="toc-backref" href="#id9">How can I locate all references to a specific function or variable?</a></h2> +<p>There are several packages already available which provide this capability. +Namely, these are: GLOBAL source code tag system, GNU id-utils, cscope, +and cflow. As of this writing, they can be found in the following locations:</p> +<ul class="simple"> +<li>GLOBAL: <a class="reference external" href="http://www.gnu.org/software/global">http://www.gnu.org/software/global</a></li> +<li>id-utils: <a class="reference external" href="http://www.gnu.org/software/idutils/idutils.html">http://www.gnu.org/software/idutils/idutils.html</a></li> +<li>cscope: <a class="reference external" href="http://cscope.sourceforge.net">http://cscope.sourceforge.net</a></li> +<li>cflow: <a class="reference external" href="ftp://www.ibiblio.org/pub/Linux/devel/lang/c">ftp://www.ibiblio.org/pub/Linux/devel/lang/c</a></li> +</ul> +</div> +<div class="section" id="why-does-appending-tags-to-a-tag-file-tag-so-long"> +<h2><a class="toc-backref" href="#id10">Why does appending tags to a tag file tag so long?</a></h2> +<p>Sometimes, in an attempt to build a global tag file for all source files in +a large source tree of many directories, someone will make an attempt to run +ctags in append (<tt class="docutils literal"><span class="pre">-a</span></tt>) mode on every directory in the hierarchy. Each time +ctags is invoked, its default behavior is to sort the tag file once the tags +for that execution have been added. As the cumulative tag file grows, the sort +time increases arithmetically.</p> +<p>The best way to avoid this problem (and the most efficient) is to make +use of the <tt class="docutils literal"><span class="pre">--recurse</span></tt> (or <tt class="docutils literal"><span class="pre">-R</span></tt>) option of ctags by executing the following +command in the root of the directory hierarchy (thus running ctags only once):</p> +<blockquote> +<pre class="code sh literal-block"> +ctags -R +</pre> +</blockquote> +<p>If you really insist on running ctags separately on each directory, you can +avoid the sort pass each time by specifying the option <tt class="docutils literal"><span class="pre">--sort=no</span></tt>. Once the +tag file is completely built, use the sort command to manually sort the +final tag file, or let the final invocation of ctags sort the file.</p> +</div> +<div class="section" id="how-should-i-set-up-tag-files-for-a-multi-level-directory-hierarchy"> +<h2><a class="toc-backref" href="#id11">How should I set up tag files for a multi-level directory hierarchy?</a></h2> +<p>There are a few ways of approaching this:</p> +<ol class="arabic simple"> +<li>A local tag file in each directory containing only the tags for source +files in that directory.</li> +<li>One single big, global tag file present in the root directory of your +hierarchy, containing all tags present in all source files in the +hierarchy.</li> +<li>A local tag file in each directory containing only the tags for source +files in that directory, in addition to one single global tag file +present in the root directory of your hierarchy, containing all +non-static tags present in all source files in the hierarchy.</li> +<li>A local tag file in each directory of the hierarchy, each one +containing all tags present in source files in that directory and all +non-static tags in every directory below it (note that this implies +also having one big tag file in the root directory of the hierarchy).</li> +</ol> +<p>Each of these approaches has its own set of advantages and disadvantages, +depending upon your particular conditions. Which approach is deemed best +depends upon the following factors:</p> +<ol class="upperalpha"> +<li><p class="first">The ability of your editor to use multiple tag files.</p> +<p>If your editor cannot make use of multiple tag files (original vi +implementations could not), then one large tag file is the only way to +go if you ever desire to jump to tags located in other directories. If +you never need to jump to tags in another directory (i.e. the source +in each directory is entirely self-contained), then a local tag file +in each directory will fit your needs.</p> +</li> +<li><p class="first">The time is takes for your editor to look up a tag in the tag file.</p> +<p>The significance of this factor depends upon the size of your source +tree and on whether the source files are located on a local or remote +file system. For source and tag files located on a local file system, +looking up a tag is not as big a hit as one might first imagine, since +vi implementations typically perform a binary search on a sorted tag +file. This may or may not be true for the editor you use. For files +located on a remote file system, reading a large file is an expensive +operation.</p> +</li> +<li><p class="first">Whether or not you expect the source code to change and the time it +takes to rebuild a tag file to account for changes to the source code.</p> +<p>While Universal Ctags is particularly fast in scanning source code +(around 1-2 MB/sec), a large project may still result in objectionable +delays if one wishes to keep their tag file(s) up to date on a +frequent basis, or if the files are located on a remote file system.</p> +</li> +<li><p class="first">The presence of duplicate tags in the source code and the ability to +handle them.</p> +<p>The impact of this factor is influenced by the following three issues:</p> +<ol class="arabic"> +<li><p class="first">How common are duplicate tags in your project?</p> +</li> +<li><p class="first">Does your editor provide any facilities for dealing with duplicate +tags?</p> +<p>While standard vi does not, many modern vi implementations, such +as Vim have good facilities for selecting the desired match from +the list of duplicates. If your editor does not support duplicate +tags, then it will typically send you to only one of them, whether +or not that is the one you wanted (and not even notifying you that +there are other potential matches).</p> +</li> +<li><p class="first">What is the significance of duplicate tags?</p> +<p>For example, if you have two tags of the same name from entirely +isolated software components, jumping first to the match found +in component B while working in component A may be entirely +misleading, distracting or inconvenient (to keep having to choose +which one if your editor provides you with a list of matches). +However, if you have two tags of the same name for parallel builds +(say two initialization routines for different hosts), you may +always want to specify which one you want.</p> +</li> +</ol> +</li> +</ol> +<p>Of the approaches listed above, I tend to favor Approach 3. My editor of +choice is Vim, which provides a rich set of features for handling multiple +tag files, which partly influences my choice. If you are working with +source files on a remote file system, then I would recommend either +Approach 3 or Approach 4, depending upon the hit when reading the global +tag file.</p> +<p>The advantages of Approach 3 are many (assuming that your editor has +the ability to support both multiple tag files and duplicate tags). All +lookups of tag located in the current directory are fast and the local +tag file can be quickly and easily regenerated in one second or less +(I have even mapped a keystroke to do this easily). A lookup of a +(necessarily non-static) tag found in another directory fails a lookup in +the local tag file, but is found in the global tag file, which satisfies +all cross-directory lookups. The global tag file can be automatically +regenerated periodically with a cron job (and perhaps the local tag files +also).</p> +<p>Now I give an example of how you would implement Approach 3. Means of +implementing the other approaches can be performed in a similar manner.</p> +<p>Here is a visual representation of an example directory hierarchy:</p> +<pre class="literal-block"> +project +`-----misccomp +| `... +`-----sysint + `-----client + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----common + | `-----hdrs + | `-----lib + | `-----src + | `-----test + `-----server + `-----hdrs + `-----lib + `-----src + `-----test +</pre> +<p>Here is a recommended solution (conceptually) to build the tag files:</p> +<ol class="arabic"> +<li><p class="first">Within each of the leaf nodes (i.e. <tt class="docutils literal">hdrs</tt>, <tt class="docutils literal">lib</tt>, <tt class="docutils literal">src</tt>, <tt class="docutils literal">test</tt>) build a tag +file using "<tt class="docutils literal">ctags <span class="pre">*.[ch]</span></tt>". This can be easily be done for the whole +hierarchy by making a shell script, call it <tt class="docutils literal">dirtags</tt>, containing the +following lines:</p> +<blockquote> +<pre class="code sh literal-block"> +<span class="comment hashbang">#!/bin/sh +</span><span class="name builtin">cd</span> <span class="name variable">$1</span> +ctags * +</pre> +</blockquote> +<p>Now execute the following command:</p> +<blockquote> +<pre class="code sh literal-block"> +find * -type d -exec dirtags <span class="operator">{}</span> <span class="literal string escape">\;</span> +</pre> +</blockquote> +<p>These tag files are trivial (and extremely quick) to rebuild while +making changes within a directory. The following Vim key mapping is +quite useful to rebuild the tag file in the directory of the current +source file:</p> +<blockquote> +<pre class="code text literal-block"> +:nmap ,t :!(cd %:p:h;ctags *.[ch])&<CR><CR> +</pre> +</blockquote> +</li> +<li><p class="first">Build the global tag file:</p> +<blockquote> +<pre class="code sh literal-block"> +<span class="name builtin">cd</span> ~/project +ctags --file-scope<span class="operator">=</span>no -R +</pre> +</blockquote> +<p>thus constructing a tag file containing only non-static tags for all +source files in all descendent directories.</p> +</li> +<li><p class="first">Configure your editor to read the local tag file first, then consult +the global tag file when not found in the local tag file. In Vim, +this is done as follows:</p> +<blockquote> +<pre class="code text literal-block"> +:set tags=./tags,tags,~/project/tags +</pre> +</blockquote> +</li> +</ol> +<p>If you wish to implement Approach 4, you would need to replace the +<tt class="docutils literal">dirtags</tt> script of step 1 with the following:</p> +<blockquote> +<pre class="code sh literal-block"> +<span class="comment hashbang">#!/bin/sh +</span><span class="name builtin">cd</span> <span class="name variable">$1</span> +ctags * +<span class="comment single"># Now append the non-static tags from descendent directories +</span>find * -type d -prune -print <span class="punctuation">|</span> ctags -aR --file-scope<span class="operator">=</span>no -L- +</pre> +</blockquote> +<p>And replace the configuration of step 3 with this:</p> +<blockquote> +<pre class="code text literal-block"> +:set tags=./tags;$HOME,tags +</pre> +</blockquote> +<p>As a caveat, it should be noted that step 2 builds a global tag file whose +file names will be relative to the directory in which the global tag file +is being built. This takes advantage of the Vim <tt class="docutils literal">tagrelative</tt> option, +which causes the path to be interpreted a relative to the location of the +tag file instead of the current directory. For standard vi, which always +interprets the paths as relative to the current directory, we need to +build the global tag file with absolute path names. This can be +accomplished by replacing step 2 with the following:</p> +<blockquote> +<pre class="code sh literal-block"> +<span class="name builtin">cd</span> ~/project +ctags --file-scope<span class="operator">=</span>no -R <span class="literal string backtick">`</span><span class="name builtin">pwd</span><span class="literal string backtick">`</span> +</pre> +</blockquote> +</div> +<div class="section" id="does-universal-ctags-support-unicode-file-names"> +<h2><a class="toc-backref" href="#id12">Does Universal Ctags support Unicode file names?</a></h2> +<!-- MEMO: from https://github.com/universal-ctags/ctags/issues/1837 --> +<p>Yes, Unicode file names are supported on unix-like platforms (Linux, macOS, +Cygwin, etc.).</p> +<p>However, on Windows, you need to use Windows 10 version 1903 or later to use +Unicode file names. (This is an experimental feature, though.) On older versions +on Windows, Universal Ctags only support file names represented in the current +code page. If you still want to use Unicode file names on them, use Cygwin or +MSYS2 version of Universal Ctags as a workaround.</p> +</div> +<div class="section" id="why-does-zsh-cause-zsh-no-matches-found-error"> +<h2><a class="toc-backref" href="#id13">Why does zsh cause "zsh: no matches found" error?</a></h2> +<!-- MEMO: from https://github.com/universal-ctags/ctags/issues/2842 --> +<p>zsh causes error on the following cases;</p> +<blockquote> +<pre class="code sh literal-block"> +ctags --extra<span class="operator">=</span>+* ... +ctags --exclude<span class="operator">=</span>foo/* ... +</pre> +</blockquote> +<p>This is the 2nd most significant incompatibility <em>feature</em> of zsh.</p> +<p>Cited from "Z-Shell Frequently-Asked Questions", "<a class="reference external" href="http://zsh.sourceforge.net/FAQ/zshfaq02.html">2.1: Differences from sh and +ksh</a>";</p> +<blockquote> +... The next most classic difference is that unmatched glob patterns cause +the command to abort; set <tt class="docutils literal">NO_NOMATCH</tt> for those.</blockquote> +<p>You may add "<tt class="docutils literal">setopt nonomatch</tt>" on your <tt class="docutils literal"><span class="pre">~/.zshrc</span></tt>. Or you can escape glob +patterns with backslash;</p> +<blockquote> +<pre class="code sh literal-block"> +ctags --extra<span class="operator">=</span>+<span class="literal string escape">\*</span> ... +ctags --exclude<span class="operator">=</span>foo/<span class="literal string escape">\*</span> ... +</pre> +</blockquote> +<p>Or quote them;</p> +<blockquote> +<pre class="code sh literal-block"> +ctags <span class="literal string single">'--extra=+*'</span> ... +ctags <span class="literal string single">'--exclude=foo/*'</span> ... +</pre> +</blockquote> +</div> +</div> +<div class="section" id="see-also"> +<h1><a class="toc-backref" href="#id14">SEE ALSO</a></h1> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>ctags(1), tags(5)</p> +</div> +<div class="section" id="author"> +<h1><a class="toc-backref" href="#id15">AUTHOR</a></h1> +<p>This FAQ is based on <a class="reference external" href="http://ctags.sourceforge.net/faq.html">Exuberant Ctags FAQ</a> by +Darren Hiebert and <a class="reference external" href="mailto:vberthoux@users.sourceforge.net">vberthoux@users.sourceforge.net</a></p> +<p>Universal Ctags project: <a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-incompatibilities.7.html b/ctags/man/ctags-incompatibilities.7.html new file mode 100644 index 0000000..8e540e1 --- /dev/null +++ b/ctags/man/ctags-incompatibilities.7.html @@ -0,0 +1,571 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-incompatibilities</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-incompatibilities"> +<span id="ctags-incompatibilities-7"></span> +<h1 class="title">ctags-incompatibilities</h1> +<h2 class="subtitle" id="incompatibilities-between-universal-ctags-and-exuberant-ctags">Incompatibilities between Universal Ctags and Exuberant Ctags</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [options] [file(s)]</div> +<div class="line"><strong>etags</strong> [options] [file(s)]</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>This page describes major incompatible changes introduced to +Universal Ctags forked from Exuberant Ctags.</p> +<div class="section" id="option-files-loading-at-starting-up-time-preload-files"> +<h2>Option files loading at starting up time (preload files)</h2> +<p>Universal Ctags doesn't load <tt class="docutils literal"><span class="pre">~/.ctags</span></tt> at starting up time. +File paths for preload files are changed. +See "FILES" section of ctags(1).</p> +</div> +<div class="section" id="environment-variables-for-arranging-command-lines"> +<h2>Environment variables for arranging command lines</h2> +<p>Universal Ctags doesn't read <tt class="docutils literal">CTAGS</tt> and/or <tt class="docutils literal">ETAGS</tt> environment +variables.</p> +</div> +<div class="section" id="incompatibilities-in-command-line-interface"> +<h2>Incompatibilities in command line interface</h2> +<div class="section" id="ordering-in-a-command-line"> +<h3>Ordering in a command line</h3> +<!-- NOTE: #1889 --> +<p>The command line format of Universal Ctags is "<tt class="docutils literal">ctags [options] +[source_file(s)]</tt>" following the standard POSIX convention.</p> +<p>Exuberant Ctags accepts a option following a source file.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags -o - foo.c --list-kinds<span class="operator">=</span>Sh +<span class="generic output">f functions</span> +</pre> +<p>Universal Ctags warns and ignores the option <tt class="docutils literal"><span class="pre">--list-kinds=Sh</span></tt> as follows.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags -o - foo.c --list-kinds<span class="operator">=</span>Sh +<span class="generic output">ctags: Warning: cannot open input file "--list-kinds=Sh" : No such file or directory +a foo.c /^void a () {}$/;" f typeref:typename:void +b foo.c /^void b () {}$/;" f typeref:typename:void</span> +</pre> +</div> +<div class="section" id="the-order-of-application-of-patterns-and-extensions-in-langmap"> +<h3>The order of application of patterns and extensions in <tt class="docutils literal"><span class="pre">--langmap</span></tt></h3> +<p>When applying mappings for a name of given source file, +Exuberant Ctags tests file name patterns <em>AFTER</em> file extensions +(<em>e-map-order</em>). Universal Ctags does this differently; it tests file +name patterns <em>BEFORE</em> file extensions (<em>u-map-order</em>).</p> +<p>This incompatible change is introduced to deal with the following +situation:</p> +<blockquote> +<ul class="simple"> +<li><tt class="docutils literal">build.xml</tt> as a source file,</li> +<li>The Ant parser declares it handles a file name pattern <tt class="docutils literal">build.xml</tt>, and</li> +<li>The XML parser declares it handles a file extension <tt class="docutils literal">.xml</tt>.</li> +</ul> +</blockquote> +<p>Which parser should be used for parsing <tt class="docutils literal">build.xml</tt>? The assumption +of Universal Ctags is the user may want to use the Ant parser; the +file name pattern it declares is more specific than the file extension +that the XML parser declares. However, e-map-order chooses the XML +parser.</p> +<p>So Universal Ctags uses the u-map-order even though it introduces an +incompatibility.</p> +<p><tt class="docutils literal"><span class="pre">--list-map-extensions=<language></span></tt> and <tt class="docutils literal"><span class="pre">--list-map-patterns=<language></span></tt> +options are helpful to verify and the file extensions and the file +name patterns of given <em><language></em>.</p> +</div> +<div class="section" id="remove-file-tags-and-file-scope-options"> +<h3>Remove <tt class="docutils literal"><span class="pre">--file-tags</span></tt> and <tt class="docutils literal"><span class="pre">--file-scope</span></tt> options</h3> +<p>Even in Exuberant Ctags, <tt class="docutils literal"><span class="pre">--file-tags</span></tt> is not documented in its man page. +Instead of specifying <tt class="docutils literal"><span class="pre">--file-tags</span></tt> or <tt class="docutils literal"><span class="pre">--file-tags=yes</span></tt>, use +<tt class="docutils literal"><span class="pre">--extras=+f</span></tt> or <tt class="docutils literal"><span class="pre">--extras=+{inputFile}</span></tt>.</p> +<p>Instead of specifying <tt class="docutils literal"><span class="pre">--file-tags=no</span></tt>, use +<tt class="docutils literal"><span class="pre">--extras=-f</span></tt> or <tt class="docutils literal"><span class="pre">--extras=-{inputFile}</span></tt>.</p> +<p>Universal Ctags introduces <tt class="docutils literal">F/fileScope</tt> extra as the replacement for +<tt class="docutils literal"><span class="pre">--file-scope</span></tt> option.</p> +<p>Instead of specifying <tt class="docutils literal"><span class="pre">--file-tags</span></tt> or <tt class="docutils literal"><span class="pre">--file-tags=yes</span></tt>, use +<tt class="docutils literal"><span class="pre">--extras=+F</span></tt> or <tt class="docutils literal"><span class="pre">--extras=+{fileScope}</span></tt>.</p> +<p>Instead of specifying <tt class="docutils literal"><span class="pre">--file-tags=no</span></tt>, use +<tt class="docutils literal"><span class="pre">--extras=-F</span></tt> or <tt class="docutils literal"><span class="pre">--extras=-{fileScope}</span></tt>.</p> +</div> +</div> +<div class="section" id="incompatibilities-in-language-and-kind-definitions"> +<h2>Incompatibilities in language and kind definitions</h2> +<div class="section" id="language-name-defined-with-langdef-name-option"> +<h3>Language name defined with <tt class="docutils literal"><span class="pre">--langdef=name</span></tt> option</h3> +<p>The characters you can use are more restricted than Exuberant Ctags. +For more details, see the description of <tt class="docutils literal"><span class="pre">--langdef=name</span></tt> in ctags-optlib(7).</p> +</div> +<div class="section" id="obsoleting-lang-kinds-option"> +<h3>Obsoleting <tt class="docutils literal"><span class="pre">--<LANG>-kinds</span></tt> option</h3> +<p>Some options have <em><LANG></em> as parameterized parts in their name like +<tt class="docutils literal"><span class="pre">--foo-<LANG>=...</span></tt> or <tt class="docutils literal"><span class="pre">--<LANG>-foo=...</span></tt>. The most of all such +options in Exuberant Ctags have the former form, <tt class="docutils literal"><span class="pre">--foo-<LANG>=...</span></tt>. +The exception is <tt class="docutils literal"><span class="pre">--<LANG>-kinds</span></tt>.</p> +<p>Universal Ctags uses the former form for all <em><LANG></em> parameterized +option. Use <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt> instead of <tt class="docutils literal"><span class="pre">--<LANG>-kinds</span></tt> in +Universal Ctags. <tt class="docutils literal"><span class="pre">--<LANG>-kinds</span></tt> still works but it will be +removed in the future.</p> +<p>The former form may be friendly to shell completion engines.</p> +</div> +<div class="section" id="disallowing-to-define-a-kind-with-file-as-name"> +<h3>Disallowing to define a kind with <tt class="docutils literal">file</tt> as name</h3> +<p>The kind name <tt class="docutils literal">file</tt> is reserved. Using it as part of kind spec in +<tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> option is now disallowed.</p> +</div> +<div class="section" id="disallowing-to-define-a-kind-with-f-as-letter"> +<h3>Disallowing to define a kind with '<tt class="docutils literal">F</tt>' as letter</h3> +<p>The kind letter '<tt class="docutils literal">F</tt>' is reserved. Using it as part of a kind spec in +<tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> option is now disallowed.</p> +</div> +<div class="section" id="disallowing-to-use-other-than-alphabetical-character-as-kind-letter"> +<h3>Disallowing to use other than alphabetical character as kind letter</h3> +<p>Exuberant Ctags accepts a character other than alphabetical character +as kind letter in <tt class="docutils literal"><span class="pre">--regex-<LANG>=...</span></tt> option. Universal Ctags +accepts only an alphabetical character.</p> +</div> +<div class="section" id="acceptable-characters-as-parts-of-a-kind-name"> +<h3>Acceptable characters as parts of a kind name</h3> +<p>Exuberant Ctags accepts any character as a part of a kind name +defined with <tt class="docutils literal"><span class="pre">--regex-<LANG>=/regex/replacement/kind-spec/</span></tt>.</p> +<p>Universal Ctags accepts only an alphabetical character as +the initial letter of a kind name. +Universal Ctags accepts only an alphabetical character or +numerical character as the rest letters.</p> +<p>An example:</p> +<pre class="literal-block"> +--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i +</pre> +<p>Universal Ctags rejects this because the kind name, <tt class="docutils literal">abstract class</tt>, +includes a whitespace character.</p> +<p>This requirement is for making the output of Universal Ctags follow +the tags file format.</p> +</div> +<div class="section" id="a-combination-of-a-kind-letter-and-a-kind-name"> +<h3>A combination of a kind letter and a kind name</h3> +<p>In Universal Ctags, the combination of +a kind letter and a kind name must be unique in a language.</p> +<p>You cannot define more than one kind reusing a kind letter with +different kind names. You cannot define more than one kind reusing a +kind name with different kind letters.</p> +<p>An example:</p> +<pre class="literal-block"> +--regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i +--regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i +</pre> +<p>Universal Ctags rejects this because the kind letter, '<tt class="docutils literal">a</tt>', used twice +for defining a kind <tt class="docutils literal">abstractClass</tt> and <tt class="docutils literal">attribute</tt>.</p> +</div> +</div> +<div class="section" id="incompatibilities-in-tags-file-format"> +<h2>Incompatibilities in tags file format</h2> +<div class="section" id="using-numerical-character-in-the-name-part-of-tag-tagfield"> +<h3>Using numerical character in the name part of tag tagfield</h3> +<p>The version 2 tags file format, the default output format of +Exuberant Ctags, accepts only alphabetical characters in the name part +of tag tagfield.</p> +<p>Universal Ctags introduces an exception to this specification; it may +use numerical characters in addition to alphabetical characters as the +letters other than initial letter of the name part.</p> +<p>The kinds <tt class="docutils literal">heading1</tt>, <tt class="docutils literal">heading2</tt>, and <tt class="docutils literal">heading3</tt> in the HTML parser +are the examples.</p> +</div> +<div class="section" id="truncating-the-pattern-for-long-input-lines"> +<h3>Truncating the pattern for long input lines</h3> +<p>To prevent generating overly large tags files, a pattern field is +truncated, by default, when its size exceeds 96 bytes. A different +limit can be specified with <tt class="docutils literal"><span class="pre">--pattern-length-limit=N</span></tt>. Specifying +0 as <em>N</em> results no truncation as Exuberant Ctags does not.</p> +</div> +<div class="section" id="kind-letters-and-names"> +<h3>Kind letters and names</h3> +<p>A kind letter '<tt class="docutils literal">F</tt>' and a kind name <tt class="docutils literal">file</tt> are reserved in the +main part. A parser cannot have a kind conflicting with +these reserved ones. Some incompatible changes are introduced +to follow the above rule.</p> +<ul class="simple"> +<li>Cobol's <tt class="docutils literal">file</tt> kind is renamed to <tt class="docutils literal">fileDesc</tt> because the +kind name <tt class="docutils literal">file</tt> is reserved.</li> +<li>Ruby's '<tt class="docutils literal">F</tt>' (singletonMethod) is changed to '<tt class="docutils literal">S</tt>'.</li> +<li>SQL's '<tt class="docutils literal">F</tt>' (field) is changed to '<tt class="docutils literal">E</tt>'.</li> +</ul> +</div> +</div> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-optlib(7), and tags(5).</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-lang-iPythonCell.7.html b/ctags/man/ctags-lang-iPythonCell.7.html new file mode 100644 index 0000000..6147e70 --- /dev/null +++ b/ctags/man/ctags-lang-iPythonCell.7.html @@ -0,0 +1,449 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-lang-iPythonCell</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-lang-ipythoncell"> +<span id="ctags-lang-ipythoncell-7"></span> +<h1 class="title">ctags-lang-iPythonCell</h1> +<h2 class="subtitle" id="the-man-page-of-the-ipythoncell-parser-for-universal-ctags">The man page of the iPythonCell parser for Universal Ctags</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> ... --extras={subparser} --languages=+iPythonCell,Python \</div> +<div class="line-block"> +<div class="line">[--extras-IPythonCell=+{doubleSharps}] \</div> +<div class="line">[--regex-IPythonCell=/<PATTERN>/\n/c/] ...</div> +</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>iPythonCell is a subparser stacked on top of the Python parser. +It works when:</p> +<ul class="simple"> +<li>The Python parser is enabled,</li> +<li>the <tt class="docutils literal">subparser</tt> extra is enabeld, and</li> +<li>the iPythonCell parser itself is enabled.</li> +</ul> +<p>iPythonCell extracts cells explained as in vim-ipython-cell +(<a class="reference external" href="https://github.com/hanschen/vim-ipython-cell/blob/master/README.md">https://github.com/hanschen/vim-ipython-cell/blob/master/README.md</a>).</p> +</div> +<div class="section" id="kind-s"> +<h1>KIND(S)</h1> +<p>The iPythonCell parser defines only a <tt class="docutils literal">cell</tt> kind.</p> +</div> +<div class="section" id="extra-s"> +<h1>EXTRA(S)</h1> +<p>Tagging cells staring with <tt class="docutils literal"><span class="pre">##...</span></tt> is disabled by default because +the pattern is too generic; with that pattern unwanted tags can be extracted.</p> +<p>Enable <tt class="docutils literal">doubleSharps</tt> language specific extra for tagging cells +staring with <tt class="docutils literal"><span class="pre">##...</span></tt>.</p> +</div> +<div class="section" id="customizing"> +<h1>CUSTOMIZING</h1> +<p>If your favorite cell pattern is not supported in the parser, you can +define the pattern in your <tt class="docutils literal">.ctagd.d/your.ctags</tt> or command lines. +Here is an example how to support "<tt class="docutils literal"># CTAGS: ...</tt>":</p> +<p>"input.py"</p> +<pre class="code Python literal-block"> +<span class="name">x</span><span class="operator">=</span><span class="literal number integer">1</span> +<span class="comment single"># CTAGS: DEFINE F</span> +<span class="keyword">def</span> <span class="name function">F</span><span class="punctuation">():</span> + <span class="comment single"># CTAGS: DO NOTING</span> + <span class="keyword">pass</span> +</pre> +<p>"output.tags" +with "--options=NONE --sort=no --extras=+{subparser} --regex-IPythonCell=/[ t]*# CTAGS:[ ]?(.*)$/1/c/ -o - input.py"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-iPythonCell.7.rst</tt>, line 63)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + x input.py /^x=1$/;" v + DEFINE F input.py /^# CTAGS: DEFINE F$/;" c + F input.py /^def F():$/;" f + DO NOTING input.py /^ # CTAGS: DO NOTING$/;" c + +</pre> +</div> +<p>You can put "<tt class="docutils literal"><span class="pre">--regex-IPythonCell=/[</span> <span class="pre">\t]*#</span> CTAGS:[ <span class="pre">]?(.*)$/\1/c/</span></tt>" in <tt class="docutils literal">your.ctags</tt> +to avoid specifying the pattern repeatedly.</p> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-client-tools(7), ctags-lang-python(7)</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-lang-inko.7.html b/ctags/man/ctags-lang-inko.7.html new file mode 100644 index 0000000..a3546c5 --- /dev/null +++ b/ctags/man/ctags-lang-inko.7.html @@ -0,0 +1,400 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-lang-inko</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-lang-inko"> +<span id="ctags-lang-inko-7"></span> +<h1 class="title">ctags-lang-inko</h1> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> ... --languages=+Inko ...</div> +<div class="line"><strong>ctags</strong> ... --language-force=Inko ...</div> +<div class="line"><strong>ctags</strong> ... --map-Inko=+.inko ...</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>This man page describes the Inko parser for Universal Ctags.</p> +<p>The input file is expected to be valid Inko source code, otherwise the output of +ctags is undefined.</p> +<p>Tags are generated for objects, traits, methods, attributes, and constants. +String literals are ignored.</p> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-client-tools(7)</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-lang-julia.7.html b/ctags/man/ctags-lang-julia.7.html new file mode 100644 index 0000000..8787eb4 --- /dev/null +++ b/ctags/man/ctags-lang-julia.7.html @@ -0,0 +1,600 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-lang-julia</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-lang-julia"> +<span id="ctags-lang-julia-7"></span> +<h1 class="title">ctags-lang-julia</h1> +<h2 class="subtitle" id="random-notes-about-tagging-julia-source-code-with-universal-ctags">Random notes about tagging Julia source code with Universal-ctags</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal-ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> ... --languages=+Julia ...</div> +<div class="line"><strong>ctags</strong> ... --language-force=Julia ...</div> +<div class="line"><strong>ctags</strong> ... --map-Julia=+.jl ...</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>This man page gathers random notes about tagging Julia source code.</p> +</div> +<div class="section" id="tagging-import-and-using-expressions"> +<h1>TAGGING <tt class="docutils literal">import</tt> AND <tt class="docutils literal">using</tt> EXPRESSIONS</h1> +<div class="section" id="summary"> +<h2>Summary</h2> +<p><cite>using X</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>X</td> +<td>module</td> +<td>used</td> +<td>N/A</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>using X: a, b</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>X</td> +<td>module</td> +<td>namespace</td> +<td>N/A</td> +</tr> +<tr><td>a, b</td> +<td>unknown</td> +<td>used</td> +<td>scope:module:X</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>import X</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>X</td> +<td>module</td> +<td>imported</td> +<td>N/A</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>import X.a, Y.b</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>X, Y</td> +<td>module</td> +<td>namespace</td> +<td>N/A</td> +</tr> +<tr><td>a</td> +<td>unknown</td> +<td>imported</td> +<td>scope:module:X</td> +</tr> +<tr><td>b</td> +<td>unknown</td> +<td>imported</td> +<td>scope:module:Y</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>import X: a, b</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>X</td> +<td>module</td> +<td>namespace</td> +<td>N/A</td> +</tr> +<tr><td>a,b</td> +<td>unknown</td> +<td>imported</td> +<td>scope:module:X</td> +</tr> +</tbody> +</table> +</blockquote> +</div> +<div class="section" id="examples"> +<h2>Examples</h2> +<p>"input.jl"</p> +<pre class="code Julia literal-block"> +<span class="keyword">using</span> <span class="name">X0</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK input.jl"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-julia.7.rst</tt>, line 84)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + X0 input.jl /^using X0$/;" kind:module roles:used + +</pre> +</div> +<p><tt class="docutils literal"><span class="pre">--extras=+r</span></tt> (or <tt class="docutils literal"><span class="pre">--extras=+{reference}</span></tt>) option is needed for this tag, +since it's a reference tag. This is because module <tt class="docutils literal">X</tt> is not defined here. +It is defined in another file. Enable <tt class="docutils literal">roles:</tt> field with <tt class="docutils literal"><span class="pre">--fields=+r</span></tt> is +for recording that the module is "used", i.e., loaded by <tt class="docutils literal">using</tt>.</p> +<p>"input.jl"</p> +<pre class="code Julia literal-block"> +<span class="keyword">import</span> <span class="name">X1</span><span class="operator">.</span><span class="name">a</span><span class="punctuation">,</span> <span class="name">X2</span><span class="operator">.</span><span class="name">b</span><span class="punctuation">,</span> <span class="name">X3</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzKZ input.jl"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-julia.7.rst</tt>, line 102)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + X1 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace + X2 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace + X3 input.jl /^import X1.a, X2.b, X3$/;" kind:module roles:imported + a input.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X1 roles:imported + b input.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X2 roles:imported + +</pre> +</div> +<p>Why <tt class="docutils literal">X1</tt> and <tt class="docutils literal">X2</tt> have role "namespace", while <tt class="docutils literal">X3</tt> have role "imported"? +It's because the symbol <tt class="docutils literal">a</tt> in module <tt class="docutils literal">X1</tt>, and <tt class="docutils literal">b</tt> in module <tt class="docutils literal">X2</tt> are +brought to the current scope, but <tt class="docutils literal">X1</tt> and <tt class="docutils literal">X2</tt> themselves are not. We use +"namespace" role for such modules.</p> +<p><tt class="docutils literal">X3</tt> is different. The symbol <tt class="docutils literal">X3</tt>, together with all exported symbols in +<tt class="docutils literal">X3</tt>, is brought to current scope. For such modules, we use "imported" or +"used" role depending whether they are loaded by <tt class="docutils literal">import</tt> or <tt class="docutils literal">using</tt>.</p> +<p>Also, notice that <tt class="docutils literal">a</tt> and <tt class="docutils literal">b</tt> have the "unknown" kind. This is because we +cannot know whether it's a function, constant, or macro, etc.</p> +</div> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-client-tools(7)</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-lang-python.7.html b/ctags/man/ctags-lang-python.7.html new file mode 100644 index 0000000..9e0e3ed --- /dev/null +++ b/ctags/man/ctags-lang-python.7.html @@ -0,0 +1,804 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-lang-python</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-lang-python"> +<span id="ctags-lang-python-7"></span> +<h1 class="title">ctags-lang-python</h1> +<h2 class="subtitle" id="random-notes-about-tagging-python-source-code-with-universal-ctags">Random notes about tagging python source code with Universal Ctags</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> ... --languages=+Python ...</div> +<div class="line"><strong>ctags</strong> ... --language-force=Python ...</div> +<div class="line"><strong>ctags</strong> ... --map-Python=+.py ...</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>This man page gathers random notes about tagging python source code.</p> +</div> +<div class="section" id="tagging-import-statements"> +<h1>TAGGING <tt class="docutils literal">import</tt> STATEMENTS</h1> +<div class="section" id="summary"> +<h2>Summary</h2> +<p><cite>import X</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>X</td> +<td>module</td> +<td>imported</td> +<td>N/A</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>import X as Y</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>X</td> +<td>module</td> +<td>indirectlyImported</td> +<td>N/A</td> +</tr> +<tr><td>Y</td> +<td>namespace</td> +<td>definition</td> +<td>nameref:module:X</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>from X import *</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td><cite>X</cite></td> +<td>module</td> +<td>namespace</td> +<td>N/A</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>from X import Y</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td><cite>X</cite></td> +<td>module</td> +<td>namespace</td> +<td>N/A</td> +</tr> +<tr><td><cite>Y</cite></td> +<td>unknown</td> +<td>imported</td> +<td>scope:module:<cite>X</cite></td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>from X import Y as Z</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="7%" /> +<col width="18%" /> +<col width="33%" /> +<col width="42%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td><cite>X</cite></td> +<td>module</td> +<td>namespace</td> +<td>N/A</td> +</tr> +<tr><td><cite>Y</cite></td> +<td>unknown</td> +<td>indirectlyImported</td> +<td>scope:module:<cite>X</cite></td> +</tr> +<tr><td><cite>Z</cite></td> +<td>unknown</td> +<td>definition</td> +<td>nameref:unknown:<cite>X</cite></td> +</tr> +</tbody> +</table> +</blockquote> +<!-- ===================== ==== ========== ================== =================== +input code name kind role other noticeable fields +===================== ==== ========== ================== =================== +import X X module imported +import X as Y X module indirectlyImported +import X as Y Y namespace definition nameref:module:X +from X import * X module namespace +from X import Y X module namespace +from X import Y Y unknown imported scope:module:X +from X import Y as Z X module namespace +from X import Y as Z Y unknown indirectlyImported scope:module:X +from X import Y as Z Z unknown definition nameref:unknown:X +===================== ==== ========== ================== =================== --> +<!-- a table having merged cells cannot be converted to man page --> +<!-- +- - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+ +|input code |output tags | +| +- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +| |name| kind |role |other noticeable fields | ++====================+====+==========+==================+===================+ +|import X |X | module |imported | | ++- - - - - - - - - - - - - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +|import X as Y |X | module |indirectlyImported| | +| +- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +| |Y | namespace|definition |nameref:module:X | ++- - - - - - - - - - - - - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +|from X import * |X | module |namespace | | ++- - - - - - - - - - - - - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +|from X import Y |X | module |namespace | | +| +- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +| |Y | unknown |imported |scope:module:X | ++- - - - - - - - - - - - - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +|from X import Y as Z|X | module |namespace | | +| +- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +| |Y | unknown |indirectlyImported|scope:module:X | +| +- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ +| |Z | unknown |definition |nameref:unknown:Y | ++- - - - - - - - - - - - - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ --> +</div> +<div class="section" id="examples"> +<h2>Examples</h2> +<p>"input.py"</p> +<pre class="code Python literal-block"> +<span class="keyword namespace">import</span> <span class="name namespace">X0</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK input.py"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-python.7.rst</tt>, line 125)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + X0 input.py /^import X0$/;" kind:module roles:imported + +</pre> +</div> +<p>A tag for an imported module has <tt class="docutils literal">module</tt> kind with <tt class="docutils literal">imported</tt> role. The +module is not defined here; it is defined in another file. So the tag for the +imported module is a reference tag; specify <tt class="docutils literal"><span class="pre">--extras=+r</span></tt> (or +<tt class="docutils literal"><span class="pre">--extras=+{reference}</span></tt>) option for tagging it. "roles:" field enabled with +<tt class="docutils literal"><span class="pre">--fields=+r</span></tt> is for recording the module is "imported" to the tag file.</p> +<p>"input.py"</p> +<pre class="code Python literal-block"> +<span class="keyword namespace">import</span> <span class="name namespace">X1</span> <span class="keyword">as</span> <span class="name namespace">Y1</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK --fields-Python=+{nameref} input.py"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-python.7.rst</tt>, line 144)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + X1 input.py /^import X1 as Y1$/;" kind:module roles:indirectlyImported + Y1 input.py /^import X1 as Y1$/;" kind:namespace roles:def nameref:module:X1 + +</pre> +</div> +<p>"Y1" introduces a new name and is defined here. So "Y1" is tagged as a +definition tag. "X1" is imported in a way that its name cannot be used +in this source file. For letting client tools know that the name cannot be used, +<tt class="docutils literal">indirectlyImported</tt> role is assigned for "X1". "Y1" is the name for +accessing objects defined in the module imported via "X1". For recording this +relationship, <tt class="docutils literal">nameref:</tt> field is attached to the tag of "Y1". Instead of +<tt class="docutils literal">module</tt> kind, <tt class="docutils literal">namespace</tt> kind is assigned to "Y1" because "Y1" itself +isn't a module.</p> +<p>"input.py"</p> +<pre class="code Python literal-block"> +<span class="keyword namespace">from</span> <span class="name namespace">X2</span> <span class="keyword namespace">import</span> <span class="operator">*</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzK input.py"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-python.7.rst</tt>, line 167)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + X2 input.py /^from X2 import *$/;" kind:module roles:namespace + +</pre> +</div> +<p>The module is not defined here; it is defined in another file. So the tag for +the imported module is a reference tag. Unlike "X0" in "import X0", "X2" may not +be used because the names defined in "X2" can be used in this source file. To represent +the difference <tt class="docutils literal">namespace</tt> role is attached to "X2" instead of <tt class="docutils literal">imported</tt>.</p> +<p>"input.py"</p> +<pre class="code Python literal-block"> +<span class="keyword namespace">from</span> <span class="name namespace">X3</span> <span class="keyword namespace">import</span> <span class="name">Y3</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzKZ input.py"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-python.7.rst</tt>, line 185)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + X3 input.py /^from X3 import Y3$/;" kind:module roles:namespace + Y3 input.py /^from X3 import Y3$/;" kind:unknown scope:module:X3 roles:imported + +</pre> +</div> +<p>"Y3" is a name for a language object defined in "X3" module. "scope:module:X3" +attached to "Y3" represents this relation between "Y3" and "X3". ctags +assigns <tt class="docutils literal">unknown</tt> kind to "Y3" because ctags cannot know whether "Y3" is a +class, a variable, or a function from the input file.</p> +<p>"input.py"</p> +<pre class="code Python literal-block"> +<span class="keyword namespace">from</span> <span class="name namespace">X4</span> <span class="keyword namespace">import</span> <span class="name">Y4</span> <span class="keyword">as</span> <span class="name">Z4</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --extras=+r --fields=+rzKZ input.py"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-python.7.rst</tt>, line 204)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + X4 input.py /^from X4 import Y4 as Z4$/;" kind:module roles:namespace + Y4 input.py /^from X4 import Y4 as Z4$/;" kind:unknown scope:module:X4 roles:indirectlyImported + Z4 input.py /^from X4 import Y4 as Z4$/;" kind:unknown roles:def nameref:unknown:Y4 + +</pre> +</div> +<p>"Y4" is similar to "Y3" of "from X3 import Y3" but the name cannot be used here. +<tt class="docutils literal">indirectlyImported</tt> role assigned to "Y4" representing this. "Z4" is the name for +accessing the language object named in "Y4" in "X4" module. "nameref:unknown:Y4" +attached to "Z4" and "scope:module:X4" attached to "Y4" represent the relations.</p> +</div> +</div> +<div class="section" id="lambda-expression-and-type-hint"> +<h1>LAMBDA EXPRESSION AND TYPE HINT</h1> +<div class="section" id="id1"> +<h2>Summary</h2> +<p><cite>id = lambda var0: var0</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="18%" /> +<col width="16%" /> +<col width="29%" /> +<col width="37%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td><cite>id</cite></td> +<td>function</td> +<td>definition</td> +<td>signature:(<cite>var0</cite>)</td> +</tr> +</tbody> +</table> +</blockquote> +<p><cite>id_t: Callable[[int], int] = lambda var1: var1</cite></p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="10%" /> +<col width="10%" /> +<col width="17%" /> +<col width="63%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">name</th> +<th class="head">kind</th> +<th class="head">role</th> +<th class="head">other noticeable fields</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td><cite>id_t</cite></td> +<td>variable</td> +<td>definition</td> +<td>typeref:typename:<cite>Callable[[int], int]</cite> nameref:function:anonFuncN</td> +</tr> +<tr><td>anonFuncN</td> +<td>function</td> +<td>definition</td> +<td>signature:(<cite>var1</cite>)</td> +</tr> +</tbody> +</table> +</blockquote> +</div> +<div class="section" id="id2"> +<h2>Examples</h2> +<p>"input.py"</p> +<pre class="code Python literal-block"> +<span class="keyword namespace">from</span> <span class="name namespace">typing</span> <span class="keyword namespace">import</span> <span class="name">Callable</span> +<span class="name builtin">id</span> <span class="operator">=</span> <span class="keyword">lambda</span> <span class="name">var0</span><span class="punctuation">:</span> <span class="name">var0</span> +<span class="name">id_t</span><span class="punctuation">:</span> <span class="name">Callable</span><span class="punctuation">[[</span><span class="name builtin">int</span><span class="punctuation">],</span> <span class="name builtin">int</span><span class="punctuation">]</span> <span class="operator">=</span> <span class="keyword">lambda</span> <span class="name">var1</span><span class="punctuation">:</span> <span class="name">var1</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --sort=no --fields=+KS --fields-Python=+{nameref} --extras=+{anonymous} input.py"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-python.7.rst</tt>, line 251)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + id input.py /^id = lambda var0: var0$/;" function signature:(var0) + id_t input.py /^id_t: Callable[[int], int] = lambda var1: var1$/;"\ + variable typeref:typename:Callable[[int], int] nameref:function:anonFunc84011d2c0101 + anonFunc84011d2c0101 input.py /^id_t: Callable[[int], int] = lambda var1: var1$/;"\ + function signature:(var1) + +</pre> +</div> +<p>If a variable ("id") with no type hint is initialized with a lambda expression, +ctags assigns <tt class="docutils literal">function</tt> kind for the tag of "id".</p> +<p>If a variable ("id_t") with a type hint is initialized with a lambda expression, +ctags assigns <tt class="docutils literal">variable</tt> kind for the tag of "id_t" with <tt class="docutils literal">typeref:</tt> and +<tt class="docutils literal">nameref:</tt> fields. ctags fills <tt class="docutils literal">typeref:</tt> field with the value of the type +hint. The way of filling <tt class="docutils literal">nameref:</tt> is a bit complicated.</p> +<p>For the lambda expression used in initializing the type-hint'ed variable, ctags +creates <tt class="docutils literal">anonymous</tt> extra tag ("anonFunc84011d2c0101"). ctags fills the +<tt class="docutils literal">nameref:</tt> field of "id_t" with the name of <tt class="docutils literal">anonymous</tt> extra tag: +"nameref:function:anonFunc84011d2c0101".</p> +<p>You may think why ctags does so complicated, and why ctags doesn't emit +following tags output for the input:</p> +<pre class="literal-block"> +id input.py /^id = \\$/;" function signature:(var0) +id_t input.py /^id_t: \\$/;" function typeref:typename:Callable[[int], int] signature:(var1) +</pre> +<p>There is a reason. The other languages of ctags obey the following rule: ctags fills +<tt class="docutils literal">typeref:</tt> field for a tag of a callable object (like function) with the type +of its return value. If we consider "id_t" is a function, its <tt class="docutils literal">typeref:</tt> field +should have "typename:int". However, for filling <tt class="docutils literal">typeref:</tt> with "typename:int", +ctags has to analyze "Callable[[int], int]" deeper. We don't want to do so.</p> +</div> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-client-tools(7), ctags-lang-iPythonCell(7)</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-lang-r.7.html b/ctags/man/ctags-lang-r.7.html new file mode 100644 index 0000000..3ac7c5e --- /dev/null +++ b/ctags/man/ctags-lang-r.7.html @@ -0,0 +1,482 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-lang-r</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-lang-r"> +<span id="ctags-lang-r-7"></span> +<h1 class="title">ctags-lang-r</h1> +<h2 class="subtitle" id="random-notes-about-tagging-r-source-code-with-universal-ctags">Random notes about tagging R source code with Universal Ctags</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> ... --languages=+R ...</div> +<div class="line"><strong>ctags</strong> ... --language-force=R ...</div> +<div class="line"><strong>ctags</strong> ... --map-Python=+.r ...</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>This man page gathers random notes about tagging R source code +with Universal Ctags.</p> +</div> +<div class="section" id="kinds"> +<h1>Kinds</h1> +<p>If a variable gets a value returned from a <em>well-known constructor</em> +and the variable appears for the first time in the current input file, +the R parser makes a tag for the variable and attaches a kind +associated with the constructor to the tag regardless of whether +the variable appears in the top-level context or a function.</p> +<p>Well-known constructor and kind mapping</p> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="40%" /> +<col width="60%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">Constructor</th> +<th class="head">kind</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>function()</td> +<td>function</td> +</tr> +<tr><td>c()</td> +<td>vector</td> +</tr> +<tr><td>list()</td> +<td>list</td> +</tr> +<tr><td>data.frame()</td> +<td>dataframe</td> +</tr> +</tbody> +</table> +</blockquote> +<p>If a variable doesn't get a value returned from one of well-known +constructors, the R parser attaches <tt class="docutils literal">globalVar</tt> or <tt class="docutils literal">functionVar</tt> kind +to the tag for the variable depending on the context.</p> +<p>Here is an example demonstrating the usage of the kinds:</p> +<p>"input.r"</p> +<pre class="code R literal-block"> +<span class="name">G</span> <span class="operator"><-</span> <span class="literal number">1</span> +<span class="name">v</span> <span class="operator"><-</span> <span class="name function">c</span><span class="punctuation">(</span><span class="literal number">1</span><span class="punctuation">,</span> <span class="literal number">2</span><span class="punctuation">)</span> +<span class="name">l</span> <span class="operator"><-</span> <span class="name function">list</span><span class="punctuation">(</span><span class="literal number">3</span><span class="punctuation">,</span> <span class="literal number">4</span><span class="punctuation">)</span> +<span class="name">d</span> <span class="operator"><-</span> <span class="name function">data.frame</span><span class="punctuation">(</span><span class="name">n</span> <span class="operator">=</span> <span class="name">v</span><span class="punctuation">)</span> +<span class="name">f</span> <span class="operator"><-</span> <span class="name function">function</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">)</span> <span class="punctuation">{</span> + <span class="name">g</span> <span class="operator"><-</span> <span class="name function">function </span><span class="punctuation">(</span><span class="name">b</span><span class="punctuation">)</span> <span class="name">a</span> <span class="operator">+</span> <span class="name">b</span> + <span class="name">w</span> <span class="operator"><-</span> <span class="name function">c</span><span class="punctuation">(</span><span class="literal number">1</span><span class="punctuation">,</span> <span class="literal number">2</span><span class="punctuation">)</span> + <span class="name">m</span> <span class="operator"><-</span> <span class="name function">list </span><span class="punctuation">(</span><span class="literal number">3</span><span class="punctuation">,</span> <span class="literal number">4</span><span class="punctuation">)</span> + <span class="name">e</span> <span class="operator"><-</span> <span class="name function">data.frame</span><span class="punctuation">(</span><span class="name">n</span> <span class="operator">=</span> <span class="name">w</span><span class="punctuation">)</span> + <span class="name">L</span> <span class="operator"><-</span> <span class="literal number">2</span> +<span class="punctuation">}</span> +</pre> +<p>"output.tags" +with "--options=NONE --sort=no --fields=+KZ -o - input.r"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-r.7.rst</tt>, line 68)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + G input.r /^G <- 1$/;" globalVar + v input.r /^v <- c(1, 2)$/;" vector + l input.r /^l <- list(3, 4)$/;" list + d input.r /^d <- data.frame(n = v)$/;" dataframe + n input.r /^d <- data.frame(n = v)$/;" nameattr scope:dataframe:d + f input.r /^f <- function(a) {$/;" function + g input.r /^ g <- function (b) a + b$/;" function scope:function:f + w input.r /^ w <- c(1, 2)$/;" vector scope:function:f + m input.r /^ m <- list (3, 4)$/;" list scope:function:f + e input.r /^ e <- data.frame(n = w)$/;" dataframe scope:function:f + n input.r /^ e <- data.frame(n = w)$/;" nameattr scope:dataframe:f.e + L input.r /^ L <- 2$/;" functionVar scope:function:f + +</pre> +</div> +<!-- TODO: + +- other kinds +- operators for assignment, <-, <<-, ->>, ->, = +- illuminating duplicated tags +- fields (constructor, assignmentop) +- sub parsers --> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1)</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-lang-sql.7.html b/ctags/man/ctags-lang-sql.7.html new file mode 100644 index 0000000..c2245b5 --- /dev/null +++ b/ctags/man/ctags-lang-sql.7.html @@ -0,0 +1,518 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-lang-sql</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-lang-sql"> +<span id="ctags-lang-sql-7"></span> +<h1 class="title">ctags-lang-sql</h1> +<h2 class="subtitle" id="the-man-page-of-the-sql-parser-for-universal-ctags">The man page of the SQL parser for Universal Ctags</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> ... [--extras={guest}] --languages=+SQL ...</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>The SQL parser supports various SQL dialects. PostgreSQL is one of them.</p> +<p>PostgreSQL allows user-defined functions to be written in other +languages (<em>procedural languages</em>) besides SQL and C <a class="citation-reference" href="#pl" id="id1">[PL]</a>.</p> +<p>The SQL parser makes tags for language objects in the user-defined +functions written in the procedural languages if the <tt class="docutils literal">guest</tt> extra +is enabled.</p> +<p>The SQL parser looks for a token coming after <tt class="docutils literal">LANGUAGE</tt> keyword in +the source code to choose a proper guest parser.</p> +<pre class="code SQL literal-block"> +<span class="punctuation">...</span> <span class="keyword">LANGUAGE</span> <span class="name">plpythonu</span> <span class="keyword">AS</span> <span class="literal string single">'... user-defined function '</span> <span class="punctuation">...</span> +<span class="punctuation">...</span> <span class="keyword">AS</span> <span class="error">$$</span> <span class="keyword">user</span><span class="operator">-</span><span class="keyword">defined</span> <span class="keyword">function</span> <span class="error">$$</span> <span class="keyword">LANGUAGE</span> <span class="name">plv8</span> <span class="punctuation">...</span> +</pre> +<p>In the above examples, <tt class="docutils literal">plpythonu</tt> and <tt class="docutils literal">plv8</tt> are the names of +procedural languages. The SQL parser trims <cite>pl</cite> at the start and <cite>u</cite> +at the end of the name before finding a parser ctags having. For +<tt class="docutils literal">plpythonu</tt> and <tt class="docutils literal">`plv8</tt>, the SQL parser extracts <tt class="docutils literal">python</tt> and +<tt class="docutils literal">v8</tt> as the candidates of guest parsers.</p> +<p>For <tt class="docutils literal">plpythonu</tt>, ctags can run its Python parser. ctags doesn't +have a parser named <tt class="docutils literal">v8</tt>. However, JavaScript parser of ctags has +<tt class="docutils literal">v8</tt> as an alias. So ctags can run the JavaScript parser as the +guest parser for <tt class="docutils literal">plv8</tt>.</p> +</div> +<div class="section" id="examples"> +<h1>EXAMPLES</h1> +<p>tagging code including a user-defined function in a string literal <a class="citation-reference" href="#gh3006" id="id2">[GH3006]</a>:</p> +<p>"input.sql"</p> +<pre class="code SQL literal-block"> +<span class="keyword">CREATE</span> <span class="keyword">OR</span> <span class="keyword">REPLACE</span> <span class="keyword">FUNCTION</span> <span class="name">fun1</span><span class="punctuation">()</span> <span class="keyword">RETURNS</span> <span class="name builtin">VARCHAR</span> <span class="keyword">AS</span> <span class="literal string single">' +DECLARE + test1_var1 VARCHAR(64) := $$ABC$$; + test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$; + test1_var3 INTEGER := 1; +BEGIN + RETURN TO_CHAR(test_var3, ''000'') || test1_var1 || test1_var2; +END; +'</span> <span class="keyword">LANGUAGE</span> <span class="name">plpgsql</span><span class="punctuation">;</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-sql.7.rst</tt>, line 70)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + fun1 input.sql /^CREATE OR REPLACE FUNCTION fun1() RETURNS VARCHAR AS '$/;" f + test1_var1 input.sql /^ test1_var1 VARCHAR(64) := $$ABC$$;$/;" v + test1_var2 input.sql /^ test1_var2 VARCHAR(64) := $xyz$XYZ$xyz$;$/;" v + test1_var3 input.sql /^ test1_var3 INTEGER := 1;$/;" v + +</pre> +</div> +<p>tagging code including a user-defined function in a dollar quote <a class="citation-reference" href="#gh3006" id="id3">[GH3006]</a>:</p> +<p>"input.sql"</p> +<pre class="code SQL literal-block"> +<span class="keyword">CREATE</span> <span class="keyword">OR</span> <span class="keyword">REPLACE</span> <span class="keyword">FUNCTION</span> <span class="name">fun2</span><span class="punctuation">()</span> <span class="keyword">RETURNS</span> <span class="name builtin">VARCHAR</span> <span class="keyword">LANGUAGE</span> <span class="name">plpgsql</span> <span class="keyword">AS</span> <span class="error">$$</span> +<span class="keyword">DECLARE</span> + <span class="name">test2_var1</span> <span class="name builtin">VARCHAR</span><span class="punctuation">(</span><span class="literal number integer">64</span><span class="punctuation">)</span> <span class="punctuation">:</span><span class="operator">=</span> <span class="literal string single">'ABC2'</span><span class="punctuation">;</span> + <span class="name">test2_var2</span> <span class="name builtin">VARCHAR</span><span class="punctuation">(</span><span class="literal number integer">64</span><span class="punctuation">)</span> <span class="punctuation">:</span><span class="operator">=</span> <span class="literal string single">'XYZ2'</span><span class="punctuation">;</span> + <span class="name">test2_var3</span> <span class="name builtin">INTEGER</span> <span class="punctuation">:</span><span class="operator">=</span> <span class="literal number integer">2</span><span class="punctuation">;</span> +<span class="keyword">BEGIN</span> + <span class="keyword">RETURN</span> <span class="name">TO_CHAR</span><span class="punctuation">(</span><span class="name">test2_var3</span><span class="punctuation">,</span> <span class="literal string single">'000'</span><span class="punctuation">)</span> <span class="operator">||</span> <span class="name">test2_var1</span> <span class="operator">||</span> <span class="name">test2_var2</span><span class="punctuation">;</span> +<span class="keyword">END</span><span class="punctuation">;</span> +<span class="error">$$</span><span class="punctuation">;</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-sql.7.rst</tt>, line 96)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + fun2 input.sql /^CREATE OR REPLACE FUNCTION fun2() RETURNS VARCHAR LANGUAGE plpgsql AS $\$$/;" f + test2_var1 input.sql /^ test2_var1 VARCHAR(64) := 'ABC2';$/;" v + test2_var2 input.sql /^ test2_var2 VARCHAR(64) := 'XYZ2';$/;" v + test2_var3 input.sql /^ test2_var3 INTEGER := 2;$/;" v + +</pre> +</div> +<p>tagging code including a user-defined written in JavaScript:</p> +<pre class="code SQL literal-block"> +<span class="comment single">-- Derived from https://github.com/plv8/plv8/blob/r3.0alpha/sql/plv8.sql +</span><span class="keyword">CREATE</span> <span class="keyword">FUNCTION</span> <span class="name">test</span><span class="punctuation">(</span><span class="name">keys</span> <span class="name builtin">text</span><span class="punctuation">[],</span> <span class="name">vals</span> <span class="name builtin">text</span><span class="punctuation">[])</span> <span class="keyword">RETURNS</span> <span class="name builtin">text</span> <span class="keyword">AS</span> +<span class="error">$$</span> + <span class="name">var</span> <span class="name">o</span> <span class="operator">=</span> <span class="error">{}</span><span class="punctuation">;</span> + <span class="keyword">for</span> <span class="punctuation">(</span><span class="name">var</span> <span class="name">i</span> <span class="operator">=</span> <span class="literal number integer">0</span><span class="punctuation">;</span> <span class="name">i</span> <span class="operator"><</span> <span class="name">keys</span><span class="punctuation">.</span><span class="keyword">length</span><span class="punctuation">;</span> <span class="name">i</span><span class="operator">++</span><span class="punctuation">)</span> + <span class="name">o</span><span class="punctuation">[</span><span class="name">keys</span><span class="punctuation">[</span><span class="name">i</span><span class="punctuation">]]</span> <span class="operator">=</span> <span class="name">vals</span><span class="punctuation">[</span><span class="name">i</span><span class="punctuation">];</span> + <span class="keyword">return</span> <span class="name">JSON</span><span class="punctuation">.</span><span class="name">stringify</span><span class="punctuation">(</span><span class="name">o</span><span class="punctuation">);</span> +<span class="error">$$</span> +<span class="keyword">LANGUAGE</span> <span class="name">plv8</span> <span class="keyword">IMMUTABLE</span> <span class="keyword">STRICT</span><span class="punctuation">;</span> +</pre> +<p>"output.tags" +with "--options=NONE -o - --sort=no --extras=+{guest} input.sql"</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-lang-sql.7.rst</tt>, line 120)</p> +<p>Cannot analyze code. No Pygments lexer found for "tags".</p> +<pre class="literal-block"> +.. code-block:: tags + + test input.sql /^CREATE FUNCTION test(keys text[], vals text[]) RETURNS text AS$/;" f + o input.sql /^ var o = {};$/;" v + +</pre> +</div> +</div> +<div class="section" id="known-bugs"> +<h1>KNOWN BUGS</h1> +<p>Escape sequences (<cite>''</cite>) in a string literal may make a guest parser confused.</p> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-client-tools(7)</p> +</div> +<div class="section" id="references"> +<h1>REFERENCES</h1> +<table class="docutils citation" frame="void" id="pl" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label"><a class="fn-backref" href="#id1">[PL]</a></td><td>PostgreSQL 9.5.25 Documentation, "Chapter 39. Procedural Languages", <a class="reference external" href="https://www.postgresql.org/docs/9.5/xplang.html">https://www.postgresql.org/docs/9.5/xplang.html</a></td></tr> +</tbody> +</table> +<table class="docutils citation" frame="void" id="gh3006" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label">[GH3006]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> @bagl's comment submitted to <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/3006">https://github.com/universal-ctags/ctags/issues/3006</a></td></tr> +</tbody> +</table> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-lang-verilog.7.html b/ctags/man/ctags-lang-verilog.7.html new file mode 100644 index 0000000..45f5f66 --- /dev/null +++ b/ctags/man/ctags-lang-verilog.7.html @@ -0,0 +1,569 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-lang-verilog</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-lang-verilog"> +<span id="ctags-lang-verilog-7"></span> +<h1 class="title">ctags-lang-verilog</h1> +<h2 class="subtitle" id="the-man-page-about-systemverilog-verilog-parser-for-universal-ctags">The man page about SystemVerilog/Verilog parser for Universal Ctags</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> ... [--kinds-systemverilog=+Q] [--fields-SystemVerilog=+{parameter}] ...</div> +<div class="line"><strong>ctags</strong> ... [--fields-Verilog=+{parameter}] ...</div> +</div> +<blockquote> +<table border="1" class="docutils"> +<colgroup> +<col width="31%" /> +<col width="31%" /> +<col width="39%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">Language</th> +<th class="head">Language ID</th> +<th class="head">File Mapping</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>SystemVerilog</td> +<td>SystemVerilog</td> +<td>.sv, .svh, svi</td> +</tr> +<tr><td>Verilog</td> +<td>Verilog</td> +<td>.v</td> +</tr> +</tbody> +</table> +</blockquote> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>This man page describes about the SystemVerilog/Verilog parser for Universal Ctags. +SystemVerilog parser supports IEEE Std 1800-2017 keywords. +Verilog parser supports IEEE Std 1364-2005 keywords.</p> +<div class="section" id="supported-kinds"> +<h2>Supported Kinds</h2> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --list-kinds-full<span class="operator">=</span>SystemVerilog +<span class="generic prompt">#</span>LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="generic output">A assert yes no 0 NONE assertions (assert, assume, cover, restrict) +C class yes no 0 NONE classes +E enum yes no 0 NONE enumerators +H checker yes no 0 NONE checkers +I interface yes no 0 NONE interfaces +K package yes no 0 NONE packages +L clocking yes no 0 NONE clocking +M modport yes no 0 NONE modports +N nettype yes no 0 NONE nettype declarations +O constraint yes no 0 NONE constraints +P program yes no 0 NONE programs +Q prototype no no 0 NONE prototypes (extern, pure) +R property yes no 0 NONE properties +S struct yes no 0 NONE structs and unions +T typedef yes no 0 NONE type declarations +V covergroup yes no 0 NONE covergroups +b block yes no 0 NONE blocks (begin, fork) +c constant yes no 0 NONE constants (define, parameter, specparam, enum values) +e event yes no 0 NONE events +f function yes no 0 NONE functions +i instance yes no 0 NONE instances of module or interface +l ifclass yes no 0 NONE interface class +m module yes no 0 NONE modules +n net yes no 0 NONE net data types +p port yes no 0 NONE ports +q sequence yes no 0 NONE sequences +r register yes no 0 NONE variable data types +t task yes no 0 NONE tasks +w member yes no 0 NONE struct and union members</span> +</pre> +<p>Note that <tt class="docutils literal">prototype</tt> (<tt class="docutils literal">Q</tt>) is disabled by default.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --list-kinds-full<span class="operator">=</span>Verilog +<span class="generic prompt">#</span>LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="generic output">b block yes no 0 NONE blocks (begin, fork) +c constant yes no 0 NONE constants (define, parameter, specparam) +e event yes no 0 NONE events +f function yes no 0 NONE functions +i instance yes no 0 NONE instances of module +m module yes no 0 NONE modules +n net yes no 0 NONE net data types +p port yes no 0 NONE ports +r register yes no 0 NONE variable data types +t task yes no 0 NONE tasks</span> +</pre> +</div> +<div class="section" id="supported-language-specific-fields"> +<h2>Supported Language Specific Fields</h2> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --list-fields<span class="operator">=</span>Verilog +<span class="generic prompt">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="generic output">- parameter no Verilog --b no parameter whose value can be overridden. +</span><span class="generic prompt">$ </span>ctags --list-fields<span class="operator">=</span>SystemVerilog +<span class="generic prompt">#</span>LETTER NAME ENABLED LANGUAGE JSTYPE FIXED DESCRIPTION +<span class="generic output">- parameter no SystemVerilog --b no parameter whose value can be overridden.</span> +</pre> +<div class="section" id="parameter-field"> +<h3><tt class="docutils literal">parameter</tt> field</h3> +<p>If the field <tt class="docutils literal">parameter</tt> is enabled, a field <tt class="docutils literal">parameter:</tt> is added on a parameter whose +value can be overridden on an instantiated module, interface, or program. +This is useful for a editor plugin or extension to enable auto-instantiation of modules with +parameters which can be overridden.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags ... --fields-Verilog<span class="operator">=</span>+<span class="operator">{</span>parameter<span class="operator">}</span> ... +<span class="generic prompt">$ </span>ctags ... --fields-SystemVerilog<span class="operator">=</span>+<span class="operator">{</span>parameter<span class="operator">}</span> ... +</pre> +<p>On the following source code fields <tt class="docutils literal">parameter:</tt> are added on +parameters <tt class="docutils literal">P*</tt>, not on ones <tt class="docutils literal">L*</tt>. Note that <tt class="docutils literal">L4</tt> and <tt class="docutils literal">L6</tt> is declared by +<tt class="docutils literal">parameter</tt> statement, but fields <tt class="docutils literal">parameter:</tt> are not added, +because they cannot be overridden.</p> +<p>"input.sv"</p> +<pre class="code systemverilog literal-block"> +<span class="comment single">// compilation unit scope +</span><span class="keyword">parameter</span> <span class="name">L1</span> <span class="operator">=</span> <span class="literal string">"synonym for the localparam"</span><span class="punctuation">;</span> + +<span class="keyword">module</span> <span class="name">with_parameter_port_list</span> <span class="punctuation">#(</span> + <span class="name">P1</span><span class="punctuation">,</span> + <span class="keyword">localparam</span> <span class="name">L2</span> <span class="operator">=</span> <span class="name">P1</span><span class="operator">+</span><span class="literal number integer">1</span><span class="punctuation">,</span> + <span class="keyword">parameter</span> <span class="name">P2</span><span class="punctuation">)</span> + <span class="punctuation">(</span> <span class="comment multiline">/*port list...*/</span> <span class="punctuation">);</span> + <span class="keyword">parameter</span> <span class="name">L3</span> <span class="operator">=</span> <span class="literal string">"synonym for the localparam"</span><span class="punctuation">;</span> + <span class="keyword">localparam</span> <span class="name">L4</span> <span class="operator">=</span> <span class="literal string">"localparam"</span><span class="punctuation">;</span> + <span class="comment single">// ... +</span><span class="keyword">endmodule</span> + +<span class="keyword">module</span> <span class="name">with_empty_parameter_port_list</span> <span class="punctuation">#()</span> + <span class="punctuation">(</span> <span class="comment multiline">/*port list...*/</span> <span class="punctuation">);</span> + <span class="keyword">parameter</span> <span class="name">L5</span> <span class="operator">=</span> <span class="literal string">"synonym for the localparam"</span><span class="punctuation">;</span> + <span class="keyword">localparam</span> <span class="name">L6</span> <span class="operator">=</span> <span class="literal string">"localparam"</span><span class="punctuation">;</span> + <span class="comment single">// ... +</span><span class="keyword">endmodule</span> + +<span class="keyword">module</span> <span class="name">no_parameter_port_list</span> + <span class="punctuation">(</span> <span class="comment multiline">/*port list...*/</span> <span class="punctuation">);</span> + <span class="keyword">parameter</span> <span class="name">P3</span> <span class="operator">=</span> <span class="literal string">"parameter"</span><span class="punctuation">;</span> + <span class="keyword">localparam</span> <span class="name">L7</span> <span class="operator">=</span> <span class="literal string">"localparam"</span><span class="punctuation">;</span> + <span class="comment single">// ... +</span><span class="keyword">endmodule</span> +</pre> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags -uo - --fields-SystemVerilog<span class="operator">=</span>+<span class="operator">{</span>parameter<span class="operator">}</span> input.sv +<span class="generic output">L1 input.sv /^parameter L1 = "synonym for the localparam";$/;" c parameter: +with_parameter_port_list input.sv /^module with_parameter_port_list #($/;" m +P1 input.sv /^ P1,$/;" c module:with_parameter_port_list parameter: +L2 input.sv /^ localparam L2 = P1+1,$/;" c module:with_parameter_port_list +P2 input.sv /^ parameter P2)$/;" c module:with_parameter_port_list parameter: +L3 input.sv /^ parameter L3 = "synonym for the localparam";$/;" c module:with_parameter_port_list +L4 input.sv /^ localparam L4 = "localparam";$/;" c module:with_parameter_port_list +with_empty_parameter_port_list input.sv /^module with_empty_parameter_port_list #()$/;" m +L5 input.sv /^ parameter L5 = "synonym for the localparam";$/;" c module:with_empty_parameter_port_list +L6 input.sv /^ localparam L6 = "localparam";$/;" c module:with_empty_parameter_port_list +no_parameter_port_list input.sv /^module no_parameter_port_list$/;" m +P3 input.sv /^ parameter P3 = "parameter";$/;" c module:no_parameter_port_list parameter: +L7 input.sv /^ localparam L7 = "localparam";$/;" c module:no_parameter_port_list</span> +</pre> +</div> +</div> +<div class="section" id="tips"> +<h2>TIPS</h2> +<p>If you want to map files <tt class="docutils literal">*.v</tt> to SystemVerilog, add +<tt class="docutils literal"><span class="pre">--langmap=SystemVerilog:.v</span></tt> option.</p> +</div> +</div> +<div class="section" id="known-issues"> +<h1>KNOWN ISSUES</h1> +<p>See <a class="reference external" href="https://github.com/universal-ctags/ctags/issues/2674">https://github.com/universal-ctags/ctags/issues/2674</a> for more information.</p> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<ul class="simple"> +<li>ctags(1)</li> +<li>ctags-client-tools(7)</li> +<li><dl class="first docutils"> +<dt>Language Reference Manuals (LRM)</dt> +<dd><ul class="first last"> +<li>IEEE Standard for SystemVerilog — Unified Hardware Design, Specification, and +Verification Language, IEEE Std 1800-2017, +<a class="reference external" href="https://ieeexplore.ieee.org/document/8299595">https://ieeexplore.ieee.org/document/8299595</a></li> +<li>IEEE Standard for Verilog Hardware Description Language, IEEE Std 1364-2005, +<a class="reference external" href="https://ieeexplore.ieee.org/document/1620780">https://ieeexplore.ieee.org/document/1620780</a></li> +</ul> +</dd> +</dl> +</li> +</ul> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags-optlib.7.html b/ctags/man/ctags-optlib.7.html new file mode 100644 index 0000000..6c3e742 --- /dev/null +++ b/ctags/man/ctags-optlib.7.html @@ -0,0 +1,785 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags-optlib</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags-optlib"> +<span id="ctags-optlib-7"></span> +<h1 class="title">ctags-optlib</h1> +<h2 class="subtitle" id="universal-ctags-parser-definition-language">Universal Ctags parser definition language</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">7</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [options] [file(s)]</div> +<div class="line"><strong>etags</strong> [options] [file(s)]</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p><em>Exuberant Ctags</em>, the ancestor of <em>Universal Ctags</em>, has provided +the way to define a new parser from command line. Universal Ctags +extends and refines this feature. <em>optlib parser</em> is the name for such +parser in Universal Ctags. "opt" intends a parser is defined with +combination of command line options. "lib" intends an optlib parser +can be more than ad-hoc personal configuration.</p> +<p>This man page is for people who want to define an optlib parser. The +readers should read ctags(1) of Universal Ctags first.</p> +<p>Following options are for defining (or customizing) a parser:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">--langdef=<name></span></tt></li> +<li><tt class="docutils literal"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></tt></li> +<li><tt class="docutils literal"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></tt></li> +<li><tt class="docutils literal"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt></li> +<li><tt class="docutils literal"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt></li> +</ul> +<p>Following options are for controlling loading parser definition:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">--options=<pathname></span></tt></li> +<li><tt class="docutils literal"><span class="pre">--options-maybe=<pathname></span></tt></li> +<li><tt class="docutils literal"><span class="pre">--optlib-dir=[+]<directory></span></tt></li> +</ul> +<p>The design of options and notations for defining a parser in +Exuberant Ctags may focus on reducing the number of typing by user. +Reducing the number of typing is important for users who want to +define (or customize) a parser quickly.</p> +<p>On the other hand, the design in Universal Ctags focuses on +maintainability. The notation of Universal Ctags is redundant than +that of Exuberant Ctags; the newly introduced kind should be declared +explicitly, (long) names are approved than one-letter flags +specifying kinds, and naming rules are stricter.</p> +<p>This man page explains only stable options and flags. Universal Ctags +also introduces experimental options and flags which have names starting +with <tt class="docutils literal">_</tt>. For documentation on these options and flags, visit +Universal Ctags web site at <a class="reference external" href="https://ctags.io/">https://ctags.io/</a>.</p> +<div class="section" id="storing-a-parser-definition-to-a-file"> +<h2>Storing a parser definition to a file</h2> +<p>Though it is possible to define a parser from command line, you don't +want to type the same command line each time when you need the parser. +You can store options for defining a parser into a file.</p> +<p>ctags loads files (preload files) listed in "FILES" +section of ctags(1) at program starting up. You can put your parser +definition needed usually to the files.</p> +<p><tt class="docutils literal"><span class="pre">--options=<pathname></span></tt>, <tt class="docutils literal"><span class="pre">--options-maybe=<pathname></span></tt>, and +<tt class="docutils literal"><span class="pre">--optlib-dir=[+]<directory></span></tt> are for loading optlib files you need +occasionally. See "Option File Options" section of ctags(1) for +these options.</p> +<p>As explained in "FILES" section of ctags(1), options for defining a +parser listed line by line in an optlib file. Prefixed white spaces are +ignored. A line starting with '#' is treated as a comment. Escaping +shell meta character is not needed.</p> +<p>Use <tt class="docutils literal">.ctags</tt> as file extension for optlib file. You can define +multiple parsers in an optlib file but it is better to make a file for +each parser definition.</p> +<p><tt class="docutils literal"><span class="pre">--_echo=<msg></span></tt> and <tt class="docutils literal"><span class="pre">--_force-quit=<num></span></tt> options are for debugging +optlib parser.</p> +</div> +<div class="section" id="overview-for-defining-a-parser"> +<h2>Overview for defining a parser</h2> +<ol class="arabic"> +<li><p class="first">Design the parser</p> +<p>You need know both the target language and the ctags' +concepts (definition, reference, kind, role, field, extra). About +the concepts, ctags(1) of Universal Ctags may help you.</p> +</li> +<li><p class="first">Give a name to the parser</p> +<p>Use <tt class="docutils literal"><span class="pre">--langdef=<name></span></tt> option. <em><name></em> is referred as <em><LANG></em> in +the later steps.</p> +</li> +<li><p class="first">Give a file pattern or file extension for activating the parser</p> +<p>Use <tt class="docutils literal"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></tt>.</p> +</li> +<li><p class="first">Define kinds</p> +<p>Use <tt class="docutils literal"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></tt> option. +Universal Ctags introduces this option. Exuberant Ctags doesn't +have. In Exuberant Ctags, a kind is defined as a side effect of +specifying <tt class="docutils literal"><span class="pre">--regex-<LANG>=</span></tt> option. So user doesn't have a +chance to recognize how important the definition of kind.</p> +</li> +<li><p class="first">Define patterns</p> +<p>Use <tt class="docutils literal"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt> +option for a single-line regular expression. You can also use +<tt class="docutils literal"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt> +option for a multi-line regular expression.</p> +<p>As <em><kind-spec></em>, you can use the one-letter flag defined with +<tt class="docutils literal"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></tt> option.</p> +</li> +</ol> +</div> +</div> +<div class="section" id="options"> +<h1>OPTIONS</h1> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--langdef=<name></span></tt></dt> +<dd><p class="first">Defines a new user-defined language, <em><name></em>, to be parsed with regular +expressions. Once defined, <em><name></em> may be used in other options taking +language names.</p> +<p><em><name></em> must consist of alphanumeric characters, '<tt class="docutils literal">#</tt>', or '<tt class="docutils literal">+</tt>' +('[a-zA-Z0-9#+]+'). The graph characters other than '<tt class="docutils literal">#</tt>' and +'<tt class="docutils literal">+</tt>' are disallowed (or reserved). Some of them (<tt class="docutils literal"><span class="pre">[-=:{.]</span></tt>) are +disallowed because they can make the command line parser of +ctags confused. The rest of them are just +reserved for future extending ctags.</p> +<p><tt class="docutils literal">all</tt> is an exception. <tt class="docutils literal">all</tt> as <em><name></em> is not acceptable. It is +a reserved word. See the description of +<tt class="docutils literal"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></tt> option in ctags(1) about how the +reserved word is used.</p> +<p class="last">The names of built-in parsers are capitalized. When +ctags evaluates an option in a command line, and +chooses a parser, ctags uses the names of +parsers in a case-insensitive way. Therefore, giving a name +started from a lowercase character doesn't help you to avoid the +parser name confliction. However, in a tags file, +ctags prints parser names in a case-sensitive +way; it prints a parser name as specified in <tt class="docutils literal"><span class="pre">--langdef=<name></span></tt> +option. Therefore, we recommend you to give a name started from a +lowercase character to your private optlib parser. With this +convention, people can know where a tag entry in a tag file comes +from a built-in parser or a private optlib parser.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></tt></dt> +<dd><p class="first">Define a kind for <em><LANG></em>. +Be not confused this with <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt>.</p> +<p><em><letter></em> must be an alphabetical character ('[a-zA-EG-Z]') +other than "F". "F" has been reserved for representing a file +since Exuberant Ctags.</p> +<p><em><name></em> must start with an alphabetic character, and the rest +must be alphanumeric ('[a-zA-Z][a-zA-Z0-9]*'). Do not use +"file" as <em><name></em>. It has been reserved for representing a file +since Exuberant Ctags.</p> +<p>Note that using a number character in a <em><name></em> violates the +version 2 of tags file format though ctags +accepts it. For more detail, see tags(5).</p> +<p><em><description></em> comes from any printable ASCII characters. The +exception is <tt class="docutils literal">{</tt> and <tt class="docutils literal">\</tt>. <tt class="docutils literal">{</tt> is reserved for adding flags +this option in the future. So put <tt class="docutils literal">\</tt> before <tt class="docutils literal">{</tt> to include +<tt class="docutils literal">{</tt> to a description. To include <tt class="docutils literal">\</tt> itself to a description, +put <tt class="docutils literal">\</tt> before <tt class="docutils literal">\</tt>.</p> +<p>Both <em><letter></em>, <em><name></em> and their combination must be unique in +a <em><LANG></em>.</p> +<p>This option is newly introduced in Universal Ctags. This option +reduces the typing defining a regex pattern with +<tt class="docutils literal"><span class="pre">--regex-<LANG>=</span></tt>, and keeps the consistency of kind +definitions in a language.</p> +<p>The <em><letter></em> can be used as an argument for <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt> +option to enable or disable the kind. Unless <tt class="docutils literal">K</tt> field is +enabled, the <em><letter></em> is used as value in the "kind" extension +field in tags output.</p> +<p>The <em><name></em> surrounded by braces can be used as an argument for +<tt class="docutils literal"><span class="pre">--kind-<LANG></span></tt> option. If <tt class="docutils literal">K</tt> field is enabled, the <em><name></em> +is used as value in the "kind" extension field in tags output.</p> +<p class="last">The <em><description></em> and <em><letter></em> are listed in <tt class="docutils literal"><span class="pre">--list-kinds</span></tt> +output. All three elements of the kind-spec are listed in +<tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt> output. Don't use braces in the +<em><description></em>. They will be used meta characters in the future.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt></dt> +<dd><p class="first">Define a single-line regular expression.</p> +<p>The <em>/<line_pattern>/<name_pattern>/</em> pair defines a regular expression +replacement pattern, similar in style to <tt class="docutils literal">sed</tt> substitution +commands, <tt class="docutils literal">s/regexp/replacement/</tt>, with which to generate tags from source files mapped to +the named language, <em><LANG></em>, (case-insensitive; either a built-in +or user-defined language).</p> +<p>The regular expression, <em><line_pattern></em>, defines +an extended regular expression (roughly that used by egrep(1)), +which is used to locate a single source line containing a tag and +may specify tab characters using <tt class="docutils literal">\t</tt>.</p> +<p>When a matching line is +found, a tag will be generated for the name defined by +<em><name_pattern></em>, which generally will contain the special +back-references <tt class="docutils literal">\1</tt> through <tt class="docutils literal">\9</tt> to refer to matching sub-expression +groups within <em><line_pattern></em>.</p> +<p>The '<tt class="docutils literal">/</tt>' separator characters shown in the +parameter to the option can actually be replaced by any +character. Note that whichever separator character is used will +have to be escaped with a backslash ('<tt class="docutils literal">\</tt>') character wherever it is +used in the parameter as something other than a separator. The +regular expression defined by this option is added to the current +list of regular expressions for the specified language unless the +parameter is omitted, in which case the current list is cleared.</p> +<p>Unless modified by <em><flags></em>, <em><line_pattern></em> is interpreted as a POSIX +extended regular expression. The <em><name_pattern></em> should expand for all +matching lines to a non-empty string of characters, or a warning +message will be reported unless <tt class="docutils literal">{placeholder}</tt> regex flag is +specified.</p> +<p>A kind specifier (<em><kind-spec></em>) for tags matching regexp may +follow <em><name_pattern></em>, which will determine what kind of tag is +reported in the <tt class="docutils literal">kind</tt> extension field (see tags(5)).</p> +<p><em><kind-spec></em> has two forms: <em>one-letter form</em> and <em>full form</em>.</p> +<p>The one-letter form in the form of <tt class="docutils literal"><letter></tt>. It just refers a kind +<em><letter></em> defined with <tt class="docutils literal"><span class="pre">--kinddef-<LANG></span></tt>. This form is recommended in +Universal Ctags.</p> +<p>The full form of <em><kind-spec></em> is in the form of +<tt class="docutils literal"><span class="pre"><letter>,<name>,<description></span></tt>. Either the kind <em><name></em> and/or the +<em><description></em> can be omitted. See the description of +<tt class="docutils literal"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></tt> option about the +elements.</p> +<p>The full form is supported only for keeping the compatibility with Exuberant +Ctags which does not have <tt class="docutils literal"><span class="pre">--kinddef-<LANG></span></tt> option. Supporting the +form will be removed from Universal Ctags in the future.</p> +<!-- MEMO: the following line is commented out +If *<kind-spec>* is omitted, it defaults to ``r,regex``. --> +<p>About <em><flags></em>, see "FLAGS FOR <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> OPTION".</p> +<p class="last">For more information on the regular expressions used by +ctags, see either the regex(5,7) man page, or +the GNU info documentation for regex (e.g. "<tt class="docutils literal">info regex</tt>").</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-regex-flags</span></tt></dt> +<dd>Lists the flags that can be used in <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> option.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-mline-regex-flags</span></tt></dt> +<dd>Lists the flags that can be used in <tt class="docutils literal"><span class="pre">--mline-regex-<LANG></span></tt> option.</dd> +<dt><tt class="docutils literal"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt></dt> +<dd><p class="first">Define a multi-line regular expression.</p> +<p class="last">This option is similar to <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> option except the pattern is +applied to the whole file’s contents, not line by line.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--_echo=<message></span></tt></dt> +<dd>Print <em><message></em> to the standard error stream. This is helpful to +understand (and debug) optlib loading feature of Universal Ctags.</dd> +<dt><tt class="docutils literal"><span class="pre">--_force-quit[=<num>]</span></tt></dt> +<dd>Exits immediately when this option is processed. If <em><num></em> is used +as exit status. The default is 0. This is helpful to debug optlib +loading feature of Universal Ctags.</dd> +</dl> +<div class="section" id="flags-for-regex-lang-option"> +<h2>FLAGS FOR <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> OPTION</h2> +<p>You can specify more than one flag, <tt class="docutils literal"><span class="pre"><letter>|{<name>}</span></tt>, at the end of <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> to +control how Universal Ctags uses the pattern.</p> +<p>Exuberant Ctags uses a <em><letter></em> to represent a flag. In +Universal Ctags, a <em><name></em> surrounded by braces (name form) can be used +in addition to <em><letter></em>. The name form makes a user reading an optlib +file easier.</p> +<p>The most of all flags newly added in Universal Ctags +don't have the one-letter representation. All of them have only the name +representation. <tt class="docutils literal"><span class="pre">--list-regex-flags</span></tt> lists all the flags.</p> +<dl class="docutils"> +<dt><tt class="docutils literal">basic</tt> (one-letter form <tt class="docutils literal">b</tt>)</dt> +<dd>The pattern is interpreted as a POSIX basic regular expression.</dd> +<dt><tt class="docutils literal">exclusive</tt> (one-letter form <tt class="docutils literal">x</tt>)</dt> +<dd>Skip testing the other patterns if a line is matched to this +pattern. This is useful to avoid using CPU to parse line comments.</dd> +<dt><tt class="docutils literal">extend</tt> (one-letter form <tt class="docutils literal">e</tt>)</dt> +<dd>The pattern is interpreted as a POSIX extended regular +expression (default).</dd> +<dt><tt class="docutils literal">icase</tt> (one-letter form <tt class="docutils literal">i</tt>)</dt> +<dd>The regular expression is to be applied in a case-insensitive +manner.</dd> +<dt><tt class="docutils literal">placeholder</tt></dt> +<dd>Don't emit a tag captured with a regex pattern. The replacement +can be an empty string. See the following description of +<tt class="docutils literal"><span class="pre">scope=...</span></tt> flag about how this is useful.</dd> +</dl> +<p><tt class="docutils literal"><span class="pre">scope=(ref|push|pop|clear|set)</span></tt></p> +<blockquote> +<p>Specify what to do with the internal scope stack.</p> +<p>A parser programmed with <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> has a stack (scope +stack) internally. You can use it for tracking scope +information. The <tt class="docutils literal"><span class="pre">scope=...</span></tt> flag is for manipulating and +utilizing the scope stack.</p> +<p>If <tt class="docutils literal">{scope=push}</tt> is specified, a tag captured with +<tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> is pushed to the stack. <tt class="docutils literal">{scope=push}</tt> +implies <tt class="docutils literal">{scope=ref}</tt>.</p> +<p>You can fill the scope field of captured tag with +<tt class="docutils literal">{scope=ref}</tt>. If <tt class="docutils literal">{scope=ref}</tt> flag is given, +ctags attaches the tag at the top to the tag +captured with <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> as the value for the <tt class="docutils literal">scope:</tt> +field.</p> +<p>ctags pops the tag at the top of the stack when +<tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> with <tt class="docutils literal">{scope=pop}</tt> is matched to the input +line.</p> +<p>Specifying <tt class="docutils literal">{scope=clear}</tt> removes all the tags in the scope. +Specifying <tt class="docutils literal">{scope=set}</tt> removes all the tags in the scope, and +then pushes the captured tag as <tt class="docutils literal">{scope=push}</tt> does.</p> +<p>In some cases, you may want to use <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> only for its +side effects: using it only to manipulate the stack but not for +capturing a tag. In such a case, make <em><name_pattern></em> component of +<tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> option empty while specifying <tt class="docutils literal">{placeholder}</tt> +as a regex flag. For example, a non-named tag can be put on +the stack by giving a regex flag "<tt class="docutils literal"><span class="pre">{scope=push}{placeholder}</span></tt>".</p> +<p>You may wonder what happens if a regex pattern with +<tt class="docutils literal">{scope=ref}</tt> flag matches an input line but the stack is empty, +or a non-named tag is at the top. If the regex pattern contains a +<tt class="docutils literal">{scope=ref}</tt> flag and the stack is empty, the <tt class="docutils literal">{scope=ref}</tt> +flag is ignored and nothing is attached to the <tt class="docutils literal">scope:</tt> field.</p> +<p>If the top of the stack contains an unnamed tag, +ctags searches deeper into the stack to find the +top-most named tag. If it reaches the bottom of the stack without +finding a named tag, the <tt class="docutils literal">{scope=ref}</tt> flag is ignored and +nothing is attached to the <tt class="docutils literal">scope:</tt> field.</p> +<p>When a named tag on the stack is popped or cleared as the side +effect of a pattern matching, ctags attaches the +line number of the match to the <tt class="docutils literal">end:</tt> field of +the named tag.</p> +<p>ctags clears all of the tags on the stack when it +reaches the end of the input source file. The line number of the +end is attached to the <tt class="docutils literal">end:</tt> field of the cleared tags.</p> +</blockquote> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">warning=<message></span></tt></dt> +<dd>print the given <em><message></em> at WARNING level</dd> +<dt><tt class="docutils literal"><span class="pre">fatal=<message></span></tt></dt> +<dd>print the given <em><message></em> and exit</dd> +</dl> +</div> +</div> +<div class="section" id="examples"> +<h1>EXAMPLES</h1> +<div class="section" id="perl-pod"> +<h2>Perl Pod</h2> +<p>This is the definition (pod.ctags) used in ctags for parsing Pod +(<a class="reference external" href="https://perldoc.perl.org/perlpod.html">https://perldoc.perl.org/perlpod.html</a>) file.</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-optlib.7.rst</tt>, line 395)</p> +<p>Cannot analyze code. No Pygments lexer found for "ctags".</p> +<pre class="literal-block"> +.. code-block:: ctags + + --langdef=pod + --map-pod=+.pod + + --kinddef-pod=c,chapter,chapters + --kinddef-pod=s,section,sections + --kinddef-pod=S,subsection,subsections + --kinddef-pod=t,subsubsection,subsubsections + + --regex-pod=/^=head1[ \t]+(.+)/\1/c/ + --regex-pod=/^=head2[ \t]+(.+)/\1/s/ + --regex-pod=/^=head3[ \t]+(.+)/\1/S/ + --regex-pod=/^=head4[ \t]+(.+)/\1/t/ + +</pre> +</div> +</div> +<div class="section" id="using-scope-regex-flags"> +<h2>Using scope regex flags</h2> +<p>Let's think about writing a parser for a very small subset of the Ruby +language.</p> +<p>input source file (<tt class="docutils literal">input.srb</tt>):</p> +<pre class="literal-block"> +class Example + def methodA + puts "in class_method" + end + def methodB + puts "in class_method" + end +end +</pre> +<p>The parser for the input should capture <tt class="docutils literal">Example</tt> with <tt class="docutils literal">class</tt> kind, +<tt class="docutils literal">methodA</tt>, and <tt class="docutils literal">methodB</tt> with <tt class="docutils literal">method</tt> kind. <tt class="docutils literal">methodA</tt> and <tt class="docutils literal">methodB</tt> +should have <tt class="docutils literal">Example</tt> as their scope. <tt class="docutils literal">end:</tt> fields of each tag +should have proper values.</p> +<p>optlib file (<tt class="docutils literal"><span class="pre">sub-ruby.ctags</span></tt>):</p> +<div class="system-message"> +<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">ctags-optlib.7.rst</tt>, line 434)</p> +<p>Cannot analyze code. No Pygments lexer found for "ctags".</p> +<pre class="literal-block"> +.. code-block:: ctags + + --langdef=subRuby + --map-subRuby=.srb + --kinddef-subRuby=c,class,classes + --kinddef-subRuby=m,method,methods + --regex-subRuby=/^class[ \t]+([a-zA-Z][a-zA-Z0-9]+)/\1/c/{scope=push} + --regex-subRuby=/^end///{scope=pop}{placeholder} + --regex-subRuby=/^[ \t]+def[ \t]+([a-zA-Z][a-zA-Z0-9_]+)/\1/m/{scope=push} + --regex-subRuby=/^[ \t]+end///{scope=pop}{placeholder} + +</pre> +</div> +<p>command line and output:</p> +<pre class="literal-block"> +$ ctags --quiet --fields=+eK \ +--options=./sub-ruby.ctags -o - input.srb +Example input.srb /^class Example$/;" class end:8 +methodA input.srb /^ def methodA$/;" method class:Example end:4 +methodB input.srb /^ def methodB$/;" method class:Example end:7 +</pre> +</div> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>ctags(1), tags(5), regex(3), regex(7), egrep(1)</p> +</div> +<div class="section" id="author"> +<h1>AUTHOR</h1> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a> +(This man page partially derived from ctags(1) of +Executable-ctags)</p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert@users.sourceforge.net">dhiebert@users.sourceforge.net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/ctags.1.html b/ctags/man/ctags.1.html new file mode 100644 index 0000000..949814d --- /dev/null +++ b/ctags/man/ctags.1.html @@ -0,0 +1,2273 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>ctags</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="ctags"> +<span id="ctags-1"></span> +<h1 class="title">ctags</h1> +<h2 class="subtitle" id="generate-tag-files-for-source-code">Generate tag files for source code</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">1</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>ctags</strong> [<options>] [<source_file(s)>]</div> +<div class="line"><strong>etags</strong> [<options>] [<source_file(s)>]</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>The <em>ctags</em> and <em>etags</em> (see <tt class="docutils literal"><span class="pre">-e</span></tt> option) programs +(hereinafter collectively referred to as ctags, +except where distinguished) generate an index (or "tag") file for a +variety of <em>language objects</em> found in <em>source file(s)</em>. This tag file allows +these items to be quickly and easily located by a text editor or other +utilities (<em>client tools</em>). A <em>tag</em> signifies a language object for which an index entry is +available (or, alternatively, the index entry created for that object).</p> +<p>Alternatively, ctags can generate a cross reference +file which lists, in human readable form, information about the various +language objects found in a set of source files.</p> +<p>Tag index files are supported by numerous editors, which allow the user to +locate the object associated with a name appearing in a source file and +jump to the file and line which defines the name. See the manual of your +favorite editor about utilizing ctags command and +the tag index files in the editor.</p> +<p>ctags is capable of generating different <em>kinds</em> of tags +for each of many different <em>languages</em>. For a complete list of supported +languages, the names by which they are recognized, and the kinds of tags +which are generated for each, see the <tt class="docutils literal"><span class="pre">--list-languages</span></tt> and <tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt> +options.</p> +<p>This man page describes <em>Universal Ctags</em>, an implementation of ctags +derived from <em>Exuberant Ctags</em>. The major incompatible changes between +Universal Ctags and Exuberant Ctags are enumerated in +ctags-incompatibilities(7).</p> +<p>One of the advantages of Exuberant Ctags is that it allows a user to +define a new parser from the command line. Extending this capability is one +of the major features of Universal Ctags. ctags-optlib(7) +describes how the capability is extended.</p> +<p>Newly introduced experimental features are not explained here. If you +are interested in such features and ctags internals, +visit <a class="reference external" href="https://docs.ctags.io/">https://docs.ctags.io/</a>.</p> +</div> +<div class="section" id="command-line-interface"> +<h1>COMMAND LINE INTERFACE</h1> +<p>Despite the wealth of available options, defaults are set so that +ctags is most commonly executed without any options (e.g. +"<tt class="docutils literal">ctags *</tt>", or "<tt class="docutils literal">ctags <span class="pre">-R</span></tt>"), which will +create a tag file in the current directory for all recognized source +files. The options described below are provided merely to allow custom +tailoring to meet special needs.</p> +<p>Note that spaces separating the single-letter options from their parameters +are optional.</p> +<p>Note also that the boolean parameters to the long form options (those +beginning with <tt class="docutils literal"><span class="pre">--</span></tt> and that take a <tt class="docutils literal"><span class="pre">[=(yes|no)]</span></tt> parameter) may be omitted, +in which case <tt class="docutils literal">=yes</tt> is implied. (e.g. <tt class="docutils literal"><span class="pre">--sort</span></tt> is equivalent to <tt class="docutils literal"><span class="pre">--sort=yes</span></tt>). +Note further that <tt class="docutils literal">=1</tt>, <tt class="docutils literal">=on</tt>, and <tt class="docutils literal">=true</tt> are considered synonyms for <tt class="docutils literal">=yes</tt>, +and that <tt class="docutils literal">=0</tt>, <tt class="docutils literal">=off</tt>, and <tt class="docutils literal">=false</tt> are considered synonyms for <tt class="docutils literal">=no</tt>.</p> +<p>Some options are either ignored or useful only when used while running in +etags mode (see <tt class="docutils literal"><span class="pre">-e</span></tt> option). Such options will be noted.</p> +<p><em><options></em> must precede the <em><source_file(s)></em> following the standard POSIX +convention.</p> +<p>Options taking language names will accept those names in either upper or +lower case. See the <tt class="docutils literal"><span class="pre">--list-languages</span></tt> option for a complete list of the +built-in language names.</p> +<div class="section" id="letters-and-names"> +<h2>Letters and names</h2> +<p>Some options take one-letter flags as parameters (e.g. <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt> option). +Specifying just letters help a user create a complicated command line +quickly. However, a command line including sequences of one-letter flags +becomes difficult to understand.</p> +<p>Universal Ctags accepts long-name flags in +addition to such one-letter flags. The long-name and one-letter flags can be mixed in an +option parameter by surrounding each long-name by braces. Thus, for an +example, the following three notations for <tt class="docutils literal"><span class="pre">--kinds-C</span></tt> option have +the same meaning:</p> +<pre class="literal-block"> +--kinds-C=+pLl +--kinds-C=+{prototype}{label}{local} +--kinds-C=+{prototype}L{local} +</pre> +<p>Note that braces may be meta characters in your shell. Put +single quotes in such case.</p> +<p><tt class="docutils literal"><span class="pre">--list-...</span></tt> options shows one-letter flags and associated long-name flags.</p> +</div> +<div class="section" id="list-options"> +<h2>List options</h2> +<p>Universal Ctags introduces many <tt class="docutils literal"><span class="pre">--list-...</span></tt> options that provide +the internal data of Universal Ctags (See "<a class="reference internal" href="#listing-options">Listing Options</a>"). Both users and client tools may +use the data. <tt class="docutils literal"><span class="pre">--with-list-header</span></tt> and <tt class="docutils literal"><span class="pre">--machinable</span></tt> options +adjust the output of the most of <tt class="docutils literal"><span class="pre">--list-...</span></tt> options.</p> +<p>The default setting (<tt class="docutils literal"><span class="pre">--with-list-header=yes</span></tt> and <tt class="docutils literal"><span class="pre">--machinable=no</span></tt>) +is for using interactively from a terminal. The header that explains +the meaning of columns is simply added to the output, and each column is +aligned in all lines. The header line starts with a hash ('<tt class="docutils literal">#</tt>') character.</p> +<p>For scripting in a client tool, <tt class="docutils literal"><span class="pre">--with-list-header=no</span></tt> and +<tt class="docutils literal"><span class="pre">--machinable=yes</span></tt> may be useful. The header is not added to the +output, and each column is separated by tab characters.</p> +<p>Note the order of columns will change in the future release. +However, labels in the header will not change. So by scanning +the header, a client tool can find the index for the target +column.</p> +<!-- options that should be explained and revised here +``- -list-features`` (done) +``- -machinable`` (done) +``- -with-list-header`` (done) --> +</div> +</div> +<div class="section" id="options"> +<h1>OPTIONS</h1> +<p>ctags has more options than listed here. +Options starting with an underscore character, such as <tt class="docutils literal"><span class="pre">--_echo=<msg></span></tt>, +are not listed here. They are experimental or for debugging purpose.</p> +<p>Notation: <tt class="docutils literal"><foo></tt> is for a variable string <tt class="docutils literal">foo</tt>, <tt class="docutils literal">[ ... ]</tt> for optional, +<tt class="docutils literal">|</tt> for selection, and <tt class="docutils literal">( ... )</tt> for grouping. For example +<tt class="docutils literal"><span class="pre">--foo[=(yes|no)]''</span> means <span class="pre">``--foo</span></tt>, <tt class="docutils literal"><span class="pre">-foo=yes</span></tt>, or <tt class="docutils literal"><span class="pre">-foo=no</span></tt>.</p> +<div class="section" id="input-output-file-options"> +<span id="option-input-output-file"></span><h2>Input/Output File Options</h2> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--exclude=<pattern></span></tt></dt> +<dd><p class="first">Add <em><pattern></em> to a list of excluded files and directories. This option may +be specified as many times as desired. For each file name considered +by ctags, each pattern specified using this option +will be compared against both the complete path (e.g. +<tt class="docutils literal">some/path/base.ext</tt>) and the base name (e.g. <tt class="docutils literal">base.ext</tt>) of the file, thus +allowing patterns which match a given file name irrespective of its +path, or match only a specific path.</p> +<p>If appropriate support is available +from the runtime library of your C compiler, then pattern may +contain the usual shell wildcards (not regular expressions) common on +Unix (be sure to quote the option parameter to protect the wildcards from +being expanded by the shell before being passed to ctags; +also be aware that wildcards can match the slash character, '<tt class="docutils literal">/</tt>'). +You can determine if shell wildcards are available on your platform by +examining the output of the <tt class="docutils literal"><span class="pre">--list-features</span></tt> option, which will include +<tt class="docutils literal">wildcards</tt> in the compiled feature list; otherwise, pattern is matched +against file names using a simple textual comparison.</p> +<p>If <em><pattern></em> begins with the character '<tt class="docutils literal">@</tt>', then the rest of the string +is interpreted as a file name from which to read exclusion patterns, +one per line. If pattern is empty, the list of excluded patterns is +cleared.</p> +<p>Note that at program startup, the default exclude list contains names of +common hidden and system files, patterns for binary files, and directories +for which it is generally not desirable to descend while processing the +<tt class="docutils literal"><span class="pre">--recurse</span></tt> option. To see the list of built-in exclude patterns, use +<tt class="docutils literal"><span class="pre">--list-excludes</span></tt>.</p> +<p class="last">See also the description for <tt class="docutils literal"><span class="pre">--exclude-exception=</span></tt> option.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--exclude-exception=<pattern></span></tt></dt> +<dd><p class="first">Add <em><pattern></em> to a list of included files and directories. The pattern +affects the files and directories that are excluded by the pattern +specified with <tt class="docutils literal"><span class="pre">--exclude=</span></tt> option.</p> +<p class="last">For an example, you want ctags to ignore all files +under <tt class="docutils literal">foo</tt> directory except <tt class="docutils literal">foo/main.c</tt>, use the following command +line: <tt class="docutils literal"><span class="pre">--exclude=foo/*</span> <span class="pre">--exclude-exception=foo/main.c</span></tt>.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--filter[=(yes|no)]</span></tt></dt> +<dd>Makes ctags behave as a filter, reading source +file names from standard input and printing their tags to standard +output on a file-by-file basis. If <tt class="docutils literal"><span class="pre">--sort</span></tt> is enabled, tags are sorted +only within the source file in which they are defined. File names are +read from standard input in line-oriented input mode (see note for <tt class="docutils literal"><span class="pre">-L</span></tt> +option) and only after file names listed on the command line or from +any file supplied using the <tt class="docutils literal"><span class="pre">-L</span></tt> option. When this option is enabled, +the options <tt class="docutils literal"><span class="pre">-f</span></tt>, <tt class="docutils literal"><span class="pre">-o</span></tt>, and <tt class="docutils literal"><span class="pre">--totals</span></tt> are ignored. This option is quite +esoteric and is disabled by default.</dd> +<dt><tt class="docutils literal"><span class="pre">--filter-terminator=<string></span></tt></dt> +<dd><p class="first">Specifies a <em><string></em> to print to standard output following the tags for +each file name parsed when the <tt class="docutils literal"><span class="pre">--filter</span></tt> option is enabled. This may +permit an application reading the output of ctags +to determine when the output for each file is finished.</p> +<p>Note that if the +file name read is a directory and <tt class="docutils literal"><span class="pre">--recurse</span></tt> is enabled, this string will +be printed only once at the end of all tags found for by descending +the directory. This string will always be separated from the last tag +line for the file by its terminating newline.</p> +<p class="last">This option is quite esoteric and is empty by default.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--links[=(yes|no)]</span></tt></dt> +<dd>Indicates whether symbolic links (if supported) should be followed. +When disabled, symbolic links are ignored. This option is on by default.</dd> +<dt><tt class="docutils literal"><span class="pre">--maxdepth=<N></span></tt></dt> +<dd>Limits the depth of directory recursion enabled with the <tt class="docutils literal"><span class="pre">--recurse</span></tt> +(<tt class="docutils literal"><span class="pre">-R</span></tt>) option.</dd> +<dt><tt class="docutils literal"><span class="pre">--recurse[=(yes|no)]</span></tt></dt> +<dd><p class="first">Recurse into directories encountered in the list of supplied files.</p> +<p>If the list of supplied files is empty and no file list is specified with +the <tt class="docutils literal"><span class="pre">-L</span></tt> option, then the current directory (i.e. '<tt class="docutils literal">.</tt>') is assumed. +Symbolic links are followed by default (See <tt class="docutils literal"><span class="pre">--links</span></tt> option). If you don't like these behaviors, either +explicitly specify the files or pipe the output of <tt class="docutils literal">find(1)</tt> into +"<tt class="docutils literal">ctags <span class="pre">-L</span> -</tt>" instead. See, also, the <tt class="docutils literal"><span class="pre">--exclude</span></tt> and +<tt class="docutils literal"><span class="pre">--maxdepth</span></tt> to limit recursion.</p> +<p class="last">Note: This option is not supported on +all platforms at present. It is available if the output of the <tt class="docutils literal"><span class="pre">--help</span></tt> +option includes this option.</p> +</dd> +</dl> +<!-- TODO(code): - -list-features option should support this. --> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">-R</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--recurse</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">-L</span> <file></tt></dt> +<dd><p class="first">Read from <em><file></em> a list of file names for which tags should be generated.</p> +<p>If file is specified as '<tt class="docutils literal">-</tt>', then file names are read from standard +input. File names read using this option are processed following file +names appearing on the command line. Options are also accepted in this +input. If this option is specified more than once, only the last will +apply.</p> +<p class="last">Note: file is read in line-oriented mode, where a new line is +the only delimiter and non-trailing white space is considered significant, +in order that file names containing spaces may be supplied +(however, trailing white space is stripped from lines); this can affect +how options are parsed if included in the input.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--append[=(yes|no)]</span></tt></dt> +<dd>Indicates whether tags generated from the specified files should be +appended to those already present in the tag file or should replace them. +This option is <tt class="docutils literal">no</tt> by default.</dd> +<dt><tt class="docutils literal"><span class="pre">-a</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--append</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">-f</span> <tagfile></tt></dt> +<dd><p class="first">Use the name specified by <em><tagfile></em> for the tag file (default is "<tt class="docutils literal">tags</tt>", +or "<tt class="docutils literal">TAGS</tt>" when running in etags mode). If <em><tagfile></em> is specified as '<tt class="docutils literal">-</tt>', +then the tags are written to standard output instead.</p> +<p>ctags +will stubbornly refuse to take orders if tagfile exists and +its first line contains something other than a valid tags line. This +will save your neck if you mistakenly type "<tt class="docutils literal">ctags <span class="pre">-f</span> +*.c</tt>", which would otherwise overwrite your first C file with the tags +generated by the rest! It will also refuse to accept a multi-character +file name which begins with a '<tt class="docutils literal">-</tt>' (dash) character, since this most +likely means that you left out the tag file name and this option tried to +grab the next option as the file name. If you really want to name your +output tag file <tt class="docutils literal"><span class="pre">-ugly</span></tt>, specify it as "<tt class="docutils literal"><span class="pre">-f</span> <span class="pre">./-ugly</span></tt>".</p> +<p class="last">This option must +appear before the first file name. If this option is specified more +than once, only the last will apply.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">-o</span> <tagfile></tt></dt> +<dd>Equivalent to "<tt class="docutils literal"><span class="pre">-f</span> tagfile</tt>".</dd> +</dl> +</div> +<div class="section" id="output-format-options"> +<span id="option-output-format"></span><h2>Output Format Options</h2> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--format=(1|2)</span></tt></dt> +<dd>Change the format of the output tag file. Currently the only valid +values for level are 1 or 2. Level 1 specifies the original tag file +format and level 2 specifies a new extended format containing extension +fields (but in a manner which retains backward-compatibility with +original <tt class="docutils literal">vi(1)</tt> implementations). The default level is 2. +[Ignored in etags mode]</dd> +<dt><tt class="docutils literal"><span class="pre">--output-format=(u-ctags|e-ctags|etags|xref|json)</span></tt></dt> +<dd>Specify the output format. The default is <tt class="docutils literal"><span class="pre">u-ctags</span></tt>. +See tags(5) for <tt class="docutils literal"><span class="pre">u-ctags</span></tt> and <tt class="docutils literal"><span class="pre">e-ctags</span></tt>. +See <tt class="docutils literal"><span class="pre">-e</span></tt> for <tt class="docutils literal">etags</tt>, and <tt class="docutils literal"><span class="pre">-x</span></tt> for <tt class="docutils literal">xref</tt>. +<tt class="docutils literal">json</tt> format is available only if +the ctags executable is built with <tt class="docutils literal">libjansson</tt>. +See ctags-client-tools(7) for more about <tt class="docutils literal">json</tt> format.</dd> +<dt><tt class="docutils literal"><span class="pre">-e</span></tt></dt> +<dd>Same as <tt class="docutils literal"><span class="pre">--output-format=etags</span></tt>. +Enable etags mode, which will create a tag file for use with the Emacs +editor. Alternatively, if ctags is invoked by a +name containing the string "etags" (either by renaming, +or creating a link to, the executable), etags mode will be enabled.</dd> +<dt><tt class="docutils literal"><span class="pre">-x</span></tt></dt> +<dd><p class="first">Same as <tt class="docutils literal"><span class="pre">--output-format=xref</span></tt>. +Print a tabular, human-readable cross reference (xref) file to standard +output instead of generating a tag file. The information contained in +the output includes: the tag name; the kind of tag; the line number, +file name, and source line (with extra white space condensed) of the +file which defines the tag. No tag file is written and all options +affecting tag file output will be ignored.</p> +<p class="last">Example applications for this +feature are generating a listing of all functions located in a source +file (e.g. "<tt class="docutils literal">ctags <span class="pre">-x</span> <span class="pre">--kinds-c=f</span> file</tt>"), or generating +a list of all externally visible global variables located in a source +file (e.g. "<tt class="docutils literal">ctags <span class="pre">-x</span> <span class="pre">--kinds-c=v</span> <span class="pre">--extras=-F</span> file</tt>").</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--sort=(yes|no|foldcase)</span></tt></dt> +<dd>Indicates whether the tag file should be sorted on the tag name +(default is <tt class="docutils literal">yes</tt>). Note that the original <tt class="docutils literal">vi(1)</tt> required sorted tags. +The <tt class="docutils literal">foldcase</tt> value specifies case insensitive (or case-folded) sorting. +Fast binary searches of tag files sorted with case-folding will require +special support from tools using tag files, such as that found in the +ctags readtags library, or Vim version 6.2 or higher +(using "<tt class="docutils literal">set ignorecase</tt>"). +[Ignored in etags mode]</dd> +<dt><tt class="docutils literal"><span class="pre">-u</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--sort=no</span></tt> (i.e. "unsorted").</dd> +<dt><tt class="docutils literal"><span class="pre">--etags-include=<file></span></tt></dt> +<dd>Include a reference to <em><file></em> in the tag file. This option may be specified +as many times as desired. This supports Emacs' capability to use a +tag file which <em>includes</em> other tag files. [Available only in etags mode]</dd> +<dt><tt class="docutils literal"><span class="pre">--input-encoding=<encoding></span></tt></dt> +<dd>Specifies the <em><encoding></em> of the input files. +If this option is specified, Universal Ctags converts the input from this +encoding to the encoding specified by <tt class="docutils literal"><span class="pre">--output-encoding=encoding</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--input-encoding-<LANG>=<encoding></span></tt></dt> +<dd>Specifies a specific input <em><encoding></em> for <em><LANG></em>. It overrides the global +default value given with <tt class="docutils literal"><span class="pre">--input-encoding</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--output-encoding=<encoding></span></tt></dt> +<dd><p class="first">Specifies the <em><encoding></em> of the tags file. +Universal Ctags converts the encoding of input files from the encoding +specified by <tt class="docutils literal"><span class="pre">--input-encoding=<encoding></span></tt> to this encoding.</p> +<p class="last">In addition <em><encoding></em> is specified at the top the tags file as the +value for the <tt class="docutils literal">TAG_FILE_ENCODING</tt> pseudo-tag. The default value of +<em><encoding></em> is <tt class="docutils literal"><span class="pre">UTF-8</span></tt>.</p> +</dd> +</dl> +</div> +<div class="section" id="language-selection-and-mapping-options"> +<span id="option-lang-mapping"></span><h2>Language Selection and Mapping Options</h2> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--language-force=(<language>|auto)</span></tt></dt> +<dd><p class="first">By default, ctags automatically selects the language +of a source file, ignoring those files whose language cannot be +determined (see "<a class="reference internal" href="#determining-file-language">Determining file language</a>"). This option forces the specified +<em>language</em> (case-insensitive; either built-in or user-defined) to be used +for every supplied file instead of automatically selecting the language +based upon its extension.</p> +<p class="last">In addition, the special value <tt class="docutils literal">auto</tt> indicates +that the language should be automatically selected (which effectively +disables this option).</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--languages=[+|-](<list>|all)</span></tt></dt> +<dd><p class="first">Specifies the languages for which tag generation is enabled, with <em><list></em> +containing a comma-separated list of language names (case-insensitive; +either built-in or user-defined).</p> +<p>If the first language of <em><list></em> is not +preceded by either a '<tt class="docutils literal">+</tt>' or '<tt class="docutils literal">-</tt>', the current list (the current settings +of enabled/disabled languages managed in ctags internally) +will be cleared before adding or removing the languages in <em><list></em>. Until a '<tt class="docutils literal">-</tt>' is +encountered, each language in the <em><list></em> will be added to the current list.</p> +<p>As either the '<tt class="docutils literal">+</tt>' or '<tt class="docutils literal">-</tt>' is encountered in the <em><list></em>, the languages +following it are added or removed from the current list, respectively. +Thus, it becomes simple to replace the current list with a new one, or +to add or remove languages from the current list.</p> +<p>The actual list of +files for which tags will be generated depends upon the language +extension mapping in effect (see the <tt class="docutils literal"><span class="pre">--langmap</span></tt> option). Note that the most of +languages, including user-defined languages, are enabled unless explicitly +disabled using this option. Language names included in list may be any +built-in language or one previously defined with <tt class="docutils literal"><span class="pre">--langdef</span></tt>.</p> +<p>The default +is <tt class="docutils literal">all</tt>, which is also accepted as a valid argument. See the +<tt class="docutils literal"><span class="pre">--list-languages</span></tt> option for a list of the all (built-in and user-defined) +language names.</p> +<p class="last">Note <tt class="docutils literal"><span class="pre">--languages=</span></tt> option works cumulative way; the option can be +specified with different arguments multiple times in a command line.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--alias-<LANG>=[+|-](<pattern>|default)</span></tt></dt> +<dd><p class="first">Adds ('<tt class="docutils literal">+</tt>') or removes ('<tt class="docutils literal">-</tt>') an alias <em><pattern></em> to a language specified +with <em><LANG></em>. ctags refers to the alias pattern in +"<a class="reference internal" href="#determining-file-language">Determining file language</a>" stage.</p> +<p>The parameter <em><pattern></em> is not a list. Use this option multiple +times in a command line to add or remove multiple alias +patterns.</p> +<p>To restore the default language aliases, specify <tt class="docutils literal">default</tt>.</p> +<p>Using <tt class="docutils literal">all</tt> for <em><LANG></em> has meaning in following two cases:</p> +<dl class="last docutils"> +<dt><tt class="docutils literal"><span class="pre">--alias-all=</span></tt></dt> +<dd>This clears aliases setting of all languages.</dd> +<dt><tt class="docutils literal"><span class="pre">--alias-all=default</span></tt></dt> +<dd>This restores the default languages aliases for all languages.</dd> +</dl> +</dd> +<dt><tt class="docutils literal"><span class="pre">--guess-language-eagerly</span></tt></dt> +<dd>Looks into the file contents for heuristically guessing the proper language parser. +See "<a class="reference internal" href="#determining-file-language">Determining file language</a>".</dd> +<dt><tt class="docutils literal"><span class="pre">-G</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--guess-language-eagerly</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--langmap=<map>[,<map>[...]]</span></tt></dt> +<dd><p class="first">Controls how file names are mapped to languages (see the <tt class="docutils literal"><span class="pre">--list-maps</span></tt> +option). Each comma-separated <em><map></em> consists of the language name (either +a built-in or user-defined language), a colon, and a list of <em>file +extensions</em> and/or <em>file name patterns</em>. A file extension is specified by +preceding the extension with a period (e.g. <tt class="docutils literal">.c</tt>). A file name pattern +is specified by enclosing the pattern in parentheses (e.g. +<tt class="docutils literal">([Mm]akefile)</tt>).</p> +<p>If appropriate support is available from the runtime +library of your C compiler, then the file name pattern may contain the usual +shell wildcards common on Unix (be sure to quote the option parameter to +protect the wildcards from being expanded by the shell before being +passed to ctags). You can determine if shell wildcards +are available on your platform by examining the output of the +<tt class="docutils literal"><span class="pre">--list-features</span></tt> option, which will include <tt class="docutils literal">wildcards</tt> in the compiled +feature list; otherwise, the file name patterns are matched against +file names using a simple textual comparison.</p> +<p>When mapping a file extension with <tt class="docutils literal"><span class="pre">--langmap</span></tt> option, +it will first be unmapped from any other languages. (<tt class="docutils literal"><span class="pre">--map-<LANG></span></tt> +option provides more fine-grained control.)</p> +<p>If the first character in a <em><map></em> is a plus sign ('<tt class="docutils literal">+</tt>'), then the extensions and +file name patterns in that map will be appended to the current map +for that language; otherwise, the map will replace the current map. +For example, to specify that only files with extensions of <tt class="docutils literal">.c</tt> and <tt class="docutils literal">.x</tt> are +to be treated as C language files, use <tt class="docutils literal"><span class="pre">--langmap=c:.c.x</span></tt>; to also add +files with extensions of <tt class="docutils literal">.j</tt> as Java language files, specify +<tt class="docutils literal"><span class="pre">--langmap=c:.c.x,java:+.j</span></tt>. To map makefiles (e.g. files named either +<tt class="docutils literal">Makefile</tt>, <tt class="docutils literal">makefile</tt>, or having the extension <tt class="docutils literal">.mak</tt>) to a language +called <tt class="docutils literal">make</tt>, specify <tt class="docutils literal"><span class="pre">--langmap=make:([Mm]akefile).mak</span></tt>. To map files +having no extension, specify a period not followed by a non-period +character (e.g. '<tt class="docutils literal">.</tt>', <tt class="docutils literal">..x</tt>, <tt class="docutils literal">.x.</tt>).</p> +<p>To clear the mapping for a +particular language (thus inhibiting automatic generation of tags for +that language), specify an empty extension list (e.g. <tt class="docutils literal"><span class="pre">--langmap=fortran:</span></tt>). +To restore the default language mappings for a particular language, +supply the keyword <tt class="docutils literal">default</tt> for the mapping. To specify restore the +default language mappings for all languages, specify <tt class="docutils literal"><span class="pre">--langmap=default</span></tt>.</p> +<p class="last">Note that file name patterns are tested before file extensions when inferring +the language of a file. This order of Universal Ctags is different from +Exuberant Ctags. See ctags-incompatibilities(7) for the background of +this incompatible change.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></tt></dt> +<dd><p class="first">This option provides the way to control mapping(s) of file names to +languages in a more fine-grained way than <tt class="docutils literal"><span class="pre">--langmap</span></tt> option.</p> +<p>In ctags, more than one language can map to a +file name <em><pattern></em> or file <em><extension></em> (<em>N:1 map</em>). Alternatively, +<tt class="docutils literal"><span class="pre">--langmap</span></tt> option handle only <em>1:1 map</em>, only one language +mapping to one file name <em><pattern></em> or file <em><extension></em>. A typical N:1 +map is seen in C++ and ObjectiveC language; both languages have +a map to <tt class="docutils literal">.h</tt> as a file extension.</p> +<p>A file extension is specified by preceding the extension with a period (e.g. <tt class="docutils literal">.c</tt>). +A file name pattern is specified by enclosing the pattern in parentheses (e.g. +<tt class="docutils literal">([Mm]akefile)</tt>). A prefixed plus ('<tt class="docutils literal">+</tt>') sign is for adding, and +minus ('<tt class="docutils literal">-</tt>') is for removing. No prefix means replacing the map of <em><LANG></em>.</p> +<p class="last">Unlike <tt class="docutils literal"><span class="pre">--langmap</span></tt>, <em><extension></em> (or <em><pattern></em>) is not a list. +<tt class="docutils literal"><span class="pre">--map-<LANG></span></tt> takes one extension (or pattern). However, +the option can be specified with different arguments multiple times +in a command line.</p> +</dd> +</dl> +</div> +<div class="section" id="tags-file-contents-options"> +<span id="option-tags-file-contents"></span><h2>Tags File Contents Options</h2> +<p>See "<a class="reference internal" href="#id1">TAG ENTRIES</a>" about fields, kinds, roles, and extras.</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--excmd=(number|pattern|mix|combine)</span></tt></dt> +<dd><p class="first">Determines the type of <tt class="docutils literal">EX</tt> command used to locate tags in the source +file. [Ignored in etags mode]</p> +<p>The valid values for type (either the entire word or the first letter +is accepted) are:</p> +<dl class="last docutils"> +<dt><tt class="docutils literal">number</tt></dt> +<dd><p class="first">Use only line numbers in the tag file for locating tags. This has +four advantages:</p> +<ol class="arabic simple"> +<li>Significantly reduces the size of the resulting tag file.</li> +<li>Eliminates failures to find tags because the line defining the +tag has changed, causing the pattern match to fail (note that +some editors, such as <tt class="docutils literal">vim</tt>, are able to recover in many such +instances).</li> +<li>Eliminates finding identical matching, but incorrect, source +lines (see "<a class="reference internal" href="#bugs">BUGS</a>").</li> +<li>Retains separate entries in the tag file for lines which are +identical in content. In pattern mode, duplicate entries are +dropped because the search patterns they generate are identical, +making the duplicate entries useless.</li> +</ol> +<p>However, this option has one significant drawback: changes to the +source files can cause the line numbers recorded in the tag file +to no longer correspond to the lines in the source file, causing +jumps to some tags to miss the target definition by one or more +lines. Basically, this option is best used when the source code +to which it is applied is not subject to change. Selecting this +option type causes the following options to be ignored: <tt class="docutils literal"><span class="pre">-B</span></tt>, <tt class="docutils literal"><span class="pre">-F</span></tt>.</p> +<p class="last"><tt class="docutils literal">number</tt> type is ignored in Xref and JSON output formats. Use +<tt class="docutils literal"><span class="pre">--_xformat="...%n"</span></tt> for Xref output format, or <tt class="docutils literal"><span class="pre">--fields=+n-P</span></tt> for +JSON output format.</p> +<!-- NOTE: #2792 --> +</dd> +<dt><tt class="docutils literal">pattern</tt></dt> +<dd>Use only search patterns for all tags, rather than the line numbers +usually used for macro definitions. This has the advantage of +not referencing obsolete line numbers when lines have been added or +removed since the tag file was generated.</dd> +<dt><tt class="docutils literal">mixed</tt></dt> +<dd><p class="first">In this mode, patterns are generally used with a few exceptions. +For C, line numbers are used for macro definition tags. For Fortran, line numbers +are used for common blocks because their corresponding source lines +are generally identical, making pattern searches useless +for finding all matches.</p> +<p class="last">This was the default format generated by the original ctags and is, +therefore, retained as the default for this option.</p> +</dd> +<dt><tt class="docutils literal">combine</tt></dt> +<dd>Concatenate the line number and pattern with a semicolon in between.</dd> +</dl> +</dd> +<dt><tt class="docutils literal"><span class="pre">-n</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--excmd=number</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">-N</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--excmd=pattern</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--extras=[+|-][<flags>|*]</span></tt></dt> +<dd><p class="first">Specifies whether to include extra tag entries for certain kinds of +information. See also "<a class="reference internal" href="#extras">Extras</a>" subsection to know what are extras.</p> +<p>The parameter <em><flags></em> is a set of one-letter flags (and/or long-name flags), each +representing one kind of extra tag entry to include in the tag file. +If flags is preceded by either the '<tt class="docutils literal">+</tt>' or '<tt class="docutils literal">-</tt>' character, the effect of +each flag is added to, or removed from, those currently enabled; +otherwise the flags replace any current settings. All entries are +included if '<tt class="docutils literal">*</tt>' is given.</p> +<p class="last">This <tt class="docutils literal"><span class="pre">--extras=</span></tt> option is for controlling extras common in all +languages (or language-independent extras). Universal Ctags also +supports language-specific extras. (See "<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>" about the concept). Use <tt class="docutils literal"><span class="pre">--extras-<LANG>=</span></tt> option for +controlling them.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--extras-(<LANG>|all)=[+|-][<flags>|*]</span></tt></dt> +<dd><p class="first">Specifies whether to include extra tag entries for certain kinds of +information for language <em><LANG></em>. Universal Ctags +introduces language-specific extras. See "<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>" about the concept. This option is for controlling them.</p> +<p>Specifies <tt class="docutils literal">all</tt> as <em><LANG></em> to apply the parameter <em><flags></em> to all +languages; all extras are enabled with specifying '<tt class="docutils literal">*</tt>' as the +parameter flags. If specifying nothing as the parameter flags +(<tt class="docutils literal"><span class="pre">--extras-all=</span></tt>), all extras are disabled. These two combinations +are useful for testing.</p> +<p class="last">Check the output of the <tt class="docutils literal"><span class="pre">--list-extras=<LANG></span></tt> option for the +extras of specific language <em><LANG></em>.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--fields=[+|-][<flags>|*]</span></tt></dt> +<dd><p class="first">Specifies which language-independent fields are to be included in the tag +entries. Language-independent fields are extension fields which are common +in all languages. See "<a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a>" section, and "<a class="reference internal" href="#extension-fields">Extension fields</a>" +subsection, for details of extension fields.</p> +<p>The parameter <em><flags></em> is a set of one-letter or long-name flags, +each representing one type of extension field to include. +Each flag or group of flags may be preceded by either '<tt class="docutils literal">+</tt>' to add it +to the default set, or '<tt class="docutils literal">-</tt>' to exclude it. In the absence of any +preceding '<tt class="docutils literal">+</tt>' or '<tt class="docutils literal">-</tt>' sign, only those fields explicitly listed in flags +will be included in the output (i.e. overriding the default set). All +fields are included if '<tt class="docutils literal">*</tt>' is given.</p> +<p>This option is ignored if the +option <tt class="docutils literal"><span class="pre">--format=1</span></tt> (legacy tag file format) has been specified.</p> +<p class="last">Use <tt class="docutils literal"><span class="pre">--fields-<LANG>=</span></tt> option for controlling language-specific fields.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--fields-(<LANG>|all)=[+|-][<flags>|*]</span></tt></dt> +<dd><p class="first">Specifies which language-specific fields are to be included in +the tag entries. Universal Ctags +supports language-specific fields. (See "<a class="reference internal" href="#language-specific-fields-and-extras">Language-specific fields and +extras</a>" about the concept).</p> +<p>Specify <tt class="docutils literal">all</tt> as <em><LANG></em> to apply the parameter <em><flags></em> to all +languages; all fields are enabled with specifying '<tt class="docutils literal">*</tt>' as the +parameter flags. If specifying nothing as the parameter <em><flags></em> +(i.e. <tt class="docutils literal"><span class="pre">--fields-all=</span></tt>), all fields are disabled. These two combinations +are useful for testing.</p> +<p>See the description of <tt class="docutils literal"><span class="pre">--fields=[+|-][<flags>|*]</span></tt> about <em><flags></em>.</p> +<p class="last">Use <tt class="docutils literal"><span class="pre">--fields=</span></tt> option for controlling language-independent fields.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></tt></dt> +<dd><p class="first">Specifies a list of language-specific <em><kinds></em> of tags (or kinds) to +include in the output file for a particular language, where <em><LANG></em> is +case-insensitive and is one of the built-in language names (see the +<tt class="docutils literal"><span class="pre">--list-languages</span></tt> option for a complete list).</p> +<p>The parameter <em><kinds></em> is a group +of one-letter or long-name flags designating kinds of tags (particular to the language) +to either include or exclude from the output. The specific sets of +flags recognized for each language, their meanings and defaults may be +list using the <tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt> option.</p> +<p>Each letter or group of letters +may be preceded by either '<tt class="docutils literal">+</tt>' to add it to, or '<tt class="docutils literal">-</tt>' to remove it from, +the default set. In the absence of any preceding '<tt class="docutils literal">+</tt>' or '<tt class="docutils literal">-</tt>' sign, only +those kinds explicitly listed in kinds will be included in the output +(i.e. overriding the default for the specified language).</p> +<p>Specify '<tt class="docutils literal">*</tt>' as the parameter to include all kinds implemented +in <em><LANG></em> in the output. Furthermore if <tt class="docutils literal">all</tt> is given as <em><LANG></em>, +specification of the parameter <tt class="docutils literal">kinds</tt> affects all languages defined +in ctags. Giving <tt class="docutils literal">all</tt> makes sense only when '<tt class="docutils literal">*</tt>' or +'<tt class="docutils literal">F</tt>' is given as the parameter <tt class="docutils literal">kinds</tt>.</p> +<p>As an example for the C language, in order to add prototypes and +external variable declarations to the default set of tag kinds, +but exclude macros, use <tt class="docutils literal"><span class="pre">--kinds-c=+px-d</span></tt>; to include only tags for +functions, use <tt class="docutils literal"><span class="pre">--kinds-c=f</span></tt>.</p> +<p class="last">Some kinds of C and C++ languages are synchronized; enabling +(or disabling) a kind in one language enables the kind having +the same one-letter and long-name in the other language. See also the +description of <tt class="docutils literal">MASTER</tt> column of <tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt>.</p> +</dd> +</dl> +<!-- COMMENT: +``- -param-<LANG>:name=argument`` is moved to "Language Specific Options" --> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--pattern-length-limit=<N></span></tt></dt> +<dd><p class="first">Truncate patterns of tag entries after <em><N></em> characters. Disable by setting to 0 +(default is 96).</p> +<p>An input source file with long lines and multiple tag matches per +line can generate an excessively large tags file with an +unconstrained pattern length. For example, running ctags on a +minified JavaScript source file often exhibits this behavior.</p> +<p class="last">The truncation avoids cutting in the middle of a UTF-8 code point +spanning multiple bytes to prevent writing invalid byte sequences from +valid input files. This handling allows for an extra 3 bytes above the +configured limit in the worse case of a 4 byte code point starting +right before the limit. Please also note that this handling is fairly +naive and fast, and although it is resistant against any input, it +requires a valid input to work properly; it is not guaranteed to work +as the user expects when dealing with partially invalid UTF-8 input. +This also partially affect non-UTF-8 input, if the byte sequence at +the truncation length looks like a multibyte UTF-8 sequence. This +should however be rare, and in the worse case will lead to including +up to an extra 3 bytes above the limit.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--pseudo-tags=[+|-](<pseudo-tag>|*)</span></tt></dt> +<dd>Enable/disable emitting pseudo-tag named <em><pseudo-tag></em>. +If '<tt class="docutils literal">*</tt>' is given, enable/disable emitting all pseudo-tags.</dd> +<dt><tt class="docutils literal"><span class="pre">--put-field-prefix</span></tt></dt> +<dd><p class="first">Put <tt class="docutils literal">UCTAGS</tt> as prefix for the name of fields newly introduced in +Universal Ctags.</p> +<p>Some fields are newly introduced in Universal Ctags and more will +be introduced in the future. Other tags generators may also +introduce their specific fields.</p> +<p>In such a situation, there is a concern about conflicting field +names; mixing tags files generated by multiple tags generators +including Universal Ctags is difficult. This option provides a +workaround for such station.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span><span class="literal string single">'{line}{end}'</span> -o - hello.c +<span class="generic output">main hello.c /^main(int argc, char **argv)$/;" f line:3 end:6 +</span><span class="generic prompt">$ </span>ctags --put-field-prefix --fields<span class="operator">=</span><span class="literal string single">'{line}{end}'</span> -o - hello.c +<span class="generic output">main hello.c /^main(int argc, char **argv)$/;" f line:3 UCTAGSend:6</span> +</pre> +<p class="last">In the above example, the prefix is put to <tt class="docutils literal">end</tt> field which is +newly introduced in Universal Ctags.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]</span></tt></dt> +<dd><p class="first">Specifies a list of kind-specific roles of tags to include in the +output file for a particular language. +<em><kind></em> specifies the kind where the <em><roles></em> are defined. +<em><LANG></em> specifies the language where the kind is defined. +Each role in <em><roles></em> must be surrounded by braces (e.g. <tt class="docutils literal">{system}</tt> +for a role named "system").</p> +<p>Like <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt> option, '<tt class="docutils literal">+</tt>' is for adding the role to the +list, and '<tt class="docutils literal">-</tt>' is for removing from the list. '<tt class="docutils literal">*</tt>' is for including +all roles of the kind to the list. The option with no argument +makes the list empty.</p> +<p>Both a one-letter flag or a long name flag surrounded by braces are +acceptable for specifying a kind (e.g. <tt class="docutils literal"><span class="pre">--roles-C.h=+{system}{local}</span></tt> +or <tt class="docutils literal"><span class="pre">--roles-C.{header}=+{system}{local}</span></tt>). '<tt class="docutils literal">*</tt>' can be used for <em><KIND></em> +only for adding/removing all roles of all kinds in a language to/from +the list (e.g. <tt class="docutils literal"><span class="pre">--roles-C.*=*</span></tt> or <tt class="docutils literal"><span class="pre">--roles-C.*=</span></tt>).</p> +<p class="last"><tt class="docutils literal">all</tt> can be used for <em><LANG></em> only for adding/removing all roles of +all kinds in all languages to/from the list +(e.g. <tt class="docutils literal"><span class="pre">--roles-all.*=*</span></tt> or <tt class="docutils literal"><span class="pre">--roles-all.*=</span></tt>).</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--tag-relative=(yes|no|always|never)</span></tt></dt> +<dd><p class="first">Specifies how the file paths recorded in the tag file. +The default is <tt class="docutils literal">yes</tt> when running in etags mode (see +the <tt class="docutils literal"><span class="pre">-e</span></tt> option), <tt class="docutils literal">no</tt> otherwise.</p> +<dl class="last docutils"> +<dt><tt class="docutils literal">yes</tt></dt> +<dd>indicates that the file paths recorded in the tag file should be +<em>relative to the directory containing the tag file</em> +unless the files supplied on the command line +are specified with absolute paths.</dd> +<dt><tt class="docutils literal">no</tt></dt> +<dd>indicates that the file paths recorded in the tag file should be +<em>relative to the current directory</em> +unless the files supplied on the command line +are specified with absolute paths.</dd> +<dt><tt class="docutils literal">always</tt></dt> +<dd>indicates the recorded file paths should be relative +even if source file names are passed in with absolute paths.</dd> +<dt><tt class="docutils literal">never</tt></dt> +<dd>indicates the recorded file paths should be absolute +even if source file names are passed in with relative paths.</dd> +</dl> +</dd> +<dt><tt class="docutils literal"><span class="pre">--use-slash-as-filename-separator[=(yes|no)]</span></tt></dt> +<dd><p class="first">Uses slash ('<tt class="docutils literal">/</tt>') character as filename separators instead of backslash +('<tt class="docutils literal">\</tt>') character when printing <tt class="docutils literal">input:</tt> field. +The default is <tt class="docutils literal">yes</tt> for the default "u-ctags" output format, and +<tt class="docutils literal">no</tt> for the other formats.</p> +<p class="last">This option is available on MS Windows only.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">-B</span></tt></dt> +<dd>Use backward searching patterns (e.g. <tt class="docutils literal"><span class="pre">?pattern?</span></tt>). [Ignored in etags mode]</dd> +<dt><tt class="docutils literal"><span class="pre">-F</span></tt></dt> +<dd>Use forward searching patterns (e.g. <tt class="docutils literal">/pattern/</tt>) (default). [Ignored +in etags mode]</dd> +</dl> +</div> +<div class="section" id="option-file-options"> +<h2>Option File Options</h2> +<!-- TODO: merge some of description in option-file.rst into FILE or a dedicated +section --> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--options=<pathname></span></tt></dt> +<dd><p class="first">Read additional options from file or directory.</p> +<p>ctags searches <em><pathname></em> in the optlib path list +first. If ctags cannot find a file or directory +in the list, ctags reads a file or directory +at the specified <em><pathname></em>.</p> +<p>If a file is specified, it should contain one option per line. If +a directory is specified, files suffixed with <tt class="docutils literal">.ctags</tt> under it +are read in alphabetical order.</p> +<p class="last">As a special case, if <tt class="docutils literal"><span class="pre">--options=NONE</span></tt> is specified as the first +option on the command line, preloading is disabled; the option +will disable the automatic reading of any configuration options +from a file (see "<a class="reference internal" href="#files">FILES</a>").</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--options-maybe=<pathname></span></tt></dt> +<dd>Same as <tt class="docutils literal"><span class="pre">--options</span></tt> but doesn't cause an error if file +(or directory) specified with <em><pathname></em> doesn't exist.</dd> +<dt><tt class="docutils literal"><span class="pre">--optlib-dir=[+]<directory></span></tt></dt> +<dd>Add an optlib <em><directory></em> to or reset the optlib path list. +By default, the optlib path list is empty.</dd> +</dl> +</div> +<div class="section" id="optlib-options"> +<h2>optlib Options</h2> +<p>See ctags-optlib(7) for details of each option.</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--kinddef-<LANG>=<letter>,<name>,<description></span></tt></dt> +<dd>Define a kind for <em><LANG></em>. +Don't be confused this with <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--langdef=<name></span></tt></dt> +<dd>Defines a new user-defined language, <em><name></em>, to be parsed with regular +expressions.</dd> +<dt><tt class="docutils literal"><span class="pre">--mline-regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt></dt> +<dd>Define multi-line regular expression for locating tags in specific language.</dd> +<dt><tt class="docutils literal"><span class="pre">--regex-<LANG>=/<line_pattern>/<name_pattern>/<kind-spec>/[<flags>]</span></tt></dt> +<dd>Define single-line regular expression for locating tags in specific language.</dd> +</dl> +</div> +<div class="section" id="language-specific-options"> +<span id="option-lang-specific"></span><h2>Language Specific Options</h2> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--if0[=(yes|no)]</span></tt></dt> +<dd><p class="first">Indicates a preference as to whether code within an "<tt class="docutils literal">#if 0</tt>" branch of a +preprocessor conditional should be examined for non-macro tags (macro +tags are always included). Because the intent of this construct is to +disable code, the default value of this option is <tt class="docutils literal">no</tt> (disabled).</p> +<p class="last">Note that this +indicates a preference only and does not guarantee skipping code within +an "<tt class="docutils literal">#if 0</tt>" branch, since the fall-back algorithm used to generate +tags when preprocessor conditionals are too complex follows all branches +of a conditional.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--line-directives[=(yes|no)]</span></tt></dt> +<dd><p class="first">Specifies whether <tt class="docutils literal">#line</tt> directives should be recognized. These are +present in the output of a preprocessor and contain the line number, and +possibly the file name, of the original source file(s) from which the +preprocessor output file was generated. This option is off by default.</p> +<p>When enabled, this option will +cause ctags to generate tag entries marked with the +file names and line numbers of their locations original source file(s), +instead of their actual locations in the preprocessor output. The actual +file names placed into the tag file will have the same leading path +components as the preprocessor output file, since it is assumed that +the original source files are located relative to the preprocessor +output file (unless, of course, the <tt class="docutils literal">#line</tt> directive specifies an +absolute path).</p> +<p class="last">Note: This option is generally +only useful when used together with the <tt class="docutils literal"><span class="pre">--excmd=number</span></tt> (<tt class="docutils literal"><span class="pre">-n</span></tt>) option. +Also, you may have to use either the <tt class="docutils literal"><span class="pre">--langmap</span></tt> or <tt class="docutils literal"><span class="pre">--language-force</span></tt> option +if the extension of the preprocessor output file is not known to +ctags.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">-D</span> <span class="pre"><macro>=<definition></span></tt></dt> +<dd>Defines a C preprocessor <em><macro></em>. This emulates the behavior of the +corresponding gcc option. All types of macros are supported, +including the ones with parameters and variable arguments. +Stringification, token pasting and recursive macro expansion are also +supported. +This extends the function provided by <tt class="docutils literal"><span class="pre">-I</span></tt> option.</dd> +<dt><tt class="docutils literal"><span class="pre">-h</span> <span class="pre">(<list>|default)</span></tt></dt> +<dd><p class="first">Specifies a <em><list></em> of file extensions, separated by periods, which are +to be interpreted as include (or header) files. To indicate files having +no extension, use a period not followed by a non-period character +(e.g. '<tt class="docutils literal">.</tt>', <tt class="docutils literal">..x</tt>, <tt class="docutils literal">.x.</tt>).</p> +<p>This option only affects how the scoping of +particular kinds of tags are interpreted (i.e. whether or not they are +considered as globally visible or visible only within the file in which +they are defined); it does not map the extension to any particular +language. Any tag which is located in a non-include file and cannot be +seen (e.g. linked to) from another file is considered to have file-limited +(e.g. static) scope. No kind of tag appearing in an include file +will be considered to have file-limited scope.</p> +<p>If the first character in the list is '<tt class="docutils literal">+</tt>', then the extensions in the list will be +appended to the current list; otherwise, the list will replace the +current list. See, also, the <tt class="docutils literal">fileScope</tt>/<tt class="docutils literal">F</tt> flag of <tt class="docutils literal"><span class="pre">--extras</span></tt> option.</p> +<p>The default list is +<tt class="docutils literal"><span class="pre">.h.H.hh.hpp.hxx.h++.inc.def</span></tt>. To restore the default list, specify "<tt class="docutils literal"><span class="pre">-h</span> +default</tt>".</p> +<p class="last">Note that if an extension supplied to this option is not +already mapped to a particular language (see "<a class="reference internal" href="#determining-file-language">Determining file language</a>", above), +you will also need to use either the <tt class="docutils literal"><span class="pre">--map-<LANG></span></tt>, <tt class="docutils literal"><span class="pre">--langmap</span></tt> or +<tt class="docutils literal"><span class="pre">--language-force</span></tt> option.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">-I</span> <span class="pre"><identifier-list></span></tt></dt> +<dd><p class="first">Specifies a <em><identifier-list></em> of identifiers which are to be specially handled while +parsing C and C++ source files. This option is specifically provided +to handle special cases arising through the use of preprocessor macros. +When the identifiers listed are simple identifiers, these identifiers +will be ignored during parsing of the source files.</p> +<p>If an identifier is +suffixed with a '<tt class="docutils literal">+</tt>' character (i.e. "<tt class="docutils literal"><span class="pre">-I</span> FOO+</tt>"), ctags will also +ignore any parenthesis-enclosed argument list which may immediately +follow the identifier in the source files. See the example of "<tt class="docutils literal"><span class="pre">-I</span> +MODULE_VERSION+</tt>" below.</p> +<p>If two identifiers are +separated with the '<tt class="docutils literal">=</tt>' character (i.e. <tt class="docutils literal"><span class="pre">-I</span> FOO=BAR</tt>), the first identifiers is replaced by +the second identifiers for parsing purposes. The list of identifiers may +be supplied directly on the command line or read in from a separate file. +See the example of "<tt class="docutils literal"><span class="pre">-I</span> CLASS=class</tt>" below.</p> +<p>If the first character of <em><identifier-list></em> is '<tt class="docutils literal">@</tt>', '<tt class="docutils literal">.</tt>' or a pathname +separator ('<tt class="docutils literal">/</tt>' or '<tt class="docutils literal">\</tt>'), or the first two characters specify a drive +letter (e.g. <tt class="docutils literal">C:</tt>), the parameter <em><identifier-list></em> will be interpreted as +a filename from which to read a list of identifiers, one per input line.</p> +<p>Otherwise, <em><identifier-list></em> is a list of identifiers (or identifier +pairs) to be specially handled, each delimited by either a comma or +by white space (in which case the list should be quoted to keep the +entire list as one command line argument).</p> +<p>Multiple <tt class="docutils literal"><span class="pre">-I</span></tt> options may be +supplied. To clear the list of ignore identifiers, supply a single +dash ('<tt class="docutils literal">-</tt>') for <em><identifier-list></em>.</p> +<p>This feature is useful when preprocessor macros are used in such a way +that they cause syntactic confusion due to their presence. Indeed, +this is the best way of working around a number of problems caused by +the presence of syntax-busting macros in source files (see "<a class="reference internal" href="#caveats">CAVEATS</a>"). +Some examples will illustrate this point.</p> +<pre class="code C literal-block"> +<span class="keyword type">int</span> <span class="name">foo</span> <span class="name">ARGDECL4</span><span class="punctuation">(</span><span class="keyword type">void</span> <span class="operator">*</span><span class="punctuation">,</span> <span class="name">ptr</span><span class="punctuation">,</span> <span class="keyword type">long</span> <span class="keyword type">int</span><span class="punctuation">,</span> <span class="name">nbytes</span><span class="punctuation">)</span> +</pre> +<p>In the above example, the macro <tt class="docutils literal">ARGDECL4</tt> would be mistakenly +interpreted to be the name of the function instead of the correct name +of <tt class="docutils literal">foo</tt>. Specifying "<tt class="docutils literal"><span class="pre">-I</span> ARGDECL4</tt>" results in the correct behavior.</p> +<pre class="code C literal-block"> +<span class="comment multiline">/* creates an RCS version string in module */</span> +<span class="name">MODULE_VERSION</span><span class="punctuation">(</span><span class="literal string">"$Revision$"</span><span class="punctuation">)</span> +</pre> +<p>In the above example the macro invocation looks too much like a function +definition because it is not followed by a semicolon (indeed, it +could even be followed by a global variable definition that would look +much like a K&R style function parameter declaration). In fact, this +seeming function definition could possibly even cause the rest of the +file to be skipped over while trying to complete the definition. +Specifying "<tt class="docutils literal"><span class="pre">-I</span> MODULE_VERSION+</tt>" would avoid such a problem.</p> +<pre class="code C literal-block"> +<span class="name">CLASS</span> <span class="name">Example</span> <span class="punctuation">{</span> + <span class="comment single">// your content here +</span><span class="punctuation">};</span> +</pre> +<p class="last">The example above uses <tt class="docutils literal">CLASS</tt> as a preprocessor macro which expands to +something different for each platform. For instance <tt class="docutils literal">CLASS</tt> may be +defined as <tt class="docutils literal">class __declspec(dllexport)</tt> on Win32 platforms and simply +<tt class="docutils literal">class</tt> on UNIX. Normally, the absence of the C++ keyword <tt class="docutils literal">class</tt> +would cause the source file to be incorrectly parsed. Correct behavior +can be restored by specifying "<tt class="docutils literal"><span class="pre">-I</span> CLASS=class</tt>".</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--param-<LANG>:<name>=<argument></span></tt></dt> +<dd><p class="first">Set a <em><LANG></em> specific parameter, a parameter specific to the <em><LANG></em>.</p> +<p class="last">Available parameters can be listed with <tt class="docutils literal"><span class="pre">--list-params</span></tt>.</p> +</dd> +</dl> +</div> +<div class="section" id="listing-options"> +<span id="option-listing"></span><h2>Listing Options</h2> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--list-aliases[=(<language>|all)]</span></tt></dt> +<dd>Lists the aliases for either the specified <em><language></em> or <tt class="docutils literal">all</tt> +languages, and then exits. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted. +The aliases are used when heuristically testing a language parser for a +source file.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-excludes</span></tt></dt> +<dd>Lists the current exclusion patterns used to exclude files.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-extras[=(<language>|all)]</span></tt></dt> +<dd><p class="first">Lists the extras recognized for either the specified <em><language></em> or +<tt class="docutils literal">all</tt> languages. See "<a class="reference internal" href="#extras">Extras</a>" subsection to know what are extras. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</p> +<p>An extra can be enabled or disabled with <tt class="docutils literal"><span class="pre">--extras=</span></tt> for common +extras in all languages, or <tt class="docutils literal"><span class="pre">--extras-<LANG>=</span></tt> for the specified +language. These option takes one-letter flag or long-name flag as a parameter +for specifying an extra.</p> +<p>The meaning of columns in output are as follows:</p> +<dl class="last docutils"> +<dt>LETTER</dt> +<dd>One-letter flag. '<tt class="docutils literal">-</tt>' means the extra does not have one-letter flag.</dd> +<dt>NAME</dt> +<dd>Long-name flag. The long-name is used in <tt class="docutils literal">extras</tt> field.</dd> +<dt>ENABLED</dt> +<dd>Whether the extra is enabled or not. It takes <tt class="docutils literal">yes</tt> or <tt class="docutils literal">no</tt>.</dd> +<dt>LANGUAGE</dt> +<dd>The name of language if the extra is owned by a parser. +<tt class="docutils literal">NONE</tt> means the extra is common in parsers.</dd> +<dt>DESCRIPTION</dt> +<dd>Human readable description for the extra.</dd> +</dl> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-features</span></tt></dt> +<dd>Lists the compiled features.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-fields[=(<language>|all)]</span></tt></dt> +<dd><p class="first">Lists the fields recognized for either the specified <em><language></em> or +<tt class="docutils literal">all</tt> languages. See "<a class="reference internal" href="#extension-fields">Extension fields</a>" subsection to know what are fields. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</p> +<p>The meaning of columns are as follows:</p> +<dl class="last docutils"> +<dt>LETTER</dt> +<dd>One-letter flag. '<tt class="docutils literal">-</tt>' means the field does not have one-letter flag.</dd> +<dt>NAME</dt> +<dd>Long-name of field.</dd> +<dt>ENABLED</dt> +<dd>Whether the field is enabled or not. It takes <tt class="docutils literal">yes</tt> or <tt class="docutils literal">no</tt>.</dd> +<dt>LANGUAGE</dt> +<dd>The name of language if the field is owned by a parser. +<tt class="docutils literal">NONE</tt> means that the field is a language-independent field which is +common in all languages.</dd> +<dt>JSTYPE</dt> +<dd>JSON type used in printing the value of field when <tt class="docutils literal"><span class="pre">--output-format=json</span></tt> +is specified. See ctags-client-tools(7).</dd> +<dt>FIXED</dt> +<dd><p class="first">Whether this field can be disabled or not in tags output.</p> +<p>Some fields are printed always in tags output. +They have <tt class="docutils literal">yes</tt> as the value for this column.</p> +<p class="last">Unlike the tag output mode, JSON output mode allows disabling +any fields.</p> +</dd> +<dt>OP</dt> +<dd>How this field can be accessed from optscript code. +This field is for Universal Ctags developers.</dd> +<dt>DESCRIPTION</dt> +<dd>Human readable description for the field.</dd> +</dl> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-kinds[=(<language>|all)]</span></tt></dt> +<dd><p class="first">Subset of <tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt>. This option is kept for +backward-compatibility with Exuberant Ctags.</p> +<p>This option prints only LETTER, DESCRIPTION, and ENABLED fields +of <tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt> output. However, the presentation of +ENABLED column is different from that of <tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt> +option; <tt class="docutils literal">[off]</tt> follows after description if the kind is disabled, +and nothing follows if enabled. The most of all kinds are enabled +by default.</p> +<p>The critical weakness of this option is that this option does not +print the name of kind. Universal Ctags introduces +<tt class="docutils literal"><span class="pre">--list-kinds-full</span></tt> because it considers that names are +important.</p> +<p class="last">This option does not work with <tt class="docutils literal"><span class="pre">--machinable</span></tt> nor +<tt class="docutils literal"><span class="pre">--with-list-header</span></tt>.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-kinds-full[=(<language>|all)]</span></tt></dt> +<dd><p class="first">Lists the tag kinds recognized for either the specified <em><language></em> +or <tt class="docutils literal">all</tt> languages, and then exits. See "<a class="reference internal" href="#kinds">Kinds</a>" subsection to +learn what kinds are. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</p> +<p>Each kind of tag recorded in the tag file is represented by a +one-letter flag, or a long-name flag. They are also used to filter the tags +placed into the output through use of the <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt> +option.</p> +<p>The meaning of columns are as follows:</p> +<dl class="last docutils"> +<dt>LANGUAGE</dt> +<dd>The name of language having the kind.</dd> +<dt>LETTER</dt> +<dd>One-letter flag. This must be unique in a language.</dd> +<dt>NAME</dt> +<dd>The long-name flag of the kind. This can be used as the alternative +to the one-letter flag described above. If enabling <tt class="docutils literal">K</tt> field with +<tt class="docutils literal"><span class="pre">--fields=+K</span></tt>, ctags uses long-names instead of +one-letters in tags output. To enable/disable a kind with +<tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt> option, long-name surrounded by braces instead +of one-letter. See "<a class="reference internal" href="#letters-and-names">Letters and names</a>" for details. This must be +unique in a language.</dd> +<dt>ENABLED</dt> +<dd>Whether the kind is enabled or not. It takes <tt class="docutils literal">yes</tt> or <tt class="docutils literal">no</tt>.</dd> +<dt>REFONLY</dt> +<dd>Whether the kind is specialized for reference tagging or not. +If the column is <tt class="docutils literal">yes</tt>, the kind is for reference tagging, and +it is never used for definition tagging. See also "<a class="reference internal" href="#id1">TAG ENTRIES</a>".</dd> +<dt>NROLES</dt> +<dd>The number of roles this kind has. See also "<a class="reference internal" href="#roles">Roles</a>".</dd> +<dt>MASTER</dt> +<dd><p class="first">The master parser controlling enablement of the kind. +A kind belongs to a language (owner) in Universal Ctags; +enabling and disabling a kind in a language has no effect on +a kind in another language even if both kinds has the +same one-letter flag and/or the same long-name flag. In other words, +the namespace of kinds are separated by language.</p> +<p>However, Exuberant Ctags does not separate the kinds of C and +C++. Enabling/disabling kindX in C language enables/disables a +kind in C++ language having the same long-name flag with kindX. To +emulate this behavior in Universal Ctags, a concept named +<em>master parser</em> is introduced. Enabling/disabling some kinds +are synchronized under the control of a master language.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --kinds-C<span class="operator">=</span>+<span class="literal string single">'{local}'</span> --list-kinds-full <span class="literal string escape">\ +</span><span class="generic output"> | grep -E '^(#|C\+\+ .* local)' +</span><span class="generic prompt">#</span>LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="generic output">C++ l local yes no 0 C local variables +</span><span class="generic prompt">$ </span>ctags --kinds-C<span class="operator">=</span>-<span class="literal string single">'{local}'</span> --list-kinds-full <span class="literal string escape">\ +</span><span class="generic output"> | grep -E '^(#|C\+\+ .* local)' +</span><span class="generic prompt">#</span>LANGUAGE LETTER NAME ENABLED REFONLY NROLES MASTER DESCRIPTION +<span class="generic output">C++ l local no no 0 C local variables</span> +</pre> +<p class="last">You see <tt class="docutils literal">ENABLED</tt> field of <tt class="docutils literal">local</tt> kind of C++ language is changed +Though <tt class="docutils literal">local</tt> kind of C language is enabled/disabled. If you swap the languages, you +see the same result.</p> +<!-- TODO: need a reference to "master parser" --> +</dd> +<dt>DESCRIPTION</dt> +<dd>Human readable description for the kind.</dd> +</dl> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-languages</span></tt></dt> +<dd><p class="first">Lists the names of the languages understood by ctags, +and then exits. These language names are case insensitive and may be +used in many other options like <tt class="docutils literal"><span class="pre">--language-force</span></tt>, +<tt class="docutils literal"><span class="pre">--languages</span></tt>, <tt class="docutils literal"><span class="pre">--kinds-<LANG></span></tt>, <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt>, and so on.</p> +<p>Each language listed is disabled if followed by <tt class="docutils literal">[disabled]</tt>. +To use the parser for such a language, specify the language as an +argument of <tt class="docutils literal"><span class="pre">--languages=+</span></tt> option.</p> +<p class="last"><tt class="docutils literal"><span class="pre">--machinable</span></tt> and <tt class="docutils literal"><span class="pre">--with-list-header</span></tt> options are ignored if they are +specified with this option.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-map-extensions[=(<language>|all)]</span></tt></dt> +<dd>Lists the file extensions which associate a file +name with a language for either the specified <em><language></em> or <tt class="docutils literal">all</tt> +languages, and then exits. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-map-patterns[=(<language>|all)]</span></tt></dt> +<dd>Lists the file name patterns which associate a file +name with a language for either the specified <em><language></em> or <tt class="docutils literal">all</tt> +languages, and then exits. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-maps[=(<language>|all)]</span></tt></dt> +<dd><p class="first">Lists file name patterns and the file extensions which associate a file +name with a language for either the specified <em><language></em> or <tt class="docutils literal">all</tt> +languages, and then exits. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</p> +<p>To list the file extensions or file name patterns individually, use +<tt class="docutils literal"><span class="pre">--list-map-extensions</span></tt> or <tt class="docutils literal"><span class="pre">--list-map-patterns</span></tt> option. +See the <tt class="docutils literal"><span class="pre">--langmap</span></tt> option, and "<a class="reference internal" href="#determining-file-language">Determining file language</a>", above.</p> +<p class="last">This option does not work with <tt class="docutils literal"><span class="pre">--machinable</span></tt> nor +<tt class="docutils literal"><span class="pre">--with-list-header</span></tt>.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-mline-regex-flags</span></tt></dt> +<dd>Output list of flags which can be used in a multiline regex parser +definition. +See ctags-optlib(7).</dd> +<dt><tt class="docutils literal"><span class="pre">--list-params[=(<language>|all)]</span></tt></dt> +<dd>Lists the parameters for either the specified <em><language></em> or <tt class="docutils literal">all</tt> +languages, and then exits. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-pseudo-tags</span></tt></dt> +<dd>Output list of pseudo-tags.</dd> +<dt><tt class="docutils literal"><span class="pre">--list-regex-flags</span></tt></dt> +<dd>Lists the flags that can be used in <tt class="docutils literal"><span class="pre">--regex-<LANG></span></tt> option. +See ctags-optlib(7).</dd> +<dt><tt class="docutils literal"><span class="pre">--list-roles[=(<language>|all)[.(<kind-specs>|*)]]</span></tt></dt> +<dd><p class="first">List the roles for either the specified <em><language></em> or <tt class="docutils literal">all</tt> languages. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</p> +<p>If the parameter <em><kindspecs></em> is given after the parameter +<em><language></em> or <tt class="docutils literal">all</tt> with concatenating with '<tt class="docutils literal">.</tt>', list only roles +defined in the kinds. Both one-letter flags and long name flags surrounded +by braces are acceptable as the parameter <em><kindspecs></em>.</p> +<p>The meaning of columns are as follows:</p> +<dl class="last docutils"> +<dt>LANGUAGE</dt> +<dd>The name of language having the role.</dd> +<dt>KIND(L/N)</dt> +<dd>The one-letter flag and the long-name flag of kind having the role.</dd> +<dt>NAME</dt> +<dd>The long-name flag of the role.</dd> +<dt>ENABLED</dt> +<dd>Whether the kind is enabled or not. It takes <tt class="docutils literal">yes</tt> or <tt class="docutils literal">no</tt>.</dd> +<dt>DESCRIPTION</dt> +<dd>Human readable description for the role.</dd> +</dl> +</dd> +<dt><tt class="docutils literal"><span class="pre">--list-subparsers[=(<baselang>|all)]</span></tt></dt> +<dd>Lists the subparsers for a base language for either the specified +<em><baselang></em> or <tt class="docutils literal">all</tt> languages, and then exits. +<tt class="docutils literal">all</tt> is used as default value if the option argument is omitted.</dd> +<dt><tt class="docutils literal"><span class="pre">--machinable[=(yes|no)]</span></tt></dt> +<dd>Use tab character as separators for <tt class="docutils literal"><span class="pre">--list-</span></tt> option output. It +may be suitable for scripting. See "<a class="reference internal" href="#list-options">List options</a>" for considered +use cases. Disabled by default.</dd> +<dt><tt class="docutils literal"><span class="pre">--with-list-header[=(yes|no)]</span></tt></dt> +<dd>Print headers describing columns in <tt class="docutils literal"><span class="pre">--list-</span></tt> option output. +See also "<a class="reference internal" href="#list-options">List options</a>".</dd> +</dl> +</div> +<div class="section" id="miscellaneous-options"> +<span id="option-misc"></span><h2>Miscellaneous Options</h2> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">--help</span></tt></dt> +<dd>Prints to standard output a detailed usage description, and then exits.</dd> +<dt><tt class="docutils literal"><span class="pre">-?</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--help</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--help-full</span></tt></dt> +<dd>Prints to standard output a detailed usage description including experimental +features, and then exits. Visit <a class="reference external" href="https://docs.ctags.io/">https://docs.ctags.io/</a> for information +about the latest exciting experimental features.</dd> +<dt><tt class="docutils literal"><span class="pre">--license</span></tt></dt> +<dd>Prints a summary of the software license to standard output, and then exits.</dd> +<dt><tt class="docutils literal"><span class="pre">--print-language</span></tt></dt> +<dd>Just prints the language parsers for specified source files, and then exits.</dd> +<dt><tt class="docutils literal"><span class="pre">--quiet[=(yes|no)]</span></tt></dt> +<dd>Write fewer messages (default is <tt class="docutils literal">no</tt>).</dd> +<dt><tt class="docutils literal"><span class="pre">--totals[=(yes|no|extra)]</span></tt></dt> +<dd><p class="first">Prints statistics about the source files read and the tag file written +during the current invocation of ctags. This option +is <tt class="docutils literal">no</tt> by default.</p> +<p class="last">The <tt class="docutils literal">extra</tt> value prints parser specific statistics for parsers +gathering such information.</p> +</dd> +<dt><tt class="docutils literal"><span class="pre">--verbose[=(yes|no)]</span></tt></dt> +<dd>Enable verbose mode. This prints out information on option processing +and a brief message describing what action is being taken for each file +considered by ctags. Normally, ctags +does not read command line arguments until after options are read +from the configuration files (see "<a class="reference internal" href="#files">FILES</a>", below). +However, if this option is the first argument on +the command line, it will take effect before any options are read from +these sources. The default is <tt class="docutils literal">no</tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">-V</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--verbose</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--version</span></tt></dt> +<dd>Prints a version identifier for ctags to standard +output, and then exits. This is guaranteed to always contain the string +"Universal Ctags".</dd> +</dl> +</div> +<div class="section" id="obsoleted-options"> +<h2>Obsoleted Options</h2> +<p>These options are kept for backward-compatibility with Exuberant Ctags.</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">-w</span></tt></dt> +<dd>This option is silently ignored for backward-compatibility with the +ctags of SVR4 Unix.</dd> +<dt><tt class="docutils literal"><span class="pre">--file-scope[=(yes|no)]</span></tt></dt> +<dd>This options is removed. Use <tt class="docutils literal"><span class="pre">--extras=[+|-]F</span></tt> or +<tt class="docutils literal"><span class="pre">--extras=[+|-]{fileScope}</span></tt> instead.</dd> +<dt><tt class="docutils literal"><span class="pre">--extra=[+|-][<flags>|*]</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--extras=[+|-][<flags>|*]</span></tt>, which was introduced to make +the option naming convention align to the other options like +<tt class="docutils literal"><span class="pre">--kinds-<LANG>=</span></tt> and <tt class="docutils literal"><span class="pre">--fields=</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">--<LANG>-kinds=[+|-](<kinds>|*)</span></tt></dt> +<dd>This option is obsolete. Use <tt class="docutils literal"><span class="pre">--kinds-<LANG>=...</span></tt> instead.</dd> +</dl> +</div> +</div> +<div class="section" id="operational-details"> +<h1>OPERATIONAL DETAILS</h1> +<p>As ctags considers each source file name in turn, it tries to +determine the language of the file by applying tests described in +"<a class="reference internal" href="#determining-file-language">Determining file language</a>".</p> +<p>If a language was identified, the file is opened and then the appropriate +language parser is called to operate on the currently open file. The parser +parses through the file and adds an entry to the tag file for each +language object it is written to handle. See "<a class="reference internal" href="#tag-file-format">TAG FILE FORMAT</a>", below, +for details on these entries.</p> +<div class="section" id="notes-for-c-c-parser"> +<h2>Notes for C/C++ Parser</h2> +<!-- TODO: move the following description to parser-cxx.rst. --> +<p>This implementation of ctags imposes no formatting +requirements on C code as do legacy implementations. Older implementations +of ctags tended to rely upon certain formatting assumptions in order to +help it resolve coding dilemmas caused by preprocessor conditionals.</p> +<p>In general, ctags tries to be smart about conditional +preprocessor directives. If a preprocessor conditional is encountered +within a statement which defines a tag, ctags follows +only the first branch of that conditional (except in the special case of +<tt class="docutils literal">#if 0</tt>, in which case it follows only the last branch). The reason for +this is that failing to pursue only one branch can result in ambiguous +syntax, as in the following example:</p> +<pre class="code C literal-block"> +<span class="comment preproc">#ifdef TWO_ALTERNATIVES +</span><span class="keyword">struct</span> <span class="punctuation">{</span> +<span class="comment preproc">#else +</span><span class="keyword">union</span> <span class="punctuation">{</span> +<span class="comment preproc">#endif +</span> <span class="keyword type">short</span> <span class="name">a</span><span class="punctuation">;</span> + <span class="keyword type">long</span> <span class="name">b</span><span class="punctuation">;</span> +<span class="punctuation">}</span> +</pre> +<p>Both branches cannot be followed, or braces become unbalanced and +ctags would be unable to make sense of the syntax.</p> +<p>If the application of this heuristic fails to properly parse a file, +generally due to complicated and inconsistent pairing within the +conditionals, ctags will retry the file using a +different heuristic which does not selectively follow conditional +preprocessor branches, but instead falls back to relying upon a closing +brace ('<tt class="docutils literal">}</tt>') in column 1 as indicating the end of a block once any brace +imbalance results from following a <tt class="docutils literal">#if</tt> conditional branch.</p> +<p>ctags will also try to specially handle arguments lists +enclosed in double sets of parentheses in order to accept the following +conditional construct:</p> +<pre class="literal-block"> +extern void foo __ARGS((int one, char two)); +</pre> +<p>Any name immediately preceding the '<tt class="docutils literal">((</tt>' will be automatically ignored and +the previous name will be used.</p> +<p>C++ operator definitions are specially handled. In order for consistency +with all types of operators (overloaded and conversion), the operator +name in the tag file will always be preceded by the string "operator " +(i.e. even if the actual operator definition was written as "operator<<").</p> +<p>After creating or appending to the tag file, it is sorted by the tag name, +removing identical tag lines.</p> +</div> +<div class="section" id="determining-file-language"> +<span id="guessing"></span><h2>Determining file language</h2> +<div class="section" id="file-name-mapping"> +<h3>File name mapping</h3> +<p>Unless the <tt class="docutils literal"><span class="pre">--language-force</span></tt> option is specified, the language of each source +file is automatically selected based upon a <em>mapping</em> of file names to +languages. The mappings in effect for each language may be displayed using +the <tt class="docutils literal"><span class="pre">--list-maps</span></tt> option and may be changed using the <tt class="docutils literal"><span class="pre">--langmap</span></tt> or +<tt class="docutils literal"><span class="pre">--map-<LANG></span></tt> options.</p> +<p>If the name of a file is not mapped to a language, ctags tries +to heuristically guess the language for the file by inspecting its content.</p> +<p>All files that have no file name mapping and no guessed parser are +ignored. This permits running ctags on all files in +either a single directory (e.g. "<tt class="docutils literal">ctags *</tt>"), or on +all files in an entire source directory tree +(e.g. "<tt class="docutils literal">ctags <span class="pre">-R</span></tt>"), since only those files whose +names are mapped to languages will be scanned.</p> +<p>An extension may be mapped to multiple parsers. For example, <tt class="docutils literal">.h</tt> +are mapped to C++, C and ObjectiveC. These mappings can cause +issues. ctags tries to select the proper parser +for the source file by applying heuristics to its content, however +it is not perfect. In case of issues one can use <tt class="docutils literal"><span class="pre">--language-force=<language></span></tt>, +<tt class="docutils literal"><span class="pre">--langmap=<map>[,<map>[...]]</span></tt>, or the <tt class="docutils literal"><span class="pre">--map-<LANG>=[+|-]<extension>|<pattern></span></tt> +options. (Some of the heuristics are applied whether <tt class="docutils literal"><span class="pre">--guess-language-eagerly</span></tt> +is given or not.)</p> +<!-- TODO: all heuristics??? To be confirmed. --> +</div> +<div class="section" id="heuristically-guessing"> +<h3>Heuristically guessing</h3> +<p>If ctags cannot select a parser from the mapping of file names, +various heuristic tests are conducted to determine the language:</p> +<dl class="docutils"> +<dt>template file name testing</dt> +<dd>If the file name has an <tt class="docutils literal">.in</tt> extension, ctags applies +the mapping to the file name without the extension. For example, +<tt class="docutils literal">config.h</tt> is tested for a file named <tt class="docutils literal">config.h.in</tt>.</dd> +<dt>"interpreter" testing</dt> +<dd><p class="first">The first line of the file is checked to see if the file is a <tt class="docutils literal">#!</tt> +script for a recognized language. ctags looks for +a parser having the same name.</p> +<p>If ctags finds no such parser, +ctags looks for the name in alias lists. For +example, consider if the first line is <tt class="docutils literal"><span class="pre">#!/bin/sh</span></tt>. Though +ctags has a "shell" parser, it doesn't have a "sh" +parser. However, <tt class="docutils literal">sh</tt> is listed as an alias for <tt class="docutils literal">shell</tt>, therefore +ctags selects the "shell" parser for the file.</p> +<p>An exception is <tt class="docutils literal">env</tt>. If <tt class="docutils literal">env</tt> is specified (for example +"<tt class="docutils literal"><span class="pre">#!/usr/bin/env</span> python</tt>"), ctags +reads more lines to find real interpreter specification.</p> +<p class="last">To display the list of aliases, use <tt class="docutils literal"><span class="pre">--list-aliases</span></tt> option. +To add an item to the list or to remove an item from the list, use the +<tt class="docutils literal"><span class="pre">--alias-<LANG>=+<pattern></span></tt> or <tt class="docutils literal"><span class="pre">--alias-<LANG>=-<pattern></span></tt> option +respectively.</p> +</dd> +<dt>"zsh autoload tag" testing</dt> +<dd>If the first line starts with <tt class="docutils literal">#compdef</tt> or <tt class="docutils literal">#autoload</tt>, +ctags regards the line as "zsh".</dd> +<dt>"emacs mode at the first line" testing</dt> +<dd><p class="first">The Emacs editor has multiple editing modes specialized for programming +languages. Emacs can recognize a marker called modeline in a file +and utilize the marker for the mode selection. This heuristic test does +the same as what Emacs does.</p> +<p>ctags treats <tt class="docutils literal">MODE</tt> as a name of interpreter and applies the same +rule of "interpreter" testing if the first line has one of +the following patterns:</p> +<pre class="literal-block"> +-*- mode: MODE -*- +</pre> +<p>or</p> +<pre class="last literal-block"> +-*- MODE -*- +</pre> +</dd> +<dt>"emacs mode at the EOF" testing</dt> +<dd><p class="first">Emacs editor recognizes another marker at the end of file as a +mode specifier. This heuristic test does the same as what Emacs does.</p> +<p>ctags treats <tt class="docutils literal">MODE</tt> as a name of an interpreter and applies the same +rule of "interpreter" heuristic testing, if the lines at the tail of the file +have the following pattern:</p> +<pre class="literal-block"> +Local Variables: +... +mode: MODE +... +End: +</pre> +<p class="last">3000 characters are sought from the end of file to find the pattern.</p> +</dd> +<dt>"vim modeline" testing</dt> +<dd><p class="first">Like the modeline of the Emacs editor, Vim editor has the same concept. +ctags treats <tt class="docutils literal">TYPE</tt> as a name of interpreter and applies the same +rule of "interpreter" heuristic testing if the last 5 lines of the file +have one of the following patterns:</p> +<pre class="literal-block"> +filetype=TYPE +</pre> +<p>or</p> +<pre class="last literal-block"> +ft=TYPE +</pre> +</dd> +<dt>"PHP marker" testing</dt> +<dd>If the first line is started with <tt class="docutils literal"><span class="pre"><?php</span></tt>, +ctags regards the line as "php".</dd> +</dl> +<p>Looking into the file contents is a more expensive operation than file +name matching. So ctags runs the testings in limited +conditions. "interpreter" testing is enabled only when a file is an +executable or the <tt class="docutils literal"><span class="pre">--guess-language-eagerly</span></tt> (<tt class="docutils literal"><span class="pre">-G</span></tt> in short) option is +given. The other heuristic tests are enabled only when <tt class="docutils literal"><span class="pre">-G</span></tt> option is +given.</p> +<p>The <tt class="docutils literal"><span class="pre">--print-language</span></tt> option can be used just to print the results of +parser selections for given files instead of generating a tags file.</p> +<p>Examples:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --print-language config.h.in input.m input.unknown +<span class="generic output">config.h.in: C++ +input.m: MatLab +input.unknown: NONE</span> +</pre> +<p><tt class="docutils literal">NONE</tt> means that ctags does not select any parser for the file.</p> +</div> +</div> +</div> +<div class="section" id="tag-file-format"> +<h1>TAG FILE FORMAT</h1> +<p>This section describes the tag file format briefly. See tags(5) and +ctags-client-tools(7) for more details.</p> +<p>When not running in etags mode, each entry in the tag file consists of a +separate line, each looking like this, called <em>regular tags</em>, in the most general case:</p> +<pre class="literal-block"> +<tag_name><TAB><file_name><TAB><ex_cmd>;"<TAB><extension_fields> +</pre> +<p>The fields and separators of these lines are specified as follows:</p> +<blockquote> +<ol class="arabic"> +<li><p class="first"><tt class="docutils literal"><tag_name></tt>: tag name</p> +</li> +<li><p class="first"><tt class="docutils literal"><TAB></tt>: single tab character</p> +</li> +<li><p class="first"><tt class="docutils literal"><file_name></tt>: name of the file in which the object associated with the tag is located</p> +</li> +<li><p class="first"><tt class="docutils literal"><TAB></tt>: single tab character</p> +</li> +<li><p class="first"><tt class="docutils literal"><ex_cmd></tt>: EX command used to locate the tag within the file; generally a +search pattern (either <tt class="docutils literal">/pattern/</tt> or <tt class="docutils literal"><span class="pre">?pattern?</span></tt>) or line number (see +<tt class="docutils literal"><span class="pre">--excmd=<type></span></tt> option).</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">;"<TAB><extension_fields></span></tt>: a set of extension fields. See +"<a class="reference internal" href="#extension-fields">Extension fields</a>" for more details.</p> +<p>Tag file format 2 (see <tt class="docutils literal"><span class="pre">--format</span></tt>) extends the EX command +to include the extension fields embedded in an EX comment immediately appended +to the EX command, which leaves it backward-compatible with original +<tt class="docutils literal">vi(1)</tt> implementations.</p> +</li> +</ol> +</blockquote> +<p>A few special tags, called <em>pseudo tags</em>, are written into the tag file for internal purposes.</p> +<pre class="literal-block"> +!_TAG_FILE_FORMAT 2 /extended format; --format=1 will not append ;" to lines/ +!_TAG_FILE_SORTED 1 /0=unsorted, 1=sorted, 2=foldcase/ +... +</pre> +<p><tt class="docutils literal"><span class="pre">--pseudo-tags=[+|-](<pseudo-tag>|*)</span></tt> option enables or disables emitting pseudo-tags.</p> +<p>See the output of "<tt class="docutils literal">ctags <span class="pre">--list-pseudo-tags</span></tt>" for the list of +the kinds. +See also tags(5) and ctags-client-tools(7) for more details of the pseudo tags.</p> +<p>These tags are composed in such a way that they always sort to the top of +the file. Therefore, the first two characters of these tags are used a magic +number to detect a tag file for purposes of determining whether a +valid tag file is being overwritten rather than a source file.</p> +<p>Note that the name of each source file will be recorded in the tag file +exactly as it appears on the command line. Therefore, if the path you +specified on the command line was relative to the current directory, then +it will be recorded in that same manner in the tag file. See, however, +the <tt class="docutils literal"><span class="pre">--tag-relative=(yes|no|always|never)</span></tt> option for how this behavior can be +modified.</p> +</div> +<div class="section" id="id1"> +<span id="tag-entries"></span><h1>TAG ENTRIES</h1> +<p>A tag is an index for a language object. The concept of a tag and related +items in Exuberant Ctags are refined and extended in Universal Ctags.</p> +<p>A tag is categorized into <em>definition tags</em> or <em>reference tags</em>. +In general, Exuberant Ctags only tags <em>definitions</em> of +language objects: places where newly named language objects <em>are introduced</em>. +Universal Ctags, on the other hand, can also tag <em>references</em> of language +objects: places where named language objects <em>are used</em>. However, support +for generating reference tags is new and limited to specific areas of +specific languages in the current version.</p> +<div class="section" id="extension-fields"> +<h2>Extension fields</h2> +<p>A tag can record various information, called <em>extension fields</em>.</p> +<p>Extension fields are tab-separated key-value pairs appended to the end of +the EX command as a comment, as described above. These key value pairs +appear in the general form <tt class="docutils literal">key:value</tt>.</p> +<p>In addition, information on the scope of the tag definition may be +available, with the key portion equal to some language-dependent construct +name and its value the name declared for that construct in the program. +This scope entry indicates the scope in which the tag was found. +For example, a tag generated for a C structure member would have a scope +looking like <tt class="docutils literal">struct:myStruct</tt>.</p> +<p><tt class="docutils literal"><span class="pre">--fields=[+|-][<flags>|*]</span></tt> and <tt class="docutils literal"><span class="pre">--fields-(<LANG>|all)=[+|-][<flags>|*]</span></tt> options specifies +which available extension fields are to be included in the tag entries.</p> +<p>See the output of "<tt class="docutils literal">ctags <span class="pre">--list-fields</span></tt>" for the list of +extension fields. +The essential fields are <tt class="docutils literal">name</tt>, <tt class="docutils literal">input</tt>, <tt class="docutils literal">pattern</tt>, and <tt class="docutils literal">line</tt>. +The meaning of major fields is as follows (long-name flag/one-letter flag):</p> +<dl class="docutils"> +<dt><tt class="docutils literal">access</tt>/<tt class="docutils literal">a</tt></dt> +<dd>Indicates the visibility of this class member, where value is specific +to the language.</dd> +<dt><tt class="docutils literal">end</tt>/<tt class="docutils literal">e</tt></dt> +<dd>Indicates the line number of the end lines of the language object.</dd> +<dt><tt class="docutils literal">extras</tt>/<tt class="docutils literal">E</tt></dt> +<dd>Extra tag type information. See "<a class="reference internal" href="#extras">Extras</a>" for details.</dd> +<dt><tt class="docutils literal">file</tt>/<tt class="docutils literal">f</tt></dt> +<dd>Indicates that the tag has file-limited visibility. This key has no +corresponding value. Enabled by default.</dd> +<dt><tt class="docutils literal">implementation</tt>/<tt class="docutils literal">m</tt></dt> +<dd>When present, this indicates a limited implementation (abstract vs. +concrete) of a routine or class, where value is specific to the +language (<tt class="docutils literal">virtual</tt> or <tt class="docutils literal">pure virtual</tt> for C++; <tt class="docutils literal">abstract</tt> for Java).</dd> +<dt><tt class="docutils literal">inherits</tt>/<tt class="docutils literal">i</tt></dt> +<dd>When present, value is a comma-separated list of classes from which +this class is derived (i.e. inherits from).</dd> +<dt><tt class="docutils literal">input</tt>/<tt class="docutils literal">F</tt></dt> +<dd>The name of source file where <tt class="docutils literal">name</tt> is defined or referenced.</dd> +<dt><tt class="docutils literal">k</tt></dt> +<dd><a class="reference external" href="Kinds">Kind</a> of tag as one-letter. Enabled by default. +This field has no long-name. +See also <tt class="docutils literal">kind</tt>/<tt class="docutils literal">z</tt> flag.</dd> +<dt><tt class="docutils literal">K</tt></dt> +<dd><a class="reference external" href="Kinds">Kind</a> of tag as long-name. +This field has no long-name. +See also <tt class="docutils literal">kind</tt>/<tt class="docutils literal">z</tt> flag.</dd> +<dt><tt class="docutils literal">kind</tt>/<tt class="docutils literal">z</tt></dt> +<dd>Include the <tt class="docutils literal">kind:</tt> key in <a class="reference external" href="Kinds">kind field</a>. See also <tt class="docutils literal">k</tt> and <tt class="docutils literal">K</tt> flags.</dd> +<dt><tt class="docutils literal">language</tt>/<tt class="docutils literal">l</tt></dt> +<dd>Language of source file containing tag</dd> +<dt><tt class="docutils literal">line</tt>/<tt class="docutils literal">n</tt></dt> +<dd>The line number where <tt class="docutils literal">name</tt> is defined or referenced in <tt class="docutils literal">input</tt>.</dd> +<dt><tt class="docutils literal">name</tt>/<tt class="docutils literal">N</tt></dt> +<dd>The name of language objects.</dd> +<dt><tt class="docutils literal">pattern</tt>/<tt class="docutils literal">P</tt></dt> +<dd>Can be used to search the <tt class="docutils literal">name</tt> in <tt class="docutils literal">input</tt></dd> +<dt><tt class="docutils literal">roles</tt>/<tt class="docutils literal">r</tt></dt> +<dd>Roles assigned to the tag. See "<a class="reference internal" href="#roles">Roles</a>" for more details.</dd> +<dt><tt class="docutils literal">s</tt></dt> +<dd>Scope of tag definition. Enabled by default. +This field has no long-name. +See also <tt class="docutils literal">scope</tt>/<tt class="docutils literal">Z</tt> flag.</dd> +<dt><tt class="docutils literal">scope</tt>/<tt class="docutils literal">Z</tt></dt> +<dd>Prepend the <tt class="docutils literal">scope:</tt> key to scope (<tt class="docutils literal">s</tt>) field. +See also <tt class="docutils literal">s</tt> flag.</dd> +<dt><tt class="docutils literal">scopeKind</tt>/<tt class="docutils literal">p</tt></dt> +<dd>Kind of scope as long-name</dd> +<dt><tt class="docutils literal">signature</tt>/<tt class="docutils literal">S</tt></dt> +<dd>When present, value is a language-dependent representation of the +signature of a routine (e.g. prototype or parameter list). A routine signature in its complete form +specifies the return type of a routine and its formal argument list. +This extension field is presently supported only for C-based +languages and does not include the return type.</dd> +<dt><tt class="docutils literal">typeref</tt>/<tt class="docutils literal">t</tt></dt> +<dd>Type and name of a variable, typedef, or return type of +callable like function as <tt class="docutils literal">typeref:</tt> field. +Enabled by default.</dd> +</dl> +<div class="section" id="kinds"> +<h3>Kinds</h3> +<p><tt class="docutils literal">kind</tt> is a field which represents the <em>kind</em> of language object +specified by a tag. Kinds used and defined are very different between +parsers. For example, C language defines <tt class="docutils literal">macro</tt>, <tt class="docutils literal">function</tt>, +<tt class="docutils literal">variable</tt>, <tt class="docutils literal">typedef</tt>, etc.</p> +<p><tt class="docutils literal"><span class="pre">--kinds-(<LANG>|all)=[+|-](<kinds>|*)</span></tt> option specifies a list of language-specific +kinds of tags (or kinds) to include in the output file for a particular +language.</p> +<p>See the output of "<tt class="docutils literal">ctags <span class="pre">--list-kinds-full</span></tt>" for the complete +list of the kinds.</p> +<p>Its value is either one of the +corresponding one-letter flags or a long-name flag. It is permitted +(and is, in fact, the default) for the key portion of this field to be +omitted. The optional behaviors are controlled with the <tt class="docutils literal"><span class="pre">--fields</span></tt> option as follows.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags -o - kinds.c +<span class="generic output">foo kinds.c /^int foo() {$/;" f typeref:typename:int +</span><span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+k -o - kinds.c +<span class="generic output">foo kinds.c /^int foo() {$/;" f typeref:typename:int +</span><span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+K -o - kinds.c +<span class="generic output">foo kinds.c /^int foo() {$/;" function typeref:typename:int +</span><span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+z -o - kinds.c +<span class="generic output">foo kinds.c /^int foo() {$/;" kind:f typeref:typename:int +</span><span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+zK -o - kinds.c +<span class="generic output">foo kinds.c /^int foo() {$/;" kind:function typeref:typename:int</span> +</pre> +</div> +<div class="section" id="roles"> +<h3>Roles</h3> +<p><em>Role</em> is a newly introduced concept in Universal Ctags. Role is a +concept associated with reference tags, and is not implemented widely yet.</p> +<p>As described previously in "<a class="reference internal" href="#kinds">Kinds</a>", the <tt class="docutils literal">kind</tt> field represents the type +of language object specified with a tag, such as a function vs. a variable. +Specific kinds are defined for reference tags, such as the C++ kind <tt class="docutils literal">header</tt> for +header file, or Java kind <tt class="docutils literal">package</tt> for package statements. For such reference +kinds, a <tt class="docutils literal">roles</tt> field can be added to distinguish the role of the reference +kind. In other words, the <tt class="docutils literal">kind</tt> field identifies the <em>what</em> of the language +object, whereas the <tt class="docutils literal">roles</tt> field identifies the <em>how</em> of a referenced language +object. Roles are only used with specific kinds.</p> +<p>For a definition tag, this field takes <tt class="docutils literal">def</tt> as a value.</p> +<p>For example, <tt class="docutils literal">Baz</tt> is tagged as a reference tag with kind <tt class="docutils literal">package</tt> and with +role <tt class="docutils literal">imported</tt> with the following code.</p> +<pre class="code java literal-block"> +<span class="keyword namespace">package</span> <span class="name namespace">Bar</span><span class="punctuation">;</span> +<span class="keyword namespace">import</span> <span class="name namespace">Baz</span><span class="punctuation">;</span> + +<span class="keyword declaration">class</span> <span class="name class">Foo</span> <span class="punctuation">{</span> + <span class="comment single">// ... +</span><span class="punctuation">}</span> +</pre> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+KEr -uo - roles.java +<span class="generic output">Bar roles.java /^package Bar;$/;" package roles:def +Foo roles.java /^class Foo {$/;" class roles:def +</span><span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+EKr --extras<span class="operator">=</span>+r -uo - roles.java +<span class="generic output">Bar roles.java /^package Bar;$/;" package roles:def +Baz roles.java /^import Baz;$/;" package roles:imported extras:reference +Foo roles.java /^class Foo {$/;" class roles:def</span> +</pre> +<p><tt class="docutils literal"><span class="pre">--roles-(<LANG>|all).(<kind>|all)=[+|-][<roles>|*]</span></tt> option specifies a list of kind-specific +roles of tags to include in the output file for a particular language.</p> +<p>Inquire the output of "<tt class="docutils literal">ctags <span class="pre">--list-roles</span></tt>" for the list of +roles.</p> +</div> +</div> +<div class="section" id="extras"> +<h2>Extras</h2> +<p>Generally, ctags tags only language objects appearing +in source files, as is. In other words, a value for a <tt class="docutils literal">name:</tt> field +should be found on the source file associated with the <tt class="docutils literal">name:</tt>. An +<tt class="docutils literal">extra</tt> type tag (<em>extra</em>) is for tagging a language object with a processed +name, or for tagging something not associated with a language object. A typical +extra tag is <tt class="docutils literal">qualified</tt>, which tags a language object with a +class-qualified or scope-qualified name.</p> +<p><tt class="docutils literal"><span class="pre">--extras-(<LANG>|all)=[+|-][<flags>|*]</span></tt> option specifies +whether to include extra tag entries for certain kinds of information.</p> +<p>Inquire the output of <tt class="docutils literal">ctags <span class="pre">--list-extras</span></tt> for the list of extras. +The meaning of major extras is as follows (long-name flag/one-letter flag):</p> +<dl class="docutils"> +<dt><tt class="docutils literal">anonymous</tt>/none</dt> +<dd><p class="first">Include an entry for the language object that has no name like lambda +function. This extra has no one-letter flag and is enabled by +default.</p> +<p>The extra tag is useful as a placeholder to fill scope fields +for language objects defined in a language object with no name.</p> +<pre class="code C literal-block"> +<span class="keyword">struct</span> <span class="punctuation">{</span> + <span class="keyword type">double</span> <span class="name">x</span><span class="punctuation">,</span> <span class="name">y</span><span class="punctuation">;</span> +<span class="punctuation">}</span> <span class="name">p</span> <span class="operator">=</span> <span class="punctuation">{</span> <span class="punctuation">.</span><span class="name">x</span> <span class="operator">=</span> <span class="literal number float">0.0</span><span class="punctuation">,</span> <span class="punctuation">.</span><span class="name">y</span> <span class="operator">=</span> <span class="literal number float">0.0</span> <span class="punctuation">};</span> +</pre> +<p>'<tt class="docutils literal">x</tt>' and '<tt class="docutils literal">y</tt>' are the members of a structure. When filling the scope +fields for them, ctags has trouble because the struct +where '<tt class="docutils literal">x</tt>' and '<tt class="docutils literal">y</tt>' belong to has no name. For overcoming the trouble, +ctags generates an anonymous extra tag for the struct +and fills the scope fields with the name of the extra tag.</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>-f -uo - input.c +<span class="generic output">__anon9f26d2460108 input.c /^struct {$/;" s +x input.c /^ double x, y;$/;" m struct:__anon9f26d2460108 +y input.c /^ double x, y;$/;" m struct:__anon9f26d2460108 +p input.c /^} p = { .x = 0.0, .y = 0.0 };$/;" v typeref:struct:__anon9f26d2460108</span> +</pre> +<p class="last">The above tag output has <tt class="docutils literal">__anon9f26d2460108</tt> as an anonymous extra tag. +The typeref field of '<tt class="docutils literal">p</tt>' also receives the benefit of it.</p> +</dd> +<dt><tt class="docutils literal">fileScope</tt>/<tt class="docutils literal">F</tt></dt> +<dd><p class="first">Indicates whether tags scoped only for a single file (i.e. tags which +cannot be seen outside of the file in which they are defined, such as +language objects with <tt class="docutils literal">static</tt> modifier of C language) should be included +in the output. See also the <tt class="docutils literal"><span class="pre">-h</span></tt> option.</p> +<p>This extra tag is enabled by default. Add <tt class="docutils literal"><span class="pre">--extras=-F</span></tt> option not to +output tags scoped only for a single-file. This is the replacement for +<tt class="docutils literal"><span class="pre">--file-scope</span></tt> option of Exuberant Ctags.</p> +<pre class="code c literal-block"> +<span class="keyword">static</span> <span class="keyword type">int</span> <span class="name function">f</span><span class="punctuation">()</span> <span class="punctuation">{</span> + <span class="keyword">return</span> <span class="literal number integer">0</span><span class="punctuation">;</span> +<span class="punctuation">}</span> +<span class="keyword type">int</span> <span class="name function">g</span><span class="punctuation">()</span> <span class="punctuation">{</span> + <span class="keyword">return</span> <span class="literal number integer">0</span><span class="punctuation">;</span> +<span class="punctuation">}</span> +</pre> +<pre class="code console last literal-block"> +<span class="generic prompt">$ </span>ctags -uo - filescope.c +<span class="generic output">f filescope.c /^static int f() {$/;" f typeref:typename:int file: +g filescope.c /^int g() {$/;" f typeref:typename:int +</span><span class="generic prompt">$ </span>ctags --extras<span class="operator">=</span>-F -uo - filescope.c +<span class="generic output">g filescope.c /^int g() {$/;" f typeref:typename:int</span> +</pre> +</dd> +<dt><tt class="docutils literal">inputFile</tt>/<tt class="docutils literal">f</tt></dt> +<dd><p class="first">Include an entry for the base file name of every source file +(e.g. <tt class="docutils literal">example.c</tt>), which addresses the first line of the file. +This flag is the replacement for <tt class="docutils literal"><span class="pre">--file-tags</span></tt> hidden option of +Exuberant Ctags.</p> +<p>If the <tt class="docutils literal">end:</tt> field is enabled, the end line number of the file can be +attached to the tag. (However, ctags omits the <tt class="docutils literal">end:</tt> field +if no newline is in the file like an empty file.)</p> +<p>By default, ctags doesn't create the <tt class="docutils literal">inputFile</tt>/<tt class="docutils literal">f</tt> extra +tag for the source file when ctags doesn't find a parser +for it. Enabling <tt class="docutils literal">Unknown</tt> parser with <tt class="docutils literal"><span class="pre">--languages=+Unknown</span></tt> forces +ctags to create the extra tags for any source files.</p> +<p class="last">The etags mode enables the <tt class="docutils literal">Unknown</tt> parser implicitly.</p> +</dd> +<dt><tt class="docutils literal">pseudo</tt>/<tt class="docutils literal">p</tt></dt> +<dd>Include pseudo-tags. Enabled by default unless the tag file is +written to standard output. See ctags-client-tools(7) about +the detail of pseudo-tags.</dd> +<dt><tt class="docutils literal">qualified</tt>/<tt class="docutils literal">q</tt></dt> +<dd><p class="first">Include an extra class-qualified or namespace-qualified tag entry +for each tag which is a member of a class or a namespace.</p> +<p>This may allow easier location of a specific tags when +multiple occurrences of a tag name occur in the tag file. +Note, however, that this could potentially more than double +the size of the tag file.</p> +<p>The actual form of the qualified tag depends upon the language +from which the tag was derived (using a form that is most +natural for how qualified calls are specified in the +language). For C++ and Perl, it is in the form +<tt class="docutils literal"><span class="pre">class::member</span></tt>; for Eiffel and Java, it is in the form +<tt class="docutils literal">class.member</tt>.</p> +<p>Note: Using backslash characters as separators forming +qualified name in PHP. However, in tags output of +Universal Ctags, a backslash character in a name is escaped +with a backslash character. See tags(5) about the escaping.</p> +<p>The following example demonstrates the <tt class="docutils literal">qualified</tt> extra tag.</p> +<pre class="code Java literal-block"> +<span class="keyword declaration">class</span> <span class="name class">point</span> <span class="punctuation">{</span> + <span class="keyword type">double</span> <span class="name">x</span><span class="punctuation">;</span> +<span class="punctuation">};</span> +</pre> +<p>For the above source file, ctags tags <tt class="docutils literal">point</tt> and <tt class="docutils literal">x</tt> by +default. If the <tt class="docutils literal">qualified</tt> extra is enabled from the command line +(<tt class="docutils literal"><span class="pre">--extras=+q</span></tt>), then <tt class="docutils literal">point.x</tt> is also tagged even though the string +"<tt class="docutils literal">point.x</tt>" is not in the source code.</p> +<pre class="code console last literal-block"> +<span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+K -uo - qualified.java +<span class="generic output">point qualified.java /^class point {$/;" class +x qualified.java /^ double x;$/;" field class:point +</span><span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+K --extras<span class="operator">=</span>+q -uo - qualified.java +<span class="generic output">point qualified.java /^class point {$/;" class +x qualified.java /^ double x;$/;" field class:point +point.x qualified.java /^ double x;$/;" field class:point</span> +</pre> +</dd> +<dt><tt class="docutils literal">reference</tt>/<tt class="docutils literal">r</tt></dt> +<dd><p class="first">Include reference tags. See "<a class="reference internal" href="#id1">TAG ENTRIES</a>" about reference tags.</p> +<p>The following example demonstrates the <tt class="docutils literal">reference</tt> extra tag.</p> +<pre class="code c literal-block"> +<span class="comment preproc">#include</span> <span class="comment preprocfile"><stdio.h></span><span class="comment preproc"> +#include</span> <span class="comment preprocfile">"utils.h"</span><span class="comment preproc"> +#define X +#undef X</span> +</pre> +<p>The <tt class="docutils literal">roles:system</tt> or <tt class="docutils literal">roles:local</tt> fields will be +added depending on whether the include file name begins with '<tt class="docutils literal"><</tt>' or not.</p> +<p>"<tt class="docutils literal">#define X</tt>" emits a definition tag. On the other hand "<tt class="docutils literal">#undef X</tt>" emits a +reference tag.</p> +<pre class="code console last literal-block"> +<span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+EKr -uo - inc.c +<span class="generic output">X inc.c /^#define X$/;" macro file: roles:def extras:fileScope +</span><span class="generic prompt">$ </span>ctags --fields<span class="operator">=</span>+EKr --extras<span class="operator">=</span>+r -uo - inc.c +<span class="generic output">stdio.h inc.c /^#include <stdio.h>/;" header roles:system extras:reference +utils.h inc.c /^#include "utils.h"/;" header roles:local extras:reference +X inc.c /^#define X$/;" macro file: roles:def extras:fileScope +X inc.c /^#undef X$/;" macro file: roles:undef extras:fileScope,reference</span> +</pre> +</dd> +</dl> +</div> +<div class="section" id="language-specific-fields-and-extras"> +<h2>Language-specific fields and extras</h2> +<p>Exuberant Ctags has the concept of <em>fields</em> and <em>extras</em>. They are common +between parsers of different languages. Universal Ctags extends this concept +by providing language-specific fields and extras.</p> +<!-- Note: kinds are language-specific since e-ctags. roles are new to u-ctags. --> +<!-- TODO: move the following "Hot to ..." sections to FAQ man page when available --> +</div> +</div> +<div class="section" id="how-to-use-with-vi"> +<h1>HOW TO USE WITH VI</h1> +<p><tt class="docutils literal">vi(1)</tt> will, by default, expect a tag file by the name <tt class="docutils literal">tags</tt> in the current +directory. Once the tag file is built, the following commands exercise +the tag indexing feature:</p> +<dl class="docutils"> +<dt><tt class="docutils literal">vi <span class="pre">-t</span> tag</tt></dt> +<dd>Start vi and position the cursor at the file and line where <tt class="docutils literal">tag</tt> +is defined.</dd> +<dt><tt class="docutils literal">:ta tag</tt></dt> +<dd>Find a tag.</dd> +<dt><tt class="docutils literal"><span class="pre">Ctrl-]</span></tt></dt> +<dd>Find the tag under the cursor.</dd> +<dt><tt class="docutils literal"><span class="pre">Ctrl-T</span></tt></dt> +<dd>Return to previous location before jump to tag (not widely implemented).</dd> +</dl> +</div> +<div class="section" id="how-to-use-with-gnu-emacs"> +<h1>HOW TO USE WITH GNU EMACS</h1> +<p><tt class="docutils literal">emacs(1)</tt> will, by default, expect a tag file by the name <tt class="docutils literal">TAGS</tt> in the +current directory. Once the tag file is built, the following commands +exercise the tag indexing feature:</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">visit-tags-table</span> <RET> FILE <RET></tt></dt> +<dd>Select the tag file, <tt class="docutils literal">FILE</tt>, to use.</dd> +<dt><tt class="docutils literal"><span class="pre">M-.</span> [TAG] <RET></tt></dt> +<dd>Find the first definition of TAG. The default tag is the identifier +under the cursor.</dd> +<dt><tt class="docutils literal"><span class="pre">M-*</span></tt></dt> +<dd>Pop back to where you previously invoked <tt class="docutils literal"><span class="pre">M-.</span></tt>.</dd> +<dt><tt class="docutils literal"><span class="pre">C-u</span> <span class="pre">M-.</span></tt></dt> +<dd>Find the next definition for the last tag.</dd> +</dl> +<p>For more commands, see the Tags topic in the Emacs info document.</p> +</div> +<div class="section" id="how-to-use-with-nedit"> +<h1>HOW TO USE WITH NEDIT</h1> +<p>NEdit version 5.1 and later can handle the new extended tag file format +(see <tt class="docutils literal"><span class="pre">--format</span></tt>).</p> +<ul class="simple"> +<li>To make NEdit use the tag file, select "File->Load Tags File".</li> +<li>To jump to the definition for a tag, highlight the word, then press <tt class="docutils literal"><span class="pre">Ctrl-D</span></tt>.</li> +</ul> +<p>NEdit 5.1 can read multiple tag files from different +directories. Setting the X resource <tt class="docutils literal">nedit.tagFile</tt> to the name of a tag +file instructs NEdit to automatically load that tag file at startup time.</p> +</div> +<div class="section" id="caveats"> +<h1>CAVEATS</h1> +<p>Because ctags is neither a preprocessor nor a compiler, +use of preprocessor macros can fool ctags into either +missing tags or improperly generating inappropriate tags. Although +ctags has been designed to handle certain common cases, +this is the single biggest cause of reported problems. In particular, +the use of preprocessor constructs which alter the textual syntax of C +can fool ctags. You can work around many such problems +by using the <tt class="docutils literal"><span class="pre">-I</span></tt> option.</p> +<p>Note that since ctags generates patterns for locating +tags (see the <tt class="docutils literal"><span class="pre">--excmd</span></tt> option), it is entirely possible that the wrong line +may be found by your editor if there exists another source line which is +identical to the line containing the tag. The following example +demonstrates this condition:</p> +<pre class="code C literal-block"> +<span class="keyword type">int</span> <span class="name">variable</span><span class="punctuation">;</span> + +<span class="comment multiline">/* ... */</span> +<span class="keyword type">void</span> <span class="name function">foo</span><span class="punctuation">(</span><span class="name">variable</span><span class="punctuation">)</span> +<span class="keyword type">int</span> <span class="name">variable</span><span class="punctuation">;</span> +<span class="punctuation">{</span> + <span class="comment multiline">/* ... */</span> +<span class="punctuation">}</span> +</pre> +<p>Depending upon which editor you use and where in the code you happen to be, +it is possible that the search pattern may locate the local parameter +declaration before it finds the actual global variable definition, +since the lines (and therefore their search patterns) are +identical.</p> +<p>This can be avoided by use of the <tt class="docutils literal"><span class="pre">--excmd=n</span></tt> option.</p> +</div> +<div class="section" id="bugs"> +<h1>BUGS</h1> +<p>ctags has more options than <tt class="docutils literal">ls(1)</tt>.</p> +<p>ctags assumes the input file is written in the correct +grammar. Otherwise output of ctags is undefined. In other words it has garbage +in, garbage out (GIGO) feature.</p> +<!-- TODO: move the following paragraph to parser-cxx.rst. --> +<p>When parsing a C++ member function definition (e.g. <tt class="docutils literal"><span class="pre">className::function</span></tt>), +ctags cannot determine whether the scope specifier +is a class name or a namespace specifier and always lists it as a class name +in the scope portion of the extension fields. Also, if a C++ function +is defined outside of the class declaration (the usual case), the access +specification (i.e. public, protected, or private) and implementation +information (e.g. virtual, pure virtual) contained in the function +declaration are not known when the tag is generated for the function +definition. It will, however be available for prototypes (e.g. <tt class="docutils literal"><span class="pre">--kinds-c++=+p</span></tt>).</p> +<p>No qualified tags are generated for language objects inherited into a class.</p> +</div> +<div class="section" id="environment-variables"> +<h1>ENVIRONMENT VARIABLES</h1> +<dl class="docutils"> +<dt><tt class="docutils literal">TMPDIR</tt></dt> +<dd><p class="first">On Unix-like hosts where <tt class="docutils literal">mkstemp(3)</tt> is available, the value of this +variable specifies the directory in which to place temporary files. +This can be useful if the size of a temporary file becomes too large +to fit on the partition holding the default temporary directory +defined at compilation time.</p> +<p>ctags creates temporary +files only if either (1) an emacs-style tag file is being +generated, (2) the tag file is being sent to standard output, or +(3) the program was compiled to use an internal sort algorithm to sort +the tag files instead of the <tt class="docutils literal">sort(1)</tt> utility of the operating system. +If the <tt class="docutils literal">sort(1)</tt> utility of the operating system is being used, it will +generally observe this variable also.</p> +<p class="last">Note that if ctags +is setuid, the value of <tt class="docutils literal">TMPDIR</tt> will be ignored.</p> +</dd> +</dl> +</div> +<div class="section" id="files"> +<h1>FILES</h1> +<dl class="docutils"> +<dt><tt class="docutils literal">tags</tt></dt> +<dd>The default tag file created by ctags.</dd> +<dt><tt class="docutils literal">TAGS</tt></dt> +<dd>The default tag file created by etags.</dd> +</dl> +<p><tt class="docutils literal"><span class="pre">$XDG_CONFIG_HOME/ctags/*.ctags</span></tt>, or <tt class="docutils literal"><span class="pre">$HOME/.config/ctags/*.ctags</span></tt> if +<tt class="docutils literal">$XDG_CONFIG_HOME</tt> is not defined +(on other than MS Windows)</p> +<p><tt class="docutils literal"><span class="pre">$HOME/.ctags.d/*.ctags</span></tt></p> +<p><tt class="docutils literal"><span class="pre">$HOMEDRIVE$HOMEPATH/ctags.d/*.ctags</span></tt> (on MS Windows only)</p> +<p><tt class="docutils literal"><span class="pre">.ctags.d/*.ctags</span></tt></p> +<p><tt class="docutils literal"><span class="pre">ctags.d/*.ctags</span></tt></p> +<blockquote> +<p>If any of these configuration files exist, each will be expected to +contain a set of default options which are read in the order listed +when ctags starts, but before any command line options +are read. This makes it possible to set up personal or project-level defaults.</p> +<p>It +is possible to compile ctags to read an additional +configuration file before any of those shown above, which will be +indicated if the output produced by the <tt class="docutils literal"><span class="pre">--version</span></tt> option lists the +<tt class="docutils literal"><span class="pre">custom-conf</span></tt> feature.</p> +<p>Options appearing on the command line will override options +specified in these files. Only options will be read from these +files.</p> +<p>Note that the option +files are read in line-oriented mode in which spaces are significant +(since shell quoting is not possible) but spaces at the beginning +of a line are ignored. Each line of the file is read as +one command line parameter (as if it were quoted with single quotes). +Therefore, use new lines to indicate separate command-line arguments.</p> +<p>A line starting with '<tt class="docutils literal">#</tt>' is treated as a comment.</p> +<p><tt class="docutils literal">*.ctags</tt> files in a directory are loaded in alphabetical order.</p> +</blockquote> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>See ctags-optlib(7) for defining (or extending) a parser +in a configuration file.</p> +<p>See tags(5) for the format of tag files.</p> +<p>See ctags-incompatibilities(7) about known incompatible changes +with Exuberant Ctags.</p> +<p>See ctags-client-tools(7) if you are interested in writing +a tool for processing tags files.</p> +<p>See ctags-lang-python(7) about python input specific notes.</p> +<p>See readtags(1) about a client tool for binary searching a +name in a sorted tags file.</p> +<p>The official Universal Ctags web site at: <a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Also <tt class="docutils literal">ex(1)</tt>, <tt class="docutils literal">vi(1)</tt>, <tt class="docutils literal">elvis(1)</tt>, or, better yet, <tt class="docutils literal">vim(1)</tt>, the official editor of ctags. +For more information on <tt class="docutils literal">vim(1)</tt>, see the Vim web site at: <a class="reference external" href="https://www.vim.org/">https://www.vim.org/</a></p> +</div> +<div class="section" id="author"> +<h1>AUTHOR</h1> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert@users.sourceforge.net">dhiebert@users.sourceforge.net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +</div> +<div class="section" id="motivation"> +<h1>MOTIVATION</h1> +<p>"Think ye at all times of rendering some service to every member of the +human race."</p> +<p>"All effort and exertion put forth by man from the fullness of his heart is +worship, if it is prompted by the highest motives and the will to do +service to humanity."</p> +<p>-- From the Baha'i Writings</p> +</div> +<div class="section" id="credits"> +<h1>CREDITS</h1> +<p>This version of ctags (Universal Ctags) derived from +the repository, known as fishman-ctags, started by Reza Jelveh.</p> +<p>The fishman-ctags was derived from Exuberant Ctags.</p> +<p>Some parsers are taken from <tt class="docutils literal">tagmanager</tt> of the Geany (<a class="reference external" href="https://www.geany.org/">https://www.geany.org/</a>) +project.</p> +<p>Exuberant Ctags was originally derived from and +inspired by the ctags program by Steve Kirkendall <<a class="reference external" href="mailto:kirkenda@cs.pdx.edu">kirkenda@cs.pdx.edu</a>> +that comes with the Elvis vi clone (though virtually none of the original +code remains).</p> +<p>Credit is also due Bram Moolenaar <<a class="reference external" href="mailto:Bram@vim.org">Bram@vim.org</a>>, the author of vim, +who has devoted so much of his time and energy both to developing the editor +as a service to others, and to helping the orphans of Uganda.</p> +<p>The section entitled "<a class="reference internal" href="#how-to-use-with-gnu-emacs">HOW TO USE WITH GNU EMACS</a>" was shamelessly stolen +from the info page for GNU etags.</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/readtags.1.html b/ctags/man/readtags.1.html new file mode 100644 index 0000000..ba2034d --- /dev/null +++ b/ctags/man/readtags.1.html @@ -0,0 +1,692 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>readtags</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="readtags"> +<span id="readtags-1"></span> +<h1 class="title">readtags</h1> +<h2 class="subtitle" id="find-tag-file-entries-matching-specified-names">Find tag file entries matching specified names</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>5.9.0</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">1</td> +</tr> +</tbody> +</table> +<div class="section" id="synopsis"> +<h1>SYNOPSIS</h1> +<div class="line-block"> +<div class="line"><strong>readtags</strong> -h | --help</div> +<div class="line"><strong>readtags</strong> (-H | --help-expression) (filter|sorter)</div> +<div class="line"><strong>readtags</strong> [OPTION]... ACTION</div> +</div> +</div> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>The <strong>readtags</strong> program filters, sorts and prints tag entries in a tags file. +The basic filtering is done using <strong>actions</strong>, by which you can list all +regular tags, pseudo tags or regular tags matching specific name. Then, further +filtering and sorting can be done using <strong>post processors</strong>, namely <strong>filter +expressions</strong> and <strong>sorter expressions</strong>.</p> +</div> +<div class="section" id="actions"> +<h1>ACTIONS</h1> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">-l</span></tt>, <tt class="docutils literal"><span class="pre">--list</span></tt></dt> +<dd>List regular tags.</dd> +<dt><tt class="docutils literal"><span class="pre">[-]</span> NAME</tt></dt> +<dd>List regular tags matching NAME. +"-" as NAME indicates arguments after this as NAME even if they start with -.</dd> +<dt><tt class="docutils literal"><span class="pre">-D</span></tt>, <tt class="docutils literal"><span class="pre">--list-pseudo-tags</span></tt></dt> +<dd>Equivalent to <tt class="docutils literal"><span class="pre">--list-pseudo-tags</span></tt>.</dd> +</dl> +</div> +<div class="section" id="options"> +<h1>OPTIONS</h1> +<div class="section" id="controlling-the-tags-reading-behavior"> +<h2>Controlling the Tags Reading Behavior</h2> +<p>The behavior of reading tags can be controlled using these options:</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">-t</span> TAGFILE</tt>, <tt class="docutils literal"><span class="pre">--tag-file</span> TAGFILE</tt></dt> +<dd>Use specified tag file (default: "tags").</dd> +<dt><tt class="docutils literal"><span class="pre">-s[0|1|2]</span></tt>, <tt class="docutils literal"><span class="pre">--override-sort-detection</span> METHOD</tt></dt> +<dd>Override sort detection of tag file. +METHOD: unsorted|sorted|foldcase</dd> +</dl> +<p>The NAME action will perform binary search on sorted (including "foldcase") +tags files, which is much faster then on unsorted tags files.</p> +</div> +<div class="section" id="controlling-the-name-action-behavior"> +<h2>Controlling the NAME Action Behavior</h2> +<p>The behavior of the NAME action can be controlled using these options:</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">-i</span></tt>, <tt class="docutils literal"><span class="pre">--icase-match</span></tt></dt> +<dd>Perform case-insensitive matching in the NAME action.</dd> +<dt><tt class="docutils literal"><span class="pre">-p</span></tt>, <tt class="docutils literal"><span class="pre">--prefix-match</span></tt></dt> +<dd>Perform prefix matching in the NAME action.</dd> +</dl> +</div> +<div class="section" id="controlling-the-output"> +<h2>Controlling the Output</h2> +<p>By default, the output of readtags contains only the name, input and pattern +field. The Output can be tweaked using these options:</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">-d</span></tt>, <tt class="docutils literal"><span class="pre">--debug</span></tt></dt> +<dd>Turn on debugging output.</dd> +<dt><tt class="docutils literal"><span class="pre">-E</span></tt>, <tt class="docutils literal"><span class="pre">--escape-output</span></tt></dt> +<dd>Escape characters like tabs in output as described in tags(5).</dd> +<dt><tt class="docutils literal"><span class="pre">-e</span></tt>, <tt class="docutils literal"><span class="pre">--extension-fields</span></tt></dt> +<dd>Include extension fields in output.</dd> +<dt><tt class="docutils literal"><span class="pre">-n</span></tt>, <tt class="docutils literal"><span class="pre">--line-number</span></tt></dt> +<dd>Also include the line number field when <tt class="docutils literal"><span class="pre">-e</span></tt> option is give.</dd> +</dl> +<p>About the <tt class="docutils literal"><span class="pre">-E</span></tt> option: certain characters are escaped in a tags file, to make +it machine-readable. e.g., ensuring no tabs character appear in fields other +than the pattern field. By default, readtags translates them to make it +human-readable, but when utilizing readtags output in a script or a client +tool, <tt class="docutils literal"><span class="pre">-E</span></tt> option should be used. See ctags-client-tools(7) for more +discussion on this.</p> +</div> +<div class="section" id="filtering-and-sorting"> +<h2>Filtering and Sorting</h2> +<p>Further filtering and sorting on the tags listed by actions are performed using:</p> +<dl class="docutils"> +<dt><tt class="docutils literal"><span class="pre">-Q</span> EXP</tt>, <tt class="docutils literal"><span class="pre">--filter</span> EXP</tt></dt> +<dd>Filter the tags listed by ACTION with EXP before printing.</dd> +<dt><tt class="docutils literal"><span class="pre">-S</span> EXP</tt>, <tt class="docutils literal"><span class="pre">--sorter</span> EXP</tt></dt> +<dd>Sort the tags listed by ACTION with EXP before printing.</dd> +</dl> +<p>These are discussed in the <a class="reference internal" href="#expression">EXPRESSION</a> section.</p> +</div> +<div class="section" id="examples"> +<h2>Examples</h2> +<ul> +<li><p class="first">List all tags in "/path/to/tags":</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -t /path/to/tags -l +</pre> +</li> +<li><p class="first">List all tags in "tags" that start with "mymethod":</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -p - mymethod +</pre> +</li> +<li><p class="first">List all tags matching "mymethod", case insensitively:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -i - mymethod +</pre> +</li> +<li><p class="first">List all tags start with "myvar", and printing all fields (i.e., the whole line):</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -p -ne - myvar +</pre> +</li> +</ul> +</div> +</div> +<div class="section" id="expression"> +<h1>EXPRESSION</h1> +<p>Scheme-style expressions are used for the <tt class="docutils literal"><span class="pre">-Q</span></tt> and <tt class="docutils literal"><span class="pre">-S</span></tt> options. For those +who doesn't know Scheme or Lisp, just remember:</p> +<ul class="simple"> +<li>A function call is wrapped in a pair of parenthesis. The first item in it is +the function/operator name, the others are arguments.</li> +<li>Function calls can be nested.</li> +<li>Missing values and boolean false are represented by <tt class="docutils literal">#f</tt>. <tt class="docutils literal">#t</tt> and all +other values are considered to be true.</li> +</ul> +<p>So, <tt class="docutils literal">(+ 1 (+ 2 3))</tt> means add 2 and 3 first, then add the result with 1. +<tt class="docutils literal">(and "string" 1 #t)</tt> means logical AND on <tt class="docutils literal">"string"</tt>, <tt class="docutils literal">1</tt> and <tt class="docutils literal">#t</tt>, +and the result is true since there is no <tt class="docutils literal">#f</tt>.</p> +<div class="section" id="filtering"> +<h2>Filtering</h2> +<p>The tag entries that make the filter expression produces true value are printed +by readtags.</p> +<p>The basic operators for filtering are <tt class="docutils literal">eq?</tt>, <tt class="docutils literal">prefix?</tt>, <tt class="docutils literal">suffix?</tt>, +<tt class="docutils literal">substr?</tt>, and <tt class="docutils literal">#/PATTERN/</tt>. Language common fields can be accessed using +variables starting with <tt class="docutils literal">$</tt>, e.g., <tt class="docutils literal">$language</tt> represents the language field. +For example:</p> +<ul> +<li><p class="first">List all tags start with "myfunc" in Python code files:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -p -Q <span class="literal string single">'(eq? $language "Python")'</span> - myfunc +</pre> +</li> +</ul> +<p><tt class="docutils literal">downcase</tt> or <tt class="docutils literal">upcase</tt> operators can be used to perform case-insensitive +matching:</p> +<ul> +<li><p class="first">List all tags containing "my", case insensitively:</p> +<blockquote> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="literal string single">'(substr? (downcase $name) "my")'</span> -l +</pre> +</blockquote> +</li> +</ul> +<p>We have logical operators like <tt class="docutils literal">and</tt>, <tt class="docutils literal">or</tt> and <tt class="docutils literal">not</tt>. The value of a +missing field is #f, so we could deal with missing fields:</p> +<ul> +<li><p class="first">List all tags containing "impl" in Python code files, but allow the +<tt class="docutils literal">language:</tt> field to be missing:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="error">'</span><span class="operator">(</span>and <span class="operator">(</span>substr? <span class="name variable">$name</span> <span class="literal string double">"impl"</span><span class="operator">)</span><span class="literal string escape">\ +</span><span class="generic output"> (or (not $language)\ + (eq? $language "Python")))' -l</span> +</pre> +</li> +</ul> +<p><tt class="docutils literal">#/PATTERN/</tt> is for the case when string predicates (<tt class="docutils literal">prefix?</tt>, <tt class="docutils literal">suffix?</tt>, +and <tt class="docutils literal">substr?</tt>) are not enough. You can use "Posix extended regular expression" +as PATTERN.</p> +<ul> +<li><p class="first">List all tags inherits from the class "A":</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="literal string single">'(#/(^|,) ?A(,|$)/ $inherits)'</span> -l +</pre> +</li> +</ul> +<p>Here <tt class="docutils literal">$inherits</tt> is a comma-separated class list like "A,B,C", "P, A, Q", or +just "A". Notice that this filter works on both situations where there's a +space after each comma or there's not.</p> +<p>Case-insensitive matching can be performed by <tt class="docutils literal">#/PATTERN/i</tt>:</p> +<ul> +<li><p class="first">List all tags inherits from the class "A" or "a":</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="literal string single">'(#/(^|,) ?A(,|$)/i $inherits)'</span> -l +</pre> +</li> +</ul> +<p>To include "/" in a pattern, prefix <tt class="docutils literal">\</tt> to the "/".</p> +<p>NOTE: The above regular expression pattern for inspecting inheritances is just +an example to show how to use <tt class="docutils literal">#/PATTERN/</tt> expression. Tags file generators +have no consensus about the format of <tt class="docutils literal">inherits:</tt>, e.g., whether there should +be a space after a comma. Even parsers in ctags have no consensus. Noticing the +format of the <tt class="docutils literal">inherits:</tt> field of specific languages is needed for such +queries.</p> +<p>The expressions <tt class="docutils literal">#/PATTERN/</tt> and <tt class="docutils literal">#/PATTERN/i</tt> are for interactive use. +Readtags also offers an alias <tt class="docutils literal"><span class="pre">string->regexp</span></tt>, so <tt class="docutils literal">#/PATTERN/</tt> is equal to +<tt class="docutils literal"><span class="pre">(string->regexp</span> "PATTERN")</tt>, and <tt class="docutils literal">#/PATTERN/i</tt> is equal to +<tt class="docutils literal"><span class="pre">(string->regexp</span> "PATTERN" <span class="pre">:case-fold</span> #t)</tt>. <tt class="docutils literal"><span class="pre">string->regexp</span></tt> doesn't need +to prefix <tt class="docutils literal">\</tt> for including "/" in a pattern. <tt class="docutils literal"><span class="pre">string->regexp</span></tt> may simplify +a client tool building an expression. See also ctags-client-tools(7) for +building expressions in your tool.</p> +<p>Let's now consider missing fields. The tags file may have tag entries that has +no <tt class="docutils literal">inherits:</tt> field. In that case <tt class="docutils literal">$inherits</tt> is #f, and the regular +expression matching raises an error, since string operators only work for +strings. To avoid this problem:</p> +<ul> +<li><p class="first">Safely list all tags inherits from the class "A":</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="literal string single">'(and $inherits (#/(^|,) ?A(,|$)/ $inherits))'</span> -l +</pre> +</li> +</ul> +<p>This makes sure <tt class="docutils literal">$inherits</tt> is not missing first, then match it by regexp.</p> +<p>Sometimes you want to keep tags where the field <em>is</em> missing. For example, your +want to exclude reference tags, which is marked by the <tt class="docutils literal">extras:</tt> field, then +you want to keep tags who doesn't have <tt class="docutils literal">extras:</tt> field since they are also +not reference tags. Here's how to do it:</p> +<ul> +<li><p class="first">List all tags but the reference tags:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="literal string single">'(or (not $extras) (#/(^|,) ?reference(,|$)/ $extras))'</span> -l +</pre> +</li> +</ul> +<p>Notice that <tt class="docutils literal">(not $extras)</tt> produces <tt class="docutils literal">#t</tt> when <tt class="docutils literal">$extras</tt> is missing, so +the whole <tt class="docutils literal">or</tt> expression produces <tt class="docutils literal">#t</tt>.</p> +<p>Run "readtags -H filter" to know about all valid functions and variables.</p> +</div> +<div class="section" id="sorting"> +<h2>Sorting</h2> +<p>When sorting, the sorter expression is evaluated on two tag entries to decide +which should sort before the other one, until the order of all tag entries is +decided.</p> +<p>In a sorter expression, <tt class="docutils literal">$</tt> and <tt class="docutils literal">&</tt> are used to access the fields in the +two tag entries, and let's call them $-entry and &-entry. The sorter expression +should have a value of -1, 0 or 1. The value -1 means the $-entry should be put +above the &-entry, 1 means the contrary, and 0 makes their order in the output +uncertain.</p> +<p>The core operator of sorting is <tt class="docutils literal"><></tt>. It's used to compare two strings or two +numbers (numbers are for the <tt class="docutils literal">line:</tt> or <tt class="docutils literal">end:</tt> fields). In <tt class="docutils literal">(<> a b)</tt>, if +<tt class="docutils literal">a</tt> < <tt class="docutils literal">b</tt>, the result is -1; <tt class="docutils literal">a</tt> > <tt class="docutils literal">b</tt> produces 1, and <tt class="docutils literal">a</tt> = <tt class="docutils literal">b</tt> +produces 0. Strings are compared using the <tt class="docutils literal">strcmp</tt> function, see strcmp(3).</p> +<p>For example, sort by names, and make those shorter or alphabetically smaller +ones appear before the others:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -S <span class="literal string single">'(<> $name &name)'</span> -l +</pre> +<p>This reads "If the tag name in the $-entry is smaller, it goes before the +&-entry".</p> +<p>The <tt class="docutils literal"><or></tt> operator is used to chain multiple expressions until one returns +-1 or 1. For example, sort by input file names, then line numbers if in the +same file:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -S <span class="literal string single">'(<or> (<> $input &input) (<> $line &line))'</span> -l +</pre> +<p>The <tt class="docutils literal">*-</tt> operator is used to flip the compare result. i.e., <tt class="docutils literal">(*- (<> a b))</tt> +is the same as <tt class="docutils literal">(<> b a)</tt>.</p> +<p>Filter expressions can be used in sorter expressions. The technique is use +<tt class="docutils literal">if</tt> to produce integers that can be compared based on the filter, like:</p> +<pre class="code lisp literal-block"> +<span class="punctuation">(</span><span class="name variable"><></span> <span class="punctuation">(</span><span class="keyword">if</span> <span class="name variable">filter-expr-on-$-entry</span> <span class="literal number integer">-1</span> <span class="literal number integer">1</span><span class="punctuation">)</span> + <span class="punctuation">(</span><span class="keyword">if</span> <span class="name variable">filter-expr-on-&-entry</span> <span class="literal number integer">-1</span> <span class="literal number integer">1</span><span class="punctuation">))</span> +</pre> +<p>So if $-entry satisfies the filter, while &-entry doesn't, it's the same as +<tt class="docutils literal">(<> <span class="pre">-1</span> 1)</tt>, which produces <tt class="docutils literal"><span class="pre">-1</span></tt>.</p> +<p>For example, we want to put tags with "file" kind below other tags, then the +sorter would look like:</p> +<pre class="code lisp literal-block"> +<span class="punctuation">(</span><span class="name variable"><></span> <span class="punctuation">(</span><span class="keyword">if</span> <span class="punctuation">(</span><span class="name variable">eq?</span> <span class="name variable">$kind</span> <span class="literal string">"file"</span><span class="punctuation">)</span> <span class="literal number integer">1</span> <span class="literal number integer">-1</span><span class="punctuation">)</span> + <span class="punctuation">(</span><span class="keyword">if</span> <span class="punctuation">(</span><span class="name variable">eq?</span> <span class="name variable">&kind</span> <span class="literal string">"file"</span><span class="punctuation">)</span> <span class="literal number integer">1</span> <span class="literal number integer">-1</span><span class="punctuation">))</span> +</pre> +<p>A quick read tells us: If $-entry has "file" kind, and &-entry doesn't, the +sorter becomes <tt class="docutils literal">(<> 1 <span class="pre">-1)</span></tt>, which produces <tt class="docutils literal">1</tt>, so the $-entry is put below +the &-entry, exactly what we want.</p> +</div> +<div class="section" id="inspecting-the-behavior-of-expressions"> +<h2>Inspecting the Behavior of Expressions</h2> +<p>The <cite>print</cite> operator can be used to print the value of an expression. For +example:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="literal string single">'(print $name)'</span> -l +</pre> +<p>prints the name of each tag entry before it. Since the return value of +<tt class="docutils literal">print</tt> is not #f, all the tag entries are printed. We could control this +using the <tt class="docutils literal">begin</tt> or <tt class="docutils literal">begin0</tt> operator. <tt class="docutils literal">begin</tt> returns the value of its +last argument, and <tt class="docutils literal">begin0</tt> returns the value of its first argument. For +example:</p> +<pre class="code console literal-block"> +<span class="generic prompt">$ </span>readtags -Q <span class="literal string single">'(begin0 #f (print (prefix? "ctags" "ct")))'</span> -l +</pre> +<p>prints a bunch of "#t" (depending on how many lines are in the tags file), and +the actual tag entries are not printed.</p> +</div> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>See tags(5) for the details of tags file format.</p> +<p>See ctags-client-tools(7) for the tips writing a +tool utilizing tags file.</p> +<p>The official Universal Ctags web site at:</p> +<p><a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>The git repository for the library used in readtags command:</p> +<p><a class="reference external" href="https://github.com/universal-ctags/libreadtags">https://github.com/universal-ctags/libreadtags</a></p> +</div> +<div class="section" id="credits"> +<h1>CREDITS</h1> +<p>Universal Ctags project +<a class="reference external" href="https://ctags.io/">https://ctags.io/</a></p> +<p>Darren Hiebert <<a class="reference external" href="mailto:dhiebert@users.sourceforge.net">dhiebert@users.sourceforge.net</a>> +<a class="reference external" href="http://DarrenHiebert.com/">http://DarrenHiebert.com/</a></p> +<p>The readtags command and libreadtags maintained at Universal Ctags +are derived from readtags.c and readtags.h developd at +<a class="reference external" href="http://ctags.sourceforge.net">http://ctags.sourceforge.net</a>.</p> +</div> +</div> +</body> +</html> diff --git a/ctags/man/tags.5.html b/ctags/man/tags.5.html new file mode 100644 index 0000000..2d312eb --- /dev/null +++ b/ctags/man/tags.5.html @@ -0,0 +1,870 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> +<title>tags</title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 7952 2016-07-26 18:15:59Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +.subscript { + vertical-align: sub; + font-size: smaller } + +.superscript { + vertical-align: super; + font-size: smaller } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] { + overflow: hidden; +} + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title, .code .error { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left, table.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right, table.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +table.align-center { + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: inherit } + +/* div.align-center * { */ +/* text-align: left } */ + +.align-top { + vertical-align: top } + +.align-middle { + vertical-align: middle } + +.align-bottom { + vertical-align: bottom } + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block, pre.math, pre.code { + margin-left: 2em ; + margin-right: 2em } + +pre.code .ln { color: grey; } /* line numbers */ +pre.code, code { background-color: #eeeeee } +pre.code .comment, code .comment { color: #5C6576 } +pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold } +pre.code .literal.string, code .literal.string { color: #0C5404 } +pre.code .name.builtin, code .name.builtin { color: #352B84 } +pre.code .deleted, code .deleted { background-color: #DEB0A1} +pre.code .inserted, code .inserted { background-color: #A3D289} + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +/* "booktabs" style (no vertical lines) */ +table.docutils.booktabs { + border: 0px; + border-top: 2px solid; + border-bottom: 2px solid; + border-collapse: collapse; +} +table.docutils.booktabs * { + border: 0px; +} +table.docutils.booktabs th { + border-bottom: thin solid; + text-align: left; +} + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document" id="tags"> +<span id="tags-5"></span> +<h1 class="title">tags</h1> +<h2 class="subtitle" id="vi-tags-file-format-extended-in-ctags-projects">Vi tags file format extended in ctags projects</h2> +<table class="docinfo" frame="void" rules="none"> +<col class="docinfo-name" /> +<col class="docinfo-content" /> +<tbody valign="top"> +<tr><th class="docinfo-name">Version:</th> +<td>2+</td></tr> +<tr class="manual-group field"><th class="docinfo-name">Manual group:</th><td class="field-body">Universal Ctags</td> +</tr> +<tr class="manual-section field"><th class="docinfo-name">Manual section:</th><td class="field-body">5</td> +</tr> +</tbody> +</table> +<div class="section" id="description"> +<h1>DESCRIPTION</h1> +<p>The contents of next section is a copy of FORMAT file in Exuberant +Ctags source code in its subversion repository at sourceforge.net.</p> +<p>Exceptions introduced in Universal Ctags are explained inline with +"EXCEPTION" marker.</p> +</div> +<hr class="docutils" /> +<div class="section" id="proposal-for-extended-vi-tags-file-format"> +<h1>Proposal for extended Vi tags file format</h1> +<div class="line-block"> +<div class="line">Version: 0.06 DRAFT</div> +<div class="line">Date: 1998 Feb 8</div> +<div class="line">Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net></div> +</div> +<div class="section" id="introduction"> +<h2>Introduction</h2> +<p>The file format for the "tags" file, as used by Vi and many of its +descendants, has limited capabilities.</p> +<p>This additional functionality is desired:</p> +<ol class="arabic simple"> +<li>Static or local tags. +The scope of these tags is the file where they are defined. The same tag +can appear in several files, without really being a duplicate.</li> +<li>Duplicate tags. +Allow the same tag to occur more then once. They can be located in +a different file and/or have a different command.</li> +<li>Support for C++. +A tag is not only specified by its name, but also by the context (the +class name).</li> +<li>Future extension. +When even more additional functionality is desired, it must be possible to +add this later, without breaking programs that don't support it.</li> +</ol> +</div> +<div class="section" id="from-proposal-to-standard"> +<h2>From proposal to standard</h2> +<p>To make this proposal into a standard for tags files, it needs to be supported +by most people working on versions of Vi, ctags, etc.. Currently this +standard is supported by:</p> +<dl class="docutils"> +<dt>Darren Hiebert <dhiebert at users.sourceforge.net></dt> +<dd>Exuberant Ctags</dd> +<dt>Bram Moolenaar <Bram at vim.org></dt> +<dd>Vim (Vi IMproved)</dd> +</dl> +<p>These have been or will be asked to support this standard:</p> +<dl class="docutils"> +<dt>Nvi</dt> +<dd>Keith Bostic <bostic at bsdi.com></dd> +<dt>Vile</dt> +<dd>Tom E. Dickey <dickey at clark.net></dd> +<dt>NEdit</dt> +<dd>Mark Edel <edel at ltx.com></dd> +<dt>CRiSP</dt> +<dd>Paul Fox <fox at crisp.demon.co.uk></dd> +<dt>Lemmy</dt> +<dd>James Iuliano <jai at accessone.com></dd> +<dt>Zeus</dt> +<dd>Jussi Jumppanen <jussij at ca.com.au></dd> +<dt>Elvis</dt> +<dd>Steve Kirkendall <kirkenda at cs.pdx.edu></dd> +<dt>FTE</dt> +<dd>Marko Macek <Marko.Macek at snet.fri.uni-lj.si></dd> +</dl> +</div> +<div class="section" id="backwards-compatibility"> +<h2>Backwards compatibility</h2> +<p>A tags file that is generated in the new format should still be usable by Vi. +This makes it possible to distribute tags files that are usable by all +versions and descendants of Vi.</p> +<p>This restricts the format to what Vi can handle. The format is:</p> +<ol class="arabic"> +<li><p class="first">The tags file is a list of lines, each line in the format:</p> +<pre class="literal-block"> +{tagname}<Tab>{tagfile}<Tab>{tagaddress} +</pre> +<dl class="docutils"> +<dt>{tagname}</dt> +<dd><p class="first">Any identifier, not containing white space..</p> +<p class="last">EXCEPTION: Universal Ctags violates this item of the proposal; +tagname may contain spaces. However, tabs are not allowed.</p> +</dd> +<dt><Tab></dt> +<dd><p class="first last">Exactly one TAB character (although many versions of Vi can +handle any amount of white space).</p> +</dd> +<dt>{tagfile}</dt> +<dd><p class="first last">The name of the file where {tagname} is defined, relative to +the current directory (or location of the tags file?).</p> +</dd> +<dt>{tagaddress}</dt> +<dd><p class="first last">Any Ex command. When executed, it behaves like 'magic' was +not set.</p> +</dd> +</dl> +</li> +<li><p class="first">The tags file is sorted on {tagname}. This allows for a binary search in +the file.</p> +</li> +<li><p class="first">Duplicate tags are allowed, but which one is actually used is +unpredictable (because of the binary search).</p> +</li> +</ol> +<p>The best way to add extra text to the line for the new functionality, without +breaking it for Vi, is to put a comment in the {tagaddress}. This gives the +freedom to use any text, and should work in any traditional Vi implementation.</p> +<p>For example, when the old tags file contains:</p> +<pre class="literal-block"> +main main.c /^main(argc, argv)$/ +DEBUG defines.c 89 +</pre> +<p>The new lines can be:</p> +<pre class="literal-block"> +main main.c /^main(argc, argv)$/;"any additional text +DEBUG defines.c 89;"any additional text +</pre> +<p>Note that the ';' is required to put the cursor in the right line, and then +the '"' is recognized as the start of a comment.</p> +<p>For Posix compliant Vi versions this will NOT work, since only a line number +or a search command is recognized. I hope Posix can be adjusted. Nvi suffers +from this.</p> +</div> +<div class="section" id="security"> +<h2>Security</h2> +<p>Vi allows the use of any Ex command in a tags file. This has the potential of +a trojan horse security leak.</p> +<p>The proposal is to allow only Ex commands that position the cursor in a single +file. Other commands, like editing another file, quitting the editor, +changing a file or writing a file, are not allowed. It is therefore logical +to call the command a tagaddress.</p> +<p>Specifically, these two Ex commands are allowed:</p> +<ul> +<li><p class="first">A decimal line number:</p> +<pre class="literal-block"> +89 +</pre> +</li> +<li><p class="first">A search command. It is a regular expression pattern, as used by Vi, +enclosed in // or ??:</p> +<pre class="literal-block"> +/^int c;$/ +?main()? +</pre> +</li> +</ul> +<p>There are two combinations possible:</p> +<ul> +<li><p class="first">Concatenation of the above, with ';' in between. The meaning is that the +first line number or search command is used, the cursor is positioned in +that line, and then the second search command is used (a line number would +not be useful). This can be done multiple times. This is useful when the +information in a single line is not unique, and the search needs to start +in a specified line.</p> +<pre class="literal-block"> +/struct xyz {/;/int count;/ +389;/struct foo/;/char *s;/ +</pre> +</li> +<li><p class="first">A trailing comment can be added, starting with ';"' (two characters: +semi-colon and double-quote). This is used below.</p> +<pre class="literal-block"> +89;" foo bar +</pre> +</li> +</ul> +<p>This might be extended in the future. What is currently missing is a way to +position the cursor in a certain column.</p> +</div> +<div class="section" id="goals"> +<h2>Goals</h2> +<p>Now the usage of the comment text has to be defined. The following is aimed +at:</p> +<ol class="arabic simple"> +<li>Keep the text short, because:<ul> +<li>The line length that Vi can handle is limited to 512 characters.</li> +<li>Tags files can contain thousands of tags. I have seen tags files of +several Mbytes.</li> +<li>More text makes searching slower.</li> +</ul> +</li> +<li>Keep the text readable, because:<ul> +<li>It is often necessary to check the output of a new ctags program.</li> +<li>Be able to edit the file by hand.</li> +<li>Make it easier to write a program to produce or parse the file.</li> +</ul> +</li> +<li>Don't use special characters, because:<ul> +<li>It should be possible to treat a tags file like any normal text file.</li> +</ul> +</li> +</ol> +</div> +<div class="section" id="proposal"> +<h2>Proposal</h2> +<p>Use a comment after the {tagaddress} field. The format would be:</p> +<pre class="literal-block"> +{tagname}<Tab>{tagfile}<Tab>{tagaddress}[;"<Tab>{tagfield}..] +</pre> +<dl class="docutils"> +<dt>{tagname}</dt> +<dd><p class="first">Any identifier, not containing white space..</p> +<p class="last">EXCEPTION: Universal Ctags violates this item of the proposal; +name may contain spaces. However, tabs are not allowed. +Conversion, for some characters including <Tab> in the "value", +explained in the last of this section is applied.</p> +</dd> +<dt><Tab></dt> +<dd>Exactly one TAB character (although many versions of Vi can +handle any amount of white space).</dd> +<dt>{tagfile}</dt> +<dd>The name of the file where {tagname} is defined, relative to +the current directory (or location of the tags file?).</dd> +<dt>{tagaddress}</dt> +<dd>Any Ex command. When executed, it behaves like 'magic' was +not set. It may be restricted to a line number or a search +pattern (Posix).</dd> +</dl> +<p>Optionally:</p> +<dl class="docutils"> +<dt>;"</dt> +<dd>semicolon + doublequote: Ends the tagaddress in way that looks +like the start of a comment to Vi.</dd> +<dt>{tagfield}</dt> +<dd>See below.</dd> +</dl> +<p>A tagfield has a name, a colon, and a value: "name:value".</p> +<ul> +<li><p class="first">The name consist only out of alphabetical characters. Upper and lower case +are allowed. Lower case is recommended. Case matters ("kind:" and "Kind: +are different tagfields).</p> +<p>EXCEPTION: Universal Ctags allows users to use a numerical character +in the name other than its initial letter.</p> +</li> +<li><p class="first">The value may be empty. +It cannot contain a <Tab>.</p> +<ul class="simple"> +<li>When a value contains a <tt class="docutils literal">\t</tt>, this stands for a <Tab>.</li> +<li>When a value contains a <tt class="docutils literal">\r</tt>, this stands for a <CR>.</li> +<li>When a value contains a <tt class="docutils literal">\n</tt>, this stands for a <NL>.</li> +<li>When a value contains a <tt class="docutils literal">\\</tt>, this stands for a single <tt class="docutils literal">\</tt> character.</li> +</ul> +<p>Other use of the backslash character is reserved for future expansion. +Warning: When a tagfield value holds an MS-DOS file name, the backslashes +must be doubled!</p> +<p>EXCEPTION: Universal Ctags introduces more conversion rules.</p> +<ul class="simple"> +<li>When a value contains a <tt class="docutils literal">\a</tt>, this stands for a <BEL> (0x07).</li> +<li>When a value contains a <tt class="docutils literal">\b</tt>, this stands for a <BS> (0x08).</li> +<li>When a value contains a <tt class="docutils literal">\v</tt>, this stands for a <VT> (0x0b).</li> +<li>When a value contains a <tt class="docutils literal">\f</tt>, this stands for a <FF> (0x0c).</li> +<li>The characters in range 0x01 to 0x1F included, and 0x7F are +converted to <tt class="docutils literal">\x</tt> prefixed hexadecimal number if the characters are +not handled in the above "value" rules.</li> +<li>The leading space (0x20) and <tt class="docutils literal">!</tt> (0x21) in {tagname} are converted +to <tt class="docutils literal">\x</tt> prefixed hexadecimal number (<tt class="docutils literal">\x20</tt> and <tt class="docutils literal">\x21</tt>) if the +tag is not a pseudo-tag. As described later, a pseudo-tag starts with +<tt class="docutils literal">!</tt>. These rules are for distinguishing pseudo-tags and non pseudo-tags +(regular tags) when tags lines in a tag file are sorted.</li> +</ul> +</li> +</ul> +<p>Proposed tagfield names:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="16%" /> +<col width="84%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">FIELD-NAME</th> +<th class="head">DESCRIPTION</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>arity</td> +<td>Number of arguments for a function tag.</td> +</tr> +<tr><td>class</td> +<td>Name of the class for which this tag is a member or method.</td> +</tr> +<tr><td>enum</td> +<td>Name of the enumeration in which this tag is an enumerator.</td> +</tr> +<tr><td>file</td> +<td>Static (local) tag, with a scope of the specified file. When +the value is empty, {tagfile} is used.</td> +</tr> +<tr><td>function</td> +<td>Function in which this tag is defined. Useful for local +variables (and functions). When functions nest (e.g., in +Pascal), the function names are concatenated, separated with +'/', so it looks like a path.</td> +</tr> +<tr><td>kind</td> +<td><p class="first">Kind of tag. The value depends on the language. For C and +C++ these kinds are recommended:</p> +<dl class="docutils"> +<dt>c</dt> +<dd>class name</dd> +<dt>d</dt> +<dd>define (from #define XXX)</dd> +<dt>e</dt> +<dd>enumerator</dd> +<dt>f</dt> +<dd>function or method name</dd> +<dt>F</dt> +<dd>file name</dd> +<dt>g</dt> +<dd>enumeration name</dd> +<dt>m</dt> +<dd>member (of structure or class data)</dd> +<dt>p</dt> +<dd>function prototype</dd> +<dt>s</dt> +<dd>structure name</dd> +<dt>t</dt> +<dd>typedef</dd> +<dt>u</dt> +<dd>union name</dd> +<dt>v</dt> +<dd>variable</dd> +</dl> +<p class="last">When this field is omitted, the kind of tag is undefined.</p> +</td> +</tr> +<tr><td>struct</td> +<td>Name of the struct in which this tag is a member.</td> +</tr> +<tr><td>union</td> +<td>Name of the union in which this tag is a member.</td> +</tr> +</tbody> +</table> +<p>Note that these are mostly for C and C++. When tags programs are written for +other languages, this list should be extended to include the used field names. +This will help users to be independent of the tags program used.</p> +<p>Examples:</p> +<pre class="literal-block"> +asdf sub.cc /^asdf()$/;" new_field:some\svalue file: +foo_t sub.h /^typedef foo_t$/;" kind:t +func3 sub.p /^func3()$/;" function:/func1/func2 file: +getflag sub.c /^getflag(arg)$/;" kind:f file: +inc sub.cc /^inc()$/;" file: class:PipeBuf +</pre> +<p>The name of the "kind:" field can be omitted. This is to reduce the size of +the tags file by about 15%. A program reading the tags file can recognize the +"kind:" field by the missing ':'. Examples:</p> +<pre class="literal-block"> +foo_t sub.h /^typedef foo_t$/;" t +getflag sub.c /^getflag(arg)$/;" f file: +</pre> +<p>Additional remarks:</p> +<ul class="simple"> +<li>When a tagfield appears twice in a tag line, only the last one is used.</li> +</ul> +<p>Note about line separators:</p> +<p>Vi traditionally runs on Unix systems, where the line separator is a single +linefeed character <NL>. On MS-DOS and compatible systems <CR><NL> is the +standard line separator. To increase portability, this line separator is also +supported.</p> +<p>On the Macintosh a single <CR> is used for line separator. Supporting this on +Unix systems causes problems, because most fgets() implementation don't see +the <CR> as a line separator. Therefore the support for a <CR> as line +separator is limited to the Macintosh.</p> +<p>Summary:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="23%" /> +<col width="36%" /> +<col width="41%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">line separator</th> +<th class="head">generated on</th> +<th class="head">accepted on</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td><LF></td> +<td>Unix</td> +<td>Unix, MS-DOS, Macintosh</td> +</tr> +<tr><td><CR></td> +<td>Macintosh</td> +<td>Macintosh</td> +</tr> +<tr><td><CR><LF></td> +<td>MS-DOS</td> +<td>Unix, MS-DOS, Macintosh</td> +</tr> +</tbody> +</table> +<p>The characters <CR> and <LF> cannot be used inside a tag line. This is not +mentioned elsewhere (because it's obvious).</p> +<p>Note about white space:</p> +<p>Vi allowed any white space to separate the tagname from the tagfile, and the +filename from the tagaddress. This would need to be allowed for backwards +compatibility. However, all known programs that generate tags use a single +<Tab> to separate fields.</p> +<p>There is a problem for using file names with embedded white space in the +tagfile field. To work around this, the same special characters could be used +as in the new fields, for example <tt class="docutils literal">\s</tt>. But, unfortunately, in MS-DOS the +backslash character is used to separate file names. The file name +<tt class="docutils literal"><span class="pre">c:\vim\sap</span></tt> contains <tt class="docutils literal">\s</tt>, but this is not a <Space>. The number of +backslashes could be doubled, but that will add a lot of characters, and make +parsing the tags file slower and clumsy.</p> +<p>To avoid these problems, we will only allow a <Tab> to separate fields, and +not support a file name or tagname that contains a <Tab> character. This +means that we are not 100% Vi compatible. However, there is no known tags +program that uses something else than a <Tab> to separate the fields. Only +when a user typed the tags file himself, or made his own program to generate a +tags file, we could run into problems. To solve this, the tags file should be +filtered, to replace the arbitrary white space with a single <Tab>. This Vi +command can be used:</p> +<pre class="literal-block"> +:%s/^\([^ ^I]*\)[ ^I]*\([^ ^I]*\)[ ^I]*/\1^I\2^I/ +</pre> +<p>(replace ^I with a real <Tab>).</p> +<p>TAG FILE INFORMATION:</p> +<p>Pseudo-tag lines can be used to encode information into the tag file regarding +details about its content (e.g. have the tags been sorted?, are the optional +tagfields present?), and regarding the program used to generate the tag file. +This information can be used both to optimize use of the tag file (e.g. +enable/disable binary searching) and provide general information (what version +of the generator was used).</p> +<p>The names of the tags used in these lines may be suitably chosen to ensure +that when sorted, they will always be located near the first lines of the tag +file. The use of "!_TAG_" is recommended. Note that a rare tag like "!" +can sort to before these lines. The program reading the tags file should be +smart enough to skip over these tags.</p> +<p>The lines described below have been chosen to convey a select set of +information.</p> +<p>Tag lines providing information about the content of the tag file:</p> +<pre class="literal-block"> +!_TAG_FILE_FORMAT {version-number} /optional comment/ +!_TAG_FILE_SORTED {0|1} /0=unsorted, 1=sorted/ +</pre> +<p>The {version-number} used in the tag file format line reserves the value of +"1" for tag files complying with the original UNIX vi/ctags format, and +reserves the value "2" for tag files complying with this proposal. This value +may be used to determine if the extended features described in this proposal +are present.</p> +<p>Tag lines providing information about the program used to generate the tag +file, and provided solely for documentation purposes:</p> +<pre class="literal-block"> +!_TAG_PROGRAM_AUTHOR {author-name} /{email-address}/ +!_TAG_PROGRAM_NAME {program-name} /optional comment/ +!_TAG_PROGRAM_URL {URL} /optional comment/ +!_TAG_PROGRAM_VERSION {version-id} /optional comment/ +</pre> +<p>EXCEPTION: Universal Ctags introduces more kinds of pseudo-tags. +See ctags-client-tools(7) about them.</p> +</div> +</div> +<hr class="docutils" /> +<div class="section" id="exceptions-in-universal-ctags"> +<h1>Exceptions in Universal Ctags</h1> +<p>Universal Ctags supports this proposal with some +exceptions.</p> +<div class="section" id="exceptions"> +<h2>Exceptions</h2> +<ol class="arabic simple"> +<li>{tagname} in tags file generated by Universal Ctags may contain +spaces and several escape sequences. Parsers for documents like Tex and +reStructuredText, or liberal languages such as JavaScript need these +exceptions. See {tagname} of Proposal section for more detail about the +conversion.</li> +<li>"name" part of {tagfield} in a tag generated by Universal Ctags may +contain numeric characters, but the first character of the "name" +must be alphabetic.<!-- NOT REVIEWED YET (above item) --> +</li> +</ol> +</div> +<div class="section" id="compatible-output-and-weakness"> +<span id="compat-output"></span><h2>Compatible output and weakness</h2> +<!-- NOT REVIEWED YET --> +<p>Default behavior (<tt class="docutils literal"><span class="pre">--output-format=u-ctags</span></tt> option) has the +exceptions. In other hand, with <tt class="docutils literal"><span class="pre">--output-format=e-ctags</span></tt> option +ctags has no exception; Universal Ctags command may use the same file +format as Exuberant Ctags. However, <tt class="docutils literal"><span class="pre">--output-format=e-ctags</span></tt> throws +away a tag entry which name includes a space or a tab +character. <tt class="docutils literal">TAG_OUTPUT_MODE</tt> pseudo-tag tells which format is +used when ctags generating tags file.</p> +</div> +</div> +<div class="section" id="see-also"> +<h1>SEE ALSO</h1> +<p>ctags(1), ctags-client-tools(7), ctags-incompatibilities(7), readtags(1)</p> +</div> +</div> +</body> +</html> diff --git a/ctags/readtags.exe b/ctags/readtags.exe Binary files differnew file mode 100644 index 0000000..6a21dc7 --- /dev/null +++ b/ctags/readtags.exe |
