3.04 Input Templates

Template Format

A template can be any combination of the following objects. They must be separated by at least one space.

variable name
a variable to be assigned a value
.
a place-holder used as an alternative to a target variable. Any value assigned to a place-holder is lost.
literal string
a literal string used as string pattern to split the source at that point.
,
a comma used to match a comma in the source string and split the source at that point.
#
an integer value that is an absolute character position within the source
=#
an integer value that is an absolute character position within the source
+#
an integer value that is a relative character position within the source (move right)
-#
an integer value that is a relative character position within the source (move left)
/variable name
a literal string saved in a variable used as a string pattern to split the source.
=variable name
a variable containing an absolute character position within the source
+variable name
a variable containing a relative character position within the source (move right)
-variable name
a variable containing a relative character position within the source (move left)

Templates are processed from left to right. Items are extracted from the source string as determined by the template.

Where delimiters are used, each part of the template between the delimiters can be considered to be a separate template. How this works can be seen in some of the examples.

Simple String

The simplest form of template is a string of variables used to split a string into separate words.

Each word in the source string is stored in a separate variable. With the exception of the last variable the spaces between the words are not saved. All the text, including spaces, following the previous match is stored in the last variable.

string = "This    is       a       string "
GET STRING string, v1 v2 v3 v4
// v1 = "This",  v2 = "is",  v3 = "a",  v4 = "       string "

If there is only a single variable in the template, that variable is also the last variable. This is the same as a simple assignment.

GET STRING "This    is       a       string ", v1
// v1 = "This    is       a       string "

All variables in a template will be given a new value. If the end of the string is reached and there are no more words available, the remaining variables will be set to an empty string.

In the first example below the final space is assigned to v5, but in the second there is no final space and so both v5 and v6 are empty strings.

string = "This    is       a       string "
GET STRING string, v1 v2 v3 v4 v5
// v1 = "This",  v2 = "is",  v3 = "a",  v4 = "string", v5 = " "
GET STRING string, v1 v2 v3 v4 v5 v6
// v1 = "This",  v2 = "is",  v3 = "a",  v4 = "string",
// v5 = "", v6 = ""

If there are more words in the source than variables in the template, the last variable receives all words remaining in the source.

GET STRING "This    is       a       string ", v1 v2 v3
// v1 = "This",  v2 = "is",  v3 = "       a       string "

Place-Holders

A place-holder is used to ignore parts of the source string. It is treated the same as a target variable but any data assigned to it is lost.

string = "The boy stood on the burning deck"
GET STRING string, v1 . v2 . . v3 .
// v1 = "The", v2 = "stood", v3 = "burning"

Place-holders are only necessary where part of a stream is to be lost. Where delimiters are used, each part between delimiters is a separate template. If no data would be assigned anyhow a place-holder is not necessary.

In this example month is the current two digit month.

GET STRING DATE(), '-' month '-'

Unwanted spaces can be removed by using a place-holder as an additional target.

string = "This    is       a       string "
GET STRING string, v1 v2 v3 v4 .
// v1 = "This",  v2 = "is",  v3 = "a",  v4 = "string"

Comma Delimiters

In addition to using spaces as a delimiter it is possible to use commas as well. These match with commas in the source string. The template objects between commas are treated as a separate template.

string = "This    is       a, comma separated,       string "
GET STRING string, v1 v2 v3 ., v4, v5 .
// v1 = "This",  v2 = "is",  v3 = "a",  
// v4 = "comma separated"
// v5 = "string"

String Patterns

String patterns can be used to split the string using text within the string. The string is split at the string patterns. The string patterns themselves are not stored in a variable.

string = "days=Monday//Tuesday//Wednesday"
GET STRING string, key "=" v1 "//" v2 "//" v3
// key = "days",  v1 = "Monday",  v2 = "Tuesday", v3 = Wednesday"

Where there is no match for a delimiter it matches the end of the string. Any variables in the template after the delimiter are set to an empty string. This is also the case if the delimiter is an empty string.

GET STRING "Monday // Tuesday Wednesday", v1 "//" v2 "--" v3
// v1 = "Monday ", v2 = " Tuesday Wednesday", v3 = ""
GET STRING "Monday // Tuesday Wednesday", v1 "//" v2 "" v3
// v1 = "Monday ", v2 = " Tuesday Wednesday", v3 = ""

Positional Parsing

Positional parsing can be used where the source string consists of a series of fixed length fields. The source string is split at the supplied positions and each substring is assigned to a variable. Everything, including any spaces, is kept.

//        0        1         2         3         4         5
//        12345678901234567890123456789012345678901234567890
string = "The Old Swan   Toller PorcorumDorset         "
GET STRING string, v1 16 v2 31 v3
// v1 = "The Old Swan   ", v2 = "Toller Porcorum"
// v3 = "Dorset         "

The positional values can also be signed and in this case they are relative to the previous match.

//        0        1         2         3         4         5
//        12345678901234567890123456789012345678901234567890
string = "The Old Swan   Toller PorcorumDorset         "
GET STRING string, v1 +15 v2 +15 v3
// v1 = "The Old Swan   ", v2 = "Toller Porcorum"
// v3 = "Dorset         "

Out of Range Delimiters

Where a positional delimiter results in a position beyond the end of the string it is considered to match the end of the data. Similarly a position to the left of the beginning of the string is considered to match the beginning of the string.

An out of range positional delimiter, an unmatched comma, an unmatched string or an empty string can be used to position to the end of the source string and then negative relative positions can be used to retrieve characters from the end of the string.

string = "anything not needed      44 55 66 77"
GET STRING string, "" -2 v1 +2 -5 v2 +2 -5 v3 +2 -5 v4 +2
// v1 = 77, v2 = 66, v3 = 55, v4 = 44

Multiple Parsing

Using positional parsing you can parse the source string with different templates in one instruction.

string = "a--b c++d r//g"
GET STRING string, w1 w2 w3 . , 
                   1 p1 "--" p2 "++" p3 "//" p4 ,
                   1 c1 2 4 c2 5 9 c3 10 c4 11 14 c5
// w1 = "a--b", w2 = "c++d", w3 = "r//g"
// p1 = "a", p2 = "b c", p3 = "d r", p4 = "g"
// c1 = "a", c2 = "b", c3 = "d", c4 = " ", c5 = "g"

Mixed Delimiters

It is possible to mix string patterns, positional parsing and variables in one instruction. In this case the results depend very much on the contents of the string.

//        0        1         2         3         4         5   
//        1234567890123456789012345678901234567890123456789012345
string = "This a remark field (up to 39 chars)   44 55 //66    77"
GET STRING string, 40 d1 d2 . "//" d3 d4 .
// d1 = "44", d2 = "55", d3 = "66", d4 = "77"

Recursive Parsing

As the last variable in a template receives the remaining data from the source and the output can also be written to the source string, it is possible to re-process the variable repeatedly to extract each word separately.

string = "Monday Tuesday Wednesday Thursday Friday"
DO UNTIL string = ""
  GET STRING string, name string
  PUT "Day is" name
  PUT @string "remaining"
  END // do until string = ""

Assigning Default Values

By using a place-holder to lose all but the first word of a string, it is possible to provide a default value for an optional argument.

default = "Saturday"
arg = "Monday"
GET STRING arg default, arg .
// arg = "Monday"
arg = ""
GET STRING arg default, arg .
// arg = "Saturday"

Variable Delimiters

There may be times when you what to break up a string but you do not know at the time of coding what delimiter will be used. In this case it is possible to supply a delimiter using a variable. The variable is identified as a delimiter by preceding it with a slash.

The variable can be set earlier in the processing or the variable can be set as part of the template processing.

string = "/Monday/Tuesday/Wednesday/"
GET STRING string, sep 2 w1 /sep w2 /sep w3 /sep
//                 \ /      |       |       |
//                  |       \-------+-------/
//               set the    use the variable "sep"
//            variable "sep"
// sep = "/", w1 = "Monday", w2 = "Tuesday", w3 = "Wednesday"

lynplex/lp0304.txt · Last modified: 2011/09/08 16:07 (external edit)