Skip to content

Commit

Permalink
docs(web): update optscript.rst (in progress)
Browse files Browse the repository at this point in the history 
Signed-off-by: Masatake YAMATO <yamato@redhat.com>
  • Loading branch information
@masatake
masatake committed Dec 28, 2022
1 parent 9e8a785 commit 3b9df16
Showing 1 changed file with 138 additions and 38 deletions.
176 changes: 138 additions & 38 deletions docs/optscript.rst
View file
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

0 comments on commit 3b9df16

Please sign in to comment.