Enhanced C#
Language of your choice: library documentation
Properties | Public Member Functions | List of all members
LeMP.IMacroContext Interface Reference

This interface provides services offered by the lexical macro processor (LeMP). More...


Source file:
Inheritance diagram for LeMP.IMacroContext:
Loyc.IMessageSink< in in TContext >

Remarks

This interface provides services offered by the lexical macro processor (LeMP).

Macros receive this as their second argument (see LexicalMacro)

Properties

IMessageSink Sink [get]
 Returns the message sink, used for writing warnings and errors. More...
 
IDictionary< object, object > ScopedProperties [get]
 Returns a table of "properties" (arbitrary key-value pairs) that exist in the current scope. This dictionary is "persistent" in the computer science sense; any changes to these properties affect only the current scope and child scopes. When the current scope ends, the set of properties that existed in the parent scope are restored. More...
 
IReadOnlyList< LNodeAncestors [get]
 Returns a list of ancestors of the current node being processed. Normally Ancestors[0] is a #splice node that contains a list of all top-level statements in the file, and Ancestors.Last() is the current node. More...
 
LNode Parent [get]
 Gets the logical parent of the current node, which is Ancestors[Ancestors.Count - 2], or null if the current node is the root node. More...
 
IListSource< LNodeRemainingNodes [get]
 Gets a list of the remaining nodes (arguments/statements or attributes) after this point in the code stream. More...
 
bool IsAttribute [get]
 Returns true if the current node is in the attribute list of its immediate parent. More...
 
bool IsTarget [get]
 Returns true if the current node is the target of its parent call node. More...
 
bool DropRemainingNodes [get, set]
 Gets or sets a value that indicates whether to drop all remaining node after the current one when the current macro returns. This property has no effect if the macro rejects the input by returning null. More...
 
IReadOnlyDictionary< Symbol, VList< MacroInfo > > AllKnownMacros [get]
 Gets information about all macros registered with the macro processor, including macros whose namespace has not been opened with #importMacros. More...
 
int NextTempCounter [get]
 Gets the next number to use as a suffix for temporary variables (without incrementing it). More...
 
ICollection< SymbolOpenMacroNamespaces [get]
 Gets the list of namespaces that are being searched for macros in the current scope. You can modify this collection. More...
 

Public Member Functions

LNode PreProcessChildren ()
 Applies all available macros to the current node's children and returns the result. More...
 
LNodeList PreProcess (LNodeList input, bool asRoot=false, bool resetOpenNamespaces=false, bool resetProperties=false, bool areAttributes=false)
 Runs the macro processor on the specified node(s). More...
 
LNode PreProcess (LNode input, bool asRoot=false, bool resetOpenNamespaces=false, bool resetProperties=false, bool isTarget=false)
 
int IncrementTempCounter ()
 Gets the next number to use as a suffix for temporary variables, then increments it. More...
 
void RegisterMacro (MacroInfo macroInfo)
 Registers a new macro in the current scope. More...
 
- Public Member Functions inherited from Loyc.IMessageSink< in in TContext >
void Write (Severity level, TContext context, [Localizable] string format)
 Writes a message to the target that this object represents. More...
 
void Write (Severity level, TContext context, [Localizable] string format, object arg0, object arg1=null)
 
void Write (Severity level, TContext context, [Localizable] string format, params object[] args)
 
bool IsEnabled (Severity level)
 Returns true if messages of the specified type will actually be printed, or false if Write(type, ...) has no effect. More...
 

Member Function Documentation

◆ IncrementTempCounter()

int LeMP.IMacroContext.IncrementTempCounter ( )

Gets the next number to use as a suffix for temporary variables, then increments it.

◆ PreProcess()

LNodeList LeMP.IMacroContext.PreProcess ( LNodeList  input,
bool  asRoot = false,
bool  resetOpenNamespaces = false,
bool  resetProperties = false,
bool  areAttributes = false 
)

Runs the macro processor on the specified node(s).

Parameters
inputThe node or node list to process.
asRootIf false, the nodes are treated as children of the current node (using the current list of ancestors as a basis); if true, the list of parent nodes is cleared.
resetOpenNamespacesIf false, the set of open namespaces stays the same; if true it is cleared to the set of pre-opened namespaces (MacroProcessor.PreOpenedNamespaces) and macros defined with RegisterMacro are forgotten.
resetPropertiesIf true, ScopedProperties is reset to contain only predefined properties.
areAttributesThis parameter controls the value of IsAttribute while the items in the list are processed.

The node(s)

◆ PreProcessChildren()

LNode LeMP.IMacroContext.PreProcessChildren ( )

Applies all available macros to the current node's children and returns the result.

This method only processes children once. If this method is called again for the same node, it returns a cached result.

If the currently-running macro fails, the result may be thrown away and the effort of processing the children will have been wasted. If the macro succeeds, and its LexicalMacroAttribute uses the default MacroMode.Normal processing mode, the children will (normally) be processed again after the macro returns.

◆ RegisterMacro()

void LeMP.IMacroContext.RegisterMacro ( MacroInfo  macroInfo)

Registers a new macro in the current scope.

Parameters
macroInfoInformation about the macro

The macro will be forgotten at the end of the current scope (regardless of which namespace it is assigned to).

Macros defined in child scopes do not shadow macros in outer scopes; if there are macros with the same name in the outer scopes, conflicts are handled in the same way as with groups of macros that are imported in the same scope. For example, Mode = MacroMode.PriorityOverride can be used to make macros that override normal-priority macros.

Property Documentation

◆ AllKnownMacros

IReadOnlyDictionary<Symbol, VList<MacroInfo> > LeMP.IMacroContext.AllKnownMacros
get

Gets information about all macros registered with the macro processor, including macros whose namespace has not been opened with #importMacros.

◆ Ancestors

IReadOnlyList<LNode> LeMP.IMacroContext.Ancestors
get

Returns a list of ancestors of the current node being processed. Normally Ancestors[0] is a #splice node that contains a list of all top-level statements in the file, and Ancestors.Last() is the current node.

You would expect that Ancestors[N] would contain Ancestors[N+1] as part of the attributes, target or arguments, but this is not always true. The ancestor list contains original versions of each node; when a child node is changed by a macro, the parent is not updated in this list, but macro processing continues for the descendants of that child, so the ancestor list may occasionally seem incoherent.

◆ DropRemainingNodes

bool LeMP.IMacroContext.DropRemainingNodes
getset

Gets or sets a value that indicates whether to drop all remaining node after the current one when the current macro returns. This property has no effect if the macro rejects the input by returning null.

See remarks at MacroContext.GetArgsAndBody.

Referenced by LeMP.MacroContext.GetArgsAndBody().

◆ IsAttribute

bool LeMP.IMacroContext.IsAttribute
get

Returns true if the current node is in the attribute list of its immediate parent.

◆ IsTarget

bool LeMP.IMacroContext.IsTarget
get

Returns true if the current node is the target of its parent call node.

◆ NextTempCounter

int LeMP.IMacroContext.NextTempCounter
get

Gets the next number to use as a suffix for temporary variables (without incrementing it).

◆ OpenMacroNamespaces

ICollection<Symbol> LeMP.IMacroContext.OpenMacroNamespaces
get

Gets the list of namespaces that are being searched for macros in the current scope. You can modify this collection.

The naming scheme of namespaces is not standardized in cases where the namespace name is not a "normal" identifier. It is recommended that macros be placed in namespaces whose names are valid identifiers in most languages (C++, C#, Java, Python, etc.). It's okay to put macros in nested namespaces.

◆ Parent

LNode LeMP.IMacroContext.Parent
get

Gets the logical parent of the current node, which is Ancestors[Ancestors.Count - 2], or null if the current node is the root node.

Please note that the current node may not actually exist in the parent node due to changes made earlier to the current node by other macros (or even the same macro); the Parent property still returns the old version of the parent node.

◆ RemainingNodes

IListSource<LNode> LeMP.IMacroContext.RemainingNodes
get

Gets a list of the remaining nodes (arguments/statements or attributes) after this point in the code stream.

The list is null when processing a target node.

For example, if your macro is called "macro" and it appears in the following context:

{
a();
macro(b());
c();
d();
}

Then this list will contain two items, c() and d(). Similarly, if the context is [a, b, macro(c), d, e] then the list will contain the items d and e.

Referenced by LeMP.MacroContext.GetArgsAndBody().

◆ ScopedProperties

IDictionary<object, object> LeMP.IMacroContext.ScopedProperties
get

Returns a table of "properties" (arbitrary key-value pairs) that exist in the current scope. This dictionary is "persistent" in the computer science sense; any changes to these properties affect only the current scope and child scopes. When the current scope ends, the set of properties that existed in the parent scope are restored.

Scopes are bounded by curly brace nodes (Call nodes named "{}").

◆ Sink

IMessageSink LeMP.IMacroContext.Sink
get

Returns the message sink, used for writing warnings and errors.

For backward compatibility, IMacroContext itself implements IMessageSink also.

Referenced by Loyc.LLPG.Macros.LLLPG_lexer(), Loyc.LLPG.Macros.LLLPG_parser(), and Loyc.LLPG.Macros.LllpgMacro().