From 37c9d1ff64ffe27e0e49960575bef199e3bd32e8 Mon Sep 17 00:00:00 2001 From: Christian Rinderknecht Date: Thu, 16 May 2019 10:06:34 +0200 Subject: [PATCH] Added mini-documentation of internals. Fixing links after change of git repository. --- src/parser/pascaligo/.links | 10 +- src/parser/pascaligo/Doc/pascaligo.txt | 144 ++++++++++++++++++ src/parser/pascaligo/Parser.mly | 5 +- .../Stubs/{Tezos_utils.ml => Simple_utils.ml} | 0 4 files changed, 151 insertions(+), 8 deletions(-) create mode 100644 src/parser/pascaligo/Doc/pascaligo.txt rename src/parser/pascaligo/Stubs/{Tezos_utils.ml => Simple_utils.ml} (100%) diff --git a/src/parser/pascaligo/.links b/src/parser/pascaligo/.links index 34a1424ad..8af33d655 100644 --- a/src/parser/pascaligo/.links +++ b/src/parser/pascaligo/.links @@ -1,7 +1,7 @@ $HOME/git/OCaml-build/Makefile $HOME/git/OCaml-build/Makefile.cfg -$HOME/git/tezos/src/lib_utils/pos.mli -$HOME/git/tezos/src/lib_utils/pos.ml -$HOME/git/tezos/src/lib_utils/region.mli -$HOME/git/tezos/src/lib_utils/region.ml -Stubs/Tezos_utils.ml +$HOME/git/ligo/vendors/ligo-utils/simple-utils/pos.mli +$HOME/git/ligo/vendors/ligo-utils/simple-utils/pos.ml +$HOME/git/ligo/vendors/ligo-utils/simple-utils/region.mli +$HOME/git/ligo/vendors/ligo-utils/simple-utils/region.ml +Stubs/Simple_utils.ml diff --git a/src/parser/pascaligo/Doc/pascaligo.txt b/src/parser/pascaligo/Doc/pascaligo.txt new file mode 100644 index 000000000..ad329933c --- /dev/null +++ b/src/parser/pascaligo/Doc/pascaligo.txt @@ -0,0 +1,144 @@ +INTERNAL DOCUMENTATION OF THE PARSER OF PASCALIGO (Pascal-like LIGO) + +This document describes the source code in the directory +ligo/src/parser/pascaligo and some maintenance workflows. + +The directory contains the following: + + Doc + The directory containing this documentation. + + Tests + The directory containing tests. + + Version.ml + A source containing a commit hash. It should be deleted, as Dune + knows how to generate and updated version. + + dune + The Dune file for building the Pascaligo parser. + + pascaligo.ml + A source needed for building the parser with Dune. + + check_dot_git_is_dir.sh + A shell initially made to distinguish a git worktree from the + working directory (currently broken). + + Stubs + A directory containing Tezos_utils.ml, which is ignored by Dune, + but linked from the parent directory ligo/src/parser/pascaligo + when building with the Christian's Makefile for OCaml + projects. (See http://github.com/rinderknecht/OCaml-build) Ignore + them. + + .LexerMain.tag + .Lexer.ml.tag + .ParserMain.tag + .Parser.mly.tag + .links + As ligo/src/parser/pascaligo/Stubs/Tezos_utils.ml, these files + are only used by Christian's build system. Ignore them. + + LexerMain.ml + ParserMain.ml + Source for two entry points enabling Christian's build system to + build only a standalone lexer or a standalone parser. Do not + change, unless you change EvalOpt and use Christian's build system. + + LexerLog.ml + LexerLog.mli + Source for instantiating a standalone lexer for LexerMain.ml and + ParserMain.ml. Ignore them. + + ParserLog.mli + ParserLog.ml + Source for printing the AST. Used by ParserMain.ml, pascaligo.ml + and the translator from this AST to the one needed by the + type-checker (see directory ligo/src/simplify). + + Utils.mli + Utils.ml + Some utility types and functions. + + AST.mli + AST.ml + The abstract syntax tree of Pascaligo. + + EvalOpt.mli + EvalOpt.ml + The module EvalOpt parses the command-line for options to the + parser. That action is performed as a side-effect when the module + is initialised at run-time: this is ugly and easy to fix. See + ligo/src/parser/ligodity/EvalOpt.ml{i} for the right way to do + it. Ignore them: the file actually calling directly the parser is + ligo/src/parser/parser.ml. Note that, as a consequence, no option + is currently passed to the parser when building Pascaligo with + Dune. This should be made available. + + Markup.mli + Markup.ml + The definition of markup in Pascaligo source files, and some some + functions to print or convert it to strings. You are unlikely + going to modify those files, as markup is pretty much the same for + all LIGO flavours. + + FQueue.mli + FQueue.ml + A naive implementation of purely functional queues. Replace by an + imperative implementation if worst-case performance of single + operations (queue/enqueue) is an issue. + + Error.mli + The definition of the open type for errors: the lexer will add its + own errors, the downside being that matching on errors requires a + catch-all clause "| _ -> assert false" at the end. Note: the rest + of the compiler uses an error monad. + + Lexer.mli + Lexer.mll + The Pascaligo lexer is generated from two ocamllex + specifications. Lexer.mll is the first-level lexer. It exports a + functor [Make] parameterised over a module [Token] defining the + tokens, and returning a module whose signature is [Lexer.S]. (See + Lexer.mli for a rationale.) If you write a new flavour of LIGO, + this lexer is likely to be reused as is. Note that a great deal of + the complexity of this lexer stems from its purpose to report + stylistic errors (hence keeping temporarily scanned markup) and + handling UTF-8 encoded comments. The first goal implies sometimes + reading more than one token, and an extra-buffer has to be managed + above the ocamllex one, so the parser is not confused about the + location (region) of the token it has just read. + + LexToken.mli + LexToken.mll + The second-level lexer of Pascaligo, scanning the (lexical) + tokens, and used to instantiate the first-level lexer + (Lexer.mll). If you write a new flavour of LIGO, this lexer is + likely to be modified, also if you plan to add new lexemes (beware + that if you add a new token constructor to the type [LexToken.t], + you may have to change the signature [Lexer.S] so you an instantiate + the first-level lexer. + + Parser.mly + The Menhir specification of the grammar of Pascaligo and the + semantic actions building the AST. The syntax is actually a mix of + two sub-flavours: one in which compound structures, like blocks, + records, lists etc., are opened by a keyword denoting the kind of + structure, like "block", "record", "list" etc., and are closed by + the key word "end", and one in which those structures are opened + by a keyword followed by a symbol, like "{", "[" etc. and closed + by a symbol, lik "}", "]" etc. For instance, + "record x : t; y : u end" versus "record {x : t; y : u}". + In the future, these two styles should be separated and, in the + meantime, it is advise to keep to one style per LIGO contract, for + readability's sake. A first maintenance task would be to separate + this file in two, so each parses only one style, and share the + common parts of the grammar. + However you change this file, the grammar must remain without LR + conflicts, without resorting %prec or %assoc annotations. + Another example of maintenance task is to enable unary + constructors. An oversight made the definition of enumerated types + impossible, like t = A | B | C. You can first change the AST, then + the parser, or vice-versa, and then ligo/src/simplify/pascaligo.ml + if necessary. diff --git a/src/parser/pascaligo/Parser.mly b/src/parser/pascaligo/Parser.mly index fa1030981..3c6766772 100644 --- a/src/parser/pascaligo/Parser.mly +++ b/src/parser/pascaligo/Parser.mly @@ -367,7 +367,6 @@ param_type: cartesian { TProd $1 } block: -(* Begin sequence(statement,SEMI) End { failwith "TODO" } *) Begin series(statement,End) { let first, (others, terminator, closing) = $2 in let region = cover $1 closing @@ -706,7 +705,7 @@ assignment: in {region; value}} rhs: - expr { Expr $1 } + expr { Expr $1 } lhs: path { Path $1 } @@ -768,7 +767,7 @@ interactive_expr: expr: case(expr) { ECase ($1 expr_to_region) } -| annot_expr { $1 } +| annot_expr { $1 } annot_expr: LPAR disj_expr COLON type_expr RPAR { diff --git a/src/parser/pascaligo/Stubs/Tezos_utils.ml b/src/parser/pascaligo/Stubs/Simple_utils.ml similarity index 100% rename from src/parser/pascaligo/Stubs/Tezos_utils.ml rename to src/parser/pascaligo/Stubs/Simple_utils.ml