CASA XML
Introduction
The XML files found in code/xmlcasa/implement/* describe the interfaces to the tool and tasks found in CASA. These XML files use a small number of element tags to describe the interfaces. By using the following elements with their attributes we can fairly well describe the interface as well as specifying system wide defaults and in the near future enumerated types for input arguments.
While there are some code excerpts to illustrate how an element is constructed, the best (and hopefully working) examples will be found in the xml files themselves located in code/xmlcasa/implement/*/*.xml.
XMLCASA Element Tags
| Tag Name | Description |
|---|---|
| tool | A tool typically has the following elements, short description, description, one or more methods and an example. |
| task | A task is very similar to a tool method. The main difference being it will be a complex set of calls to one or more tool methods. As such it may contain output, inout, and input elements. It should always have a shortdescription, description, and returns elements. |
| code | Helper code for the C++ code generaterator. It will contain the private and or include elements. Currently no attributes. |
| include | Additional include statements, handy for forward declarations. During development this should just be a single file to avoid having to rerun the code generator each time a change is made. Currently no attributes. |
| private | What to additionally include in the private part of a class. Also during development this should just be a single include file to avoid having to rerun the code generator when making changes. Currently no attributes. |
| shortdescription | A short terse description, typically one or two lines. This will typically appear in the scripting languages help text. Currently no attributes. |
| description | A more detail description of what the tool, task, method, parameter is. The use of latex in this block is supported for generating html and pdf documentation. Currently no attributes. |
| method | A method or function of an object belonging to a tool. A method will typically contain a shortdescription, description, returns, and example elements. It may also have output, inout, and input elements. |
| output | An output element consists of one or more param elements that will be returned by the method or task. Currently no attributes. |
| inout | An inout element consists of one or more param elements that will be used as input for a method or task and possibly modified and returned as output. Currently no attributes. |
| input | An input element consists of one or more param elements that will be used as input by a method or task. Other tools maybe used as input if properly registered with the system. Currently no attributes. |
| param | A param element describes an argument to a task or tool method. Typically it will have a description element and if it has a default value on or more value elements. |
| any |
An any type, for unknown or records, i.e. string or int. |
| comments | The comments element |
| link | The link element |
| defaultrecord | The default record |
| value | A number or string, can be nested. If the value element is specfied in an input element, multiple values maybe present to indicate an enumeration of allowed values. The last value specified will be the default. This behavior may change, i.e. an addtional default attribute could be added to explicity identify the default value. |
| returns | Description of what the Method/Task returns, similar to a param element. |
| example | An example element is used to demonstrate how a tool, task or method is used by the user. We will likely make additional tags or attributes to allow inclusions of working files. |
XMLCASA Element Tag Attributes
tool
Tag for the definition of a tool, consisting of one or more methods bound to an object.
| Type | Name | Required? | Description |
|---|---|---|---|
| Attribute | name | yes | This is the name of the tool. |
| Attribute | module | yes | The name of the module to which the tool belongs |
| Element | shortdescription | yes | A short terse description, typically one or two lines. This will typically appear in the scripting languages help text. |
| Element | code | no | Helper code for the C++ code generatory. |
| Entity | output | no | One or more parameter elements that will be returned by the task. |
| Element | method | yes | Description of the actual methods implemented by this tool. |
Example:
tool for synthesis imaging
...
task
A task is an atomic set of calls to one or more tool methods, which produces a specific output, or modifies the state of the input files. It should not modify the global state of the system.
| Type | Name | Required? | Description |
|---|---|---|---|
| Attribute | name | yes | This is the name of the task. |
| Attribute | module | no | This is the module to which the task belongs |
| Attribute | category | ? | Which catagory of tasks this belongs to and should be listed in under tasklist |
| Entity | shortdescription | Yes | A short terse description, typically one or two lines. This will typically appear in the scripting languages help text. |
| Entity | input | no | One or more param elements and constraints that will be used as input by a method or task. |
| Entity | output | no | One or more parameter elements that will be returned by the task. |
| Entity | inout | no | Do we actually support this?. |
Example:
Apply calibrations solutions(s) to data.
code
The code tag designates helper files used in the code generation process.
| Type | Name | Required? | Description |
|---|---|---|---|
| Element | include | no | A file path to be included in the code generation. |
| Element | private | no | A file path to be included in the private portion of the class. |
Example:
xmlcasa/synthesis/imager_forward.h
xmlcasa/synthesis/imager_priave.h
include
Additional include statements, handy for forward declarations. During development this should just be a single file to avoid having to rerun the code generator each time a change is made. Currently no attributes or sub-elements supported.
Example: xmlcasa/synthesis/imager_forward.h
private
What to additionally include in the private part of a class. Also during development this should just be a single include file to avoid having to rerun the code generator when making changes.
| Type | Name | Required? | Description |
|---|---|---|---|
| Element | include | no | A file path to be included in the private portion of the code generated class. |
Example: xmlcasa/synthesis/imager_private.h
shortdescription
A short terse description, typically one or two lines. This will typically appear in the scripting languages help text. No attributes or sub-elements are currently supported. Please use only plain text in this description.
Example: A one or two line plane text description of the enclosing element.
description
A more detail description of what the tool, task, method, parameter is. The use of latex in this block is supported for generating html and pdf documentation. Currently no attributes or sub-elements are supported.
Example: A more lenghtly description of the element, mostly used for method based documentation. Latex is supported as are hypertext links.
defaultrecord
The default record Currently no attributes.
method
A method or function of an object belonging to a tool.
| Type | Name | Required? | Description |
|---|---|---|---|
| Attribute | type | yes | Allowed options are function or constructor. Currently constructors are ignored. |
| Attribute | name | yes | This is the name of the method |
| Element | shortdescription | yes | A short terse description, typically one or two lines. This will typically appear in the scripting languages help text. |
| Element | description | Yes | A longer description of the method. This will be used to populate the method description in the generated documentation. |
| Element | input | no | One or more param elements and constraints that will be used as input. |
| Entity | output | no | One or more parameter elements that will be returned by the task. |
| Element | inout | no | Do we actually support this?. |
| Element | returns | yes | Description of the return value of the method |
| Element | example | yes | Documenation string demonstrating usage of the method. |
Example:
Define image coordinate systems FTMs This method allows the specification of a coordinate system for the FTM configured for this imaging tool.
output
An output element consists of one or more param elements that will be returned by the method or task.
| Type | Name | Required? | Description |
|---|---|---|---|
| Element | param | yes | Description of an output parameter. |
Example:
inout
An inout element consists of one or more param elements that will be used as input for a method or tasked and possibly modified and returned as output.
input
An input element consists of one or more param elements that will be used as input by a method or task. Other tools maybe used as input if properly registered with the system.
| Type | Name | Required? | Description |
|---|---|---|---|
| Element | param | yes | Description of an input parameter. |
Example:
Number of pixels on a side
Recommended maximum cellsize
param
A param element describes an argument to a task or tool method.
| Type | Name | Required? | Description |
|---|---|---|---|
| Attribute | name | yes | The name of the parameter. |
| Attribute | type | yes | Choose from the following types: any, int, bool, string, double, intArray, boolArray, stringArray, doubleArray, casa*(tool) |
| Attribute | mustexist | no | Flag to check that a specified file (usually a ms) must exist to validate. |
| Attribute | subparam | no | Designates that this parameter is a subparameter of another subparameter. Default value is no. |
| Attribute | units | no | If present the parameter is treated as a quanta. |
| Element | description | yes | Short summary of the meaning of this parameter. |
| Element | value | yes | The default value of the parameter. |
| Element | example | no | Example usage of a parameter, particularly useful in the context of tasks. |
| Element | allowed | no | Constraints on the permitted values of the parameter. |
| Element | any | no | Refinement of the definition when type is any. |
Example:
fraction of the OFF data to mark
10%
returns
Description of what the Method/Task returns, similar to a param element.
| Attribute | Required? | Description |
|---|---|---|
| type | yes | You may specify a return type as one of the types specified in the param xsi:type attribute, additionally you may specify a tool as a return type. |
Example:
example
An example element is used to demonstrate how a tool, task or method is used by the user. We will likely make additional tags or attributes to allow inclusions of working files. Currently no attributes.
Example:
im.ft(model='3C273XC1.model', complist='3C273XC1.complist');
im.makeimage(type='residual', image='3C273XC1.residual')
im.makeimage(type='psf', image='3C273XC1.psf') \end{verbatim}
any
An any type, for unknown or records, i.e. string or int.
| Attribute | Required? | Description |
|---|---|---|
| type | yes | Currently an any element may be specified as either a record or variant |
Example:
threshold for mask
0.0Jy
1.0
amplitude of Gaussian, or 3 numeric values
link
The link element. A way to specify the a link to an external document. value.
| Attribute | Required? | Description |
|---|---|---|
| anchor | yes | HTML locator |
comments
The comments element. No attributes currently.
Example:
Some useful comment to future maintainers
value
A number or string, can be nested. If the value element is specfied in an input element, multiple values maybe present to indicate an enumeration of allowed values. The last value specified will be the default. This behavior may change, i.e. an addtional default attribute could be added to explicity identify the default value.
| Attribute | Required? | Description |
|---|---|---|
| name | no | A value my have an optional name, the name is required if part of a record element. |
| type | no | The type may be specified as either vector, scalar, array, or struct(for complex) |
| xsi:type | no | Maybe any of the types in specified in the param xsi:type attribute |
| shape | no | Currently not implemented |
Examples:
Setting a "Quantity"
Start velocity (e.g. '20Km/s') 0.0
Example setting an array with one value.
Start channels (0-relative) 0
Example of an empty array
Spectral Window Ids (0 relative) to select
Example setting a vector with more than one value
Flag VLA quacks -- scan interval and quack length, in seconds 0 0
Example setting a complex array
The flux value. A vector with four real or complex numbers
1.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
Example of a multiple choice, note default is last option.
The polarization of the value field. ``Stokes'', ``linear'' or ``circular'' Circular Linear Stokes