PCD SUMMARY

From Bioinformatics.Org Wiki

Jump to: navigation, search

Click here to go back to: PCD


Contents

Language Overview

BioLegato uses a customized version of PCD, which does some semantics checking in its parser. The major differences are that every block is distinct in what it can contain, the only identifiers currently supported are predefined keywords, the only fields that are not keywords are those in the choices subsection, most of the fields must be specified in a specific order. The grammar is specified as follows (in a tree format showing the established hierarchy):

name
icon
tip
exec
system
var
    type
    label
    shell
    close
    save
    overwrite
    content
    canvas
    content
    min
    max
    default
    choices
         .....    ......
panel
    var
        ......
tabset
    tab “....”
        var
            ......

For the above tags, the following tags would only be used once per file: name. Icon, tip, exec, system. These tags correspond to the name of the menu item, the icon for the menu item, the tooltip text for the menu item, and the execution command for the menu item, respectively. The exec tag is used only for PCD commands which do not require the user to enter any parameters. These commands are launched immediately when the user clicks on the menu item (the user is not prompted for any input).

The tabset tag is used to indicate that a tabbed pane be created, and a tab created for each child tab tag.

The panel tag is used to create a panel for housing widgets. Panels are used to place more than one widget on the same line.

The var tag is the most versatile of all of the tags presented thus far. The var tag is used to specify program parameters (or variables) for the most part. The only exception to this is program buttons, which use the var tag, but are not parameters. Rather, program buttons are used to run commands using the program parameters specified by other var tags. The var field is specified as follows:

var "source"
    type          chooser
    label         "Source"
    default         1
    choices
        "Commercial" "C"
        "All"         "A"

Note that each var tag has name associated with it. The name for a var tag is specified on the same line as the var tag. In the case above, the name of the var tag is source. This means that whenever %source% is encountered in an exec field or a shell field, it is replaced with whatever choice is selected in the variable. In the above example, the variable is a drop-down box with two options (“Commercial” and “All”). Therefore, if the user of BioLegato were to select “Commercial” in this program, and click a button to perform a command, each instance of %source% in the button’s command would be replaced with “C” (the value of commercial).

Each var tag must have a different set of parameters in BioLegato, depending on what type of variable the var tag represents. For instance, using the chooser example above, each chooser variable must have the fields type and choices; type specifies what type of variable “Source” is, and choices specifies which choices should be available to the user. The fields default and label are optional fields, which specify the default value to select in the chooser (the first value the user will see selected before he or she changes it), and the text to display to the left of the chooser (this is so the user can understand what parameter the chooser is selecting for the program defined by the PCD menu).

The following list contains all of the var tag types currently supported in BioLegato. The parameters each var tag supports are listed below each type. The parameters in brackets [] are optional parameters. Each parameter below must be specified in the exact order that they are listed in each var type description (e.g. for buttons - type then label, then shell, then close):

Widgets

Buttons

   type button
 [ label “the text to display in the button” ]
   shell “the command to execute when the button is clicked”
 [ close false ]    # whether or not to close the parameter window
                    # when the button is clicked

Chooser, Comboboxes, or Lists

   type chooser   # can also be combobox or list
 [ label “the text to display beside the list/combobx/chooser” ]
 [ default 0 ]    # specifies which choice should be selected by default
   choices
       “abc” “1”    # each line of the format “name” “value” specifies
                    # a choice within the list/combobox/chooser
                    # the name specifies what the user will see and select
                    # whereas the value will specify what the program
                    # sees from the user’s selection

Text | Textboxes

   type text
 [ label “the text to display beside the textbox” ]
 [ default “the default text for the text” ]   # specifies what text should be
                                               # entered in the textbox by default

Number

   type number
   label “the text to display beside the number entry widget” ]
   min 0          # specifies the minimum number selectable by the number widget
   max 10000      # specifies the maximum number selectable by the number widget
 [ default 0 ]    # specifies the default number to be selected in the widget

File (an external file specified by the user)

   type file
 [ default “the default filename to have selected” ]

Tempfile (a temporary file containing all of the data selected in BioLegato’s main canvas)

   type tempfile
   direction out  # direction can either be in or out
                  # the direction specifies whether the file will be read as input
                  # for the program (in), or the file will receive output from the
                  # program, which will be displayed/received by the canvas (out)
   format fasta   # the file format represented by the tempfile
                  # currently BioLegato supports the following file format options:
                  #     csv, tsv, fasta, flat, gde, genbank, raw, mask
 [ save true ]    # specifies whether the file should be “saved” or deleted after
                  # program execution (true/false)
 [ overwrite true ]   # this parameter determines whether the contents of the
                      # file will replace the current selection when the file
                      # is read back into the canvas
 [ content canvas ]   # this parameter currently accepts two values:
                      #     canvas, selection
                      # If direction=in,this parameter determines whether the data that is
                      # written to the temp file is the current seletion (selection)
                      # or the entire contents of BioLegato’s main canvas (canvas)
                      # If direction=out and overwrite is true, the contents of the canvas
                      # are replaced by the contents of the file being read in.

Environment Variable Substitution

BioLegato implements two ways to substitute the values of system environment variables into PCD.

Substitution in shell commands

When BioLegato processes a shell commmand, it substitutes PCD variable values into the command, but leaves the rest of the command string unchanged. Consequently, any environment variable included in the command will be substituted correctly by the shell when the command is executed. Example:

       shell       "$BIRCH/script/chooseviewer.py $BIRCH/doc/xylem/shuffle.txt"

Substitution in PCD variable value fields

BioLegato also supports environment variable substitution in value fields for several data types. One limitation is that the first character after the "$" MUST be an upper or lowercase letter ie. a-z or A-Z.

text

The environment variable reference MUST be enclosed in quotes. No other text besides the enviroment variable reference may be within the quotes.

var "address"
    type        text
    label       "    email address"
    default     "$BL_EMAIL"

number

The environment variable reference is NOT enclosed in quotes. No other text besides the environment variable reference is permitted.

var "threads"
    type        number
    label       "Number of threads to use"
    min         1
    max         $BL_CORES
    default     4

Note: Although any value field in the above list may be coded in the .blmenu file as an environment variable, there may be cases in which this is not valid to do. This feature is new in BioLegato 1.0.4. As we get more experience with this feature, we may discover that there are situations in which it should not be used.

PCD include (NOT CURRENTLY IMPLEMENTED)

This feature is still at the proposal stage. It is intended to be similar to the #include directive in C-type languages, allowing source code from one file to be included at compile time in another file.

Personal tools
Namespaces
Variants
Actions
wiki navigation
Toolbox