1.. _optscript: 2 3Optscript, a programming language for extending optlib parsers 4-------------------------------------------------------------- 5 6.. contents:: `Table of contents` 7 :depth: 3 8 :local: 9 10Preparation for learning 11~~~~~~~~~~~~~~~~~~~~~~~~ 12**Optscript** is an implementation of PostScript(tm) alike stack 13oriented general purpose programming language. Developers of optlib 14parsers can utilize the language for extending their parsers. 15 16You may not be familiar with a stack oriented programming language. 17Though there are some differences, the syntax and core non-graphical 18operators of Optscript and PostScript are the same. You can get the 19basic knowledge for using Optscript from the materials for learning 20PostScript. 21 22"PostScript Language Tutorial & Cookbook" published by Adobe Systems 23Inc. The book is known as "blue book". This is the best place to 24start. PostScript is a language for controlling printers. So it has 25many graphical operators. Optscript is for tagging, and doesn't have 26such graphical operators. So you can skip the sections about graphics 27(but you may want to read them because the book is written well). 28 29Ghostscript (``gs`` or ``gsnd``) is an interpreter for the PostScript 30language and PDF files. Unlike Optscript, it implements the full-set of 31PostScript features including graphical operators. It is available 32under either the GNU GPL Affero license. You can Ghostscript while 33reading the blue book. Do web searching to know about Ghostscript. 34 35``optscript`` is an command that source files are included in 36Universal Ctags source tree. You can use it as the replacement of 37``gs``. However, I recommend you to have ``gs`` at hand because 38``optscript`` may have bugs. ``gs`` is much mature than ``optscript``. 39Having two interpreters helps you to know correct behavior. 40 41Though ``gs`` has much higher qualities than ``optscript``, eventually 42you may have to build the ``optscript`` command to learn Optscript 43specific operators. You can built the command with "``make 44optscript``". 45 46* red book 47 48 TBW 49 50Syntax extension 51~~~~~~~~~~~~~~~~~~~~~~~~ 52 53``?`` is a prefix for representing a character literal. 54 55For an example, ``?x`` represents 120. This is a short cut for ``(x) 0 56get``. 57 58Some characters has special notation using ``\``. 59 60``?\t`` 61 62 tab 63 64``?\n`` 65 66 newline 67 68``?\_`` 69 70 space 71 72 73The ``optscript`` command 74~~~~~~~~~~~~~~~~~~~~~~~~~ 75 76You can run optscript with no argument: 77 78.. code-block:: console 79 80 $ ./optsript 81 OPT> 82 83``OPT>`` is the prompt of the interpreter. 84You can stop it with ``quit`` operator: 85 86.. code-block:: console 87 88 $ ./optsript 89 OPT> quit 90 $ 91 92 93Let's see some example sessions. To help you understand the session 94easily, Python sessions doing the same as Optscript are also written. 95 96* hello world 97 98 Optscript: 99 100 .. code-block:: console 101 102 OPT> (hello, world) = 103 hello, world 104 105 Python: 106 107 .. code-block:: console 108 109 >>> print ('hello, world') 110 hello, world 111 112* Adding 113 114 Optscript: 115 116 .. code-block:: console 117 118 OPT> 2 3 add = 119 5 120 121 Python: 122 123 .. code-block:: console 124 125 >>> print (2 + 3) 126 5 127 128* Variables 129 130 Optscript: 131 132 .. code-block:: console 133 134 OPT> /x 2 def 135 OPT> /y 3 def 136 OPT> x y add = 137 5 138 139 Python: 140 141 .. code-block:: console 142 143 >>> x = 2 144 >>> y = 3 145 >>> print (x + y) 146 5 147 148* Procedures 149 150 Optscript: 151 152 .. code-block:: console 153 154 OPT> /add5_and_print { 5 add = } def 155 OPT> 4 add5_and_print 156 9 157 158 Python: 159 160 .. code-block:: console 161 162 >>> def add5_and_print(x): 163 ... print(x + 5); 164 >>> add5_and_print(4) 165 9 166 167* string manipulation 168 169 TBW 170 171* array manipulation 172 173 TBW 174 175* dict manipulation 176 177 TBW 178 179* control flow 180 181 TBW 182 183* operators for printing 184 185 TBW 186 187* reading script from file 188 189 TBW 190 191Optscript in ctags 192~~~~~~~~~~~~~~~~~~ 193 194Related options 195............... 196 197.. code-block:: ctags 198 199 --_prelude-<LANG>={{ 200 OPTSCRIPT CODE FRAGMENTS 201 }} 202 203 --_sequel-<LANG>={{ 204 OPTSCRIPT CODE FRAGMENTS 205 }} 206 207 --regex-<LANG>=<PATTERN>/<NAME>/[<KIND>/]LONGFLAGS...{{ 208 OPTSCRIPT CODE FRAGMENTS 209 }} 210 211 --regex-<LANG>=<PATTERN>//LONGFLAGS...{{ 212 OPTSCRIPT CODE FRAGMENTS 213 }} 214 215 --mline-regex-<LANG>=<PATTERN>/<NAME>/[<KIND>/]LONGFLAGS...{{ 216 OPTSCRIPT CODE FRAGMENTS 217 }} 218 219 --mline-regex-<LANG>=<PATTERN>//LONGFLAGS...{{ 220 OPTSCRIPT CODE FRAGMENTS 221 }} 222 223 --_mtable-regex-<LANG>=<TABLE>/<PATTERN>/<NAME>/[<KIND>/]LONGFLAGS...{{ 224 OPTSCRIPT CODE FRAGMENTS 225 }} 226 227 --_mtable-regex-<LANG>=<TABLE>/<PATTERN>//LONGFLAGS...{{ 228 OPTSCRIPT CODE FRAGMENTS 229 }} 230 231 --_list-operators 232 233 --list-fields 234 235You can run optscript code fragments when pattern specified with 236options matches successfully. The options are ``--regex-<LANG>``, 237``--mline-regex-<LANG>``, and ``--_mtable-regex-<LANG>`` as you 238expect. In addition, ``--_prelude-<LANG>`` and ``--_sequel-<LANG>`` 239options also take code fragments. 240 241TBW: two timings of evaluation 242 243Put code fragments at the end of options with surrounding "``{{``" and 244"``}}``". Though it is not impossible, a command line is not suitable 245place to put code fragments because the code fragments may be long. 246Instead, you should write them to a .ctags file. 247 248.. warning:: An important rule in writing Optscript code in a file is 249 the start marker, ``{{`` must be at the end of line, and the end 250 marker ``}}`` must be at the beginning of line. If you break the 251 rule, the optlib loader of ctags fails to read your file. 252 253``--_prelude-<LANG>`` is for specified code fragments run at the 254beginning of parsing a source file. You can use this option for 255defining the common code used in the parser. 256 257``--_sequel-<LANG>`` is for for specified code fragments run at the end 258of parser a source file. You can use this option for debug-printing 259the final state of parsing the source file. 260e.g. ``--_sequel-Foo={{ _traced { pstack } if }}``. 261 262``--_list-operators`` lists all operators (and built-in procedures) 263and exits. In additions to operators defined in ``optscript``, 264``ctags`` provides operators for tagging. 265 266``OP`` column of ``--list-fields`` represents the availability of 267operators for accessing the field specified in the line. ``r`` 268represents the field has an operator for reading 269(``:fieldname``). ``w`` represents the field has an operator for 270writing (``fieldname:``). 271 272Operators 273............................ 274 275**.** -> ``-`` **.** ``corkIndex:int`` 276 277 Push the cork index for the tag 278 279**\\n** -> ``-`` **\\n** ``matchedString:string`` 280 281 ``n`` is an integer (0...9) representing a group in a pattern. 282 Push the matched string for the group. 283 284``_matchloc`` 285 286 TBW 287 288``:field`` (See the output of ``--_list-operators``) 289 290 Get the value for the specified field from a tag 291 and put it. 292 293``field:`` (See the output of ``--_list-operators``) 294 295 Set a value at the stack to the specified field of a tag. 296 297``_tag`` 298 299 TBW 300 301``_COMMIT`` 302 303 TBW 304 305``_traced`` 306 307 TBW 308 309Data types 310.......... 311 312``MATCHLOC`` 313 314 TBW 315 316``index:int`` 317 318 TBW 319 320``TAG`` 321 322 TBW 323 324Recipes 325~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 326 327TBW 328 329Difference between Optscript and PostScript 330~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 331 332* Memory management 333 334* Dynamically extendable data type 335 336 - string 337 338 - array 339