Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
Have a look at [https://github.com/goccmack/gogll](https://github.com/goccmack/gogll) for scannerless GLL parser generation.
# Gocc

![Build Status](https://github.com/goccmack/gocc/workflows/build/badge.svg)
[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/goccmack/gocc)
[![Go Report Card](https://goreportcard.com/badge/github.com/goccmack/gocc)](https://goreportcard.com/report/github.com/goccmack/gocc)
![Build Status](https://github.com/johnkerl/gocc/workflows/build/badge.svg)
[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/johnkerl/gocc)
[![Go Report Card](https://goreportcard.com/badge/github.com/johnkerl/gocc)](https://goreportcard.com/report/github.com/johnkerl/gocc)

## Introduction

Expand All @@ -27,16 +27,16 @@ in the BNF.

See the [README](example/bools/README) for an included example.

[User Guide (PDF): Learn You a gocc for Great Good](https://raw.githubusercontent.com/goccmack/gocc/master/doc/gocc_user_guide.pdf) (gocc3 user guide will be published shortly)
[User Guide (PDF): Learn You a gocc for Great Good](https://raw.githubusercontent.com/johnkerl/gocc/master/doc/gocc_user_guide.pdf) (gocc3 user guide will be published shortly)

## Installation

* First download and Install Go From http://golang.org/
* Setup your GOPATH environment variable.
* Next in your command line run: go get github.com/goccmack/gocc (go get will
git clone gocc into GOPATH/src/github.com/goccmack/gocc and run go install)
* Alternatively clone the source: https://github.com/goccmack/gocc . Followed
by go install github.com/goccmack/gocc
* Next in your command line run: go get github.com/johnkerl/gocc (go get will
git clone gocc into GOPATH/src/github.com/johnkerl/gocc and run go install)
* Alternatively clone the source: https://github.com/johnkerl/gocc . Followed
by go install github.com/johnkerl/gocc
* Finally, make sure that the bin folder where the gocc binary is located is
in your PATH environment variable.

Expand Down
106 changes: 53 additions & 53 deletions doc/gocc_user_guide.tex
Original file line number Diff line number Diff line change
Expand Up @@ -117,17 +117,17 @@ \section{Getting started}

\item Install \gocc:
\begin{enumerate}
\item In your command line run: \Code{go get github.com/goccmack/gocc/} (go get will git clone gocc into GOPATH/src/github.com/goccmack/gocc and run go install)
\item In your command line run: \Code{go get github.com/johnkerl/gocc/} (go get will git clone gocc into GOPATH/src/github.com/johnkerl/gocc and run go install)

or

\item Alternatively clone the repository: \url{https://github.com/goccmack/gocc/archive/master.zip}. Followed by:
\verb|go install github.com/goccmack/gocc|.
\item Alternatively clone the repository: \url{https://github.com/johnkerl/gocc/archive/master.zip}. Followed by:
\verb|go install github.com/johnkerl/gocc|.
\end{enumerate}

\end{enumerate}

Test your installation by running \verb|make test| from \verb|$GOPATH/src/github.com/goccmack/gocc|.
Test your installation by running \verb|make test| from \verb|$GOPATH/src/github.com/johnkerl/gocc|.

\section{How to create and use a parser with gocc}
Figure~\ref{fig:hl design} shows the high-level design of a user application, which uses a parser generated with gocc.
Expand Down Expand Up @@ -174,7 +174,7 @@ \section{First example}\label{sec:first example}

The source code of the following example can be found at

\verb|$GOPATH/src/github.com/goccmack/gocc/example/calc|
\verb|$GOPATH/src/github.com/johnkerl/gocc/example/calc|

The grammar implements the simple desktop calculator described in~\cite{Dragon Book}. The generated code is both a parser and an interpreter for the calculator.

Expand Down Expand Up @@ -256,8 +256,8 @@ \section{First example}\label{sec:first example}

<<
import(
"github.com/goccmack/gocc/example/calc/token"
"github.com/goccmack/gocc/example/calc/util"
"github.com/johnkerl/gocc/example/calc/token"
"github.com/johnkerl/gocc/example/calc/util"
)
>>

Expand All @@ -282,7 +282,7 @@ \section{First example}\label{sec:first example}

The BNF has two parts: a lexical and a syntax part. Both parts are optional -- gocc can be used to generate only a lexer or only a parser -- but every BNF must have at least a lexical part or a syntax part. This example has both and gocc will generate a lexer, a parser and all the support they require to function.

It declares the imported package \verb|github.com/goccmack/gocc/example/calc/token| (generated by gocc), which will be used in the action expressions of some productions of the grammar.
It declares the imported package \verb|github.com/johnkerl/gocc/example/calc/token| (generated by gocc), which will be used in the action expressions of some productions of the grammar.

The lexical part consists of:

Expand Down Expand Up @@ -352,8 +352,8 @@ \section{First example}\label{sec:first example}
package calc

import (
"github.com/goccmack/gocc/example/calc/lexer"
"github.com/goccmack/gocc/example/calc/parser"
"github.com/johnkerl/gocc/example/calc/lexer"
"github.com/johnkerl/gocc/example/calc/parser"
"fmt"
"testing"
)
Expand Down Expand Up @@ -402,16 +402,16 @@ \section{First example}\label{sec:first example}
\begin{verbatim}
> go test -v
warning: building out-of-date packages:
github.com/goccmack/gocc/example/calc/token
github.com/goccmack/gocc/example/calc/lexer
github.com/goccmack/gocc/example/calc/errors
github.com/goccmack/gocc/example/calc/parser
github.com/johnkerl/gocc/example/calc/token
github.com/johnkerl/gocc/example/calc/lexer
github.com/johnkerl/gocc/example/calc/errors
github.com/johnkerl/gocc/example/calc/parser
installing these packages with 'go test -i' will speed future tests.

=== RUN Test1
--- PASS: Test1 (0.00 seconds)
PASS
ok github.com/goccmack/gocc/example/calc 0.017s
ok github.com/johnkerl/gocc/example/calc 0.017s
\end{verbatim}

{\em Congratulations!} You have executed your first gocc-generated code.
Expand All @@ -428,16 +428,16 @@ \section{Commandline syntax}\label{sec:commandline}
-debug_parser=false: enable debug logging in parser
-h=false: help
-no_lexer=false: do not generate a lexer
-o="/Users/marius/goprj/src/github.com/goccmack/gocc": output dir.
-p="github.com/goccmack/gocc": package
-o="/Users/marius/goprj/src/github.com/johnkerl/gocc": output dir.
-p="github.com/johnkerl/gocc": package
-u=false: allow unreachable productions
-v=false: verbose
\end{verbatim}

\section{Example: parsing simple mail addresses} \label{sec:example mail}
This example shows how gocc can be used to generate a stand-alone FSA to parse a regular language. The goal is to parse simple mail address specifications like: \verb|mailbox@gmail.com| or \verb|"mail box"@gmail.com|. The source code of the sample can be found at

\verb|$GOPATH/src/github.com/goccmack/gocc/example/mail|
\verb|$GOPATH/src/github.com/johnkerl/gocc/example/mail|

\verb|mail.bnf| contains:

Expand Down Expand Up @@ -495,8 +495,8 @@ \section{Example: parsing simple mail addresses} \label{sec:example mail}
package mail

import (
"github.com/goccmack/gocc/example/mail/lexer"
"github.com/goccmack/gocc/example/mail/token"
"github.com/johnkerl/gocc/example/mail/lexer"
"github.com/johnkerl/gocc/example/mail/token"
"testing"
)

Expand Down Expand Up @@ -580,7 +580,7 @@ \section{Handling LR(1) conflicts} \label{sec:lr conflicts}
\section{Example: reduce/reduce conflict handling} \label{sec:example rr}
The source code of the following example can be found at

\verb|$GOPATH/src/github.com/goccmack/gocc/example/rr|
\verb|$GOPATH/src/github.com/johnkerl/gocc/example/rr|

\begin{verbatim}
RR : A | B ;
Expand All @@ -591,7 +591,7 @@ \section{Example: reduce/reduce conflict handling} \label{sec:example rr}

\end{verbatim}

When we run \gocc on \verb|$GOPATH/src/github.com/goccmack/gocc/example/rr/rr.bnf| we discover a reduce/reduce conflict:
When we run \gocc on \verb|$GOPATH/src/github.com/johnkerl/gocc/example/rr/rr.bnf| we discover a reduce/reduce conflict:

\begin{verbatim}
> gocc -v rr.bnf
Expand All @@ -600,8 +600,8 @@ \section{Example: reduce/reduce conflict handling} \label{sec:example rr}
-debug_parser = false
-h = false
-no_lexer = false
-o = /home/src/github.com/goccmack/gocc/example/rr
-p = github.com/goccmack/gocc/example/rr
-o = /home/src/github.com/johnkerl/gocc/example/rr
-p = github.com/johnkerl/gocc/example/rr
-u = false
-v = true
Error: 1 LR-1 conflicts
Expand Down Expand Up @@ -654,7 +654,7 @@ \section{Example: reduce/reduce conflict handling} \label{sec:example rr}
\section{Example: Shift/reduce conflict handling} \label{sec:example sr}
The source code of the following example can be found at

\verb|$GOPATH/src/github.com/goccmack/gocc/example/sr|
\verb|$GOPATH/src/github.com/johnkerl/gocc/example/sr|

It is the classic example of the dangling else in the \Clang:

Expand All @@ -665,7 +665,7 @@ \section{Example: Shift/reduce conflict handling} \label{sec:example sr}
;
\end{verbatim}

When we run \gocc on \verb|$GOPATH/src/github.com/goccmack/gocc/example/sr/sr.bnf| we discover a shift/reduce conflict:
When we run \gocc on \verb|$GOPATH/src/github.com/johnkerl/gocc/example/sr/sr.bnf| we discover a shift/reduce conflict:

\begin{verbatim}
> gocc -v sr.bnf
Expand Down Expand Up @@ -704,14 +704,14 @@ \section{Example: Using an AST} \label{sec:example ast}

The code for the example can be found at

\verb|$GOPATH/src/github.com/goccmack/gocc/example/astx|
\verb|$GOPATH/src/github.com/johnkerl/gocc/example/astx|

The grammar is in \verb|ast.bnf|:

\begin{verbatim}
<<
import "github.com/goccmack/gocc/example/astx/ast"
import "github.com/goccmack/gocc/example/astx/token"
import "github.com/johnkerl/gocc/example/astx/ast"
import "github.com/johnkerl/gocc/example/astx/token"
>>

StmtList :
Expand All @@ -725,20 +725,20 @@ \section{Example: Using an AST} \label{sec:example ast}
\end{verbatim}

At the top of the grammar is a file header section containing an import statement for the user-provided package,
\verb|github.com/goccmack/gocc/example/astx/ast|.
\verb|github.com/johnkerl/gocc/example/astx/ast|.

The production action expressions will use functions from the package, \verb|ast|.

The start production, \verb"StmtList" returns a tuple: \verb|(ast.StmtList, error)|, as we can see from the code of functions
\verb|NewStmtList| and \verb|AppendStmt| in

\verb|$GOPATH/src/github.com/goccmack/gocc/example/astx/ast.go|:
\verb|$GOPATH/src/github.com/johnkerl/gocc/example/astx/ast.go|:

\begin{verbatim}
package ast

import(
"github.com/goccmack/gocc/example/astx/token"
"github.com/johnkerl/gocc/example/astx/token"
)

type (
Expand Down Expand Up @@ -776,7 +776,7 @@ \section{Example: Using an AST} \label{sec:example ast}

from the directory

\verb|$GOPATH/src/github.com/goccmack/gocc/example/astx/|
\verb|$GOPATH/src/github.com/johnkerl/gocc/example/astx/|

we get the following output:

Expand All @@ -793,7 +793,7 @@ \section{Example: Using an AST} \label{sec:example ast}
expected one of: $ id
--- PASS: TestFail (0.00s)
PASS
ok github.com/goccmack/gocc/example/astx 0.006s \end{verbatim}
ok github.com/johnkerl/gocc/example/astx 0.006s \end{verbatim}

The first test, \verb"TestPass", has a valid input string, \verb|"a b c d e f"|; and parses successfully; and returns the expected StmtList, \verb|[a b c d e f]|.

Expand All @@ -806,10 +806,10 @@ \section{Example: Parser error recovery} \label{sec:error recovery}

We modify the AST example to illustrate error recovery. See:

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/errorrecovery/er.bnf|:
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/errorrecovery/er.bnf|:

\begin{verbatim}
<< import "github.com/goccmack/gocc/example/errorrecovery/ast" >>
<< import "github.com/johnkerl/gocc/example/errorrecovery/ast" >>

StmtList :
Stmt << ast.NewStmtList($0) >>
Expand All @@ -828,18 +828,18 @@ \section{Example: Parser error recovery} \label{sec:error recovery}

From the directory,

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/errorrecovery/|,
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/errorrecovery/|,

run \verb|go test| as follows:

\begin{verbatim}
> go test -v .
warning: building out-of-date packages:
github.com/goccmack/gocc/example/errorrecovery/token
github.com/goccmack/gocc/example/errorrecovery/ast
github.com/goccmack/gocc/example/errorrecovery/errors
github.com/goccmack/gocc/example/errorrecovery/parser
github.com/goccmack/gocc/example/errorrecovery/lexer
github.com/johnkerl/gocc/example/errorrecovery/token
github.com/johnkerl/gocc/example/errorrecovery/ast
github.com/johnkerl/gocc/example/errorrecovery/errors
github.com/johnkerl/gocc/example/errorrecovery/parser
github.com/johnkerl/gocc/example/errorrecovery/lexer
installing these packages with 'go test -i .' will speed future tests.

=== RUN TestFail
Expand All @@ -859,11 +859,11 @@ \section{Example: Parser error recovery} \label{sec:error recovery}
f
]
--- PASS: TestFail (0.00 seconds)
PASS ok github.com/goccmack/gocc/example/errorrecovery 0.015s
PASS ok github.com/johnkerl/gocc/example/errorrecovery 0.015s
\end{verbatim}

The test case can be found in \\
\verb|$GOPATH/src/github.com/goccmack/gocc/examples/errorrecovery/er_test.go|. \\
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/errorrecovery/er_test.go|. \\
It calls the parser with input string, \verb|"a b ; d e f"|, which contains an invalid token, \verb|;|.

From the \verb|go test| output we see that the parser successfully recovered from the input error and returned a \verb|StmtList| containing an error symbol between \verb|[a| and \verb|d, e, f]|. The \verb|id|, \verb|b|, was lost in the error recovery. \TBDx{Explain exactly why the 'b' was lost.} The errored token was \verb|;| (invalid token) when the parser expected one of \verb|error, $| (end of input) or \verb|id|.
Expand All @@ -877,19 +877,19 @@ \section{Example: Parser error recovery} \label{sec:error recovery}
\item The parser will still return a non-\verb|nil| error value if it encounters an irrecoverable error.
\end{enumerate}

See \verb|$GOPATH/src/github.com/goccmack/gocc/examples/errorrecovery/errors/error.go| for the definition of errors.Error.
See \verb|$GOPATH/src/github.com/johnkerl/gocc/examples/errorrecovery/errors/error.go| for the definition of errors.Error.

\section{Example: Using another lexer} \label{sec:no lexer}
The generation of lexer code can be suppressed with the \verb|no_lexer| option (see section~\ref{sec:commandline}). An example,
which uses a hand-written lexer, can be found at:

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/nolexer/nolexer.bnf|:
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/nolexer/nolexer.bnf|:

\begin{verbatim}
<<
import (
"fmt"
"github.com/goccmack/gocc/example/nolexer/token"
"github.com/johnkerl/gocc/example/nolexer/token"
)
>>

Expand All @@ -909,7 +909,7 @@ \section{Example: Using another lexer} \label{sec:no lexer}

This grammar contains no lexical productions. We generate code for it using

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/nolexer/gen.sh|:
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/nolexer/gen.sh|:

\verb|gocc -no_lexer nolexer.bnf|

Expand Down Expand Up @@ -937,19 +937,19 @@ \section{Example: Using another lexer} \label{sec:no lexer}

Note the absence of a \verb|lexer| directory. Instead there is a hand-written scanner in

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/nolexer/scanner/scanner.go|
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/nolexer/scanner/scanner.go|

The scanner implements the interface:

\lstinputlisting[numbers=left, linerange=89-91, firstnumber=89]{../example/nolexer/parser/parser.go}

which is declared in the generated parser:

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/nolexer/parser/parser.go|.
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/nolexer/parser/parser.go|.

The scanner must recognise the tokens required by the parser generated from the BNF. They are declared in a \verb|TokenMap| in

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/nolexer/token/token.go|:
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/nolexer/token/token.go|:

\lstinputlisting[numbers=left,linerange=59-75,firstnumber=59]{../example/nolexer/token/token.go}

Expand All @@ -961,13 +961,13 @@ \section{Example: Using another lexer} \label{sec:no lexer}

Any lexeme not matching a valid terminal symbol of the grammar must be returned as \verb|INVALID|.

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/nolexer/scanner/scanner.go| implements a lexical analyser for this grammar as follows:
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/nolexer/scanner/scanner.go| implements a lexical analyser for this grammar as follows:

\lstinputlisting[numbers=left]{../example/nolexer/scanner/scanner.go}

Examples of using the generated parser with the hand-written scanner are given in

\verb|$GOPATH/src/github.com/goccmack/gocc/examples/nolexer/nolexer_test.go|
\verb|$GOPATH/src/github.com/johnkerl/gocc/examples/nolexer/nolexer_test.go|

\section{gocc syntax}\label{sec:gocc syntax}
A gocc source file contains UTF-8 encoded Unicode text.
Expand Down
4 changes: 2 additions & 2 deletions example/astx/ast.bnf
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ id : (_letter | '_') {_idchar} ;

<<
import (
"github.com/goccmack/gocc/example/astx/ast"
"github.com/goccmack/gocc/example/astx/token"
"github.com/johnkerl/gocc/example/astx/ast"
"github.com/johnkerl/gocc/example/astx/token"
)
>>

Expand Down
2 changes: 1 addition & 1 deletion example/astx/ast/ast.go
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package ast

import (
"github.com/goccmack/gocc/example/astx/token"
"github.com/johnkerl/gocc/example/astx/token"
)

type (
Expand Down
Loading
Loading