TinyTERM Enterprise for iOS version 3.3.0 introduced screen matching. This allows the user to define certain actions, depending on text displayed on the screen. This is handled with the matching.json file.

This file defines which screens to match and what to do with that information when matches are found. All its configuration is global, applying to all sessions.

MATCHING.JSON

{
    "screens" : [
        {
          "//" : "These comments should be removed for production",
          "//" : "optional readTitle, used mostly for screen rewriting",
          "readTitle" : "Prompt Match" ,
          "//" : "optional matchCondition (can be all or any or none, defaults to all)",
          "matchCondition" : "any",
          "//" : "one or more matches, can be complete regex and location, or a simple string
          "//" : "representing a regex.",
          "//" : "A missing location means to match against the entire screen",
          "matches" : [
            {
              "//" : "Complex regular expressions, using Oniguruma stock with no extensions",
              "regex" : "string1|string2",
              "location" : { "x" :1, "y" : 1, "w" : 80, "h" : 1 }
            }
 
          ],
          "//" : "One or more destinations to be called when this screen is matched. These are",
          "//" : "called in order. See the example in CEN_PROC_CHANGE_SETTTINGS for",
          "//" : "destinations with matched and unmatched sections",
          "destinations":  [
            {
              "//" : "The proc to call",
              "proc" : "CEN_PROC_SELECT_KEYBOARD",
              "//" : "Fixed arguments, depends on what is called",
              "args" : "QWERTZ.P"
            },
            {
              "proc" : "CEN_PROC_RING_BELL",
              "args" : ""
            }
          ]
        },
        {
          "readTitle" : "Item Detail" ,
          "matches" : [
            {
              "regex" : "ID1",
              "location" : { "x" :1, "y" : 2, "w" : 80, "h" : 1 }
            }
 
          ],
          "destinations":  [
            {
              "proc" : "CEN_PROC_SEND_TRANSLATED_STRING",
              "args" : "X"
            }
          ],
          "//" : "itemGroups extract information from the matched screen and pass it to the",
          "//" : "procedures listed in the destinations section",
          "itemGroups" : {
            "itemnumber" : "Item detail for (?<itemnumber>[A-Z0-9]{5,})",
            "description" : { "regex" : "Description\\s+(?<description>.+)[ ]{2,}", "trimEnd" : true},
            "inventory" : "(?<date>[0-9]+\/[0-9]+\/[0-9]+)\\s+(?<quantity>[0-9]+)"
          }
        }
    ]
}

Download a sample matching.json file here.

Match Objects

These can be represented in two different ways. Note that the location is given in x,y,w,y format, all numbered from 1:

• x : starting column
• y : starting row
• w : number of columns
• h : number of rows

// Object specifying a regular expression, and a specific location
// When the location is not specified, it defaults to the entire screen size
// trimBeginning and trimEnd are optional, and default to false
// (they trim leading and trailing whitespace)
{
    "regex" : "string1|string2",
    "location" : { "x" :1, "y" : 1, "w" : 80, "h" : 1 }
    "trimBeginning" : false,
    "trimEnd" : false
}
 
 
// Simple matches can be specified as just a regex string without all the object cruft
// Shown here as an extract from an itemGroup. The string value is the match object
 
 
"itemnumber" : "Item detail for (?<itemnumber>[A-Z0-9]{5,})"

Location Objects

Location objects can be specified in two ways:

// As an object with x,y,w,h parameters (all numbered from 1)
"location" : { "x" :1, "y" : 1, "w" : 80, "h" : 1 }
 
 
// ... or as a simple array where x,y,w,h are assumed
"location" : [1,1,80,1]

Procedure Objects

Procedure objects have two members, proc and args. proc is the name of the procedure, and the args are arbitrary arguments to pass to the proc when it is called.

{
  "proc" : "CEN_PROC_RING_BELL",
  "args" : ""
}

The following procedures are defined:

• CEN_PROC_SELECT_KEYBOARD: Takes a single string argument with the keyboard name
• CEN_PROC_DUMP_ARGS: Debug procedure that will dump all the args passed to the log using the MACRO trace
• CEN_PROC_SEND_TRANSLATED_STRING: Takes a single string argument, performs a TCS translation on it, and then sends it to the host
• CEN_PROC_RING_BELL: No arguments, rings the bell
• CEN_PROC_NEXT_SESSION: No arguments, selects the next session
• CEN_PROC_PREV_SESSION: No arguments, selects the previous session
• CEN_PROC_CHANGE_SETTINGS Arguments are an object that contains name/value string pairs that update the named tpx settings. Also calls set_safe_values after setting values. This can be turned off by setting setSafeValues to true

CEN_PROC_CHANGE_SETTTINGS Example

{ 
   "screens":[ 
      { 
         "readTitle" : "BigSceen",
         "matchCondition" : "any",
         "matches" : [ 
            { 
               "regex" : "Big"
            }
         ],
         "destinations" : { 
            "matched" : [ 
               { 
                  "proc" : "CEN_PROC_CHANGE_SETTINGS",
                  "args" : { 
                     "setSafeValues" : true,
                     "settings" : { 
                        "col" : "80",
                        "lines" : "25",
                        "pfcol" : "80",
                        "pflines" : "25"
                     }
                  }
               }
            ],
            "unmatched" : [ 
               { 
                  "proc" : "CEN_PROC_CHANGE_SETTINGS",
                  "args" : { 
                     "setSafeValues" : true,
                     "settings" : { 
                        "col" : "40",
                        "lines" : "12",
                        "pfcol" : "40",
                        "pflines" : "12"
                     }
                  }
               }
            ]
         }
      }
   ]
}