org.quasiliteral.astro
Interface AstroBuilder

All Known Subinterfaces:

QuasiBuilder

All Known Implementing Classes:

BaseBuilder, QBuilder, QuasiBuilderAdaptor, QuasiMetaBuilder

public interface AstroBuilder

Untamed: Used to build an Astro tree -- a tree that could represent the results of parsing a string according to a grammar.

Several arguments or return values below are declared 'Object', but pseudo-declared ":Args" in the javadoc comments. For these, the concrete type represents a list of AstroArgs, but the particular type used to represent the list depends on the type of builder, and should be documented in that builder's class comment.

Author:

Mark S. Miller

Method Summary

Astro	bag(Object args) Enabled: For supporting the curly bracket shorthand for terms that represent named fields or attributes.
Astro	composite(AstroTag tag, Object data, SourceSpan optSpan) Enabled: Makes an Astro whose tag is according to 'tag', and whose one argument is a leaf according to 'data'.
AstroSchema	getSchema() Enabled: Describes the grammar whose trees we're building.
Astro	leafChar(char data, SourceSpan optSpan) Enabled: A Unicode character
Astro	leafData(Object data, SourceSpan optSpan) Enabled: Makes a leaf (eg, a Token) representing literal data.
Astro	leafFloat64(double data, SourceSpan optSpan) Enabled: An IEEE double precision floating point number
Astro	leafInteger(BigInteger data, SourceSpan optSpan) Enabled: A precision unlimited integer
Astro	leafLong(long data, SourceSpan optSpan) Enabled: Note that leafLong's data is a subrange of leafInteger's.
Astro	leafString(String data, SourceSpan optSpan) Enabled: A String is just a bare twine
Astro	leafTag(AstroTag tag, SourceSpan optSource) Enabled: Makes a leaf (eg, a Token) not representing literal data, but just a token tag (token type indicator) as identified by 'tag'.
Astro	leafTwine(Twine data, SourceSpan optSpan) Enabled: A list of characters with optional (ie, if not bare) annotation about where (source position) these characters came from.
Object	list() Enabled: The empty args list
Object	list(AstroArg first) Enabled: The args list of one element.
Object	list(AstroArg first, AstroArg second) Enabled: The two-argument args list
Object	list(AstroArg first, AstroArg second, AstroArg third) Enabled: The three-argument args list
Object	list(AstroArg first, AstroArg second, AstroArg third, AstroArg fourth) Enabled: The four-argument args list
Astro	start(Astro top) Enabled: When we're finished building, this should be applied to the root node.
Astro	term(Astro functor) Enabled: For when a functor is used as a term without being followed by an explicit '()'.
Astro	term(Astro functor, Object args) Enabled: Returns an internal node (eg, an AST or Term), for which 'leaf' is the functor and 'args' are the arguments.
Astro	tuple(Object args) Enabled: For supporting the square bracket shorthand for terms that represent tuples.
Object	unpack(Astro litString) Enabled: Turns the string into a list of arguments representing each character as a character literal.
Object	with(Object list, AstroArg next) Enabled: Extend args list with an additional term, like a backwards cons.

Method Detail

getSchema

public AstroSchema getSchema()

Enabled: Describes the grammar whose trees we're building.

start

public Astro start(Astro top)

Enabled: When we're finished building, this should be applied to the root node.

It is normally just an identity function, but allows, for example, post-parsing cleanup. This is called by the parser, but not currently by the 'build' or 'qbuild' methods of other trees.

leafTag

public Astro leafTag(AstroTag tag,
                     SourceSpan optSource)

Enabled: Makes a leaf (eg, a Token) not representing literal data, but just a token tag (token type indicator) as identified by 'tag'.

The tag of the returned Astro should be according to the schema of this builder, even though the argument tag may be in a different schema. In this case, the correspondence is by tag name, rather than tag code.

composite

public Astro composite(AstroTag tag,
                       Object data,
                       SourceSpan optSpan)

Enabled: Makes an Astro whose tag is according to 'tag', and whose one argument is a leaf according to 'data'.

Is equivalent to:

     term(leafTag(typeCode, src),
          list(term(leafData(data, src))))
 

Exists to support legacy usage of Antlr Tokens, and in order to allow lexers, which wish to emit composites, to still emit only Tokens if allowed by the concrete builder.

leafData

public Astro leafData(Object data,
                      SourceSpan optSpan)

Enabled: Makes a leaf (eg, a Token) representing literal data.

Once coerced, this is equivalent to one of the following leaf* methods, which are provided for efficiency

leafChar

public Astro leafChar(char data,
                      SourceSpan optSpan)

Enabled: A Unicode character

leafLong

public Astro leafLong(long data,
                      SourceSpan optSpan)

Enabled: Note that leafLong's data is a subrange of leafInteger's.

The former is limited to 64 bits, and the latter isn't limited.

leafInteger

public Astro leafInteger(BigInteger data,
                         SourceSpan optSpan)

Enabled: A precision unlimited integer

leafFloat64

public Astro leafFloat64(double data,
                         SourceSpan optSpan)

Enabled: An IEEE double precision floating point number

leafString

public Astro leafString(String data,
                        SourceSpan optSpan)

Enabled: A String is just a bare twine

leafTwine

public Astro leafTwine(Twine data,
                       SourceSpan optSpan)

Enabled: A list of characters with optional (ie, if not bare) annotation about where (source position) these characters came from.

term

public Astro term(Astro functor,
                  Object args)

Enabled: Returns an internal node (eg, an AST or Term), for which 'leaf' is the functor and 'args' are the arguments.

'leaf' must be a leaf (have no arguments).

May be destructive of 'leaf' and 'args'.

When parsing the term syntax, this is called if the empty args list appears explicitly, but not if it's left out. When usad as a quasi-term pattern, this allows us to distinguish between a) 'term`@foo`' and b) 'term`@foo()`'. #a matches any term, while #b matches only zero-arity terms. Note that c) 'term`@foo(*)`' or d) 'term`@foo(@args*)`' will also match any term, but in these cases, 'foo' will only be bound to the functor of the specimen, not, as in #a, the specimen as a whole. (In #c, the arguments are matched and ignored. In #d, 'args' is bound to the list of arguments.)

Similarly, this allows us to distinguish between the expressions e) 'term`$foo`' and f) 'term`$foo()`'. On success, both #e and #f mean the same thing. But #f additionally required the term bound to 'foo' to be zero-arity, or an exception will be thrown.

Parameters:

args - :Args

term

public Astro term(Astro functor)

Enabled: For when a functor is used as a term without being followed by an explicit '()'.

For literal Astros, this is equivalent to 'term(functor, list())', but is separate for support of quasi-literals, and explained at term(Astro, Object).

tuple

public Astro tuple(Object args)

Enabled: For supporting the square bracket shorthand for terms that represent tuples.

This is equivalent to 'term(leafTag(".tuple."), args)', although an individual builder/schema may have its own idea about what tagName to use to mark a tuple.

bag

public Astro bag(Object args)

Enabled: For supporting the curly bracket shorthand for terms that represent named fields or attributes.

This is equivalent to 'term(leafTag(".bag."), args)', although an individual builder/schema may have its own idea about what tagName to use to mark a tuple.

list

public Object list()

Enabled: The empty args list

Returns:

:Args

list

public Object list(AstroArg first)

Enabled: The args list of one element.

May be destructive of that element, as when it's an AST.

Should be equivalent to 'with(list(), first)'

Returns:

:Args

list

public Object list(AstroArg first,
                   AstroArg second)

Enabled: The two-argument args list

list

public Object list(AstroArg first,
                   AstroArg second,
                   AstroArg third)

Enabled: The three-argument args list

list

public Object list(AstroArg first,
                   AstroArg second,
                   AstroArg third,
                   AstroArg fourth)

Enabled: The four-argument args list

with

public Object with(Object list,
                   AstroArg next)

Enabled: Extend args list with an additional term, like a backwards cons.

May be destructive of 'list' and 'next'

Parameters:

list - :Args

Returns:

:Args

unpack

public Object unpack(Astro litString)

Enabled: Turns the string into a list of arguments representing each character as a character literal.

Returns:

:Args