Skip to main content
Jump to: navigation, search

Difference between revisions of "Painfully Simple Form"

Line 113: Line 113:
  
 
Parents are distinguished using the parent statement and the name of the parent as the value. Here's an example of two Entries that are dependent on a third such Entry:  
 
Parents are distinguished using the parent statement and the name of the parent as the value. Here's an example of two Entries that are dependent on a third such Entry:  
 
 
 
  
 
<pre style="white-space: pre-wrap;  
 
<pre style="white-space: pre-wrap;  

Revision as of 17:32, 9 February 2015

A Painfully Simple Form in ICE is a Form that was created by parsing Entries and DataComponents from a file written in the Painfully Simple Form File Format

The Painfully Simple Form File Format

The Painfully Simple Form file format (PSF) was designed to be overly simple for developers who are hooking their codes to ICE and painfully simple to parse. It is mostly the same as an ini file or a Java properties file, but with small differences that make it specific to ICE.

Comments

Any text after a "#" or "//" will be ignored by the parser whether it is a line of text commenting on a section or comments after a statement.

#Ignored text above a block
group=My Group //Ignored text after a statement
groupDescription=My Group #More ignored text

Whitespace

Empty lines are required between blocks. Whitespace within statements is kept (because all statements are treated as strings).

Item type and name

The name, description, and type of the Form should be the first thing specified in the PSF. At the moment, Item type should be either Model or Simulation.

#Form name, description and type
formName=PSF Wiki Article Form
formDescription A PSF Wiki Article Sample 
formType=Model

DataComponents

ICE DataComponents are collections of Entries and they can be described in a PSF. The "group=" statement is used to create a DataComponent and the "groupDescription=" tag is used to describe it. Both the name and description must be present or ICE will not read the file. All of the DataComponents should be specified in a block above the Entries.

#The DataComponents block
group=1st Data Component
groupDescription=The First Data Component
group=2nd Data Component
groupDescription=The Second Data Component
group=Black Sabbath Songs
groupDescription=A group of songs written and performed by the popular band "Black Sabbath"

#The Entry blocks will appear below this line

Entries

The ICE Entry class represents a value in a data file and contains a "full description" of that data, including a name, description, and default value among other things. It is possible to specify any Entry in a psf file, but these Entries will not have tailored setup() and update() operations. The name and description statements can be any string and there may be multiple allowed values for each Entry, depending on its type. The allowedValueType is the same as that for an Entry and has three possible values:


  • Discrete, meaning that the value of the Entry must be one of the allowed values
  • Continuous, meaning that it is a floating point number that is valid between the two allowed values (which also means that you can only have two allowed values)

*Undefined, meaning that it can be anything, like a string or a file name.

Entry with a small marker or note that could be used, for example, to correlate it with some external source or markup.

Each Entry needs to be added to a DataComponent using the group= flag. This should be one of the groups listed in the groups block. If it is not one of the predefined groups, or if it is missing all together, this Entry will be discarded.

Here's an example with two Entries, one discrete and one continuous:


name=Coolant Temperature                                                        //The name that a user will see
description=The temperature of the coolant that surrounds the assembly and pins //A description that will help the user
defaultValue=550                                                                //The default value
allowedValueType=Continuous                                                     //Indicates that the value can be anything between 550 and 650 K.
allowedValue=550                                                                //The lower bound of the range
allowedValue=650                                                                //The upper bound of the range
tag=coolantTemperature                                                          //A tag to mark it
group=Coolant Group                                                             //The group

name=Number of Pins
description=The number of pins in an assembly
defaultValue=289
allowedValueType=Discrete
allowedValue=196
allowedValue=289
tag=numberOfPins
group=Pin Group

Entries can also claim that they are dependent on the state of another Entry. The PSF natively supports a boolean dependency, where Entries can mark themselves as dependent on the on/off state of a parent Entry. When the parent flips between on/off states, the child will automatically be notified. The catch here is that the parent must be a boolean query ("Enable multiprocessing: y/n" for example) and that the value of that parent is one of:

  • not ready
  • yes
  • no
  • y
  • n
  • on
  • off
  • true
  • false
  • enabled
  • disabled

Parents are distinguished using the parent statement and the name of the parent as the value. Here's an example of two Entries that are dependent on a third such Entry:

name=Coolant Temperature                                                        //The name that a user will see
description=The temperature of the coolant that surrounds the assembly and pins //A description that will help the user
defaultValue=550                                                                //The default value
allowedValueType=Continuous                                                     //Indicates that the value can be anything between 550 and 650 K.
allowedValue=550                                                                //The lower bound of the range
allowedValue=650                                                                //The upper bound of the range
tag=coolantTemperature                                                          //A tag to mark it
parent=Full Assembly Flag                                                       //The parent
group=Assembly                                                                  //The group

name=Number of Pins
description=The number of pins in an assembly
defaultValue=289
allowedValueType=Discrete
allowedValue=196
allowedValue=289
tag=numberOfPins
parent=Full Assembly Flag
group=Assembly

name=Full Assembly Flag
description=True if a full assembly should be modeled, false if not
defaultValue=false
allowedValueType=Discrete
allowedValue=true
allowedValue=false
tag=fullAssemblyFlag
group=Assembly


A Complete File


Back to the top