diff --git a/src/passes/1-parser/pascaligo.mli b/src/passes/1-parser/pascaligo.mli new file mode 100644 index 000000000..e82d6ab35 --- /dev/null +++ b/src/passes/1-parser/pascaligo.mli @@ -0,0 +1,21 @@ +(* This file provides an interface to the PascaLIGO parser. *) + +open Trace + +module Parser = Parser_pascaligo.Parser +module AST = Parser_pascaligo.AST +module ParserLog = Parser_pascaligo.ParserLog +module LexToken = Parser_pascaligo.LexToken + + +(** Open a PascaLIGO filename given by string and convert into an abstract syntax tree. *) +val parse_file : string -> (AST.t result) + +(** Convert a given string into a PascaLIGO abstract syntax tree *) +val parse_string : string -> AST.t result + +(** Parse a given string as a PascaLIGO expression and return an expression AST. + +This is intended to be used for interactive interpreters, or other scenarios +where you would want to parse a PascaLIGO expression outside of a contract. *) +val parse_expression : string -> AST.expr result diff --git a/src/passes/1-parser/pascaligo/AST.mli b/src/passes/1-parser/pascaligo/AST.mli index 4984830e0..1deedf566 100644 --- a/src/passes/1-parser/pascaligo/AST.mli +++ b/src/passes/1-parser/pascaligo/AST.mli @@ -135,8 +135,15 @@ type 'a braces = { rbrace : rbrace } -(* The Abstract Syntax Tree *) +(** The Abstract Syntax Tree +The AST mirrors the contents of Parser.mly, which defines a tree of parsing +productions that are used to make a syntax tree from a given program input. + +This file defines the concrete AST for PascaLIGO, which is used to associate +regions of the source code text with the contents of the syntax tree. + +*) type t = { decl : declaration nseq; eof : eof diff --git a/src/passes/1-parser/pascaligo/LexToken.mli b/src/passes/1-parser/pascaligo/LexToken.mli index 49998a2e1..ea1f2123e 100644 --- a/src/passes/1-parser/pascaligo/LexToken.mli +++ b/src/passes/1-parser/pascaligo/LexToken.mli @@ -1,4 +1,4 @@ -(* This signature defines the lexical tokens for LIGO +(** This signature defines the lexical tokens for LIGO _Tokens_ are the abstract units which are used by the parser to build the abstract syntax tree (AST), in other words, the stream of diff --git a/src/passes/1-parser/shared/Markup.mli b/src/passes/1-parser/shared/Markup.mli index 2522b52a9..6b31c0647 100644 --- a/src/passes/1-parser/shared/Markup.mli +++ b/src/passes/1-parser/shared/Markup.mli @@ -1,12 +1,11 @@ -(* This module defines the sorts of markup recognised by the LIGO +(** This module defines the sorts of markup recognised by the LIGO lexer *) module Region = Simple_utils.Region -(* A lexeme is piece of concrete syntax belonging to a token. In +(** A lexeme is piece of concrete syntax belonging to a token. In algebraic terms, a token is also a piece of abstract lexical syntax. Lexical units emcompass both markup and lexemes. *) - type lexeme = string type t = @@ -19,7 +18,7 @@ type t = type markup = t -(* Pretty-printing of markup +(** Pretty-printing of markup The difference between [to_lexeme] and [to_string] is that the former builds the corresponding concrete syntax (the lexeme), diff --git a/src/passes/2-simplify/pascaligo.ml b/src/passes/2-simplify/pascaligo.ml index 18f2d8585..19d4d2082 100644 --- a/src/passes/2-simplify/pascaligo.ml +++ b/src/passes/2-simplify/pascaligo.ml @@ -8,7 +8,6 @@ open Combinators let nseq_to_list (hd, tl) = hd :: tl let npseq_to_list (hd, tl) = hd :: (List.map snd tl) -let npseq_to_nelist (hd, tl) = hd, (List.map snd tl) let pseq_to_list = function | None -> [] | Some lst -> npseq_to_list lst diff --git a/src/passes/2-simplify/pascaligo.mli b/src/passes/2-simplify/pascaligo.mli index ccc42e5e1..c04edcf72 100644 --- a/src/passes/2-simplify/pascaligo.mli +++ b/src/passes/2-simplify/pascaligo.mli @@ -1,81 +1,26 @@ +(** Converts PascaLIGO programs to the Simplified Abstract Syntax Tree. *) + open Trace open Ast_simplified module Raw = Parser.Pascaligo.AST module SMap = Map.String -(* -val nseq_to_list : 'a * 'a list -> 'a list -val npseq_to_list : 'a * ( 'b * 'a ) list -> 'a list -*) -val npseq_to_nelist : 'a * ( 'b * 'c ) list -> 'a * 'c list -(* -val pseq_to_list : ('a * ('b * 'a) list) option -> 'a list -val get_value : 'a Raw.reg -> 'a -*) - module Errors : sig - (* - val unsupported_cst_constr : Raw.pattern -> unit -> error - val unsupported_ass_None : Raw.wild -> unit -> error - val unsupported_entry_decl : 'a Raw.reg -> unit -> error - val unsupported_proc_decl : 'a Raw.reg -> unit -> error - *) + val bad_bytes : Location.t -> string -> unit -> error - (* - val unsupported_local_proc : Raw.wild -> unit -> error - val corner_case : loc:string -> string -> unit -> error - val unknown_predefined_type : string Raw.reg -> unit -> error - *) + val unsupported_arith_op : Raw.expr -> unit -> error - (* - val unsupported_set_expr : Raw.expr -> unit -> error - *) + val unsupported_proc_calls : 'a Raw.reg -> unit -> error - (* - val unsupported_for_loops : Raw.wild -> unit -> error - val unsupported_deep_map_assign : 'a Raw.reg -> unit -> error - val unsupported_empty_record_patch : 'a Raw.reg -> unit -> error - val unsupported_map_patches : 'a Raw.reg -> unit -> error - val unsupported_set_patches : 'a Raw.reg -> unit -> error - val unsupported_deep_map_rm : 'a Raw.reg -> unit -> error - val unsupported_set_removal : 'a Raw.reg -> unit -> error - val unsupported_non_var_pattern : Raw.pattern -> unit -> error - val only_constructors : Raw.pattern -> unit -> error - val unsupported_tuple_pattern : Raw.pattern -> unit -> error - val unsupported_deep_Some_patterns : Raw.pattern -> unit -> error - val unsupported_deep_list_patterns : 'a Raw.reg -> unit -> error - val unsupported_sub_blocks : 'a Raw.reg -> unit -> error - val simplifying_instruction : Raw.instruction -> unit -> error - *) + end -(* -val r_split : 'a Raw.reg -> 'a * Location.t -val return : expr -> ( expr option -> expr result ) result -val return_let_in : ?loc:Location.t -> string * type_expression option -> expr -> ( expr option -> expr result ) result -val simpl_type_expression : Raw.type_expr -> type_expression result -val simpl_list_type_expression : Raw.type_expr list -> type_expression result -*) + +(** Convert a concrete PascaLIGO expression AST to the simplified expression AST + used by the compiler. *) val simpl_expression : Raw.expr -> expr result -(* -val simpl_logic_expression : Raw.logic_expr -> expression result -val simpl_list_expression : Raw.list_expr -> expression result -val simpl_set_expression : Raw.set_expr -> expression result -val simpl_binop : string -> Raw.wild Raw.bin_op Region.reg -> expression result -val simpl_unop : string -> Raw.wild Raw.un_op Region.reg -> expression result -val simpl_tuple_expression : ?loc:Location.t -> Raw.expr list -> expression result -val simpl_local_declaration : Raw.local_decl -> ( expr option -> expr result) result -val simpl_data_declaration : Raw.data_decl -> ( expr option -> expr result ) result -val simpl_param : Raw.param_decl -> (type_name * type_expression) result -val simpl_fun_declaration : loc:Location.t -> Raw.fun_decl -> ((name * type_expression option) * expression) result -val simpl_declaration : Raw.declaration -> declaration Location.wrap result -val simpl_single_instruction : Raw.single_instr -> (expression option -> expression result) result -val simpl_path : Raw.path -> string * Ast_simplified.access_path -val simpl_cases : (Raw.pattern * 'a) list -> 'a matching result -val simpl_instruction_block : Raw.instruction -> (expression option -> expression result) result -val simpl_instruction : Raw.instruction -> (expression option -> expression result) result -val simpl_statements : Raw.statements -> (expression option -> expression result) result -val simpl_block : Raw.block -> (expression option -> expression result) result -*) + +(** Convert a concrete PascaLIGO program AST to the simplified program AST used + by the compiler. *) val simpl_program : Raw.ast -> program result diff --git a/src/passes/6-transpiler/transpiler.ml b/src/passes/6-transpiler/transpiler.ml index 0cef7b26b..5886ab542 100644 --- a/src/passes/6-transpiler/transpiler.ml +++ b/src/passes/6-transpiler/transpiler.ml @@ -1,3 +1,7 @@ +(* The Transpiler is a function that takes as input the Typed AST, and outputs expressions in a language that is basically a Michelson with named variables and first-class-environments. + +For more info, see back-end.md: https://gitlab.com/ligolang/ligo/blob/dev/gitlab-pages/docs/contributors/big-picture/back-end.md *) + open! Trace open Helpers diff --git a/src/stages/ast_simplified/PP.mli b/src/stages/ast_simplified/PP.mli index 4a08aaf28..aa7c9470c 100644 --- a/src/stages/ast_simplified/PP.mli +++ b/src/stages/ast_simplified/PP.mli @@ -1,3 +1,5 @@ +(** Pretty printer for the Simplified Abstract Syntax Tree *) + open Types open Format @@ -32,7 +34,7 @@ val matching_variant_case : (formatter -> 'a -> unit) -> formatter -> (construct val matching : (formatter -> 'a -> unit) -> formatter -> 'a matching -> unit *) -(* Shows the type expected for the matched value *) +(** Shows the type expected for the matched value *) val matching_type : formatter -> 'a matching -> unit (* @@ -41,4 +43,5 @@ val matching_variant_case_type : formatter -> ( ( constructor_name * name) * 'a) val declaration : formatter -> declaration -> unit *) +(** Pretty print a full program AST *) val program : formatter -> program -> unit