Skip to content

Commit

Permalink
Feature/docclean Greatly improve the godoc comments in the runtime (#…
Browse files Browse the repository at this point in the history 
…4169)

* doc: Updates to some of the Go doc comments to start a ful ldocumentation cleanup

Signed-off-by: Jim.Idle <jimi@idle.ws>

* doc: More documentation fixes.

Using this as a method of forcing myself to read every line of code in the runtime, and therefore
discover mistakes in the original implementation. And, of course, actually working docs for the
Go runtime, can only be a good thing.

Signed-off-by: Jim.Idle <jimi@idle.ws>

* doc: More documentation fixes

Also changes the exporet level of a some variables and funcs that were not correct,
even though no user has currently needed them it would seem.

Signed-off-by: Jim.Idle <jimi@idle.ws>

* doc: Many updates to document exported fuctions correctly and reformat the ingerited Java code

It looks like a massive amount of changes, but it is almost all doc or changing exports or renaming
unused paramters etc to make the Go linter happy.

No actual code changes yet.

Signed-off-by: Jim.Idle <jimi@idle.ws>

* doc: More additions and corrections to the Go documentation for the runtime

Signed-off-by: Jim.Idle <jimi@idle.ws>

* doc: Final clean of exported func and type documentation

There will be more to do here as there are a lot of things that are hidden internal to the antlr
package that probably should not be. There are also a lot of exported funcs and types without
any documentation, that will eventually need to be cleaned up.

Signed-off-by: Jim.Idle <jimi@idle.ws>

* Changed Parser typings (#4149)

Signed-off-by: Josua Frank <josua.frank@daimlertruck.com>
Co-authored-by: Josua Frank <josua.frank@daimlertruck.com>
Signed-off-by: Jim.Idle <jimi@idle.ws>

* fix: Fixes the failing go runtime test suite which was missing the /v4 off the replace option on the go.mod file (#4163)

Arrrgh!

Signed-off-by: Jim.Idle <jimi@idle.ws>

* present antlr before versioning (#4156)

Signed-off-by: Jim.Idle <jimi@idle.ws>

* fix: Prevent use of labels such as start= from generating code that clashes with builtin funcs (#4161)

Signed-off-by: Jim.Idle <jimi@idle.ws>

* Feature/gotestfix (#4168)

* fix: Fixes the failing go runtime test suite which was missing the /v4 off the replace option on the go.mod file

Arrrgh!

Signed-off-by: Jim.Idle <jimi@idle.ws>

* present antlr before versioning (#4156)

Signed-off-by: Jim.Idle <jimi@idle.ws>

* fix: Prevent use of labels such as start= from generating code that clashes with builtin funcs (#4161)

Signed-off-by: Jim.Idle <jimi@idle.ws>

* fix: Cater for the fact that some test rules use start as a label or rule name

As a fix for other cvode gen errors when start, end, or exception are used as
label names, they are now translated to have a suffix of `_` at code gen time.
However, the runtime tests sometimes use start as a rule name and so we must now
cater for this in the tests.

Signed-off-by: Jim.Idle <jimi@idle.ws>

---------

Signed-off-by: Jim.Idle <jimi@idle.ws>
Co-authored-by: ericvergnaud <eric.vergnaud@wanadoo.fr>
Signed-off-by: Jim.Idle <jimi@idle.ws>

---------

Signed-off-by: Jim.Idle <jimi@idle.ws>
Signed-off-by: Josua Frank <josua.frank@daimlertruck.com>
Co-authored-by: Josua Frank <frank.josua@gmail.com>
Co-authored-by: Josua Frank <josua.frank@daimlertruck.com>
Co-authored-by: ericvergnaud <eric.vergnaud@wanadoo.fr>
  • Loading branch information
@sharknoon @josufra @ericvergnaud
4 people committed Mar 10, 2023
1 parent c0f90d8 commit 95fd266
Show file tree
Hide file tree
Showing 45 changed files with 1,393 additions and 1,304 deletions.
15 changes: 14 additions & 1 deletion runtime/Go/antlr/v4/antlrdoc.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,19 @@ or translating structured text or binary files. It's widely used to build langua
From a grammar, ANTLR generates a parser that can build parse trees and also generates a listener interface
(or visitor) that makes it easy to respond to the recognition of phrases of interest.
# Go Runtime
At version 4.11.x and prior, the Go runtime was not properly versioned for go modules. After this point, the runtime
source code is held in the `runtime/Go/antlr/v4` directory, and the go.mod file is updated to reflect the version of
ANTLR4 that it is compatible with (I.E. uses the /v4 path). The runtime is now available as a go module, and can be
imported as `github.com/antlr/antlr4/runtime/Go/antlr/v4` (the go get command should also be used with this path). See
the main documentation for the ANTLR4 project for more information.
This means that if you are using the source code without modules, you should also use the source code in /v4. Though
we highly recommend that you use go modules, as they are now idiomatic Go.
I am aware that this change will prove Hyrum's Law, but am prepared to live with it for teh common good. JI
# Code Generation
ANTLR supports the generation of code in a number of [target languages], and the generated code is supported by a
Expand Down Expand Up @@ -58,7 +71,7 @@ From the command line at the root of your package “myproject” you can then s
# Copyright Notice
Copyright (c) 2012-2022 The ANTLR Project. All rights reserved.
Copyright (c) 2012-2023 The ANTLR Project. All rights reserved.
Use of this file is governed by the BSD 3-clause license, which can be found in the [LICENSE.txt] file in the project root.
Expand Down
9 changes: 6 additions & 3 deletions runtime/Go/antlr/v4/atn.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,11 @@ var ATNInvalidAltNumber int
// [ALL(*)]: https://www.antlr.org/papers/allstar-techreport.pdf
// [Recursive Transition Network]: https://en.wikipedia.org/wiki/Recursive_transition_network
type ATN struct {
// DecisionToState is the decision points for all rules, subrules, optional
// blocks, ()+, ()*, etc. Each subrule/rule is a decision point, and we must track them so we

// DecisionToState is the decision points for all rules, sub-rules, optional
// blocks, ()+, ()*, etc. Each sub-rule/rule is a decision point, and we must track them, so we
// can go back later and build DFA predictors for them. This includes
// all the rules, subrules, optional blocks, ()+, ()* etc...
// all the rules, sub-rules, optional blocks, ()+, ()* etc...
DecisionToState []DecisionState

// grammarType is the ATN type and is used for deserializing ATNs from strings.
Expand Down Expand Up @@ -51,6 +52,8 @@ type ATN struct {
// specified, and otherwise is nil.
ruleToTokenType []int

// ATNStates is a list of all states in the ATN, ordered by state number.
//
states []ATNState

mu sync.Mutex
Expand Down
51 changes: 44 additions & 7 deletions runtime/Go/antlr/v4/atn_config.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,29 +10,44 @@ import (

// ATNConfig is a tuple: (ATN state, predicted alt, syntactic, semantic
// context). The syntactic context is a graph-structured stack node whose
// path(s) to the root is the rule invocation(s) chain used to arrive at the
// path(s) to the root is the rule invocation(s) chain used to arrive in the
// state. The semantic context is the tree of semantic predicates encountered
// before reaching an ATN state.
type ATNConfig interface {

// Equals compares this ATNConfig to another for equality
Equals(o Collectable[ATNConfig]) bool

// Hash returns the hash code for this ATNConfig for use in maps and comparisons
Hash() int

// GetState returns the ATN state associated with this configuration
GetState() ATNState
// GetAlt returns the alternative associated with this configuration
GetAlt() int
// GetSemanticContext returns the semantic context associated with this configuration
GetSemanticContext() SemanticContext

// GetContext returns the rule invocation stack associated with this configuration
GetContext() PredictionContext
// SetContext sets the rule invocation stack associated with this configuration
SetContext(PredictionContext)

// GetReachesIntoOuterContext returns the count of references to an outer context from this configuration
GetReachesIntoOuterContext() int
// SetReachesIntoOuterContext sets the count of references to an outer context from this configuration
SetReachesIntoOuterContext(int)

// String returns a string representation of the configuration
String() string

getPrecedenceFilterSuppressed() bool
setPrecedenceFilterSuppressed(bool)
}

// BaseATNConfig is a base implementation of ATNConfig. Thi si s done to emulate Java's ability to have multiple
// constructors for a single class. This is not idiomatic Go, but it works for now.
// TODO: this isn't the way to do this I think, but it will take time to rework - JI Also, getters and setters are not Go. Might be better to just access the fields, though the compiler will probably eliminate the calls
type BaseATNConfig struct {
precedenceFilterSuppressed bool
state ATNState
Expand All @@ -42,7 +57,8 @@ type BaseATNConfig struct {
reachesIntoOuterContext int
}

func NewBaseATNConfig7(old *BaseATNConfig) ATNConfig { // TODO: Dup
//goland:noinspection GoUnusedExportedFunction
func NewBaseATNConfig7(old *BaseATNConfig) ATNConfig { // TODO: Dup - maybe delete this
return &BaseATNConfig{
state: old.state,
alt: old.alt,
Expand All @@ -52,10 +68,12 @@ func NewBaseATNConfig7(old *BaseATNConfig) ATNConfig { // TODO: Dup
}
}

// NewBaseATNConfig6 creates a new BaseATNConfig instance given a state, alt and context only
func NewBaseATNConfig6(state ATNState, alt int, context PredictionContext) *BaseATNConfig {
return NewBaseATNConfig5(state, alt, context, SemanticContextNone)
}

// NewBaseATNConfig5 creates a new BaseATNConfig instance given a state, alt, context and semantic context
func NewBaseATNConfig5(state ATNState, alt int, context PredictionContext, semanticContext SemanticContext) *BaseATNConfig {
if semanticContext == nil {
panic("semanticContext cannot be nil") // TODO: Necessary?
Expand All @@ -64,22 +82,28 @@ func NewBaseATNConfig5(state ATNState, alt int, context PredictionContext, seman
return &BaseATNConfig{state: state, alt: alt, context: context, semanticContext: semanticContext}
}

// NewBaseATNConfig4 creates a new BaseATNConfig instance given an existing config, and a state only
func NewBaseATNConfig4(c ATNConfig, state ATNState) *BaseATNConfig {
return NewBaseATNConfig(c, state, c.GetContext(), c.GetSemanticContext())
}

// NewBaseATNConfig3 creates a new BaseATNConfig instance given an existing config, a state and a semantic context
func NewBaseATNConfig3(c ATNConfig, state ATNState, semanticContext SemanticContext) *BaseATNConfig {
return NewBaseATNConfig(c, state, c.GetContext(), semanticContext)
}

// NewBaseATNConfig2 creates a new BaseATNConfig instance given an existing config, and a context only
func NewBaseATNConfig2(c ATNConfig, semanticContext SemanticContext) *BaseATNConfig {
return NewBaseATNConfig(c, c.GetState(), c.GetContext(), semanticContext)
}

// NewBaseATNConfig1 creates a new BaseATNConfig instance given an existing config, a state, and a context only
func NewBaseATNConfig1(c ATNConfig, state ATNState, context PredictionContext) *BaseATNConfig {
return NewBaseATNConfig(c, state, context, c.GetSemanticContext())
}

// NewBaseATNConfig creates a new BaseATNConfig instance given an existing config, a state, a context and a semantic context, other 'constructors'
// are just wrappers around this one.
func NewBaseATNConfig(c ATNConfig, state ATNState, context PredictionContext, semanticContext SemanticContext) *BaseATNConfig {
if semanticContext == nil {
panic("semanticContext cannot be nil")
Expand All @@ -103,29 +127,37 @@ func (b *BaseATNConfig) setPrecedenceFilterSuppressed(v bool) {
b.precedenceFilterSuppressed = v
}

// GetState returns the ATN state associated with this configuration
func (b *BaseATNConfig) GetState() ATNState {
return b.state
}

// GetAlt returns the alternative associated with this configuration
func (b *BaseATNConfig) GetAlt() int {
return b.alt
}

// SetContext sets the rule invocation stack associated with this configuration
func (b *BaseATNConfig) SetContext(v PredictionContext) {
b.context = v
}

// GetContext returns the rule invocation stack associated with this configuration
func (b *BaseATNConfig) GetContext() PredictionContext {
return b.context
}

// GetSemanticContext returns the semantic context associated with this configuration
func (b *BaseATNConfig) GetSemanticContext() SemanticContext {
return b.semanticContext
}

// GetReachesIntoOuterContext returns the count of references to an outer context from this configuration
func (b *BaseATNConfig) GetReachesIntoOuterContext() int {
return b.reachesIntoOuterContext
}

// SetReachesIntoOuterContext sets the count of references to an outer context from this configuration
func (b *BaseATNConfig) SetReachesIntoOuterContext(v int) {
b.reachesIntoOuterContext = v
}
Expand Down Expand Up @@ -182,6 +214,7 @@ func (b *BaseATNConfig) Hash() int {
return murmurFinish(h, 4)
}

// String returns a string representation of the BaseATNConfig, usually used for debugging purposes
func (b *BaseATNConfig) String() string {
var s1, s2, s3 string

Expand All @@ -200,6 +233,9 @@ func (b *BaseATNConfig) String() string {
return fmt.Sprintf("(%v,%v%v%v%v)", b.state, b.alt, s1, s2, s3)
}

// LexerATNConfig represents a lexer ATN configuration which tracks the lexer action, and which "inherits" from the
// BaseATNConfig struct.
// TODO: Stop using a pointer and embed the struct instead as this saves allocations. Same for the LexerATNConfig "constructors"
type LexerATNConfig struct {
*BaseATNConfig
lexerActionExecutor *LexerActionExecutor
Expand Down Expand Up @@ -241,6 +277,7 @@ func NewLexerATNConfig2(c *LexerATNConfig, state ATNState, context PredictionCon
}
}

//goland:noinspection GoUnusedExportedFunction
func NewLexerATNConfig1(state ATNState, alt int, context PredictionContext) *LexerATNConfig {
return &LexerATNConfig{BaseATNConfig: NewBaseATNConfig5(state, alt, context, SemanticContextNone)}
}
Expand Down Expand Up @@ -271,29 +308,29 @@ func (l *LexerATNConfig) Equals(other Collectable[ATNConfig]) bool {
if l == other {
return true
}
var othert, ok = other.(*LexerATNConfig)
var otherT, ok = other.(*LexerATNConfig)

if l == other {
return true
} else if !ok {
return false
} else if l.passedThroughNonGreedyDecision != othert.passedThroughNonGreedyDecision {
} else if l.passedThroughNonGreedyDecision != otherT.passedThroughNonGreedyDecision {
return false
}

var b bool

if l.lexerActionExecutor != nil {
b = !l.lexerActionExecutor.Equals(othert.lexerActionExecutor)
b = !l.lexerActionExecutor.Equals(otherT.lexerActionExecutor)
} else {
b = othert.lexerActionExecutor != nil
b = otherT.lexerActionExecutor != nil
}

if b {
return false
}

return l.BaseATNConfig.Equals(othert.BaseATNConfig)
return l.BaseATNConfig.Equals(otherT.BaseATNConfig)
}

func checkNonGreedyDecision(source *LexerATNConfig, target ATNState) bool {
Expand Down
Loading

0 comments on commit 95fd266

Please sign in to comment.