View of /trunk/webwork-modperl/doc/parser/README

    1 OVERVIEW:
    2 
    3 This directory contains the documentation for a new
    4 mathematical-expression parser written in perl.  It was developed for
    5 use with the WeBWorK on-line homework system, but it can be used in
    6 any perl program.
    7 
    8 The goal was to process vector-valued expressions, but the parser was 
    9 designed to be extensible, so that you could add your own functions, 
   10 operators, and data types.  It is still a work in progress, but should 
   11 provide a framework for building more sophisticated expression handling.
   12 
   13 Currenlty, the parser understands:
   14 
   15    - real and complex numbers,
   16    - points, vectors, and matrices (with real or complex entries)
   17    - arbitrary lists of elements
   18    - intervals and unions of intervals
   19    - predefined strings like 'infinity'
   20 
   21 Some other useful features are that you can write sin^2 x for (sin(x))^2
   22 and sin^-1 x for arcsin(x), and so on.
   23 
   24 Most of the documentation still needs to be written, but you can get some 
   25 ideas from the samples in the problems and extensions directories, and by 
   26 reading the files in the docs directory.
   27 
   28 
   29 INSTALLATION:
   30 
   31 The parser should already be installed as part of the WeBWorK 2.1
   32 distribution, so you should not need to install it separately.  If you
   33 don't seem to have it installed, then it can be obtained from the
   34 Union CVS repository at
   35 
   36   http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/WeBWorKCVS
   37 
   38 The README file in that directory contains the installation instructions.
   39 
   40 
   41 SAMPLE FILES:
   42 
   43 Sample problems are given in the problems and extensions directories.  Move 
   44 these to the templates directory of a course where you want to test the 
   45 Parser, and move the contents of the macros directory to that course's 
   46 macros directory.
   47 
   48 Now try looking at these problems using the Library Browser.  Edit the
   49 source to see how they work, and to read the comments within the code
   50 itself.
   51 
   52 
   53 EXAMPLE FILES:
   54 
   55 The 'problems' directory contains several examples that show how to use 
   56 Parser within your problem files.
   57 
   58     sample01.pg
   59         Uses the parser to make a string into a formula that you can
   60         evaluate and print in TeX form
   61 
   62     sample02.pg
   63         Shows how to create formulas using perl's usual mathematical
   64         expressions rather than character strings.
   65 
   66     sample03.pg
   67         Shows how to use the parser's differentiation abilities.
   68 
   69     sample04.pg and sample05.pg
   70         Use the parser in conjunction with the graphics macros to generate 
   71         function graphs on the fly.  These also show how to create a 
   72         perl function to evaluate an expression.
   73 
   74     sample06.pg
   75         Shows some simple use of vectors in a problem.
   76 
   77     sample07.pg
   78         Example if using the build-in Real object and its answer
   79         checker
   80 
   81    sample08.pg
   82         Uses complex numbers and the built-in checker
   83 
   84    sample09.pg and sample10.pg
   85         Demonstrates points and vectors and their answer checkers
   86 
   87    sample11.pg and sample12.pg
   88         Shows the answer checkers for intervals and unions.
   89 
   90    sample13.pg, sample14.pg, sample15.pg
   91         Demonstrate various list checkers, including a check for the
   92         word 'NONE', which is a predefined string.
   93 
   94    sample16.pg, sample17.pg, sample18.pg
   95         These show the multi-variable function checker in use (for
   96         functions of the form R->R, R^2->R and R->R^3).
   97 
   98    sample19.pg
   99         Uses the function checker to implement a "constant" that can
  100         be used in formulas.
  101 
  102    sample20.pg
  103         Shows how to use the parser's substitution abilities.
  104 
  105    sample21.pg
  106         Checks for a list of points.
  107 
  108    sample22.pg
  109         Shows how to provide named constants that the student can
  110 	use in his answer.
  111 
  112 The 'examples' directory contains samples that show how to extend the 
  113 parser to include your own functions, operators, and so on.  There are also 
  114 some samples of how to call the methods available for Formula objects 
  115 generated by the parser, and what some error messages look like.
  116 
  117     1-function.pg
  118        Adds a single-variable function to the parsers list of functions.
  119 
  120     2-function.pg
  121        Adds a two-variable function to the parser.
  122 
  123     3-operator.pg
  124        Adds a binary operator to the parser.  (Unary operators are similar.)
  125 
  126     4-list.pg
  127        Adds a new "list type" object.  In this case, it's really an
  128        operation [n,r] that returns n choose r.
  129 
  130     5-list.pg
  131        Add a new "equality" operator that you can use to handle answers
  132        like "x+y=0".
  133 
  134     6-precedence.pg
  135        Shows an experimental precedence setting that can be used to make
  136        sin 2x return sin(2x) rather than (sin(2))x.
  137 
  138     7-context.pg
  139        Shows how to switch contexts (in this case, to complex and to vector
  140        contexts), and how this affects the parsing.
  141 
  142     8-answer.pg
  143        Implements a simple vector-valued answer checker using the
  144        parser's computation and comparison ability.
  145