|
Functions
|
String maniulation functions:
| Function Name | Description |
|---|
| bytes |
This function will format an integer into a Kb or Mb size.
${bytes DIG=digits bytes}
This will format bytes into a Kb or Mb value with
digits digits after the decimal point. Digits must
be between 0 and 3 inclusive. If ommited, Digits defaults
to 2.
| Example | Result |
|---|
| ${bytes 5800} | 5.66 Kb |
| ${bytes DIG=0 5800} | 6 Kb |
| ${bytes DIG=1 5800000} | 5.7 Mb |
|
| concat |
This function will concatenate its arguments, with a user
defined separator string between them. The separator string
defaults to an empty string.
${concat SEP=SepStr words...}
Examples:
| Example | Result |
|---|
| ${concat A B C} | ABC |
| ${concat SEP=+ A B C} | A+B+C |
| ${concat SEP=+ A "B C"} | A+B C |
|
| charcount |
This function will count specified characters in a string (as
opposed to strlen, which returns the length of the string):
${charcount CHARS=characters string}
The number of characters in string which are contained in the set
characters is returned. If ommited, characters
defaults to a single space.
| Example | Result |
|---|
| ${charcount abc def ghi} | 2 |
| ${charcount CHARS="*-" A*B c--d} | 3 |
|
| pad |
This function will pad a string to a given length:
${pad CHAR=padchar LEN=length string}
This will return the original string if it is equal or more than
length characters long. Otherwise, a new string of
length characters is returned by prefixing string
with a sufficient number of padchar characters. If
ommited, padchar defaults to a space, and length
defaults to 4.
| Example | Result |
|---|
| ${pad CHAR=0 23} | 0023 |
| ${pad CHAR=. LEN=5 ab} | ...ab |
|
| remchars |
This function will remove a specified set of characters from
a string, or remove repeated instances of characters:
${remchars CHARS=characters MAX=max string}
A new string is returned in which no more than max
repetitions of any character in the set characters is
returned. If ommited, characters defaults to a single
space, and max defaults to 0.
| Example | Result |
|---|
| ${remchars abc def ghi} | abcdefghi |
| ${remchars CHARS=".," abc def, ghi.} | abc def ghi |
| ${remchars CHARS=. MAX=1 abc...def...ghi} | abc.def.ghi |
|
| repeat |
This function builds a repeating string:
${repeat COUNT=repeatcount string}
This will return repeatcount instances of string.
If ommited, repeatcount defaults to 2.
| Example | Result |
|---|
| ${repeat COUNT=3 Z} | ZZZ |
| ${repeat Abc} | AbcAbc |
|
| replace |
This function replaces a given substring in a string with
another substring.:
${replace OLD=old-substr NEW=new-substr ALL=bool string}
This returns a new string made by taking string and
replacing instances of old-substr with new-substr.
If ommitted, old-substr defaults to %s. If
bool is a non-zero integer, all matches for
old-substr are replaced. Otherwise, only the first match
is replaced.
| Example | Result |
|---|
| ${replace NEW=XYZ Hi %s there %s} | Hi XYZ there XYZ |
| ${replace NEW=XYZ ALL=0 Hi %s there %s} | Hi XYZ there %s |
|
| strlen |
This function returns the length of a given string in bytes:
| Example | Result |
|---|
| ${strlen abcdefghijkl} | 12 |
| ${strlen "a b c"} | 5 |
|
| substr |
This function will return a substring from a given string:
${substr LEFT=startpos LEN=length string}
This will return length characters from string
starting at character startpos. The first character of
the string is 0. If ommitted, startpos defaults to 0
and length defaults to 256.
| Example | Result |
|---|
| ${substr LEFT=2 abcdef} | cdef |
| ${substr LEFT=2 LEN=3 abcdef} | cde |
| ${substr LEN=3 abcdef} | abc |
| ${substr LEN=5 "ab cdef"} | ab cd |
|
| tolower |
This function converts a string to lower case:
| Example | Result |
|---|
| ${tolower Hi There} | hi there |
|
| toupper |
This function converts a string to upper case:
| Example | Result |
|---|
| ${toupper Hi There} | HI THERE |
|
| word |
This function will return the Nth word in a sequence:
${word POS=wordnum words}
This will return the wordnum-th word from words.
The initial word is number zero. If ommitted, wordnum
defaults to 0.
| Example | Result |
|---|
| ${word POS=1 abc def ghi} | def |
| ${word "Z abc" def ghi} | Z abc |
|
| wordcount |
This function will count the words in a sequence:
| Example | Result |
|---|
| ${wordcount abc def ghi} | 3 |
| ${wordcount abc "def ghi"} | 2 |
|
Math functions:
| Function Name | Description |
|---|
| + |
Adds arguments, returns result.
| Example | Result |
|---|
| ${+ 1 2 3} | 6 |
|
| - |
Subtracts arguments, returns result. With a single
argument, returns unitary negation of value.
| Example | Result |
|---|
| ${- 10 3} | 7 |
| ${- 10 3 1} | 6 |
| ${- 4} | -4 |
|
| * |
Multiplies arguments, returns result.
| Example | Result |
|---|
| ${* 2 3 4} | 24 |
|
| / |
Divides arguments, returns result.
| Example | Result |
|---|
| ${/ 100 5} | 20 |
| ${/ 100 10 2} | 5 |
|
| % |
Returns remainder of first argument divided by second argument:
| Example | Result |
|---|
| ${% 11 3} | 2 |
|
| min |
Returns minimum value.
| Example | Result |
|---|
| ${min 10 2 5} | 2 |
|
| max |
Returns maximum value.
| Example | Result |
|---|
| ${max 10 2 5} | 10 |
|
Comparision and logic functions:
| Function Name | Description |
|---|
| >,<,>=,<=,=,!= |
Numeric or string comparisons.
| Example | Result |
|---|
| ${= 5 1} | 0 |
| ${= 5 5} | 1 |
| ${!= 5 1} | 1 |
| ${!= 5 5} | 0 |
| ${<= 5 8} | 1 |
| ${>= 5 8} | 0 |
| ${= abc abc} | 1 |
| ${= abc abcd} | 0 |
|
| and |
Returns logical and of multiple 0 or 1 values.
| Example | Result |
|---|
| ${and 1 0 1} | 0 |
| ${and 1 1 1} | 1 |
| ${and 1} | 1 |
| ${and 0} | 0 |
|
| bound |
Test whether a given variable name is bound in the current context:
This function returns 1 if varname exists as a variable in
the current context, and 0 otherwise. Note that the variable
name should not be surrounded with ${ and } symbols.
| Example | Result |
|---|
| ${bound DayNum} | 1 |
| ${bound NoSuchVar} | 0 |
|
| cond |
Evaluate multiple conditions:
${cond cond1 result1 cond2 result2 ...}
This each condition from cond1, cond2... is
evaluated in turn, until one condition returns a non-0 value,
whereupon the associated result is returned. To force a
default value, include a 1 as the last condition.
| Example | Result |
|---|
| ${cond 0 a 0 b 1 c} | c |
| ${cond ${< 3 1} a 1 b} | b |
|
| default |
Returns the value of a variable, if it is bound, or a default
value otherwise:
${default VAR=varname default-value}
This function returns the value of the variable varname if
that exists as a variable in the current context, and the string
default-value otherwise. Note that the variable
name should not be surrounded with ${ and } symbols.
| Example | Result |
|---|
| ${default VAR=Month ZZZ} | July |
| ${default VAR=NoSuchVar ZZZ} | ZZZ |
| | if |
This function will one of two arguments based on a condition:
${if condition trueresult falseresult}
This will return the falseresult if condition is 0,
and trueresult otherwise. falseresult may be
ommitted. Note that this can be rewritten as
${cond condition trueresult 1 falseresult}.
| Example | Result |
|---|
| ${if ${> 3 0} "hi there" def} | hi there |
| ${if ${> 3 8} abc def} | def |
| ${if 1 a} | a |
| ${if 0 a} | |
|
| not |
Returns logical not of a single boolean value:
| Example | Result |
|---|
| ${not 0} | 1 |
| ${not 1} | 0 |
|
| or |
Returns logical or of multiple 0 or 1 values.
| Example | Result |
|---|
| ${or 0 0 1} | 1 |
| ${or 0 0 0} | 0 |
| ${or 1} | 1 |
| ${or 0} | 0 |
|
Execution and system functions:
| Function Name | Description |
|---|
| exec |
This function can be used to execute external commands and
return the result:
${exec CMD="command" ARGS="args" PRI=pri STACK=stack}
This will execute command with paramters args using
a task priority of pri and a stack size of stack.
Only the CMD optionis required; all others are optional.
Parameters which contain spaces or other special characters must
be quoted. Either single or double quotes may be used.
The standard output of the given command is read using an AmigaOS
pipe, and the result up to the first new line or the first 80
characters, whichever comes first, is returned as the value of
the variable.
Take care that the given command actually produces output, and
produces a finite amount of said output. NewsRog will pause
during the execution of the command.
Example: given the appropriate command, this will return current
phase of the moon in a NewsRog variable:
${exec CMD="PhaseOfMoon" ARGS="-today"}
|
| getenv |
This function returns the value of an environment variable,
or a supplied default value if none was found:
${getenv DEF="default-value" varname}
This will return the value of the varname environment
variable, if found, or the string default-value
otherwise. Example:
|
Definining Functions:
Simple functions may be defined by declaring a variable which combines
other, built in functions and optionally uses the variables ${0}, ${1},
etc to reference the arguments to the function. ${*) expands to
the entire argument list, and ${#} expands to the number of
arguments to the function. To call a function use
${func function_name arguments...}.
For example, to create a function named itemcount which, when given
numbers 1, 2, or 3, returns the strings "one", "two", or "three",
and the actual number otherwise, make a variable called itemcount
with the following definition:
${cond ${= ${0} 1} one ${= ${0} 2} two ${= ${0} 3} three 1 ${0}}
You may then call this function using the ${func} command:
| Example | Result |
|---|
| ${func itemcount 3} | three |
| ${func itemcount 1} | one |
| ${func itemcount 17} | 17 |
Functions may call other functions.
Back to Top
|
