Enhanced C#
Language of your choice: library documentation
Nested classes | Public Types | Public static fields | Properties | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected fields | Protected static fields | List of all members
Loyc.Syntax.LNode Class Referenceabstract

All nodes in a Loyc syntax tree share this base class. More...


Source file:
Inheritance diagram for Loyc.Syntax.LNode:
Loyc.Syntax.ILNode Loyc.ICloneable< LNode > Loyc.IHasLocation Loyc.IHasValue< object > Loyc.Collections.INegListSource< LNode > Loyc.Syntax.IToLNode Loyc.IHasValue< object > Loyc.Collections.INegListSource< ILNode > Loyc.IHasLocation Loyc.Syntax.CallNode Loyc.Syntax.IdNode Loyc.Syntax.LiteralNode

Remarks

All nodes in a Loyc syntax tree share this base class.

Loyc defines only three types of nodes: simple symbols, literals, and calls.

This class provides access to all properties of all three types of nodes, in order to make this class easier to access from plain C#, and to avoid unnecessary downcasting in some cases.

Loyc nodes are always immutable, except for the 8-bit Style property which normally affects printing only.

Background information

EC# (enhanced C#) is intended to be the starting point of the Loyc (Language of your choice) project, which will be a family of programming languages that will share a common representation for the syntax tree and other compiler-related data structures.

Just as LLVM assembly has emerged as a nearly universal standard intermediate representation for back-ends, Loyc nodes are intended to be a universal intermediate representation for syntax trees, and Loyc will (eventually) include a generic set of tools for semantic analysis so that it provides a generic representation for front-ends.

EC#, then, will be the first language to use the Loyc syntax tree representation, known as the "Loyc tree" for short. Most syntax trees are very strongly typed, with separate data types for, say, variable declarations, binary operators, method calls, method declarations, unary operators, and so forth. Loyc, however, defines only three types of Nodes, and this one class provides access to all the parts of a node. There are several reasons for this design:

Loyc trees are comparable to LISP trees, except that "attributes" and position information are added to the tree, and the concept of a "list" is replaced with the concept of a "call", which I feel is a more intuitive notion in most programming languages that are not LISP.

Loyc's representation is both an blessing and a curse. The advantage is that Loyc nodes can be used for almost any purpose, perhaps even representing data instead of code in some cases. However, there is no guarantee that a given AST follows the structure prescribed by a particular programming language, unless a special validation step is performed after parsing. In this way, Loyc trees are similar to XML trees, only simpler.

Another major disadvantage is that it is more difficult to interpret a syntax tree correctly: you have to remember that a method definition has the structure #fn(return_type, name, args, body), so if "node" is a method definition then node.Args[2] represents the argument list, for example. In contrast, most compilers have an AST class called MethodDefinition or something, that provides properties such as Name and ReturnType. If EC# is ever done, however, aliases could help avoid this problem by providing a more friendly veneer over the raw nodes.

For optimization purposes, the node class is a class hierarchy, but most users should only use this class.

LNodes are "persistent" in the comp-sci sense, which means that they are immutable, that a subtree can be shared among multiple syntax trees, and that nodes do not know their own parents, which allows a single node to exist at multiple locations in a syntax tree. This makes manipulation of trees convenient, as there is no need to "detach" a node from one place, or duplicate it, before it can be inserted in another place.

The reimplementation

This implementation has been redesigned (in Subversion, the last version based on the old design is revision 289.) The core concept is the same as described in my blog at http://loyc-etc.blogspot.ca/2013/04/the-loyc-tree-and-prefix-notation-in-ec.html except that the concept of a "Head" has mostly been eliminated, although you might see it occasionally because it still has a meaning. The "head" of a node refers either to the Name of a symbol, the Value of a literal, or the Target of a call (i.e. the name of the method being called, which could be an arbitrarily complex node). In the original implementation, it was also possible to have a complex head (a head that is itself a node) even when the node was not a call; this situation was used to represent an expression in parenthesis.

This didn't quite feel right, so I changed it. Now, only calls can be "complex", and the head of a call (the method being called) is called the Target.

In the new version, there are explicitly three types of nodes: symbols, literals, and calls. There is no longer a Head property, instead there are three separate properties for the three kinds of heads, Name (a Symbol), Value (an Object), and Target (an LNode). Only call nodes have a Target, and only literal nodes have a Value. Identifier nodes have a Name, but I thought it would be useful for some call nodes to also have a Name, which is defined as the name of the Target if the Target is an identifier (if the Target is not a symbol, the call has no name.)

An expression in parenthesis is now represented by a call with the #trivia_inParens attribute; use LNodeExt.IsParenthesizedExpr to detect the parentheses.

The problems that motivated a redesign are described at http://loyc-etc.blogspot.ca/2013/05/redesigning-loyc-tree-code.html

One very common use of mutable nodes is building lists of statements, e.g. you might create an empty braced block or an empty loop and then add statements to the body of the block or loop. To do this without mutable nodes, create a mutable WList<LNode> instead and add statements there; once the list is finished, create the braced block or loop afterward. The new design stores arguments and attributes in VList<LNode> objects; you can instantly convert your WList to a VList by calling WListBase<LNode>.ToVList().

During the redesign I've decided on some small changes to the representation of certain expressions in EC#.

Important properties

The main properties of a node are

  1. Attrs: holds the attributes of the node, if any.
  2. Name: the name of an IdNode, or the name of the IdNode that is acting as the Target of a CallNode.
  3. Value: the value of a LiteralNode.
  4. Target: the target of a CallNode. It represents a method, macro, or special identifier that is being called.
  5. Args: holds the arguments to a CallNode, if any. Returns an empty list if the node does not have an argument list.
  6. Range: indicates the source file that the node came from and location in that source file.
  7. Style: an 8-bit flag value that is used as a hint to the node printer about how the node should be printed. For example, a hex literal like 0x10 has the NodeStyle.Alternate style to distinguish it from decimal literals such as 16. Custom display styles that do not fit in the Style property can be expressed with attributes.

The argument and attribute lists cannot be null, since they have type VList<Node> which is a struct.

LNode implements INegListSource<T>, so you can loop through all children of the node like this:

for (int i = node.Min; i <= node.Max; i++) {
LNode child = node[i];
}

You can also use foreach. The children are numbered like this:

LNode also provides Select(child => result) and ReplaceRecursive(child => result) methods which allows you to transform all children (Atrrs, Target and Args). Currently there is no Where(child => bool) method because it is not possible to remove the Target of an LNode (you can still use standard LINQ Where(), of course, but the result is not an LNode).

Note

The argument and attribute lists should never contain null nodes. Any code that puts nulls in Args or Attrs is buggy. However, we can't ensure nulls are not placed into VList<T> since it's a general-purpose data type, not specialized for LNode. There is code to ensure nulls are not placed in Args and Attrs (NoNulls), but only in debug builds, since null-checking is fairly expensive.

Nested classes

struct  PushedPrinter
 Returned by PushPrinter(ILNodePrinter). More...
 

Public Types

enum  CompareMode { Normal = 0, Styles = 1, IgnoreTrivia = 2 }
 
enum  ReplaceOpt { ReplaceOpt.ReplaceRoot = 1, ReplaceOpt.ProcessAttrs = 2, ReplaceOpt.Default = ReplaceRoot | ProcessAttrs }
 

Public static fields

static readonly EmptySourceFile SyntheticSource = new EmptySourceFile("<Synthetic Code>")
 
static readonly IdNode Missing = Id(CodeSymbols.Missing)
 The empty identifier, used to represent missing information. More...
 
static readonly LNode InParensTrivia = Id(CodeSymbols.TriviaInParens)
 Used by the quote {...} macro. More...
 

Properties

virtual SourceRange Range [get]
 Returns the location and range in source code of this node. More...
 
ISourceFile Source [get]
 Returns the source file (shortcut for Range.Source). More...
 
NodeStyle Style [get, set]
 Indicates the preferred style to use when printing the node to a text string. More...
 
NodeStyle BaseStyle [get, set]
 
virtual VList< LNodeAttrs [get]
 Returns the attribute list for this node. More...
 
virtual bool IsFrozen [get]
 Returns true if the node is immutable, and false if any part of it can be edited. Currently, mutable nodes are not implemented. More...
 
abstract LNodeKind Kind [get]
 Returns the LNodeKind: Symbol, Literal, or Call. More...
 
bool IsCall [get]
 
bool IsId [get]
 
bool IsLiteral [get]
 
abstract Symbol Name [get]
 Returns the Symbol if IsId. If this node is a call (IsCall) and Target.IsId is true, this property returns Target.Name. In all other cases, the name is GSymbol.Empty. Shall not return null. More...
 
bool HasSpecialName [get]
 Returns true if Name is a "special" name (i.e. starts with '#' or '\'' or '.' or any character below 48 in ASCII). More...
 
bool HasValue [get]
 
abstract object Value [get]
 Returns the value of a literal node, or NoValue.Value if this node is not a literal (IsLiteral is false). More...
 
abstract LNode Target [get]
 Returns the target of a method call, or null if IsCall is false. The target can be a symbol with no name (GSymbol.Empty) to represent a parenthesized expression, if there is one argument. More...
 
abstract VList< LNodeArgs [get]
 Returns the argument list of this node. Always empty when IsCall==false. More...
 
static ILNodePrinter Printer [get, set]
 Gets or sets the default node printer on the current thread, which controls how nodes are serialized to text by default. More...
 
virtual object TriviaValue [get]
 Gets the value of Args[0].Value, if Args[0] exists; otherwise, returns NoValue.Value. More...
 
int ArgCount [get]
 
int AttrCount [get]
 
bool HasAttrs [get]
 
bool IsTrivia [get]
 
int Min [get]
 
virtual int Max [get]
 
LNode this[int index] [get]
 
int Count [get]
 
- Properties inherited from Loyc.Syntax.ILNode
LNodeKind Kind [get]
 
Symbol Name [get]
 
LNode Target [get]
 
SourceRange Range [get]
 
NodeStyle Style [get, set]
 
- Properties inherited from Loyc.IHasValue< object >
Value [get]
 
- Properties inherited from Loyc.Collections.INegListSource< ILNode >
int Min [get]
 Returns the minimum valid index in the collection. More...
 
int Max [get]
 Returns the maximum valid index in the collection. More...
 
this[int index] [get]
 Gets the item at the specified index. More...
 
- Properties inherited from Loyc.IHasLocation
object Location [get]
 
- Properties inherited from Loyc.Collections.INegListSource< LNode >
int Min [get]
 Returns the minimum valid index in the collection. More...
 
int Max [get]
 Returns the maximum valid index in the collection. More...
 
this[int index] [get]
 Gets the item at the specified index. More...
 

Public Member Functions

LNode SetBaseStyle (NodeStyle s)
 
LNode SetStyle (NodeStyle s)
 
virtual LNode WithName (Symbol name)
 Creates a node with a new value for Name. More...
 
abstract LiteralNode WithValue (object value)
 Creates a new literal node with a different Value than the current literal node. More...
 
virtual CallNode WithTarget (LNode target)
 
virtual CallNode WithTarget (Symbol name)
 
abstract CallNode WithArgs (VList< LNode > args)
 Creates a Node with a new argument list. If this node is not a call, a new node is created using this node as its target. Otherwise, the existing argument list is replaced. More...
 
virtual CallNode With (LNode target, VList< LNode > args)
 Creates a CallNode with the same attributes and Range, but a different target and argument list. If the current node is not a CallNode, it becomes one (the Range, Style and attributes of the current node are kept, but the Kind, Value, and Name are discarded.) More...
 
virtual CallNode With (Symbol target, VList< LNode > args)
 Creates a CallNode with the same attributes and Range, but a different target and argument list. If the current node is not a CallNode, it becomes one (the Range, Style and attributes of the current node are kept, but the Kind, Value, and Name are discarded.) More...
 
CallNode With (Symbol target, params LNode[] args)
 
abstract LNode Clone ()
 Creates a copy of the node. Since nodes are immutable, there is little reason for an end-user to call this, but Clone() is used internally as a helper method by the WithXyz() methods. More...
 
LNode WithRange (SourceRange range)
 
virtual LNode WithRange (int startIndex, int endIndex)
 
LNode WithStyle (NodeStyle style)
 
virtual LNode With (SourceRange range, NodeStyle style)
 
virtual LNode WithoutAttrs ()
 
abstract LNode WithAttrs (VList< LNode > attrs)
 
LNode WithAttrs (params LNode[] attrs)
 
CallNode WithArgs (params LNode[] args)
 
LNode PlusAttr (LNode attr)
 
LNode PlusAttrs (IEnumerable< LNode > attrs)
 
LNode PlusAttrs (params LNode[] attrs)
 
LNode PlusAttrs (VList< LNode > attrs)
 
LNode PlusAttrsBefore (VList< LNode > attrs)
 
LNode PlusAttrsBefore (params LNode[] attrs)
 
LNode PlusAttrBefore (LNode attr)
 
LNode PlusArg (LNode arg)
 
LNode PlusArgs (VList< LNode > args)
 
LNode PlusArgs (IEnumerable< LNode > args)
 
LNode PlusArgs (params LNode[] args)
 
LNode WithArgChanged (int index, Func< LNode, LNode > selector)
 
LNode WithArgChanged (int index, LNode newValue)
 
LNode WithAttrChanged (int index, LNode newValue)
 
LNode WithChildChanged (int index, LNode newValue)
 
abstract void Call (LNodeVisitor visitor)
 
abstract void Call (ILNodeVisitor visitor)
 
virtual string Print (ParsingMode mode=null, ILNodePrinterOptions options=null)
 
override string ToString ()
 
virtual bool Equals (ILNode other, CompareMode mode)
 Compares two nodes for structural equality. Two nodes are considered equal if they have the same kind, the same name, the same value, the same arguments, and the same attributes. More...
 
bool Equals (LNode other)
 
bool Equals (ILNode other)
 
override bool Equals (object other)
 
override int GetHashCode ()
 Gets the hash code based on the structure of the tree. More...
 
bool HasPAttrs ()
 
VList< LNodePAttrs ()
 
virtual bool Calls (Symbol name, int argCount)
 Returns true if Name == name and Max + 1 == argCount (which implies Kind == LNodeKind.Call if argCount != -1). More...
 
virtual bool Calls (string name, int argCount)
 
virtual bool Calls (Symbol name)
 
virtual bool Calls (string name)
 
virtual bool CallsMin (Symbol name, int minArgCount)
 Returns true if this is a call with the specified name and the specified minimum number of arguments. More...
 
virtual bool CallsMin (string name, int minArgCount)
 Returns true if this is a call with the specified name and the specified minimum number of arguments. More...
 
virtual bool HasSimpleHead ()
 Returns true if this is not a call, or if the call's Target is an Id or a Literal. More...
 
virtual bool HasSimpleHeadWithoutPAttrs ()
 Returns true if this is not a call, or if the call's Target is an Id or a Literal, and the Target has only trivia attributes. More...
 
virtual LNode WithAttrs (Func< LNode, Maybe< LNode >> selector)
 
virtual LNode WithArgs (Func< LNode, Maybe< LNode >> selector)
 
virtual bool IsIdWithoutPAttrs ()
 
virtual bool IsIdWithoutPAttrs (Symbol name)
 
virtual bool IsIdNamed (Symbol name)
 
virtual bool IsIdNamed (string name)
 
CallNode WithSplicedArgs (int index, LNode from, Symbol listName)
 
CallNode WithSplicedArgs (LNode from, Symbol listName)
 
LNode WithSplicedAttrs (int index, LNode from, Symbol listName)
 
LNode WithSplicedAttrs (LNode from, Symbol listName)
 
NestedEnumerable< DescendantsFrame, LNodeDescendants (NodeScanMode mode=NodeScanMode.YieldAllChildren)
 
NestedEnumerable< DescendantsFrame, LNodeDescendantsAndSelf ()
 
LNode TryGet (int index, out bool fail)
 
IRange< LNodeSlice (int start, int count=int.MaxValue)
 
IEnumerator< LNodeGetEnumerator ()
 
virtual LNode Select (Func< LNode, Maybe< LNode >> selector, ReplaceOpt options=ReplaceOpt.ProcessAttrs)
 Transforms the Target, parameters, and optionally the attributes of an LNode, returning another LNode of the same Kind. If the selector makes no changes, Select() returns this. More...
 
Maybe< LNodeReplaceRecursive (Func< LNode, Maybe< LNode >> matcher, ReplaceOpt options=ReplaceOpt.Default)
 Performs a recursive find-and-replace operation, by attempting to replace each child (among Attrs, Target, Args) using the specified selector. This method can also be used for simple searching, by giving a selector that always returns null. More...
 
LNode ReplaceRecursive (Func< LNode, LNode > matcher, ReplaceOpt options=ReplaceOpt.Default)
 
- Public Member Functions inherited from Loyc.Collections.INegListSource< ILNode >
TryGet (int index, out bool fail)
 Gets the item at the specified index, and does not throw an exception on failure. More...
 
IRange< T > Slice (int start, int count=int.MaxValue)
 Returns a sub-range of this list. More...
 
- Public Member Functions inherited from Loyc.ICloneable< LNode >
Clone ()
 
- Public Member Functions inherited from Loyc.Collections.INegListSource< LNode >
TryGet (int index, out bool fail)
 Gets the item at the specified index, and does not throw an exception on failure. More...
 
IRange< T > Slice (int start, int count=int.MaxValue)
 Returns a sub-range of this list. More...
 

Static Public Member Functions

static IdNode Id (Symbol name, LNode prototype)
 
static IdNode Id (string name, LNode prototype)
 
static IdNode Id (VList< LNode > attrs, Symbol name, LNode prototype)
 
static IdNode Id (VList< LNode > attrs, string name, LNode prototype)
 
static LiteralNode Literal (object value, LNode prototype)
 
static LiteralNode Literal (VList< LNode > attrs, object value, LNode prototype)
 
static CallNode Call (Symbol name, LNode prototype)
 
static CallNode Call (LNode target, LNode prototype)
 
static CallNode Call (Symbol name, VList< LNode > args, LNode prototype)
 
static CallNode Call (LNode target, VList< LNode > args, LNode prototype)
 
static CallNode Call (VList< LNode > attrs, Symbol name, VList< LNode > args, LNode prototype)
 
static CallNode Call (VList< LNode > attrs, LNode target, VList< LNode > args, LNode prototype)
 
static CallNode Trivia (Symbol name, object value, LNode prototype)
 
static IdNode Id (Symbol name, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static IdNode Id (string name, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static IdNode Id (VList< LNode > attrs, Symbol name, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static IdNode Id (VList< LNode > attrs, string name, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static LiteralNode Literal (object value, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static LiteralNode Literal (VList< LNode > attrs, object value, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (Symbol name, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (Symbol name, SourceRange range, int targetStart, int targetEnd, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (LNode target, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (Symbol name, VList< LNode > args, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (Symbol name, VList< LNode > args, SourceRange range, int targetStart, int targetEnd, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (LNode target, VList< LNode > args, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (VList< LNode > attrs, Symbol name, VList< LNode > args, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (VList< LNode > attrs, LNode target, VList< LNode > args, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static CallNode Trivia (Symbol name, object value, SourceRange range, NodeStyle style=NodeStyle.Default)
 
static IdNode Id (Symbol name, ISourceFile file=null)
 
static IdNode Id (string name, ISourceFile file=null)
 
static IdNode Id (VList< LNode > attrs, Symbol name, ISourceFile file=null)
 
static IdNode Id (VList< LNode > attrs, string name, ISourceFile file=null)
 
static LiteralNode Literal (object value, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static LiteralNode Literal (VList< LNode > attrs, object value, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (Symbol name, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (LNode target, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (Symbol name, VList< LNode > args, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (LNode target, VList< LNode > args, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (VList< LNode > attrs, Symbol name, VList< LNode > args, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static CallNode Call (VList< LNode > attrs, LNode target, VList< LNode > args, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static CallNode Trivia (Symbol name, object value, ISourceFile file=null, NodeStyle style=NodeStyle.Default)
 
static VList< LNodeList ()
 
static VList< LNodeList (LNode item_0)
 
static VList< LNodeList (LNode item_0, LNode item_1)
 
static VList< LNodeList (params LNode[] list)
 
static VList< LNodeList (IEnumerable< LNode > list)
 
static VList< LNodeList (VList< LNode > list)
 
static bool IsSpecialName (string name)
 Returns true if name is considered a "special" name that starts with any character below 48 in ASCII, such as '#', '\'', and '.'. More...
 
static bool IsSpecialName (Symbol name)
 
static PushedPrinter PushPrinter (ILNodePrinter printer)
 Helps you change printers temporarily. Usage in C#: using (LNode.PushPrinter(myPrinter)) { ... } More...
 
static bool Equals (VList< LNode > a, VList< LNode > b, CompareMode mode=CompareMode.Normal)
 Compares two lists of nodes for structural equality. More...
 
static bool Equals (ILNode a, ILNode b, CompareMode mode=CompareMode.Normal)
 
static LNode MergeLists (LNode node1, LNode node2, Symbol listName)
 Some CallNodes are used to represent lists. This method merges two nodes, forming or appending a list (see remarks). More...
 
static LNode MergeBinary (LNode node1, LNode node2, Symbol binaryOpName)
 Combines two nodes using a binary operator or function. More...
 

Protected Member Functions

 LNode (LNode prototype)
 
 LNode (SourceRange range, NodeStyle style)
 

Static Protected Member Functions

static void NoNulls (VList< LNode > list, string propName)
 

Protected fields

RangeAndStyle RAS
 

Protected static fields

static readonly CallNode EmptySplice = Call(CodeSymbols.Splice)
 

Member Enumeration Documentation

Enumerator
ReplaceRoot 

When calling n.ReplaceRecursive, specifies that the selector should be called on n itself, not just its children.

ProcessAttrs 

When calling ReplaceRecursive(Func<LNode, Maybe<LNode>>, ReplaceOpt) or Select(Func<LNode, Maybe<LNode>>, ReplaceOpt), specifies that attributes should be processed rather than left unchanged.

Default 

ReplaceRoot and ProcessAttrs

Member Function Documentation

virtual bool Loyc.Syntax.LNode.Calls ( Symbol  name,
int  argCount 
)
inlinevirtual
virtual bool Loyc.Syntax.LNode.CallsMin ( Symbol  name,
int  minArgCount 
)
inlinevirtual

Returns true if this is a call with the specified name and the specified minimum number of arguments.

Implements Loyc.Syntax.ILNode.

Reimplemented in Loyc.Syntax.CallNode.

Referenced by Loyc.LLParserGenerator.CodeGenHelperBase.CallRule(), Loyc.Ecs.Parser.EcsTriviaInjector.DoneAttaching(), Loyc.Ecs.EcsValidators.KeyNameComponentOf(), and Loyc.LLParserGenerator.CodeGenHelperBase.VisitInput().

virtual bool Loyc.Syntax.LNode.CallsMin ( string  name,
int  minArgCount 
)
inlinevirtual

Returns true if this is a call with the specified name and the specified minimum number of arguments.

Reimplemented in Loyc.Syntax.CallNode.

abstract LNode Loyc.Syntax.LNode.Clone ( )
pure virtual

Creates a copy of the node. Since nodes are immutable, there is little reason for an end-user to call this, but Clone() is used internally as a helper method by the WithXyz() methods.

Implemented in Loyc.Syntax.CallNode, Loyc.Syntax.LiteralNode, and Loyc.Syntax.IdNode.

static bool Loyc.Syntax.LNode.Equals ( VList< LNode a,
VList< LNode b,
CompareMode  mode = CompareMode.Normal 
)
inlinestatic

Compares two lists of nodes for structural equality.

Parameters
modeWhether to pay attention to Style and trivia attributes

Position information is not compared.

References Loyc.Collections.VList< T >.Pop().

Referenced by Loyc.LLParserGenerator.AndPred.Clone(), Loyc.LLParserGenerator.GeneralCodeGenHelper.CodeToTerminalPred(), and Loyc.LLParserGenerator.CodeGenHelperBase.VisitInput().

virtual bool Loyc.Syntax.LNode.Equals ( ILNode  other,
CompareMode  mode 
)
inlinevirtual

Compares two nodes for structural equality. Two nodes are considered equal if they have the same kind, the same name, the same value, the same arguments, and the same attributes.

Parameters
modeWhether to pay attention to Style and trivia attributes

Position information (Range) is not compared.

References Loyc.Syntax.LNode.Equals().

Referenced by Loyc.Syntax.LNode.Equals().

override int Loyc.Syntax.LNode.GetHashCode ( )
inline

Gets the hash code based on the structure of the tree.

If the tree is large, less than the entire tree is scanned to produce the hashcode (in the absolute worst case, about 4000 nodes are examined, but usually it is less than 100).

References Loyc.Syntax.LNode.GetHashCode(), and Loyc.Collections.VList< T >.SmartWhere().

Referenced by Loyc.Syntax.LNode.GetHashCode().

virtual bool Loyc.Syntax.LNode.HasSimpleHead ( )
inlinevirtual

Returns true if this is not a call, or if the call's Target is an Id or a Literal.

Reimplemented in Loyc.Syntax.CallNode.

virtual bool Loyc.Syntax.LNode.HasSimpleHeadWithoutPAttrs ( )
inlinevirtual

Returns true if this is not a call, or if the call's Target is an Id or a Literal, and the Target has only trivia attributes.

Reimplemented in Loyc.Syntax.CallNode.

static bool Loyc.Syntax.LNode.IsSpecialName ( string  name)
inlinestatic

Returns true if name is considered a "special" name that starts with any character below 48 in ASCII, such as '#', '\'', and '.'.

This returns false for the empty string or null.

In order to keep the check trivially simple, this returns true for '$' even though it is not special in some languages (e.g. JavaScript).

Letters, underscores, digits, and some punctuation do not count as special. The full list of specials is ! " # $ % & ' ( ) * + , - . / plus the space character and the control characters.

References Loyc.Symbol.Name.

Referenced by Loyc.Syntax.LNodeExt.GetCaptureIdentifier(), and Loyc.Syntax.Les.Les3PrettyPrinter.Les3PrettyPrinter().

static LNode Loyc.Syntax.LNode.MergeBinary ( LNode  node1,
LNode  node2,
Symbol  binaryOpName 
)
inlinestatic

Combines two nodes using a binary operator or function.

Parameters
node1First node, list, or null.
node2Second node, list, or null.
binaryOpNameBinary operator to use when the nodes are not null.
Returns
If either node1 or node2 is null, this method returns the other node (node1 ?? node2), otherwise the nodes are joined with the specified operator.

References Loyc.Syntax.LNode.Range, Loyc.Collections.INegListSource< out out T >.Slice(), Loyc.Syntax.IToLNode.ToLNode(), and Loyc.Collections.INegListSource< out out T >.TryGet().

static LNode Loyc.Syntax.LNode.MergeLists ( LNode  node1,
LNode  node2,
Symbol  listName 
)
inlinestatic

Some CallNodes are used to represent lists. This method merges two nodes, forming or appending a list (see remarks).

Parameters
node1First node, list, or null.
node2Second node, list, or null.
listNameThe Name used to detect whether a node is a list (typically "#splice"). Any other name is considered a normal call, not a list. If this method creates a list from two non- lists, this parameter specifies the Name that the list will have.
Returns
The merged list.

The order of the data is retained (i.e. the data in node1 is inserted before the data in node2).

  • If either node1 or node2 is null, this method returns the other (node1 ?? node2).
  • If both node1 and node2 are lists, this method merges the list into a single list by appending node2's arguments at the end of node1. The attributes of node1 are kept and those of node2 are discarded.
  • If one of the nodes is a list and the other is not, the non-list is inserted into the list's Args.
  • If neither node is a list, a list is created with both nodes as its two Args.
See also
LNodeExt.WithSpliced

References Loyc.Syntax.LNode.Calls().

Referenced by Loyc.Syntax.LNodeExt.MatchesPattern(), and Loyc.LLParserGenerator.LLParserGenerator.GenerateCodeVisitor.Visit().

static PushedPrinter Loyc.Syntax.LNode.PushPrinter ( ILNodePrinter  printer)
inlinestatic

Helps you change printers temporarily. Usage in C#: using (LNode.PushPrinter(myPrinter)) { ... }

For example, to switch to the EC# printer, use using (LNode.PushPrinter(EcsNodePrinter.Printer)) { ... }. This changes the default printer. If you don't want to change the default printer, please invoke the printer directly:

var sb = new StringBuilder();
EcsNodePrinter.Printer(node, sb, MessageSink.Trace);

Referenced by Loyc.LLParserGenerator.Program.QuickRun().

Maybe<LNode> Loyc.Syntax.LNode.ReplaceRecursive ( Func< LNode, Maybe< LNode >>  matcher,
ReplaceOpt  options = ReplaceOpt.Default 
)
inline

Performs a recursive find-and-replace operation, by attempting to replace each child (among Attrs, Target, Args) using the specified selector. This method can also be used for simple searching, by giving a selector that always returns null.

Parameters
matcherThis method is called for each descendant, and optionally the root node. If the selector returns a node, the new node replaces the node that was passed to selector and the children of the new node are ignored. If the selector returns null, children of the child are scanned recursively. If the selector returns Maybe{LNode}.NoValue then the current node is deleted if it is an argument or attribute. If the current node is a target, it cannot be deleted, so it is replaced with #splice() which, by convention, represents an empty list. If you delete the root node then this method returns Maybe{LNode}.NoValue.
optionsOptions, see ReplaceOpt.
Returns
The new node produced after all replacements have occurred.

If replaceFunc always returns null (or if replaceRoot is false and the root has no children), ReplaceRecursive returns this.

References Loyc.Syntax.LNode.Value.

Referenced by Loyc.LLParserGenerator.LLParserGenerator.GenerateCodeVisitor.Visit().

virtual LNode Loyc.Syntax.LNode.Select ( Func< LNode, Maybe< LNode >>  selector,
ReplaceOpt  options = ReplaceOpt.ProcessAttrs 
)
inlinevirtual

Transforms the Target, parameters, and optionally the attributes of an LNode, returning another LNode of the same Kind. If the selector makes no changes, Select() returns this.

The selector is not allowed to return null, but it can return NoValue.Value to delete a parameter or target. If the current node is a target, it cannot be deleted, so it is replaced with #splice() which, by convention, represents an empty list. If you're wondering why we don't use null for deletions, it is because the functionality of this method is actually implemented by VList<T>.WhereSelect(Func<T, Maybe<T>>); since T could be a value type, that method cannot use null as a signal to delete items from the collection.

It is not possible to delete the Target of a call, and if the selector returns NoValue.Value for the Target, the target is replaced with an empty call to #splice().

Reimplemented in Loyc.Syntax.CallNode.

Referenced by Loyc.LLParserGenerator.GeneralCodeGenHelper.GenerateMatchExpr().

virtual CallNode Loyc.Syntax.LNode.With ( LNode  target,
VList< LNode args 
)
inlinevirtual

Creates a CallNode with the same attributes and Range, but a different target and argument list. If the current node is not a CallNode, it becomes one (the Range, Style and attributes of the current node are kept, but the Kind, Value, and Name are discarded.)

Referenced by Loyc.LLPG.Macros.LllpgMacro(), and Loyc.Syntax.CallNode.Select().

virtual CallNode Loyc.Syntax.LNode.With ( Symbol  target,
VList< LNode args 
)
inlinevirtual

Creates a CallNode with the same attributes and Range, but a different target and argument list. If the current node is not a CallNode, it becomes one (the Range, Style and attributes of the current node are kept, but the Kind, Value, and Name are discarded.)

abstract CallNode Loyc.Syntax.LNode.WithArgs ( VList< LNode args)
pure virtual

Creates a Node with a new argument list. If this node is not a call, a new node is created using this node as its target. Otherwise, the existing argument list is replaced.

Parameters
argsNew argument list

Implemented in Loyc.Syntax.CallNode, Loyc.Syntax.LiteralNode, and Loyc.Syntax.IdNode.

Referenced by Loyc.LLParserGenerator.Rule.CreateMethod(), Loyc.LLParserGenerator.CodeGenHelperBase.CreateTryWrapperForRecognizer(), and Loyc.LLParserGenerator.Rule.GetMethodSignature().

virtual LNode Loyc.Syntax.LNode.WithName ( Symbol  name)
inlinevirtual

Creates a node with a new value for Name.

If IsId, the Name is simply changed. If IsCall, this method returns the equivalent of WithTarget(Target.WithName(name)) (which may be optimized for the particular call type). If IsLiteral, the Kind changes to LNodeKind.Id in order to set the name.

Reimplemented in Loyc.Syntax.CallNode, and Loyc.Syntax.IdNode.

abstract LiteralNode Loyc.Syntax.LNode.WithValue ( object  value)
pure virtual

Creates a new literal node with a different Value than the current literal node.

Exceptions
InvalidOperationExceptionThe node was not a literal already.

Implemented in Loyc.Syntax.CallNode, Loyc.Syntax.LiteralNode, and Loyc.Syntax.IdNode.

Member Data Documentation

readonly LNode Loyc.Syntax.LNode.InParensTrivia = Id(CodeSymbols.TriviaInParens)
static

Used by the quote {...} macro.

readonly IdNode Loyc.Syntax.LNode.Missing = Id(CodeSymbols.Missing)
static

The empty identifier, used to represent missing information.

Referenced by Loyc.LLParserGenerator.Pred.ChooseGotoLabel().

Property Documentation

abstract VList<LNode> Loyc.Syntax.LNode.Args
get
virtual VList<LNode> Loyc.Syntax.LNode.Attrs
get
bool Loyc.Syntax.LNode.HasSpecialName
get

Returns true if Name is a "special" name (i.e. starts with '#' or '\'' or '.' or any character below 48 in ASCII).

Note that this property returns false for the empty identifier @``.

virtual bool Loyc.Syntax.LNode.IsFrozen
get

Returns true if the node is immutable, and false if any part of it can be edited. Currently, mutable nodes are not implemented.

Debugger-hidden until such time as mutable nodes actually exist.

abstract LNodeKind Loyc.Syntax.LNode.Kind
get

Returns the LNodeKind: Symbol, Literal, or Call.

Referenced by Loyc.Syntax.LNodeExt.MatchesPattern().

abstract Symbol Loyc.Syntax.LNode.Name
get

Returns the Symbol if IsId. If this node is a call (IsCall) and Target.IsId is true, this property returns Target.Name. In all other cases, the name is GSymbol.Empty. Shall not return null.

Examples (using C#/LES syntax):

Expression   Kind    Name (blank if empty)
hello        Id      hello
#if         Id      #if
Foo(x, y)    Call    Foo
x += y       Call    +=
x.Foo(y)     Call    
5.0          Literal 

Referenced by LeMP.Compiler.AddStdMacros(), Loyc.Syntax.LNodeExt.AsLNode(), Loyc.LLParserGenerator.GeneralCodeGenHelper.CodeToTerminalPred(), Loyc.Ecs.EcsValidators.IsPrintableTypeParam(), Loyc.Ecs.EcsValidators.KeyNameComponentOf(), Loyc.LLPG.Macros.LllpgMacro(), Loyc.Syntax.LNodeExt.MatchesPattern(), Loyc.Ecs.EcsValidators.MethodDefinitionKind(), Loyc.Ecs.Parser.EcsPreprocessor.NextToken(), Loyc.Ecs.EcsValidators.SpaceDefinitionKind(), and Loyc.Syntax.LNodeFactory.Trivia().

ILNodePrinter Loyc.Syntax.LNode.Printer
staticgetset

Gets or sets the default node printer on the current thread, which controls how nodes are serialized to text by default.

The LES printer is the default, and will be used if you try to set this property to null.

Referenced by LeMP.Compiler.CompleteInputOutputOptions().

virtual SourceRange Loyc.Syntax.LNode.Range
get

Returns the location and range in source code of this node.

A parser should record a sufficiently wide range for each parent node, such that all children are fully contained within the range. However, this is not an invariant; macros can splice together syntax trees from different source files or add synthetic nodes, so that the parent range does not necessarily include all child ranges. (In fact, in general it is impossible to ensure that parent ranges include child ranges because a parent can only specify a single source file, while children can come from several source files.)

Referenced by Loyc.LLParserGenerator.Pred.ChooseGotoLabel(), Loyc.Ecs.Parser.EcsTriviaInjector.DoneAttaching(), Loyc.LLPG.Macros.LllpgMacro(), Loyc.Syntax.LNode.MergeBinary(), Loyc.Ecs.Parser.EcsPreprocessor.NextToken(), Loyc.Syntax.AbstractTriviaInjector< Token >.RunCore(), Loyc.Syntax.LNodeFactory.Trivia(), and Loyc.LLParserGenerator.LLParserGenerator.GenerateCodeVisitor.Visit().

ISourceFile Loyc.Syntax.LNode.Source
get

Returns the source file (shortcut for Range.Source).

Referenced by Loyc.LLPG.Macros.LllpgMacro().

NodeStyle Loyc.Syntax.LNode.Style
getset

Indicates the preferred style to use when printing the node to a text string.

The Style is an 8-bit value that acts as a hint to the node printer about how the node should be printed. Custom display styles that do not fit in the Style property can be expressed with special attributes that have a Name starting with "#trivia_". ("#trivia" attributes, which are also used to store comments in the syntax tree, are not printed like normal attributes and are normally ignored if the node printer does not specifically recognize them.)

Referenced by Loyc.LLParserGenerator.Rule.GetMethodSignature(), Loyc.LLPG.Macros.LllpgMacro(), and Loyc.Ecs.EcsNodePrinter.PrintECSharp().

abstract LNode Loyc.Syntax.LNode.Target
get

Returns the target of a method call, or null if IsCall is false. The target can be a symbol with no name (GSymbol.Empty) to represent a parenthesized expression, if there is one argument.

Referenced by Loyc.Ecs.Parser.EcsTriviaInjector.DoneAttaching(), Loyc.Ecs.EcsValidators.KeyNameComponentOf(), Loyc.LLPG.Macros.LllpgMacro(), Loyc.Syntax.LNodeExt.MatchesPattern(), and Loyc.Syntax.CallNode.Select().

virtual object Loyc.Syntax.LNode.TriviaValue
get

Gets the value of Args[0].Value, if Args[0] exists; otherwise, returns NoValue.Value.

"Trivia nodes" are used to efficiently represent the value of trivia and non-tree Lexing.Tokens; they can be created by calling the LNode.Trivia function. Since an LNode is not allowed to have both a Name and a Value (as there is no syntax in LES or EC# for such a node), a trivia node pretends that there is an argument list with one item, and that one item is always a literal whose Value is the value stored in the trivia node. Thus, a token node is printed out as TokenType(Value) where Value is some literal.

If you suspect you're dealing with a trivia node, it is wasteful to actually call node.Args[0].Value since this causes a temporary token list to be allocated. Instead you should use this property, which returns the token value without allocating memory. Of course, if this property is called on a non-trivia node, it simply returns Args[0].Value.

abstract object Loyc.Syntax.LNode.Value
get