Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(web): update optscript.rst (in progress) #2997

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs(web): update optscript.rst (in progress) #2997

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e8a785
docs(web): introduce new terms corkQueue and corkIndex
masatake May 3, 2021
3b9df16
docs(web): update optscript.rst (in progress)
masatake May 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/internal.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This description is wrong.

The entries are flushed when all parsing tasks including running guest parsers are finished. See "`cork API`_" for more details.

when ``useCork`` in unset. See "`cork API`_" for more details.

cork API
......................................................................
Expand Down
176 changes: 138 additions & 38 deletions docs/optscript.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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
...............
Expand Down Expand Up @@ -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-<LANG>`` is for specified code fragments run at the
Expand All @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down