With ``-f`` ``--storable-state`` option re2c generates a lexer that can store its current state, return to the caller, and later resume operations exactly where it left off. The default mode of operation in re2c is a "pull" model, in which the lexer "pulls" more input whenever it needs it. This may be unacceptable in cases when the input becomes available piece by piece (for example, if the lexer is invoked by the parser, or if the lexer program communicates via a socket protocol with some other program that must wait for a reply from the lexer before it transmits the next message). Storable state feature is intended exactly for such cases: it allows one to generate lexers that work in a "push" model. When the lexer needs more input, it stores its state and returns to the caller. Later, when more input becomes available, the caller resumes the lexer exactly where it stopped. There are a few changes necessary compared to the "pull" model: * Define ``YYSETSTATE()`` and ``YYGETSTATE(state)`` promitives. * Define ``yych``, ``yyaccept`` and ``state`` variables as a part of persistent lexer state. The ``state`` variable should be initialized to ``-1``. * ``YYFILL`` should return to the outer program instead of trying to supply more input. Return code should indicate that lexer needs more input. * The outer program should recognize situations when lexer needs more input and respond appropriately. * Use ``/*!getstate:re2c*/`` directive if it is necessary to execute any code before entering the lexer. * Use configurations ``state:abort`` and ``state:nextlabel`` to further tweak the generated code. Here is an example of a "push"-model lexer that reads input from ``stdin`` and expects a sequence of words separated by spaces and newlines. The lexer loops forever, waiting for more input. It can be terminated by sending a special EOF token --- a word "stop", in which case the lexer terminates successfully and prints the number of words it has seen. Abnormal termination happens in case of a syntax error, premature end of input (without the "stop" word) or in case the buffer is too small to hold a lexeme (for example, if one of the words exceeds buffer size). Premature end of input happens in case the lexer fails to read any input while being in the initial state --- this is the only case when EOF rule matches. Note that the lexer may call ``YYFILL`` twice before terminating (and thus require hitting ``Ctrl+D`` a few times). First time ``YYFILL`` is called when the lexer expects continuation of the current greedy lexeme (either a word or a whitespace sequence). If ``YYFILL`` fails, the lexer knows that it has reached the end of the current lexeme and executes the corresponding semantic action. The action jumps to the beginning of the loop, the lexer enters the initial state and calls ``YYFILL`` once more. If it fails, the lexer matches EOF rule. (Alternatively EOF rule can be used for termination instead of a special EOF lexeme.)