processing.mode.java.preproc

## Class PdePreprocessor

- Object
- - PdePreprocessor

-     public class PdePreprocessor
      extends Object

  Class that orchestrates preprocessing p5 syntax into straight Java.

  Current Preprocessor Subsitutions:
  - any function not specified as being protected or private will be made 'public'. this means that `void setup()` becomes `public void setup()`. This is important to note when coding with core.jar outside of the PDE.
  - `compiler.substitute_floats` (currently "substitute_f") treat doubles as floats, i.e. 12.3 becomes 12.3f so that people don't have to add f after their numbers all the time since it's confusing for beginners.
  - `compiler.enhanced_casting` byte(), char(), int(), float() works for casting. this is basic in the current implementation, but should be expanded as described above. color() works similarly to int(), however there is also a *function* called color(r, g, b) in p5.
  - `compiler.color_datatype` 'color' is aliased to 'int' as a datatype to represent ARGB packed into a single int, commonly used in p5 for pixels[] and other color operations. this is just a search/replace type thing, and it can be used interchangeably with int.
  - `compiler.web_colors` (currently "inline_web_colors") color c = #cc0080; should unpack to 0xffcc0080 (the ff at the top is so that the color is opaque), which is just an int.
  Other preprocessor functionality
  - detects what 'mode' the program is in: static (no function brackets at all, just assumes everything is in draw), active (setup plus draw or loop), and java mode (full java support). http://processing.org/reference/environment/

  The PDE Preprocessor is based on the Java Grammar that comes with ANTLR 2.7.2. Moving it forward to a new version of the grammar shouldn't be too difficult.

  Here's some info about the various files in this directory:

  `java.g:` this is the ANTLR grammar for Java 1.3/1.4 from the ANTLR distribution. It is in the public domain. The only change to this file from the original this file is the uncommenting of the clauses required to support assert().

  `java.tree.g:` this describes the Abstract Syntax Tree (AST) generated by java.g. It is only here as a reference for coders hacking on the preprocessor, it is not built or used at all. Note that pde.g overrides some of the java.g rules so that in PDE ASTs, there are a few minor differences. Also in the public domain.

  `pde.g:` this is the grammar and lexer for the PDE language itself. It subclasses the java.g grammar and lexer. There are a couple of overrides to java.g that I hope to convince the ANTLR folks to fold back into their grammar, but most of this file is highly specific to PDE itself. `PdeEmitter.java:` this class traverses the AST generated by the PDE Recognizer, and emits it as Java code, doing any necessary transformations along the way. It is based on JavaEmitter.java, available from antlr.org, written by Andy Tripp , who has given permission for it to be distributed under the GPL.

  `ExtendedCommonASTWithHiddenTokens.java:` this adds a necessary initialize() method, as well as a number of methods to allow for XML serialization of the parse tree in a such a way that the hidden tokens are visible. Much of the code is taken from the original CommonASTWithHiddenTokens class. I hope to convince the ANTLR folks to fold these changes back into that class so that this file will be unnecessary.

  `TokenStreamCopyingHiddenTokenFilter.java:` this class provides TokenStreamHiddenTokenFilters with the concept of tokens which can be copied so that they are seen by both the hidden token stream as well as the parser itself. This is useful when one wants to use an existing parser (like the Java parser included with ANTLR) that throws away some tokens to create a parse tree which can be used to spit out a copy of the code with only minor modifications. Partially derived from ANTLR code. I hope to convince the ANTLR folks to fold this functionality back into ANTLR proper as well.

  `whitespace_test.pde:` a torture test to ensure that the preprocessor is correctly preserving whitespace, comments, and other hidden tokens correctly. See the comments in the code for details about how to run the test.

  All other files in this directory are generated at build time by ANTLR itself. The ANTLR manual goes into a fair amount of detail about the what each type of file is for.

  Hacked to death in 2010 by

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `PdePreprocessor.Mode`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `SIZE_REGEX` Regular expression for parsing the size() method.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PdePreprocessor(String sketchName)`
    `PdePreprocessor(String sketchName, int tabSize)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addMethod(String methodName)`
    `void` | `debugAST(AST ast, boolean includeHidden)`
    `String[]` | `getCoreImports()`
    `String[]` | `getDefaultImports()`
    `boolean` | `hasMethod(String methodName)`
    `boolean` | `ignoreImport(String pkg)` Return true if this import should be removed from the code.
    `String[]` | `initSketchSize(String code, boolean sizeWarning)`
    `static String[]` | `parseSketchSize(String code, boolean fussy)` Parse a chunk of code and extract the size() command and its contents.
    `static String` | `scrubComments(String what)` Replace all commented portions of a given String as spaces.
    `void` | `setAdvClassName(String advClassName)`
    `void` | `setMode(PdePreprocessor.Mode mode)`
    `PreprocessorResult` | `write(Writer out, String program)`
    `PreprocessorResult` | `write(Writer out, String program, String[] codeFolderPackages)`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SIZE_REGEX

          public static final String SIZE_REGEX

      Regular expression for parsing the size() method. This should match against any uses of the size() function, whether numbers or variables or whatever. This way, no warning is shown if size() isn't actually used in the sketch, which is the case especially for anyone who is cutting and pasting from the reference.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PdePreprocessor

          public PdePreprocessor(String sketchName)

    - #### PdePreprocessor

          public PdePreprocessor(String sketchName,
                         int tabSize)

  - ### Method Detail

    - #### initSketchSize

          public String[] initSketchSize(String code,
                                boolean sizeWarning)
                                  throws SketchException

      Throws:
        `SketchException`

    - #### parseSketchSize

          public static String[] parseSketchSize(String code,
                                 boolean fussy)

      Parse a chunk of code and extract the size() command and its contents.
      Parameters:
        `code` - Usually the code from the main tab in the sketch
        `fussy` - true if it should show an error message if bad size()
      Returns:
        null if there was an error, otherwise an array (might contain some/all nulls)

    - #### scrubComments

          public static String scrubComments(String what)

      Replace all commented portions of a given String as spaces. Utility function used here and in the preprocessor.

    - #### addMethod

          public void addMethod(String methodName)

    - #### hasMethod

          public boolean hasMethod(String methodName)

    - #### setAdvClassName

          public void setAdvClassName(String advClassName)

    - #### setMode

          public void setMode(PdePreprocessor.Mode mode)

    - #### write

          public PreprocessorResult write(Writer out,
                                 String program)
                                   throws SketchException,
                                          RecognitionException,
                                          TokenStreamException

      Throws:
        `SketchException`
        `RecognitionException`
        `TokenStreamException`

    - #### write

          public PreprocessorResult write(Writer out,
                                 String program,
                                 String[] codeFolderPackages)
                                   throws SketchException,
                                          RecognitionException,
                                          TokenStreamException

      Throws:
        `SketchException`
        `RecognitionException`
        `TokenStreamException`

    - #### getCoreImports

          public String[] getCoreImports()

    - #### getDefaultImports

          public String[] getDefaultImports()

    - #### ignoreImport

          public boolean ignoreImport(String pkg)

      Return true if this import should be removed from the code. This is used for packages like processing.xml which no longer exist.
      Parameters:
        `pkg` - something like processing.xml.XMLElement or processing.xml.*
      Returns:
        true if this shouldn't be added to the final code

    - #### debugAST

          public void debugAST(AST ast,
                      boolean includeHidden)