Name:Value Pairs in hash functions

Hash functions generally "take" arguments. For example in

#HMI SetCursor(4, 5)

4 and 5 are the arguments to the SetCursor hash function (they specify the row and column respectively). If the arguments are specified that way, they must be in precisely the right order, separated by commas. If any optional arguments are omitted they must still appear as commas.

Name:Value Pairs (NVP) give you a simpler, less tedious way of specifying arguments, especially in hash functions that take a lot of arguments. NVP arguments also improve the readability of your program.

Example: The line above, re-written with NVP arguments, would be

#HMI SetCursor(r:4, c:5)

It would be equally permissible to reverse the arguments (something you absolutely cannot do with the old list format!):

#HMI SetCursor(c:5, r:4)

The abbreviated names for the arguments, c for column and r for row, are defined in the hash function definition. The names are always very short, to save typing, and may be UPPER or lower case.

In the pages for each hash function, the Names are defined in the page title. If you use NVP, you can list the arguments in any order. If you don't use NVP, you must list them in the order given. Hence,

#HMI SetCursor(r:4, c:5)

and

#HMI SetCursor(c:5, r:4)

are equivalent, but

#HMI SetCursor(4, 5)

and

#HMI SetCursor(5, 4)

are not.

Alternative names

Some arguments can have different names. This most often happens with screen coordinates, where you may chose to call them r and c, or you may prefer y and x. Alternative names are shown with a vertical bar (pipe symbol between the alternatives).

See for example the heading for SetCursor. "# SetCursor(r|y:Row, c|x:Col) hash function"