From 35ed2c3461b250dd81c368cf9388820c7d6a8451 Mon Sep 17 00:00:00 2001 From: Jan Max Meyer Date: Tue, 17 Apr 2018 10:18:28 +0200 Subject: [PATCH] Minor docs changes & style, v0.22 is ready --- .gitignore | 3 + CHANGELOG.md | 7 +- Version | 2 +- doc/array.t2t | 4 +- doc/list.t2t | 8 +- doc/parse.t2t | 28 +++++ doc/phorward.css | 73 ++++++++--- doc/phorward.html | 173 ++++++++++++++++++++------ doc/phorward.t2t | 10 +- doc/ref.t2t | 51 ++++---- examples/grammars/expr-with-assoc.syn | 13 ++ examples/grammars/expr.syn | 16 +++ 12 files changed, 301 insertions(+), 87 deletions(-) create mode 100644 examples/grammars/expr-with-assoc.syn create mode 100644 examples/grammars/expr.syn diff --git a/.gitignore b/.gitignore index 51bf4e06..28d53cd7 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,6 @@ run/pregex run/ppgram2c run/pvm +examples/parsing +examples/lexing +examples/regex diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b7b7515..789815be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ This file is used to document any relevant changes done to libphorward. ## v0.22 -Current development version. +Released on: April 17, 2018 - Parsing tools - Revised all modules, separating the grammar definition entirely from the @@ -15,9 +15,12 @@ Current development version. - Revised and simplified LR parser driver, now working on state machine, and not the data-structures from lr.c anymore. - Created better definition language called PBNF (Phorward BNF, pbnf.c) - - Support for a BNF, EBNF and a Phorward-style BNF (PBNF) as input grammars + - Frontends for BNF, EBNF and a Phorward-style BNF (PBNF) as input grammars using the functions pp_gram_from_bnf(), pp_gram_from_ebnf() and pp_gram_from_pbnf(). + - Implied precedence & associativity for LALR conflict resolution, which can + be used via ``<<`` (left-associative), ``>>`` (right-associative) and + ``^^`` (non-associative) in the pbnf language. - Regular expressions - Internal revisions and renamings. - Cleaning data structures from temporal and ephemeral values. diff --git a/Version b/Version index cbeaf001..07499b96 100755 --- a/Version +++ b/Version @@ -1,4 +1,4 @@ #!/bin/sh -echo "0.22.0 develop" +echo "0.22.0" # When changing version number, remove src/version.h to regenerate it! diff --git a/doc/array.t2t b/doc/array.t2t index 3a49048f..d2afbf09 100644 --- a/doc/array.t2t +++ b/doc/array.t2t @@ -10,14 +10,14 @@ The **parray** object is a general-purpose data structure which can be used for The **parray** object brings the following advantages and disadvantages: - __Advantages__ - - Chunk allocation requires lesser @pmalloc()/@prealloc() operations than with **plist** + - Chunk allocation requires lesser @pmalloc()/@prealloc() operations than with [plist #plist] - Dynamic and quick implementation for huger data structures - Elements are hold in a real array on the heap - Low memory consumption - Fast iteration over elements - - __Disadvantages__ - - Not so flexible like **plist** + - Less flexible then [plist #plist] - No hashable entries - Removing elements or rechaining requires more computing power - diff --git a/doc/list.t2t b/doc/list.t2t index 548b2667..d089baef 100644 --- a/doc/list.t2t +++ b/doc/list.t2t @@ -3,9 +3,9 @@ === Overview === -Next to the **parray** object, the **plist** object is a powerful C implementation of a double-linked list with some extra features. It is also used for handling homogenious elements of the same size in a dynamic way, and can be used for many tasks. +Next to the [parray #parray] object, the **plist** object is a powerful C implementation of a double-linked list with some extra features. It is also used for handling homogenious elements of the same size in a dynamic way, and can be used for many tasks. -**plist** can be seen as a superset of the **parray** object, because it features nearly the same operations but with other underlying data management methods. +**plist** can be seen as a superset of the [parray #parray] object, because it features nearly the same operations but with other underlying data management methods. The **plist** object implements: @@ -30,7 +30,7 @@ The **plist** object brings the following advantages and disadvantages: - Allows pointer-mode and entity-mode configuration (PLIST_MOD_PTR) - Additionally find objects using a hash-table - Provides element recycling methods (PLIST_MOD_RECYCLE) - - Elements are chained and can be re-arraged + - Elements are chained, can be re-arraged and have persistent pointers - Automatical sorting using individual sort-functions - Simple set-theory functions (union, diff) - @@ -38,7 +38,7 @@ The **plist** object brings the following advantages and disadvantages: - High memory consumption, especially in case when used with hash-tables - Iteration over elements is much slower - List elements are chained as **plistel** data structures, while the data members must be called separately - - All operations require more computing power in comparison to **parray** + - All operations require more computing power in comparison to [parray #parray] - - diff --git a/doc/parse.t2t b/doc/parse.t2t index ebffe330..1d95370e 100644 --- a/doc/parse.t2t +++ b/doc/parse.t2t @@ -142,6 +142,34 @@ expr$ : expr '+' term = add ; ``` +===== Associativity and precedence operators ===== + +With //pbnf//, and in combination with the LALR parser, precedence and associativity can also be used to resolve conflicts and write shorter grammars. Thus, the following version of the four-function calculator yields in the same parser. + +``` +%skip /[\s]+/ ; +Int : /[0-9]+/ = int; + +<< '+' '-'; +<< '*' '/'; + +expr$ : expr '*' expr = mul + | expr '/' expr = div + | expr '+' expr = add + | expr '-' expr = sub + | '(' expr ')' + | Int + ; +``` + +Here is a short table for reference. + +|| Operator | Meaning | +| << | Left-associative configuration | +| >> | Right-associative configuration | +| ^^ | Non-associative configuration | + + === More grammar-related functions === There are some more functions on grammars that need to be mentioned. diff --git a/doc/phorward.css b/doc/phorward.css index cbf62043..65e9a7e3 100644 --- a/doc/phorward.css +++ b/doc/phorward.css @@ -1,24 +1,34 @@ -html, body, table +html, body { - font-family: "Lucida Sans Unicode", "Lucida Grande", sans-serif; + font-family: Atlas, "Lucida Sans Unicode", "Lucida Grande", sans-serif; font-size: 14pt; + + background-color: #000055; } -html +body { - background-color: #333; + margin: 0 5%; + padding: 3%; + + background-color: #fff; } -body +table { - margin: 0 10%; - padding: 1%; - background-color: #fff; + border-collapse: collapse; + border-color: #ccc; + width: 100%; +} + +tr, td +{ + border-color: #ccc; } pre, code { - font-family: "Lucida Console", Monaco, monospace; + font-family: Monaco, monospace; } pre @@ -114,15 +124,6 @@ div#body h3 padding: 0; } - -@media print -{ - a.back_to_top - { - visible: none; - } -} - table.ref { } @@ -158,3 +159,39 @@ td.refreturns { } +@media print +{ + html, body, table + { + font-size: 10.5pt; + background-color: initial; + } + + body + { + margin: initial; + padding: initial; + background-color: initial; + } + + h1 + { + page-break-before: left; + } + + .header h1 + { + page-break-before: avoid; + margin-top: 8cm; + } + + div.function + { + page-break-inside: avoid; + } + + #toc1, div.toc + { + display: none; + } +} diff --git a/doc/phorward.html b/doc/phorward.html index fc4a953d..21f1e6c0 100644 --- a/doc/phorward.html +++ b/doc/phorward.html @@ -44,7 +44,7 @@

Table of Contents

  • Dynamic general-purpose objects
    • @@ -705,9 +705,15 @@

    Table of Contents

    Introduction

    +

    +Welcome to the Phorward library on-line documentation! +

    phorward is a versatile C-library. It is split into several modules, and mostly focuses on the definition and implementation of parsers, recognizers, virtual machines and regular expressions.

    +

    +The library is made up of several modules. These are: +