PXLab Manual

[Home]    [Content]    [Previous Chapter]    [Next Chapter]


Design File Grammar

This chapter describes the grammar of a PXLab design file. The grammar is defined by a language definition file for the JavaCC parser generator. This parser generator is used to automatically generate the parser for the PXLab design language. Design files are ASCII files and may be edited by any ASCII text editor. Design files may also be created by the PXLab Experimental Design Editor. An automatically generated BNF-version of the grammar is available too.

Problems with the design file grammar may best be analyzed with the parser debugging option: '-D parser'. If this option is given at runtime then a complete parser protocol is generated.

Keywords

The grammar uses some key words which may not be used as names since these represent grammar tokens. These are: adjustable, AssignmentGroup, Block, BlockData, BlockEnd, Condition, ConditionTable, Context, CovariateFactor, DependentFactor, Experiment, ExperimentData, FactorLevel, Factors, false, IndependentFactor, new, Procedure, ProcedureData, ProcedureEnd, RandomFactor, Session, SessionData, SessionEnd, Trial, TrialData, true.

Productions

Start Symbol

A design file is a declaration of the experiment:

   experimentDeclaration ::= 
      "Experiment" parameterIdentifiers "{"
         contextDeclaration 
         ( factorsDeclaration )?
         ( procedureDeclaration )?
      "}"

The experiment declaration may have an argument list and contains context, factors, and procedure declarations in its body.

Context Declaration: Display Lists and Global Assignments

The runtime context defines and creates global parameter values and defines display lists for blocks, sessions, and trials.

   contextDeclaration ::= 
      "Context" parameterIdentifiers "{"
         ( 
	    (   displayListDeclaration
               | assignmentGroupDeclaration
            )
         )* 
      "}"

The context declaration may also have arguments and contains a body with display list declarations and groups of parameter assignments.

Display list declarations define what actually happens during a trial and during block start/end and session start/end events. Display objects are PXLab's primitive units of displays. A single trial contains a sequence of display objects which make up everything which is presented to the subject. Display object properties are controlled by parameters. The sequence of display objects is controlled by the display list declaration.

   displayListDeclaration ::= 
      (
         "ExperimentData" 
         "Procedure" 
	 | "ProcedureEnd"
	 | "ProcedureData"
         | "Session" 
	 | "SessionEnd"
	 | "SessionData"
	 | "Block"
	 | "BlockEnd"
	 | "BlockData"
	 | "Trial"
	 | "TrialData"
      ) (":" Identifier )? displayListParameterIdentifiers "{" 
         ( displayDeclaration )*
      "}"

There are 12 possible display list types: trial, trial data, block start/end/data, session start/end/data, procedure start/end/data and experiment data. Multiple display lists of a single type may be defined by adding an optional identifier postfix to the display list type name. Every list declaration may have arguments and contains a list of display declarations in its body.

   displayDeclaration ::= 
      displayIdentifier displayListParameterIdentifiers
         ( ";" 
         | ( 
            "{" ( parameterValueAssignment )*
	    "}" 
	   )
	 )

A display component has a name and an argument list. The name must be unique within the display list. It must be a Displayor a DataDisplay object subclass name possibly followed by an instance identifier.

   displayIdentifier ::= 
      Identifier ( ":" Identifier )?

The display component may or may not have a body. The body, if it exists, contains a list of parameter assignments. These must be parameters of the display object. The display object name is the class name of the respective display. A parameter assignment usually assigns a value to an experimental parameter. It also may create a new parameter and may declare a parameter as an adjustable variable. Note that new parameter declarations are allowed in assignment groups only.

   globalParameterValueAssignment ::= 
      ( "new" )? parameterValueAssignment
   displayParameterValueAssignment ::= 
      ( "adjustable" )? parameterValueAssignment
   parameterValueAssignment ::= 
      Identifier ( "." Identifier )* "=" parameterValue ";"

Global parameter assignments are grouped together in assignment groups.

   assignmentGroupDeclaration ::= 
      "AssignmentGroup" parameterIdentifiers "{" 
         ( globalParameterValueAssignment )* 
      "}"

We have not yet defined parameter identifier lists. These are lists of experimental parameter names.

   parameterIdentifiers ::= 
      "(" ( parameterIdentifier ( "," parameterIdentifier )* )? ")" 

   parameterIdentifier ::= 
      ( displayListIdentifier "." displayIdentifier "." )? Identifier 

An experimental parameter is named according to the field name in its class. Parameters of display objects used outside of the display declaration have to be fully qualified by the display list and the display names as a prefix. The display list prefix may be omitted when the display parameter is used as an argument of a display list declaration.

   displayListParameterIdentifiers ::= 
      "(" ( displayListParameterIdentifier ( "," displayListParameterIdentifier )* )? ")" 

   displayListParameterIdentifier ::= 
      ( ( displayListIdentifier "." )? displayIdentifier "." )? Identifier 

Experimental Factors and Conditions

The factors section is optional. It may be used to define experimental factors, factor levels and associate these with experimental display parameters. These associations are defined via a condition table. The factors declaration simply defines a list of factors and possibly a condition table. Note that there may be only a single condition table although the grammar does not control this.

   factorsDeclaration ::= 
      "Factors" parameterIdentifiers "{"
         ( ( factorDeclaration | conditionTableDeclaration ) )*
      "}"

The declaration of a factor specifies its name and possibly its associated experimental parameters as an argument and its list of possible factor levels in a block. There are three different types of factors: independent, dependent, and covariate factors.

   factorDeclaration ::= 
      ( "RandomFactor"
         | "IndependentFactor" 
         | "DependentFactor"
         | "CovariateFactor"
      ) parameterIdentifiers
      ( ";"
	| "{" ( factorLevelDeclaration )*
	  "}" 
      )

A factor level is a parameter value possibly followed by values of associated experimental parameters.

   factorLevelDeclaration ::= 
      "FactorLevel" parameterValues ";"

The declaration of a condition table specifies the factor names and their associated experimental parameters as arguments and the list of possible conditions in a block.

   conditionTableDeclaration ::= 
      "ConditionTable" parameterIdentifiers
      ( ";"
	| "{" ( conditionDeclaration )*
	  "}" 
      )

A condition declaration is a list of factor level values combined with the values of the associated experimental parameters.

   conditionDeclaration ::= 
      "Condition" parameterValues ";"

Procedure, Sessions, Blocks, and Trials

The procedural units sessions, blocks, and trials are collected together in the procedure declaration. These, however, are preceded by a section which defines the runtime arguments of sessions, blocks, and trials.

   procedureDeclaration ::= 
      "Procedure" parameterValues "{"
         ( sessionDeclaration )*
      "}"

Session, blocks, and trials all have local parameter values. Blocks are nested into sessions and trials are nested into blocks.

   sessionDeclaration ::= 
      "Session" ( ":" Identifier )? parameterValues "{" ( blockDeclaration )* "}"

   blockDeclaration ::= 
      "Block" ( ":" Identifier )? parameterValues "{" ( trialDeclaration )* "}"

   trialDeclaration ::= 
      "Trial" ( ":" Identifier )? parameterValues ";"

Procedure units which have an identifier postfix require a corresponding display list definition.

The argument value lists of factor levels, conditions, sessions, blocks, and trials are values of experimental parameters.

   parameterValues ::= 
      "(" ( parameterValue ( "," parameterValue )* )? ")"

Parameter Values

The rest of the grammar description is concerned with methods to express parameter values.

   parameterValue ::= 
      ( defaultValue
        | array
        | replicator
        | expression
      )

   defaultValue ::=
      "?" 

   array ::= 
      "[" constantValueList "]"

   replicator ::=
     "<" constantValueList ">"

   constantValueList ::= 
      constantValue ( "," constantValue )* 

   constantValue ::= 
      valueIdentifier | signedLiteral

   valueIdentifier ::= 
      ( ( ( "de.pxlab." | "java." | "javax." ) 
          ( Identifier "." )* 
        ) | ( displayListIdentifier "." displayIdentifier "." )
      )? Identifier

   signedLiteral ::=
      ( "+" | "-" )? literal

Experimental parameter values may in some cases be undefined. The question mark is used to indicate this. All experimental parameters actually are array valued, however, single valued expressions may also be used. Array valued parameters may only contain constant values as their components. These are class constants defined as static integers in a Java class or are possible signed literal constants.

PXLab allows simple arithmetic expressions. This includes addition and multiplication and there also is a conditional expression for assigning conditional values to a parameter. The condition must be an experimental parameter too. Note that expression evaluation is done at runtime!

   expression ::= 
      conditionalOrExpression ( "?" expression ":" expression )?

   conditionalOrExpression ::= 
      conditionalAndExpression ( "||" conditionalAndExpression )*

   conditionalAndExpression ::= 
      inclusiveOrExpression ( "&&" inclusiveOrExpression )*

   inclusiveOrExpression ::=
      exclusiveOrExpression ( "|" exclusiveOrExpression )*

   exclusiveOrExpression ::= 
      andExpression ( "^" andExpression )*

   andExpression ::=
      equalityExpression ( "&" equalityExpression )*

   equalityExpression ::=
      relationalExpression ( ( "==" | "!=" ) relationalExpression )*

   relationalExpression ::=
      shiftExpression ( ( "<" | ">" | "<=" | ">=" ) shiftExpression )*

   shiftExpression ::= 
      additiveExpression ( ( "<<" | ">>" | ">>>" ) additiveExpression )*

   additiveExpression ::= 
      multiplicativeExpression ( ( "+" | "-" ) multiplicativeExpression )*
  
   multiplicativeExpression ::= 
      unaryExpression ( ( "*" | "/" | "%" ) unaryExpression )*

   unaryExpression ::= 
      ( ( "+" | "-" | "~" | "!" ) unaryExpression ) | primaryExpression

   primaryExpression ::= 
      literal 
      | Identifier parameterValues
      | valueIdentifier
      | "(" expression ")"

   literal ::=
      INTEGER_LITERAL 
      | FLOATING_POINT_LITERAL 
      | STRING_LITERAL 
      | "true" 
      | "false" 

Integer, floating point, and string literals are defined as usual. An identifier followed by parameter values is a function call. Identifiers start with a letter or an underscore character and may have arbitrary length.

[This file was last updated on July 15, 2010, 12:07:01.]

[Home]    [Content]    [Previous Chapter]    [Next Chapter]