summaryrefslogtreecommitdiff
path: root/web/yacco2/bin/man/man1/o2.1
blob: dfebb3c3c087ecd605c6553a2a88d7c2703065da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
o2(1)                                                                    o2(1)



NNAAMMEE
       o2 -- multi-threaded non-deterministic lr(1) compiler/compiler included
       in the yyaaccccoo22 system.

SSYYNNOOPPSSIISS
       oo22 [ --pp ] [ --tt ] [ --eerrrr ] [ grammar file to compile ]

OOPPTTIIOONNSS
       oo22 options are each individually prefixed by one  ``-''  only.   If  no
       grammar file is inputted, o2 will ask for one.

       --pp     Create  pdf  documents  for  the  inputted  grammar. It requires
              CWEB's program suite: ccwweeaavvee and mmppoosstt programs to do this.


       --tt     Generate ``User terminal class''  vocabulary's  c++  code  along
              with the inputted grammar.

       WWaarrnniinngg::  Option  is  required  if the ``User terminal class'' has been
       modified: Tes added, subtracted, or modified.  Not doing so leaves  the
       emitted  lr(1)  tables out-of-whack!  So regenerate aallll tthhee ggrraammmmaarrss so
       that their lr(1) tables are in sync with the new  Terminal  vocabulary.
       See  reference  to  oo22ggrraammmmaarrss..bbaatt  script on how to do it for your own
       grammars.


       --eerrrr   Generate "Error terminal class" vocabulary's c++ code along with
              the inputted grammar.  WWaarrnniinngg:: Ditto as -t warning.


DDEESSCCRRIIPPTTIIOONN
       oo22  extends  bottom-up  parsing  by defining 2 types of grammars: mono-
       lithic and threaded.  A ``thread call'' operator is introduced into the
       traditional grammar definition along with an arbitration clause.  These
       2 extensions allow multiple grammars to be run in parallel with  poten-
       tially multiple results returned to be arbitrated upon.

       The  yyaaccccoo22  system  is  written  in the ``Literate programming'' genre
       using the CCWWEEBB program suite: cweave and  ctangle.  ctangle  emits  c++
       code  while  cweave  emits a TeX file for the ppddfftteexx program to typeset
       into a pdf document.

       oo22 is just 1 program within the yacco2 translation system.  Other items
       of import: yyaaccccoo22 library for your own compiler to link to and oo22lliinnkkeerr
       that is o2's companion program to  link  all  your  grammars  together.
       Grammars and Terminal vocabulary files support cweave's language direc-
       tives and TTeeXX typesetting facilities.  By using the --pp option, oo22 emits
       files  for  _m_p_o_s_t  (a  graphic  drawing  program) and _c_w_e_a_v_e digestion.
       _m_p_o_s_t draws  Niklaus Wirth's  ``Pascal grammar like diagrams'' that get
       included into files processed by cweave.  _c_w_e_a_v_e then generates the Tex
       files for the _p_d_f_t_e_x program to generate the pdf documents.


oo22 oouuttppuutteedd ffiilleess
       c++ code and lr(1) tables for each grammar and grammar's fsc type  file
       for o2linker consumption

       Pdf documents per grammar: grammar code and its lr(1)  cross  reference
       tables


OOTTHHEERR FFEEAATTUURREESS
       -- Modular grammars allowing reuse by other compilers
       -- Simplified ambiguity resolution
       -- Programmable ``context sensitive'' lookahead per threaded grammar
       -- Self documenting
       -- Dynamic tracing / trouble shooting facilities
       -- Out-of-the-box error messaging
       -- Multiple input / output token container types:
              Files
              Trees
              In memory string



EEXXAAMMPPLLEESS
       1) Compiling one of o2's grammars
              cd /usr/local/yacco2/compiler/grammars
              /usr/local/yacco2/bin/o2 eol.lex # no options except file: emit c++ code for grammar
       2) Generate grammar's documents
              cd /usr/local/yacco2/compiler/grammars
              o2 -p eol.lex # bash PATH variable modified to resolve o2 whereabouts
       3) Compile grammar and ``Error class'' due to new error terminal added
              o2 -err /usr/local/yacco2/compiler/grammars/eol.lex


SSEEEE AALLSSOO bbyy mmaann
       oo22lliinnkkeerr((11)),,  yyaaccccoo22((11)),,  CCWWEEBB((11)),,  ccwweeaavvee((11)),,  ccttaannggllee((11)),,   mmppoosstt((11)),,
       TTeeXX((11))

       In //uussrr//llooccaall//yyaaccccoo22//ddooccss//
              wlibrary.pdf -- yacco2's library documented ``literate program''
              o2.pdf -- compiler/compiler documented ``literate program''
              o2linker.pdf -- linker documented ``literate program''
              yacco2's grammars's pdfes
              o2linker_doc.pdf -- example of o2/o2linker's grammars cross reference produced by o2linker
              o2book.pdf -- reference manual

       In //uussrr//llooccaall//yyaaccccoo22//
              READMEvx.y.pdf -- installation guide x: version number, y: minor adjustment number.
              bld_bash_APPLE script to build complete yacco2 system

       In  //uussrr//llooccaall////yyaaccccoo22//ccoommppiilleerr//ggrraammmmaarrss,,  to  help  u  out,  some bash
       scripts that u can clone off for your own projects:
              o2grammars.sh -- gen all grammars with possible inputted parameters
              gen1grammar.sh -- gen 1 grammar where appropriate parameters are asked by the script


SSUUGGGGEESSTTEEDD RREEAADDIINNGGSS GGIIVVIINNGG RREEAASSOONNSS FFOORR YYAACCCCOO22 SSYYSSTTEEMM
       In //uussrr//llooccaall//yyaaccccoo22//ddooccss
              p1 and p2 pdf documents -- unpublished essays overviewing some of whyes for yacco2 development
              Tugboat-o2.pdf --  unpublished essay on ``literate programming'' as applied to the yacco2 system


NNOOTTEE
       The bld_bash_APPLE script is used as an example. There are  other  bash
       scripts for GGNNUU and SSOOLLAARRIISS..  See READMEvx.y.pdf.



OOTTHHEERR LLIINNKKSS
       wwwwww..ttuugg..oorrgg
              -- website to download the CCWWEEBB ``Literate programming'' system,
              _m_p_o_s_t Metapost graphics program and possibly the TTeeXX typesetting
              system. These are open source. Please consider joining TTuugg..


AAUUTTHHOORR
       Dave Bone





1.0                                                                      o2(1)