• What is Auto-Completion?
• For Modules and Functions
• For Parsed Data
• For Variables
• For JSON

What is Auto-Completion?

Our goal is to make scripting easy for all our users, regardless of their coding expertise. With this in mind, we developed one of the most useful features of the Iguana Translator: the auto-completion tool.

Auto-completion provides intuitive, interactive support that you can lean on whenever you need to use a variable, map message data or call a function. With show annotations enabled, you can write code with confidence!

Auto-Completion

Whenever you type something into the Editor window, Iguana’s auto-completion feature will attempt to guess your intention and offer hints, support, and scripting help. With auto-completion enabled, you can code faster and more accurately because you skip all the guesswork.

• Auto-completion offers suggestions for any globally or locally defined item: modules, functions, variables, parameters, etc.
• Iguana will automatically offer help the moment you start typing anything that resembles either a global or local item
• Auto-completion is fully integrated with the help system that provides extensive on-the-spot scripting support

The following pages describe how auto-completion works for modules and functions, parsed data and variables.

For Modules and Functions [top]

Auto-completion offers scripting support for builtin functions and shared module functions. Say goodbye to having to look up APIs, search through module code or wrestle with errors.

How It Works

1. In this example, we want to use the Orig variable as an HL7 node tree (this technique makes working with message data much easier). To do this we need a function that will parse an incoming message into individual segments.

   We suspect this function exists in Iguana’s shared libraries, perhaps in an HL7-related module? Let’s investigate by typing “hl7”:
   
   Auto-completion suggests either the hl7 module or the hl7util module.

2. Choose an item from the list (Click on it, or use Down Arrow then Enter). Auto-completion will complete the item for you.
   
   We decided to choose the hl7 module because it mentions a ‘parse’ function:
   

3. Notice that Iguana doesn’t stop here! Auto-completion will continue to drill down and provide “what next” hints until no further options are possible.

   In this example, auto-completion indicates that the hl7 module contains two functions: message and parse:
   
   After reading the brief descriptions provided, we choose the parse function:
   

4. Some auto-completion lists are displayed using a yellow Help dialog, This indicates that more information is available via the help system, simply click the expand icon or the window title bar to open help.

   In this case we need two parameters: vmd and data, so we decide to look at the help to find out more:
   
   The hl7.parse help dialog appears:
   

5. After reading the help just return to your script and select the next option (you can leave the help window open if you wish).

   Note: When you close the help dialog, you may have to “reactivate” auto-completion. Try hitting the space bar or pressing the delete key (or one and then the other).

   In this example, we’ve reviewed the help and figured out that we need to define the vmd parameter using ‘transform.vmd’:
   
   We also need to define the data parameter using Data, the message parameter passed to the main() function:
   
   

Success! Thanks to auto-completion, we were able to call a function and define its parameters correctly without having to look up APIs, search through modules or wrestle with errors.

For Parsed Data [top]

Auto-completion will help you quickly drill down through the hierarchy of a parsed message to find the data you need. You can find any data or field without having to know its exact location in advance. Say goodbye to digging through through complex message structures, or having to count each HL7 pipe and carat.

Note: We use an HL7 example below, but auto-completion works with all parsed message node trees: HL7, X12, XML and JSON (which uses a Lua table not a node tree).

How It Works

1. Start typing the variable containing the parsed message, then select from the auto-completion list.
   
   In our previous example, we used the hl7.parse to parse the incoming message into the Orig variable. Let’s see if we can return the patient’s name from Orig.
   
   Auto-completion responds to our typing and guesses that we might be trying to use Orig:
   

   Note: Notice that the notation for the Orig option is the current incoming sample message. That’s a good indication that we’ve correctly mapped incoming message data to our variable!

2. Once we choose Orig, auto-completion recognizes that it contains parsed message data, and provides you with the first level of data to drill through: The message’s segments.
   
   In this case we select the PID segment because it includes basic patient information (like names):
   
3. Auto-completion instantly drills down to the next level of data: The fields available within the PID segment.
   
   Because we want to return the first name of our patient, the choice is fairly obvious:
   
   Notice that auto-completion adds numbers to PID rather than the proper “name” of each choice. This is because the message node tree uses the Lua table syntax. In this case, Orig.PID[5] simply means that we have selected the 5th field in the PID segment of our message (otherwise known as the Name field).
   

   Note: If you are unsure of which field to pick, notice that each list item includes corresponding example data loaded directly from the current sample message. If you still can’t figure out what an auto-completion list item represents, simply cycle through sample messages to change the example data provided. In our example, we can deduce from the example “Smith^Tracy” that the Name field must contain patient name information.

4. In HL7 format, some fields include “repeats”. Have no fear, auto-completion takes these into account as well!
   
   In this example, we’ve chosen to return the first repeat (Repeat 1) of the Name field:
   
   … and now we’ve finally found the location of our patient’s first name, the Given Name subfield:
   

Success! Thanks to auto-completion, we were able to return a very specific piece of data from our parsed message without wasting time counting pipes and carats, or risking miscounts and errors.

What is Deep Auto-Completion?

“Deep” auto-completion is Iguana’s ability to search for matches throughout the entire parsed tree, not just the current level of data. In our example, we could have started out the procedure by simply typing “Orig.Tracy” or “Orig.Given” instead of walking through each level of data in the parsed message. Auto-completion would have skipped the interim levels and drilled straight to the match we were looking for.

1. Message hierarchies like HL7 can be very complex, so deep auto-completion can be very helpful. Let’s say we remember the field Given Name but not where it is in the hierarchy.

   All we need to do is start typing “Orig.Given”, and let the Translator find the field for us:
   

2. Deep auto-completion also works with data, in this case we start typing the name Tracy:
   

For Variables [top]

Auto-completion also supports custom variables that you create in your script. Once you define a variable auto-completion will register it as a possible option whenever searching for matches. This feature works regardless of your variable’s scope (local or global), or its location in your script (in the main function, in a user-defined module, or in a predefined module).

How It Works

As we saw in our previous example, auto-completion can help you correctly use one of Iguana’s many predefined variables (such as modules and functions). Alas, scripting goes well beyond the pre-defined! You must often create new variables in order to properly execute a task.

In this example, we have defined three simple variables:

• a string of text that we’ve named String
• a number that we’ve named Number
• a table with three values that we’ve named Table

1. Let’s use the trace() function to return the value stored in our String variable. When we start typing the word “String” auto-completion presents us with all possible matches.

   As you can see our String variable he presented as one of the possibilities:
   

2. Choose an item from the list (Click on it, or use Down Arrow then Enter). Auto-completion will complete the item for you
3. Now let’s use trace() to return the value stored in our Number variable:
   

4. Completion also works with the hierarchical structure of tables. Similar to working with parsed message data, you can work your through the levels until you find what you seek.

   In this example, we want to return the second value assigned to our Table variable. First, we need to choose the correct variable:
   
   Auto-completion recognizes that Table contains several fields of data, and offers us a list of options:
   
   We can add the third field from the table in the same way:
   

5. Using annotations, we can see the results of our work:
   

Success! Thanks to auto-completion’s wide-reaching capabilities, we were able to work quickly and accurately using our own variables.

For JSON [top]

Jason trees are stored in Lua tables, therefore auto-completion works just like any other Lua table. Lets create a JSON object and demonstrate that it is actually a table.

First lets create a JSON object by parsing this JSON string ‘[1,2,3,{“Fred”:”Smith”}]’.

1. Use auto-completion to choose the json.parse() function:
   
2. The annotation shows that the table is returned by the the json.parse() function:
   
3. We can had another field just as we would with any table:
   
4. We can use auto-completion to choose the first name:
   
   
5. And deep auto-completion to choose the last name:
   
6. Lets serialize our table into a JSON string:
   
   
   
7. As you can see the result is a valid JSON string:
   

Now let’s create the same JSON manually using a JSON object and a table:

1. Adding fields manually to a JSON object produces the same table and Jason string as before:
   
2. Using a table also produces the same result:
   

Here is the code for the examples:

function main()
   local J = json.parse{data='[1,2,3,{"LastName":"Smith"}]'} 

   -- add a new field to the JSON table
   J[5] = {["FirstName"]="Fred"}
   trace(J)
   
   local Name = J[5].FirstName
   local Surname = J[4].LastName
   
   -- serialize is a JSON string
   json.serialize{data=J} 
   
   -- Create a JSON object and add fields manually
   local J1 = json.createObject()
   J1[1] = 1
   J1[2] = 2
   J1[3] = 3
   J1[4] = {["LastName"]="Smith"}
   J1[5] = {["FirstName"]="Fred"}
   trace(J1)
   json.serialize{data=J1}
   
   -- Create a table and add fields manually
   local J2 = {}
   J2[1] = 1
   J2[2] = 2
   J2[3] = 3
   J2[4] = {["LastName"]="Smith"}
   J2[5] = {["FirstName"]="Fred"}
   trace(J2)
   json.serialize{data=J2}   
end