"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/fickle/examples/README" (13 Nov 2019, 4322 Bytes) of package /linux/misc/ds9.8.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 $Id: README,v 1.1.1.1 2004/07/23 19:22:41 tang Exp $
    2 
    3 The example fickle code programs are based upon the lex examples found
    4 within "lex & yacc" by John R. Levine, Tony Mason, and Doug Brown (by
    5 O'Reilly & Associates, ISBN 1-56592-000-7).  For more information on
    6 using lex and yacc, see http://www.oreilly.com/catalog/lex/.
    7 
    8 Run the Makefile to generate resulting Tcl code.  Descriptions of
    9 individual files are below.  The reader is assumed to have a familiarity
   10 with flex; if not consider purchasing the aforementioned book.
   11 
   12 
   13 cat.fcl
   14 -------
   15 This is the simplest fickle example possible.  It copies its input (from
   16 stdin) to output (stdout), much like the cat(1) program does without any
   17 arguments.  Note that one must explicitly call yylex to run the lexer.
   18 
   19 
   20 verbs.fcl
   21 ---------
   22 This examples demonstrates a verbatim section (the text between '%{'
   23 and '%}').  Also note how fickle specification files may have
   24 Tcl-style comments embedded within.  This program searches its input
   25 for various English verbs and copies it to the output.  The program
   26 makes use of the variable $yytext (really just an upvar'ed version of
   27 the global ::yytext variable) to print out the text that matched.
   28 
   29 
   30 wc.fcl
   31 ------
   32 This program will count the number of characters, words, and lines in
   33 its input, much like wc(1).  Called without any arguments, wc.tcl reads
   34 from stdin; it reads from a file if given an argument.  Unless otherwise
   35 specified, 'yyin' points to stdin and 'yyout' to stdout.  Overriding
   36 these variables forces the lexer to read from another stream.  This
   37 program also uses $yyleng (an upvar'ed version of ::yyleng) which is
   38 set to [string length $::yytext].
   39 
   40 
   41 wc2.fcl
   42 -------
   43 This example supports multiple filenames.  With more than one argument,
   44 wc2 will print a report for each line and a summary line totalling all
   45 metrics.  No summary is displayed given zero or one argument.
   46 
   47 wc2 handles multiple files by overriding the definition for yywrap.
   48 yywrap returns 0 when additional files need to be processed.
   49 
   50 The directive `%option noheaders' causes fickle to not include
   51 comments about the autogenerated functions within wc2.tcl.  Note the
   52 difference in size between wc2.tcl and wc.tcl.
   53 
   54 
   55 cl.fcl
   56 ------
   57 This example demonstrates how to feed the lexer input from a source
   58 other than a file -- in this case, the command line.  One must rewrite
   59 YY_INPUT to use the alternative source.  The first parameter should be
   60 'upvar'ed; it holds the next string to scan.  'result' should be the
   61 size of the buffer, or zero to indicate an end of file; this too needs
   62 to be 'upvar'ed.  The final parameter indicates the maximum allowed
   63 buffer size.  By default this is 1024; use the `%option buffersize'
   64 directive to change this amount.
   65 
   66 Also note the use of `%option nodefault'.  By default fickle will
   67 write to yyout any unmatched input through the ECHO function.  Use
   68 `%option nodefault' to abort the program upon unmatched input; this is
   69 useful during debugging sessions.  One can also invoke this
   70 suppression behavior with the `-s' flag on the fickle command line.
   71 
   72 
   73 csa.fcl
   74 -------
   75 The next example is a C source analyzer.  It takes a single C source
   76 file as a parameter; it then counts the lines of code, comments, and
   77 whitespace within.
   78 
   79 This example demonstrates the start state feature of fickle, enabled
   80 through the directive `%option stack'.  fickle supports both exclusive
   81 start states (as indicated by '%x') as well as regular start states
   82 ('%s', though not featured in this program).  Start states specify
   83 when a pattern is allowed.  Switch states through calls to 'BEGIN',
   84 'yy_push_state', and 'yy_pop_state'.
   85 
   86 The initial state is called, not surprisingly, 'INITIAL'.  Unlike flex,
   87 'BEGIN 0' and 'BEGIN INITIAL' are not identical.  To match all states,
   88 prepend the pattern with '<*>'.  Patterns that have no state listed are
   89 defaulted to matching only INITIAL and any regular start state.[*]
   90 
   91 Note that if multiple patterns match the input, the largest match takes
   92 precedence.  In case of a tie the pattern appearing earlier within the
   93 specification file wins.
   94 
   95 [*] Regular start states are a source of much confusion and are rarely
   96 useful.  Avoid them like the plague.
   97 
   98 
   99 tsa.fcl
  100 -------
  101 In comparison to the above this program instead analyzes Tcl code.
  102 It's not particularly foolproof but does get the job done.