@setfilename dfasyn.info
@settitle User guide for the dfasyn DFA construction utility

@titlepage
@title dfasyn user guide
@subtitle This manual describes how to use dfasyn.
@author Richard P. Curnow
@page
@end titlepage

@c{{{ Top node
@node Top
@top
@menu
* Introduction:: The introduction
* Input file format:: A reference for the input file
* Concept Index:: Index of concepts
@end menu
@c}}}
@c{{{ ch:Introduction
@node Introduction
@chapter Introduction

@menu
* Uses for dfasyn:: The types of problem to which dfasyn is well-suited
@end menu

@node Uses for dfasyn
@section Uses for dfasyn
dfasyn is particularly suited to the following types of scanning problem, both of
which exceed flex's capabilities

@itemize @bullet
@item When the pattern describing a token cannot be written as a regular
expression.  For example, there may be iteration but with constraints between
the end of one iteration and the start of the next.
@item When more than 1 rule matches in a flex input file, flex chooses between
them based on

  @itemize -
  @item Longest match first
  @item Earliest rule in the file if more than 1 match of the same length exists
  @end itemize

dfasyn allows for a more general method of resolving multiple matches.
Conceptually, it works out which rules match, giving a true/false status for
each rule.  The input file defines an arbitrarily complex set of boolean
expressions to reduce the multiple matches down to one unique one.  (If more than
one of the boolean expressions evaluates true, this is an error.)

@item When a customised method is required to construct the input tokens that
pass to the scanner.  For example, if the tokens are the characters in a string
(rather than coming from a file), or if some special logic has to be used to
generate the tokens from the input character stream.
  
@item If you want to add actions to the scanning loop, e.g. to remember special
locations within the word being scanned.
  
@end itemize

@node Non-uses for dfasyn
@section Cases where flex might be better

In general, flex is easier and more convenient to use.  Where it is applicable
to your problem, there are no obvious benefits to using dfasyn.

@node Why written
@section Why was dfasyn written?
@c}}}

@c{{{ ch:Input file format
@node Input file format
@chapter Input file format
This section describes the format of the input file.

@c}}}


@node Concept Index
@unnumbered Concept Index
@printindex cp
@bye

@c vim:syntax=OFF:fdm=marker:fdc=4:cms=@c%s

