cda.help

This CDA modules rely heavily on the use of the Iguana help system. This makes the template much more useable with auto-completion of parameters for module functions. We simplified the built-in help functions by wrapping them in a format that is easier on the eye. We also added a helpful “check” function that raises an error when you use an incorrect parameter.

These functions are used to add and update help for the functions in the modules:

• help.set
• help.check

Information:

Now if we look at the normal API that is part of Iguana we would be populating Lua tables like this:

local addCodeHelp = {
   Title="cda.code.set",
   Usage=[[cda.code.set{root=<XML Root>, system=<value>, value=<value>,label=<value>}]],
   Desc=[[This function will populate a code element with the appropriate attributes.]],
   Returns={
      {Desc="The created code element"},
   },
   ParameterTable=true,
   Parameters={
      {root={Desc='The XML element to populate the attributes of'}},
      {system={Desc='The OID of the system, typically something like cda.code.LOINC'}},
      {value={Desc='The value'}},
      {label={Desc='The displayName to describe the code'}},
      {blah={Desc='Some optional parameter', Opt=true}}
   },
   Examples={[[local Result = cda.code.set{root=Doc, system=cda.code.LOINC, code='11488-4', label='Consultative note'}]]},    
}

And here is the new format:

It uses clearer naming “description” instead of “Desc” and “parameters” instead of “ParameterTable”. For simplicity it escapes the “<>” characters in the “usage” field, so you can use the more intuitive “<value>” (rather than “&gt;value&lt;”). However these are not escaped in the “example” field as there are times that you actually need to use html formatting in your examples (the set example below uses escaping and html formatting). Also it uses the standard Iguana lower case names for consistency with the other built-in APIs (rather than Pascal case).

addCodeHelpShort = {
   title="cda.code.set",
   usage="cda.code.set{root=<XML Root>, system=<value>, value=<value>,label=<value>}",
   description="This function will populate a code element with the appropriate attributes.",
   returns={"The created code element"},
   parameters={
      [1]{['parameter']='root',['description']='The XML element to populate the attributes of'},
      [2]={['parameter']='system',['description']='The OID of the system, typically something like cda.code.LOINC'},
      [3]={['parameter']='value',['description']='The value'},
      [4]={['parameter']='label',['description']='The displayName to describe the code'},
   },
   optional_parameters={
        [1]{['parameter']='blah,['description']='Some optional parameter'},
   },
   examples={"local Result = cda.code.set{root=Doc, system=cda.code.LOINC, code='11488-4', label='Consultative note'}"},
}

---

set() [top]

Usage: cda.help.set{func=<FUNCTION>, info=<{TABLE CONTAINING THE HELP INFORMATION}>}

Sets up the help for a function using the simplified help format passed as the second parameter.

Returns: Nothing

Required parameters:

• func: The name of the function to set the help for
• info: The help information formatted in a Lua table

Example:

This is the help table for cda.dose.add, it uses all the fields and some html formatting:

local cdaDoseAddHelp = {
   title="cda.dose.add",
   usage=[[cda.dose.add{target=<{PARENT}>, element=<ELEMENT>, numerator=<NUMERATOR>, denominator=<DENOMINATOR>}}]],
   description=[[Add dosage information to your CDA document.<br /><br />
<strong>Note</strong>: Both the numerator and denominator are optional fields. If they are not provided, they are replaced by the nullFlavor "UNK" (meaning "unknown").]],
   returns={"A parsed tree representing the populated XML element"},
   parameters={
      [1]={['param']='target',['desc']='The parent tag under which you wish to add the new element'},
      [2]={['param']='element',['desc']='The specific name of the tag you are creating'}, 
   },
   optional_parameters={
      [1]={['param']='numerator',['desc']='The numerator portion of the dose value'},
      [2]={['param']='denominator',['desc']='The denominator portion of the dose value'}, 
   },
   examples={[[ cda.dose.add{target={PARENT}, element='maxDoseQuantity', numerator='12', denominator='35'}

&lt;span style="font-size:12px;line-height:12px;"&gt;&lt;span style="font-family:verdana"&gt;&lt;strong&gt;Example Result&lt;/strong&gt;:&lt;/span&gt;&lt;/span&gt;

&lt;maxDoseQuantity&gt;
    &lt;numerator value='12'&gt;&lt;/numerator&gt;
    &lt;denominator value='35'&gt;&lt;/denominator&gt;
&lt;/maxDoseQuantity&gt;]]}

This is the call that sets the help for cda.dose.add:

cda.help.set{func=cda.dose.add, info=cdaDoseAddHelp}

check() [top]

Usage: cda.help.check(<{FUNC: FUNCTION CALL PARAMETERS}>, <{INFO: TABLE CONTAINING THE HELP INFORMATION}>)

Checks for unknown parameters and raises an error if an incorrect parameter names is used. Typical use is to call cda.help.check at the start of each module function to check for invalid calls. Notice that we use rounded brackets instead of curly braces.

Note: Checking only occurs when you are editing the channel (it is disabled at runtime).

Returns: Nothing

Required parameters:

• func: Table of parameters from the function call
• info: The help information formatted in a Lua table

Example:

Note: A variable “check” is used used as a shorthand, to make the call more concise (this is created at the start of each module).

local check = cda.help.check -- create shortcut

function cda.code.add(I)
   check(I, cdaCodeAddHelp)             -- use shorcut
   -- cda.help.check(I, cdaCodeAddHelp) -- equivalent no shortcut

   I.target = addElement(I.target, I.element)
   I.element = nil
   local T = cda.code.set(I)

   return T
end