diff --git a/docs/internal.rst b/docs/internal.rst index 2775902d91..d472ccae1d 100644 --- a/docs/internal.rst +++ b/docs/internal.rst @@ -98,9 +98,10 @@ parser does not set ``CORK_QUEUE`` to ``useCork`` field. ``writeTagEntry`` calls xrefWriter, and jsonWriter. One of them is chosen depending on the arguments passed to ctags. -If ``CORK_QUEUE`` is set to ``useCork``, the tag information goes to a queue on memory. -The queue is flushed when ``useCork`` in unset. See "`cork API`_" for more -details. +If ``CORK_QUEUE`` is set to ``useCork``, the tag information goes to a +queue (**corkQueue**) on memory, and a unique integer (**corkIndex**) +is assigned identifying the tag information. The queue is flushed +when ``useCork`` in unset. See "`cork API`_" for more details. cork API ...................................................................... diff --git a/docs/optscript.rst b/docs/optscript.rst index ed7aa32c3d..abbde97cd0 100644 --- a/docs/optscript.rst +++ b/docs/optscript.rst @@ -19,28 +19,29 @@ operators of Optscript and PostScript are the same. You can get the basic knowledge for using Optscript from the materials for learning PostScript. -"PostScript Language Tutorial & Cookbook" published by Adobe Systems -Inc. The book is known as "blue book". This is the best place to +"PostScript Language Tutorial & Cookbook" is a book published by Adobe +Systems Inc. The book, known as "blue book", 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 +many graphical operators. Optscript 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). Ghostscript (``gs`` or ``gsnd``) 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 +under either the GNU GPL Affero license. You can use Ghostscript while reading the blue book. Do web searching to know about Ghostscript. -``optscript`` is an command that source files are included in -Universal Ctags source tree. You can use it as the replacement of -``gs``. However, I recommend you to have ``gs`` at hand because -``optscript`` may have bugs. ``gs`` is much mature than ``optscript``. -Having two interpreters helps you to know correct behavior. +``optscript`` is a command that source files are included in the +source tree of Universal Ctags. You can use it as the replacement of +``gs`` to learn PostScript. However, I recommend you to have ``gs`` at +hand because ``optscript`` may have bugs. ``gs`` is much mature than +``optscript``. Having two interpreters helps you to know expected +behavior of the language. Though ``gs`` has much higher qualities than ``optscript``, eventually you may have to build the ``optscript`` command to learn Optscript -specific operators. You can built the command with "``make +specific operators for tagging. You can built the command with "``make optscript``". * red book @@ -164,9 +165,29 @@ easily, Python sessions doing the same as Optscript are also written. >>> add5_and_print(4) 9 -* string manipulation +* String manipulation + + - Comparison + + Optscript: + + .. code-block:: console + + OPT> (abc) (efg) eq { (same) = } { (different) = } ifelse + different + OPT> (abc) (abc) eq { (same) = } { (different) = } ifelse + same + + Python: + + .. code-block:: console + + >>> if 'abc' == 'efg': + ... print ('same') + ... else: + ... print ('different') + different - TBW * array manipulation @@ -190,6 +211,8 @@ easily, Python sessions doing the same as Optscript are also written. Optscript in ctags ~~~~~~~~~~~~~~~~~~ +Optscript executable in ctags assumes that all tags are in the corkQueue and +they have corkIndexes. See ":ref:`output-tag-stream`" about corkQueue and corkIndexes. Related options ............... @@ -242,12 +265,12 @@ TBW: two timings of evaluation Put code fragments at the end of options with surrounding "``{{``" and "``}}``". 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. +place to write code fragments because the options with code fragments +may be too long. Instead, you should write them to your .ctags file. -.. warning:: An important rule in writing Optscript code in a file is - the start marker, ``{{`` must be at the end of line, and the end - marker ``}}`` must be at the beginning of line. If you break the +.. warning:: An important rule in writing Optscript code in a .ctags + file is the start marker, ``{{``, must be at the end of line, and the + end marker, ``}}``, must be at the beginning of line. If you break the rule, the optlib loader of ctags fails to read your file. ``--_prelude-`` is for specified code fragments run at the @@ -269,62 +292,139 @@ represents the field has an operator for reading (``:fieldname``). ``w`` represents the field has an operator for writing (``fieldname:``). +``optlib2c``, a translator from .ctags file to C language source file +supports the code framents. Some of optlib parsers integrated to +Universal Ctags already use Optscript. You can find practical +examples of Optscript in files in ``optlib`` directory. The positional +rules about `{{` and `}}` is applicable to ``optlib2c``. + +Data types +.......... + +Non-standard data types for tagging are added. You can use it only in +``ctags`` command, not in ``optscript`` command. + +``matchloc`` + + This opaque data type is for representing a position in a source + file. The name is an acronym for "match location". ``_matchloc`` + pushes a ``matchloc`` object to ``ostack``. + +``corkIndex:int`` or ``index:int`` + + This represents a corkIndex. ``.`` pushes the corkIndex for a tag + just created with the option owning the code frament. + +``tag`` + + This represents a tag data structure which is not in the corkQueue + yet. ``_tag`` is an operator pushing a ``tag`` object to + ``ostack``. ``_commit`` puts the ``tag`` object on ``ostack`` to + the corkQueue, and pushes an integer as a corkIndex. + Operators ............................ **.** -> ``-`` **.** ``corkIndex:int`` - Push the cork index for the tag + Push the cork index for the tag **\\n** -> ``-`` **\\n** ``matchedString:string`` - ``n`` is an integer (0...9) representing a group in a pattern. + ``n`` is an integer (1...9) representing a group in a pattern. Push the matched string for the group. ``_matchloc`` - TBW + TBW ``:field`` (See the output of ``--_list-operators``) - Get the value for the specified field from a tag + Get the value for the specified field from a tag and put it. ``field:`` (See the output of ``--_list-operators``) - Set a value at the stack to the specified field of a tag. + Set a value at the stack to the specified field of a tag. ``_tag`` - TBW + TBW -``_COMMIT`` +``_commit`` - TBW + TBW ``_traced`` - TBW + TBW -Data types -.......... -``MATCHLOC`` +Recipes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - TBW +Arrange the name of a tag +........................................... -``index:int`` +"input.foo": - TBW +.. code-block:: -``TAG`` + def a + def b - TBW +Goal: If a language specific extra ``extendedName`` is given, the +parser for input.foo emits extra tags having ``X`` as prefix. -Recipes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The base version of .ctags ("foo0.ctags"): + +.. code-block:: ctags + + --langdef=foo + --map-foo=.foo + --kinddef-foo=d,definition,definitions + --regex-foo=/^def[ \t]+([a-z]+)/\1/d/ + +The tags output ("output0.tags") for the base version +with "``--optoins=foo0.ctags input.foo``": + +.. code-block:: tags + + a input.foo /^def a$/;" d + b input.foo /^def b$/;" d + +The Optscript version of .ctags ("foo1.ctags") for achieving the goal: + +.. code-block:: ctags + + --langdef=foo + --map-foo=.foo + --kinddef-foo=d,definition,definitions + --_extradef-foo=extendedName, tags prefixed with X + --regex-foo=/^def[ \t]+([a-z]+)/\1/d/{{ + /foo.extendedName _extraenabled { + mark \1 ?X _buildstring % name, \1 + 'X' + /definition % kind + 1 _matchloc % location for \1 + _tag % a tag object is pushed. + % ostack => tag + dup + % ostack => tag tag + /foo.extendedName _markextra + % ostack => tag + _commit + } if + }} + +The tags output ("output1.tags") for the Optscript version +with "``--optoins=foo1.ctags --extras-foo=+'{extendedName}' input.foo``": + +.. code-block:: tags -TBW + a input.foo /^def a$/;" d + aX input.foo /^def a$/;" d + b input.foo /^def b$/;" d + bX input.foo /^def b$/;" d Difference between Optscript and PostScript ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~