PCD SUMMARY
From Bioinformatics.Org Wiki
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
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
Textarea
type textarea
[ label “text to display beside the textarea” ]
[ default “the default text for the text” ] # specifies what text should be
# entered in the textbox by default
[ save true ] # specifies whether the file should be “saved” or deleted after
# program execution (true/false)
A textarea is a box into which 1 or more lines of text can be pasted. It is very different from a text/textbox, both with respect to how it appears in the menu, as well as how the name is used by BioLegato. In a menu, a text area appears as a box with both horizontal and vertical scroll bars. The contents of the box are exported to a tempfile. This file can be referenced using the name of the textarea object.
Example:
var "idnum"
type textarea
label " Paste in accession numbers"
default ""
For this menuitem, the shell command "cat %IDNUM%" would print the contents of the file to which the text was exported.
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
New in BioLegato 1.0.4
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. As we get more experience with this feature, we may discover that there are situations in which it should not be used.
PCD include
New in BioLegato 1.1.0
The @include directive allows source code from one file to be included in a PCD file, prior to parsing of the PCD at run time. As such, the @include directive is not strictly part of the formal PCD grammar, but is rather a pre-processing directive. At runtime, a .blmenu file is read, includes are substituted into the PCD code, and then the PCD code is parsed.
For example, in a menu for running BLAST, it would be nice if the PCD could specify that parts of the code that lists the databases available on the local system could be read from a file, rather than being hard-coded into the PCD.
For example, the PCD code might look like this
var "dbase"
type combobox
label "Database"
default 0
choices
@include $BIRCH/local/admin/BLAST/BLASTDB.pro.blinclude
"User-created BLAST database" "-db `echo %USERFILE% | sed 's/\(.*\)\..*/\1/'`"
"User-created file (FASTA format)" "-subject %USERFILE%"
where the file referenced contains the lines that should be inserted at that point in the code eg.
"Non-redundant protein (nr)" "-db nr" "RefSeq Protein" "-db refseq_protein" "Uniprot (swissprot)" "-db swissprot" "Protein sequences from PDB 3D protein structures (pdbaa)" "-db pdbaa" "Reference proteomes (landmark)" "-db landmark"
The PDB would be parsed as if the original file had been
var "dbase"
type combobox
label "Database"
default 0
choices
"Non-redundant protein (nr)" "-db nr"
"RefSeq Protein" "-db refseq_protein"
"Uniprot (swissprot)" "-db swissprot"
"Protein sequences from PDB 3D protein structures (pdbaa)" "-db pdbaa"
"Reference proteomes (landmark)" "-db landmark"
"User-created BLAST database" "-db `echo %USERFILE% | sed 's/\(.*\)\..*/\1/'`"
"User-created file (FASTA format)" "-subject %USERFILE%"
Syntax of the include line
The include line has the following structure:
[<whitespace>]@include<blank>[<blank>][quote]path[quote]
Leading whitespace allows for indention of the include line, described below. The file path may or may not be enclosed in double quotes.
Indentation of the include line
1. The include line is indented. The current indentation level will be applied to the included lines
@include path
2. The include line is left-justified (ie. not indented). This assumes that the source file is indented properly for the context of the insertion point.
@include path
It is probably better practice to indent the include line, and have the included file left-justified. Visually, it is more readable. As well, it becomes simpler to create include files without having to worry about proper indentation. Finally, if several different .blmenu file read the same include file, then indentation would be done in context by each .blmenu file.
Include file naming conventions
While there is no formal requirement for include file names, the following conventions are recommended:
- File extension should be .blinclude
- File extension should NOT be .pcd, .blmenu, .blitem or .biopcd. These file extensions are used by BioLegato for other purposes.
File paths
If the include file is in the same directory as the .blmenu file, the base file name can be used eg.
@include "nuc_keys.blinclude"
If the include file is in a different directory as the .blmenu file, a fully qualified file path must be given
@include "$BIRCH/local/admin/BLAST/localBLASTDB.blinclude"
Where fully qualified file paths are used, it is bad practice to hard-code the full file path in the include line. The preferred method, illustrated above, is to use an enviroment variable which resolves to the root of the file path.
Relative file paths (eg. ../../filename) are not supported.
Recursion
BioLegato include files may not contain @include directives. If the pre-processor detects an @include line, that line will be ignored, and an error message printed to the console.
Allowing @includes within include files could potentially result an infinite recursion, if an include file contained a reference to a previously-referenced include file.
References
BioPCD manuscript IJCA
Include in other languages
Inclusion vulnerability
