CS 453 Programming Assignment #1 (PA1): MiniSVG

PA1 due Wednesday February 2nd (by 11:59pm)

Introduction:

This first programming assignment will be done individually. Your grade on this assignment will guide the partner selection process for later assignments.

Your first programming assignment is to implement a Scalable Vector Graphics viewer for a small subset of the SVG specification by writing a lexer/scanner and a top-down predictive parser by hand. SVG is a standard for describing two-dimensional graphics and animations in XML. Most web browsers are capable of rendering .svg files like the following, which shows the contents of the file min-grammar.svg:

<svg xmlns="http://www.w3.org/2000/svg">

  <!-- rectangles -->
  <rect   x="20" y="20" width="300" height="250" fill="red" />
  <rect x="30" y="20" width="300" height="250" fill="blue" />
  <rect x = "40" y = "20" width = "300" height = "250" fill="green" />

  <!-- white circle on top of rectangles -->
  <circle cx="120" cy="150" r="60" fill="white" />

  <!-- black diagonal line -->
  <line x1="0" y1="0" x2="300" y2="300" stroke="black" />

</svg>

A rendering of the above SVG description can be seen by saving the following file to your drive and then opening it in your browser: min-grammar.svg

For this programming assignment, we provide the MiniSVG driver class and many utility routines to get you started. Download MiniSVGStart.tar. When executed with the following commands (or from within Eclipse by doing a Run As Java Application with TestCases/face.svg as the arguments):

    % tar xf MiniSVGStart.tar
    % cd MiniSVGStart/src
    % javac driver/MiniSVG.java
    % java driver.MiniSVG ../TestCases/face.svg

the MiniSVG driver opens a window and renders a HARDCODED series of graphics commands for the same set of objects described in the min-grammar.svg file. When you close the graphics window, the program will exit. The face.svg file specified above is only needed so that the MiniSVG driver is able to open a valid file. Currently the driver creates a PushbackReader for the given input file, but parser.Parse.parse_svg() does not actually read anything from the file. Your assignment is to write lexer and a parser that parses the input .svg file and renders the graphics elements specified in the .svg file. See the TODO items in the MiniSVGStart/src/lexer/Lexer.java and MiniSVGStart/src/parser/Parser.java.

The Assignment and The MiniSVG Grammar

You will be implementing a subset of SVG that includes circles, rectangles, and lines. Your program must be able to parse SVG specifications generated with the following grammar, where words in all capital letters are tokens/terminals and words in all lowercase are non-terminals:

svg -> SVG_START elem_list SVG_END
elem_list -> elem elem_list  |  epsilon
elem -> 
      RECT_START  KW_X EQ NUM KW_Y EQ NUM KW_WIDTH EQ NUM KW_HEIGHT EQ NUM KW_FILL EQ COLOR  ELEM_END
      
    | CIRCLE_START KW_CX EQ NUM KW_CY EQ NUM KW_R EQ NUM KW_FILL EQ COLOR ELEM_END
    
    | LINE_START KW_X1 EQ NUM KW_Y1 EQ NUM KW_X2 EQ NUM KW_Y2 EQ NUM KW_STROKE EQ COLOR ELEM_END

To recognize the above grammar, you should write a top-down, predictive parser. As each elem grammar rule is matched in the predictive parser, the specified element should be rendered to a window and the appropriate SVGReporter method should be called to output logging messages. (See the parse_svg() method in MiniSVGStart/src/parser/Parser.java to see examples of how this can be done with the provided IDrawSVG and IReportSVG interfaces).

The parser queries the lexer for a stream of tokens. The lexer is actually the more difficult part of this programming assignment. Here are all of the regular expressions, specified using JLex syntax, for the terminals in the MiniSVG grammar. Note that {VAR} indicates textual substitution for VAR just as in many unix scripting languages.

    // The set starting with EOL and ending with NOT_DASH
    // are not terminals/tokens.  They are just helper 
    // regular expressions.
    EOL=\r|\n|\r\n
    WHITE_SPACE=[\r\n\t]
    DIGIT=[0-9]
    NOT_GT=[^>]
    NOT_DASH=[^-]
        
    // Starting with SVG_START through NUM are the regular 
    // expressions for tokens that the lexer will pass back 
    // to the parser when scan() is called.
    // Note that the COMMENT token will be skipped by the
    // lexer and the parser will never see it.
    SVG_START="<svg"{NOT_GT}*">"
    SVG_END="</svg>"
    RECT_START="<rect"
    CIRCLE_START="<circle"
    LINE_START="<line"
    ELEM_END="/>"
    
    KW_X="x"
    KW_Y="y"
    KW_WIDTH="width"
    KW_HEIGHT="height"
    KW_FILL="fill"
    KW_CX="cx"
    KW_CY="cy"
    KW_R="r"
    KW_X1="x1"
    KW_Y1="y1"
    KW_X2="x2"
    KW_Y2="y2"
    KW_STROKE="stroke"
    
    EQ="="
    
    COLOR=\""red"\"|\""blue"\"|\""green"\"|\""black"\"|\""white"\"

    NUM=\"DIGIT+\" 
    COMMENT="<!--"({NOT_DASH})*"-->"

The MiniSVGStart project provides token classes (i.e., Token, Word, Color, Num) and provides some utility methods for implementing the lexer. As we will discuss in class, to implement the lexer the deterministic finite automatas (DFAs) for all of the tokens can be combined into a single DFA (or transition diagram) to guide implementation of the lexer. To help ensure that your implementation results in error messages identical to the reference MiniSVG implementation, use the DFA in MiniSVG-lexer-DFA-simplified.pdf for your lexer implementation. The book describes the transition diagrams (also called deterministic finite automata) in Chapter 3.4.1 and provides some sample code in Chapter 2.6.

Notes about the grammar and the tokens:

The minimal grammar expects the element information to be in a specific order (e.g., for a circle, cx = "250" cy = "250" r="43" fill="blue"). Full SVG allows any order.
The separation between the lexicographical analysis and parsing stages can vary based on how much information the parsing stage needs. For example, in a typical programming language the less than operator "<" would be its own separate token, however in the minimal SVG specification that we are supporting, it is easier to group the less than symbol with the rect, circle, svg, etc.
Where do we allow whitespace:
- NOT between < and rect, svg, etc.
- NOT inside the quotes
- NOT between the bang and dashes, and dashes and > in comments.
- YES between tokens, required after RECT_START, CIRCLE_START, and LINE_START
MiniSVG also allows comments between any of the tokens, which full SVG does not allow. It is easier to have the lexer just ignore comments rather than modify the grammar so that comments are only allowed in certain places.
Minimal grammar only uses double quotes around integer numbers and colors.
Making COLOR a token type so it is easy to enable more complex lexemes to get more colors. Otherwise you would have to change the grammar. This way, you just need to add more regular expressions for the COLOR token and handle the extra semantics during semantic analysis. On pg. 130 in the book, relop is handled in a similar fashion.
The comments do not allow any dashes other than as part of the comment delimiters.

Lexer generators such as JLex and parser generators such as JavaCUP are not allowed for this programming assignment.

Your program should include error handling through the use of the ParseException class for the following situations:

Lexer errors
- Exception thrown by match().
```
[LINE,POS] Expecting character 'X' and got 'D'.
    
```
- Exception to throw when find something other than a word or a number in quotes.
```
[LINE,POS] Expect only numbers or colors in quotes.
```
- When parse a word (anything starting with a letter and some combination of letters and numbers), if the word doesn't match any of the keywords or colors.
```
[LINE,POS] Unexpected word 'theword'.
```
- All other cases of an unexpected letter.
```
[LINE,POS] Unexpected character 'C'.
```

Parser errors

Exception thrown by match.

[LINE,POS] Expected token TOKENTAG got < OTHERTOKENTAG, otherinfo >.

All other cases of an unexpected token.

[LINE,POS] Unexpected token < TOKENTAG, otherinfo >.

Make sure your error message matches that of the reference compiler exactly. If not points will be taken off. We will not have test cases that are valid SVG, but not in the MiniSVG grammar. Therefore any extensions you make to MiniSVG should not perturb the grading.

Getting Started

First things first, this semester you are going to be using the subversion revision control system to maintain previous versions of your code and eventually exchange code with your partner. Using subversion will be worth anywhere from 5-10% of each program assignment grade. You will need to include a subversion.txt file in your final turnin. The subversion.txt file should include output from the following commands:

    % svn log -r HEAD:1
    % svn info
    % svnlook tree REPOSITORY_PATH  // svnlook must be issued on a department machine

Revision control is important. See SVN notes for an example of how to set up a subversion repository. Subversion will also be covered in the discussion section.

Start this assignment by copying MiniSVGStart.tar to your directory. MiniSVGStart.tar untars to a MiniSVGStart/ directory that contains the src/ and TestCases/ subdirectories. The TestCases/ directory contains example input and output. You can check the visual component by comparing with what a web browser displays. For grading, we will be performing diffs on your text output with the text output from the reference compiler. The src/ directory has the following organization:

    driver/
        MiniSVG.java
    exceptions/
        ...
    lexer/
        ...
        Lexer.java
        Token.java
        ...
    parser/
        Parser.java
    util/
        ...

The main for this code is in MiniSVG.java. The main function calls render(), which in turn calls parser.parse_svg(). Currently parse_svg() hardcodes calls to the reporter and drawer routines, but it should be turned into a top-down parser that makes those calls based on what is being parsed. You will be putting implementation into the Lexer.java and Parser.java files. The Lexer.scan() routine returns Token instances to the Parser.

Set up a subversion repository for the programming assignment.

After setting up the subversion repository, check that the given MiniSVG runs and step through the code with a debugger to understand what it is doing.

Implement a lexer that can recognize the various tokens in the MiniSVG grammar.

Implement a predictive parser that reports what SVG elements were parsed and renders the elements to the screen.

If you send an example .svg file to the class mailing list, then we will send you back the reference compiler text output.

Some Extra Fun

You can implement any additional pieces of the SVG specification. Last year we had some cool pictures like face.svg. To snaz up the picture, you can add more functionality to your MiniSVG renderer.

Here are some sites with SVG examples:

Submitting your Assignment

Make sure you test your implementation thoroughly. Check your output against the .out files provided in TestCases/ and also against any examples sent to the mailing list.
Only turnin one assignment per group.
The README file should include your username, email, how to compile and run your program, and any information you want the TA to have before grading your assignment. E.g., this part is not working due to..., a favorite quote or joke to amuse the TA, etc.

The subversion.txt file should include output from the following commands:

    % svn log -r HEAD:1
    % svn info
    % svnlook tree REPOSITORY_PATH  // svnlook must be issued on the machine where the repository is stored

One sample .svg files that can be generated by the minimal SVG grammar expected for this assignment. Call the file test-usernamename.svg.
Include all the source files, a README file, a subversion.txt file, and test-username.svg in a tar file.
```
tar cvf PA1_username.tar PA1
```
Submit assignment using checkin utility
```
~cs453/bin/checkin PA1 PA1_username.tar
```

Sanity Check (procedure TA will use to run your assignment):

    % tar xf PA1_username.tar
    % cd PA1/src
    % javac driver/MiniSVG.java
    % java driver.MiniSVG ../TestCases/input.svg --batch

Late Policy

Late assignments will be accepted up to 48 hours past the due date for a 10% deduction. The assignment will not be accepted past this period. Late means anything after 11:59pm on the day the assignment is due, including 12 midnight.

mstrout@cs.colostate.edu .... January 24, 2011