diff options
Diffstat (limited to 'ctags/docs/optscript.html')
| -rw-r--r-- | ctags/docs/optscript.html | 425 |
1 files changed, 425 insertions, 0 deletions
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 |