Modes

Modes (also known start conditions) control enabling and disabling entire groups of lexer rules. Modes can be switched programmatically during lexer run.

Generated lexer class contains read-only objects which correspond to defined modes. These objects are used as arguments to mode switching methods.

Lexer is always in single particular mode which can be read from CurrentMode field. The default predefined mode is called INITIAL.

Switching to particular mode can be done using a method or a convenience macro:

Mode switching interface is available only if any custom modes were defined in grammar.

Users can freely switch between modes.

A common usage scenario is to enter a mode defined for some special purpose, and once done, get back to mode used previously. To simplify using modes in such scenarios Alpag provides mode stack mechanism. It must be enabled setting Lexer.Modes.StackEnabled option to True or WhenPossible . Second alternative activates stack only when there are any custom modes defined.

With stack enabled following methods and macros become available:

Pushes current mode on stack and enters a new mode. Returns stack level (index) of newly pushed state.

Takes mode off stack and switches to it. Returns false if stack is empty.

Takes modes off the stack until given level. Removes also mode at this level and switches to it.

Pops current mode if it is equal given mode. If current mode is different, takes no action

Pops modes from stack until given mode is found. Removes also that mode and switches to it returning true. If given mode is not present on stack takes no action and returns false (stack remains intact). If includingCurrent is set to true, and current state is equal given state, than no action is taken.

Pops modes from stack until given mode is found. Does not remove this found mode. Mode which is on stack one level above becomes current.