In Match-IT, Lua scripts can be used in two contexts. They can be used as a PPS expression (Parametric Product Structure), or as a program to perform some function.

When used as an expression, you enter the expression directly into Match-IT via the expression editor. The expression becomes ‘embedded’ into a method.

When used as a program, the script is a text file you create using any text editor (e.g. Notepad, we recommend Notepad++ which can do syntax highlighting and folding, see notepad-plus.sourceforge.net). Once created they can be run directly or they can be ‘imported’ as a wizard. It's important to note that although the process is referred to as ‘importing’, it's only the properties that are imported and not the script itself, the script is ‘linked’ not embedded. This means whenever the wizard is executed, the script file is re-accessed and then run. So any changes you make to the script take effect immediately and it need not be re-imported. The main benefit of importing is that the script becomes part of your wizard library and as such can be connected to via wizard buttons available on many forms and/or turned into a menu button.

When 'importing' a script it's referred to as a template and must conform to a syntax like this:

TemplateFile

::=

[ LanguageLine ] { IgnoredLine } StartLongComment Template EndLongComment Script

LanguageLine

::=

'#lua'

IgnoredLine

::=

any line that is not a Template

Template

::=

'{{{  TEMPLATE:' TemplatePrefix,TemplateMnemonic,TemplateName,TemplateClass,TemplateUserGroups

[ Description ]

{ TemplateLine }

'}}}'

TemplateLine

::=

Comment | ContextSection | DefaultLine

StartLongComment

::=

'--[['

EndLongComment

::=

'--]]'

Script

::=

See Lua Language Script

Comment

::=

'{{{  COMMENT:' [CommentTitle]

{ TextLine }

'}}}'

ContextSection

::=

'{{{  CONTEXT:' [SectionName]

Description

{ DefaultLine }

'}}}'

This is an import section only. It does not exist in the imported template. It is just a convenient way to visually isolate all the template defaults in the import script.

DefaultLine

::=

'DEFAULT:' DefaultName,DefaultType[,DefaultValue]

A default line defines a context default for the template. This causes a qualifier of 'DefaultName' to be attached to the template. The type of the value is 'DefaultType' and the initial value is 'DefaultValue'.

These qualifiers can be accessed within the template by the normal field access mechanism using the drSelfTemplate as the reference. For example:

drh = m.open(match_it.drh)            --open file

m.load(drh,m.drSelfTemplate)          --load 'self' to gain access to qualifiers

DefaultOfInterest = drh.DefaultName   --if the name is known to be DefaultName

DefaultOfInterest = drh[DefaultName]  --if the name is in the variable "DefaultName"

...

m.close(drh)

This is a convenient mechanism to group all user tweakable stuff in one easy to get to place.

Description

::=

'{{{  DESCRIPTION:'

{ TextLine | LineBreak } [ '[END]' { TextLine } ]

'}}}'

The Description forms the text of the confirmation dialog when the template is run. The confirmation text ends at the description end or the first line containing the '[END]' marker. If the confirmation text is blank, no confirmation dialog is shown when the template is run.

All blank lines are ignored. All text following !! on any line is ignored. This is an end of line comment for use in the import script.

LineBreak

::=

'.'
This adds a line break to the description.

There must only be a single Template in the file. All lines beyond the Template are assumed to be the Lua script. To stop Lua interpreting the Template block, it should be enclosed in a long comment ('--[[' to the corresponding '--]]').

If the LanguageLine is omitted the system default language is assumed.

See Wizard Functions and Wizard DO Function for the Match-IT specific functions available within Lua. All these functions, and other facilities, are available through a Lua table called match_it (usually abbreviated to just 'm').