Encapsulates an algorithm that consumes trivia (comments and newlines) from a list and adds it as trivia attributes into LNodes. This makes it possible to preserve comments and newlines independently of the language parser, so that the parser need not be specifically designed to preserve them. More...

Source file:

/Core/Loyc.Syntax/Parsing/StandardTriviaInjector.cs

Inheritance diagram for Loyc.Syntax.StandardTriviaInjector:

Remarks

Encapsulates an algorithm that consumes trivia (comments and newlines) from a list and adds it as trivia attributes into LNodes. This makes it possible to preserve comments and newlines independently of the language parser, so that the parser need not be specifically designed to preserve them.

Usage: Call the constructor, then call AbstractTriviaInjector<T>.Run. See AbstractTriviaInjector<T> for more information.

In brief, given input code with C-style comments like

{
    // Leading Comment 1
    /* Leading Comment 2 * /
    /* Leading Comment 3 * / x = y; // Trailing Comment 1
    /* Trailing Comment 2 * /

    y = z; TheEnd();
}

[NOTE: the space in "* /" is a workaround for a serious bug in Doxygen, the html doc generator]

The output, expressed in LESv2, is

{
    @[%SLComment(" Leading Comment 1"),
      %MLComment(" Leading Comment 2 "),
      %newline,
      %MLComment(" Leading Comment 3 "),
      %trailing(
        %SLComment(" Trailing Comment 1"),
        %MLComment(" Trailing Comment 2 "),
        %newline)]
    x = y;
    y = z;
    @[%appendStatement] TheEnd();
}

By default, printers should add newlines between statements within a braced block. Therefore, this class does not add trivia to mark a single newline between statements; instead, it adds an appendStatement attribute when the expected newline prior to a statement in a braced block was NOT present. Also, a newline is expected after a single-line comment and no newline is created for the expected newline.

Finally, since printers typically add a newline before the closing brace by default, this class avoids adding an attribute for that newline, if present.

Properties
ISourceFile	SourceFile `[get, set]`

int	NewlineTypeInt `[get, set]`

string	SLCommentPrefix `[get, set]`

string	SLCommentSuffix `[get, set]`

string	MLCommentPrefix `[get, set]`

string	MLCommentSuffix `[get, set]`

bool	TopLevelIsBlock `[get, set]`

Properties inherited from Loyc.Syntax.AbstractTriviaInjector< Token >
IListSource< Trivia >	SortedTrivia `[get, set]`
	List of trivia to be injected by Run. Must be sorted. More...

int	NextIndex `[get, set]`
	Index of next trivia to be injected. More...

Public Member Functions
	StandardTriviaInjector (IListSource< Token > sortedTrivia, ISourceFile sourceFile, int newlineTypeInt, string mlCommentPrefix, string mlCommentSuffix, string slCommentPrefix, bool topLevelIsBlock=true)
	Initializes StandardTriviaInjector. More...

Public Member Functions inherited from Loyc.Syntax.AbstractTriviaInjector< Token >
	AbstractTriviaInjector (IListSource< Trivia > sortedTrivia)
	Initializes the SortedTrivia property. More...

IEnumerator< LNode >	Run (IEnumerator< LNode > nodes)
	Attaches trivia to the input nodes provided. More...

Protected Member Functions
override LNodeList	GetTriviaToAttach (LNode node, IListSource< Token > trivia, TriviaLocation loc, LNode parent, int indexInParent)

virtual bool	HasImplicitLeadingNewline (LNode child, LNode parent, int indexInParent)
	Called to find out if a newline is to be added implicitly before the current child of the specified node. More...

virtual LNode	MakeTriviaAttribute (Token t)
	Called to transform a trivia token into a trivia attribute. More...

override bool	IsNewline (Token trivia)

override SourceRange	GetRange (Token trivia)

Protected Member Functions inherited from Loyc.Syntax.AbstractTriviaInjector< Token >
abstract LNodeList	GetTriviaToAttach (LNode node, IListSource< Trivia > trivia, TriviaLocation loc, LNode parent, int indexInParent)
	Derived class translates a list of trivia (tokens) into appropriate trivia attributes. This will be called for leading trivia before trailing trivia. More...

virtual void	ProcessChildrenOfOneLiner (ref LNode node)
	This method is called when a node has no newlines or comments within it (although the node may still have a leading or trailing comment). The method should add appendStatement trivia inside blocks in the node, if necessary. More...

abstract SourceRange	GetRange (Trivia trivia)
	Gets the SourceRange for an element of trivia. More...

abstract bool	IsNewline (Trivia trivia)
	Returns true if the trivia represents a newline, false otherwise. More...

virtual LNode	GetEmptyResultSet ()
	A method called to create a virtual node, in order to apply trivia to a source file that is completely empty except for trivia. More...

virtual LNode	DoneAttaching (LNode node, LNode parent, int indexInParent)
	This method is called after a node has been processed and any applicable trivia was attached. More...

IEnumerator< Pair< LNode, int > >	RunCore (IEnumerator< Pair< LNode, int >> nodes, LNode parent)
	Core trivia associaton algorithm. More...

Additional Inherited Members
Static Protected Member Functions inherited from Loyc.Syntax.AbstractTriviaInjector< Token >
static IEnumerator< Pair< T, int > >	WithIndexes< T > (IEnumerator< T > e)

Constructor & Destructor Documentation

◆ StandardTriviaInjector()

Loyc.Syntax.StandardTriviaInjector.StandardTriviaInjector	(	IListSource< Token >	sortedTrivia,
		ISourceFile	sourceFile,
		int	newlineTypeInt,
		string	mlCommentPrefix,
		string	mlCommentSuffix,
		string	slCommentPrefix,
		bool	topLevelIsBlock = `true`
	)

inline

Initializes StandardTriviaInjector.

Parameters

sortedTrivia	A list of trivia that will be injected into the nodes passed to AbstractTriviaInjector<T>.Run. Normally, text of comments is extracted from the provided ISourceFile, but comment tokens could instead store their text as a string in their Token.Value.
sourceFile	This is used as the source file of the LNode.Range of all trivia attributes that the algorithm injects.
newlineTypeInt	A token is interpreted as a newline when this value equals Token.TypeInt.
mlCommentPrefix	If a token's text begins with this prefix it is assumed to be a multi-line comment and the prefix is removed.
mlCommentSuffix	If a multi-line comment's text ends with this suffix, the suffix is removed.
slCommentPrefix	If a token's text begins with this prefix it is assumed to be a single-line comment and the prefix is removed.
topLevelIsBlock	If true, newlines are expected between items at the top level, like in a braced block, so that, for example, if two consecutive nodes are on the same line, an @appendStatement trivia attribute will be attached to the second one.