monq.jfa

Interface FaAction

All Known Implementing Classes:

AbstractFaAction, Call, Context, Copy, Count, DefaultAction, Drop, Embed, Fail, Hold, If, IfContext, LowerCase, Printf, Replace, Run, SearchReplace, Stop, Store, SwitchDfa, TailContextN, UpperCase

public interface FaAction

describes the interface to objects implementing actions associated with stop states of a finite automaton. By adding an FaAction to an Nfa by means of Nfa.addAction(monq.jfa.FaAction) or when creating an Nfa (e.g. Nfa.Nfa(CharSequence, FaAction)), the Nfa gets a stop state having the given action associated. When the automaton is compiled and run, method invoke(java.lang.StringBuilder, int, monq.jfa.DfaRun) is called whenever the automaton finds a match which stops the automaton in the associated stop state. The callback then has the chance to change the matched text, tag it, enter it into an internal data structure, etc.

Version:

1.0

Author:

Harald Kirsch

Method Summary

Modifier and Type	Method and Description
void	invoke(java.lang.StringBuilder yytext, int start, DfaRun runner) is called by methods of DfaRun in case of a match.
FaAction	mergeWith(FaAction other) is eventually called by Nfa.compile(monq.jfa.DfaRun.FailedMatchBehaviour, monq.jfa.FaAction) to create a unified action from this object and another FaAction object.

Method Detail

invoke

void invoke(java.lang.StringBuilder yytext,
            int start,
            DfaRun runner)
     throws CallbackException

is called by methods of DfaRun in case of a match. Parameter yytext contains the matching text from position start onwards. The callback may change the whole of yytext, but the under most circumstances, only the matching text should be changed. Parameter runner is the DfaRun object which called this function. Of interest are its fields DfaRun.clientData and DfaRun.collect.

Throws:

CallbackException

mergeWith

FaAction mergeWith(FaAction other)

is eventually called by Nfa.compile(monq.jfa.DfaRun.FailedMatchBehaviour, monq.jfa.FaAction) to create a unified action from this object and another FaAction object. During compilation of an Nfa into a Dfa, two regular expressions assigned to different actions may have overlapping matches. In this case one of the actions' mergeWith methods is called with the other action as parameter to create a unified action object.

There are only four permissible results this method may return:

1. this completely unchanged,
2. other completely unchanged,
3. a newly created object or
4. null to signal that no unified action exists.

Both objects, this and other must be treated read-only. Changing them may lead to unexpected behaviour which is very hard to track down. To understand why this is so, consider the two regular expressions ax? and ay? bound to actions X and Y respectively. Both expressions match the string "a", which will cause a call to mergeWith of either one of the actions. If merging would integrate, say, Y into X and return X, the changed X would also be run for the match "ax" which most likely was not intended.

To get a simple priority based selection of one of the actions, consider extending AbstractFaAction.

Note: For two competing actions it is completely random which of the mergeWith() methods is called. Consequently, implementations of this method should be as symmetric as possible.

Parameters:

other - will never be null.