All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface parse.Parsable

public interface Parsable

extends Serializable

This code is (c) 1996 Leemon Baird <leemon@cs.cmu.edu>, http://www.cs.cmu.edu/~baird
The source and object code may be redistributed freely. If the code is modified, please state so in the comments.

Version:

1.1, 21 July 97

Author:

Leemon Baird

See Also:

Parser

symbol

The symbolic name for this object, or null if it's not in the symbol table.

BNF(int)

Return a string representing the right side of the BNF definition of what this class parses.

getParameters(int)

Return a parameter array if BNF(), parse(), and unparse() are to be automated, null otherwise.

initialize(int)

Initialize, either partially or completely.

parse(Parser, int)

Return an object representing the results of parsing, starting at the current token.

unparse(Unparser, int)

Emit a series of strings that represents this object and its current state, possibly calling the unparse() methods of child objects in the process.

 public static final String symbol

The symbolic name for this object, or null if it's not in the symbol table. This is filled in automatically by the parser and used by the unparser to handle #DEF/#USE statements correctly.

 public abstract String BNF(int lang)

Return a string representing the right side of the BNF definition of what this class parses. Use single quotes around terminals. Use identifiers for nonterminals that are parsed by a specific class. Use angled brackets <> around identifiers for nonterminals that are parsed by any class of a specific type, where the first token in the string being parsed will be the name of the class that parses the rest of the string. Use parentheses to group, [] for zero or one copy the * for 0 or more, and + for 1 or more. Use | for OR, and the dot (.) to start a short comment for this class. The parameter lang specifies the language for parsing and unparsing that the BNF describes. Finally, there should be a short, 4-5 word comment starting with "//" and ending with "." followed by more detailed comments explaining what exactly the object does.

 public abstract Object parse(Parser p,
                              int lang) throws ParserException

Return an object representing the results of parsing, starting at the current token. Return null in case of error. The parameter lang specifies the language to parse.

Throws: ParserException

parser didn't find the required token

 public abstract void unparse(Unparser u,
                              int lang)

Emit a series of strings that represents this object and its current state, possibly calling the unparse() methods of child objects in the process. The file created in this way should be readable by parse() to recreate the objects. Lang is the language to unparse into (0 is the "normal" language). If an object parses one language then unparses another, it will act as a translator between the languages. The cursor should end up on the same line as the last output (i.e. end with an emit() not an emitLine()).

 public abstract Object[][] getParameters(int lang)

Return a parameter array if BNF(), parse(), and unparse() are to be automated, null otherwise. If this method returns something other than null, then the BNF(), parse(), and unparse() methods will never be called, so they can be very simple (doing nothing but returning null); This automatic system works for any

 The array is of type Object[][], and should be of the form:
    {{String},              //a short comment, period, then longer comment for BNF documentation for this Class
     {String, var, String,  //the name of a parameter in the BNF, and the Pointer to hold the parsed value
      String, var, String,  //another parameter
      String, var, String}, //another parameter, etc. (zero or more pairs in all)
     {var,                  //a Pointer holding a value to parse and unparse only during "save-all" experiment saves
      var,                  //another such parameter
      var}}                 //another such parameter (zero or more in all)
                                                                                        

In the above description, a Pointer such as a PInt means that an integer expression will be parsed and placed into the existing PInt. The PInt itself should already exist before returning this array. At any point in the array where a Pointer is legal, it is also legal to put a single-element Parsable[] array. So, if Foo implements Parsable, then it is legal to put a variable there that contains a Foo[1] array. So, for example:

   IntExp          numCopies=new IntExp(0);
   PictureDrawer[] pic={null};
   Object[][]      parameters=
     {{"Draw N copies of a picture. The PictureDrawer must be given."},
      {"N",      numCopies,"the number of copies",
       "picture",pic,      "the picture"},
      {}};
                                                                                        

This works if IntExp is a Pointer and PictureDrawer is a Parsable. After parsing, the number of copies will be an integer stored in numCopies.val and the PictureDrawer will be stored in pic[0]. The kind of parsing that is done depends on how the variable is defined. Assuming that MyClass extends Pointer, and MyType implements Parsable, the four types of parameters can be declared this way: MyClass a=new MyClass(); //will parse the parameters for Parsable class MyClass MyType[] b={null}; //will parse the name of a class of type MyType, then its parameters Parsable[][] c={new MyType[0]}; //will parse a list of objects of type MyParsable, parsing the class name and parameters for each one. Answer is in c[0][0], c[0][1], c[0][2], ... Parsable[][] d={new MyClass[0],null}; //will parse a list of objects of class MyClass, parsing the parameters for each one. Answer is in d[0][0], d[0][1], d[0][2], ... MyClass e=new MyClass(); //a variable that is saved but not parsed MyClass f=new MyClass(); //a variable that is saved but not parsed Object[][] parameters= {{"A short description. The longer description of this class comes after the period"}, {"par1", a, "comment on this parameter", "par2", b, "another comment", "par3", c, "comment", "par4", d, "comment"}, {e,f}} //list of all the variables to save, with no strings The parameters array contains 3 subarrays. Optionally, a fourth array can be added. If this array is {"{","}"} then it has no effect, and the parameters for this object will still be in curly brackets. If the fourth array is {"[","]"} or {"<",">"} or {"(",")"} or any other pair of single-character strings other than letters and digits and "#", then the parameters will have to be enclosed within those characters rather than within curly brackets. If the empty strings {"",""} are used, then no characters surround the parameters at all. It is HIGHLY encouraged that his feature NEVER be used except when ABSOLUTELY necessary!

 public abstract void initialize(int level)

Initialize, either partially or completely. After all objects have been parsed, then all Watcher objects have had setWatchManager called, all objects should then have initialize(0) called. Also, after an object is cloned, the new copy might have initialize(0) called. If the level is greater than 0, then the initialization is less complete. For example, in a reinforcement learning experiment, the different levels are:

  -1 new object:     initialize everything, allocate new arrays
                     (this is only called once, after a saved experiment has been loaded back in)
   0 new object:     initialize everything, allocate new arrays
                     (this is only called once, after reading in an experiment description that
                      wasn't created by saving an experiment.  Either 0 or -1, but not both,
                      are called for any given execution of the program.)
   1 new experiment: initialize everything, don't reallocate arrays,
                     set the random number seed to some standard value
   2 new run         initialize weights, but don't reset the seed,
                     don't forget results of previous runs
   3 new trial       initialize state, but don't reset the seed or
                     weights or previous results                        

All Packages  Class Hierarchy  This Package  Previous  Next  Index