nraonrao
 NRAO Home > CASA > Programming > XML Element Tags

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 NameDescription
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

A tool typically has the following elements, short description, description, one or more methods and an example.

AttributeRequired?Description
name yesThis is the name of the tool.
module noThis is the module to which the tool belongs
<tool name="logsink" module="logsink"> <shortdescription>tool for logsink</shortdescription> <description></description> .... </tool>

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.

AttributeRequired?Description
name yesThis is the name of the task.
module no This is the module to which the task belongs
<task name="imagertask" module="imagertask"> <shortdescription>tool for imager tasks</shortdescription> <description>imagertask is a tool that accomplishes common tasks in synthesis processing.</description> .... </task>

code

Helper code for the C++ code generaterator. It will contain the private and or include elements. Currently no attributes.


<code> <include>xmlcasa/synthesis/imager_forward.h</include> <private> #include &lt;xmlcasa/synthesis/imager_private.h&gt; </private> </code>

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.


<code> <include>xmlcasa/synthesis/imager_forward.h</include> <private> #include &lt;xmlcasa/synthesis/imager_private.h&gt; </private> </code>

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.


<code> <include>xmlcasa/synthesis/imager_forward.h</include> <private> #include &lt;xmlcasa/synthesis/imager_private.h&gt; </private> </code>

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.


defaultrecord

The default record 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.

AttributeRequired?Description
type yes Allowed options are function or constructor. Currently constructors are ignored
name yes This is the name of the method.

<method type="function" name="advise"> <shortdescription>Advise (and optionally use) parameter values</shortdescription> ... </method>

output

An output element consists of one or more param elements that will be returned by the method or task. Currently no attributes.


<output> <param xsi:type="int" name="pixels"> <description>Number of pixels on a side</description> </param> <param xsi:type="double" name="cell" units="arcsec"> <description>Recommended maximum cellsize</description> </param> <param xsi:type="int" name="facets"> <description>Recommended number of facets on one axis</description> </param> <param xsi:type="MDirection" name="phasecenter"> <description>Direction of phase center as a measure</description> </param> </output>

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. 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.

AttributeRequired?Description
name yesThis is the name of the param.
xsi:type yes Choose from the following types: any, int, bool, string, double, intArray, boolArray, stringArray, doubleArray, casa*(tool)
units no By specifying a unit attribute, the param because a quantity.

<input> <param xsi:type="bool" name="takeadvice"> <description>Use the advised values?</description> <value>true</value> </param> <param xsi:type="double" name="amplitudeloss"> <description>Maximum fractional amplitude loss due to faceting</description> <value>0.05</value> </param> <param xsi:type="any" name="fieldofview"> <description>Desired field of view</description> <any type="variant" /> <value>1.0deg</value> </param> </input>

returns

Description of what the Method/Task returns, similar to a param element.

AttributeRequired?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.

<returns xsi:type="bool"/>

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> \begin{verbatim} im.ft(model='3C273XC1.model', complist='3C273XC1.complist'); im.makeimage(type='residual', image='3C273XC1.residual') im.makeimage(type='psf', image='3C273XC1.psf') \end{verbatim} </example>

any

An any type, for unknown or records, i.e. string or int.

AttributeRequired?Description
type yes Currently an any element may be specified as either a record or variant

<param xsi:type="any" name="threshold"> <description>threshold for mask</description> <any type="variant" /> <value>0.0Jy</value> </param> <param xsi:type="any" name="height"> <any type="record"/> <defaultrecord> <value name="amp" xsi:type="double">1.0</value> </defaultrecord> <description>amplitude of Gaussian, or 3 numeric values</description> </param>

link

The link element. A way to specify the a link to an external document. value.

AttributeRequired?Description
anchoryes HTML locator

comments

The comments element. No attributes currently.



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.

AttributeRequired?Description
nameno 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 noMaybe any of the types in specified in the param xsi:type attribute
shape no Currently not implemented

Example setting a "Quantity" <param xsi:type="double" name="mstart" units="m/s"> <description>Start velocity (e.g. '20Km/s')</description> <value>0.0</value> </param> Example setting an array with one value. <param xsi:type="intArray" name="start"> <description>Start channels (0-relative)</description> <value>0</value> </param> Example of an empty array <param xsi:type="intArray" name="spwid"> <description>Spectral Window Ids (0 relative) to select</description> <value type="vector"></value> </param> Example setting a vector with more than one value <param xsi:type="intArray" name="quack"> <description>Flag VLA quacks -- scan interval and quack length, in seconds</description> <value type="vector"> <value>0</value> <value>0</value> </value> </param> Example setting a complex array <param xsi:type="complexArray" name="flux"> <description>The flux value. A vector with four real or complex numbers</description> <value type="vector"> <value type="struct"><value name="re">1.0</value><value name="im">0.0</value></value> <value type="struct"><value name="re">0.0</value><value name="im">0.0</value></value> <value type="struct"><value name="re">0.0</value><value name="im">0.0</value></value> <value type="struct"><value name="re">0.0</value><value name="im">0.0</value></value> </value> </param> Example of a multiple choice, note default is last option. <param xsi:type="string" name="polarization"> <description>The polarization of the value field. ``Stokes'', ``linear'' or ``circular''</description> <value>Circular</value> <value>Linear</value> <value>Stokes</value> </param>

Please send any comments or questions about CASA or AIPS++ to aips2-requests@nrao.edu

Copyright © 2007 Associated Universities Inc., Washington, D.C.

This code is available under the terms of the GNU General Public Lincense


Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search

Modified on Saturday, 05-Jan-2007 13:17:19 MST