Hoodospel commands

Block commands

IF expr [OPERATOR expr]
commands
ELSE_IF expr [OPERATOR expr]
commands
ELSE
commands
END_IF

Conditional execution block. If IF is used without any suffixes (without OPERATOR part) then its argument is considered true as long as it is not empty (for strings) and not zero (for numbers). In any case all of the expressions must leave only one value in the stack.

Supported operators:

Operator Arguments Is true if first … the second
IS string, string is identical to
IS_NOT string, string is different from
MATCHES string, pattern matches
NOT_MATCHES string, pattern does not match
EQ number, number is equal to
NE number, number is not equal to
LE number, number is lesser then or equal to
GE number, number is greater then or equal to
LT number, number is lesser then
GT number, number is greater then

ELSE_IF and ELSE sections are optional, there also may be no commands after each of the block headers (IF, ELSE_IF, ELSE). Commands after block header are executed if it is the first block header in a sequence whose condition is true. Commands after ELSE will be executed if there are no block headers with condition that is true.

Commands after each block header may also start their own subblocks.

Non-block commands

PRINT LEVEL message

Print message with the given level. Given expression may leave more then one value in the stack, in this case the whole stack will be passed to printf meaning that first value will be a format string and the following values are being inserted in this string according to it.

cmd:PRINT:message_level option controls which messages are output and which are not.

Supported levels (in order of significance): DEBUG_INFO, MESSAGE, WARNING, ERROR.

ABORT message
Abort execution. This will abort with a error ID aborted and message constructed from expr like in PRINT command.
VERSION version

Check whether current hoodospel version matches given one. It is considered matching if current major version number is identical to requested one and the following numbers are less then or equal to current. If some number is missing it is considered to be zero. E.g.

Current Requested Resolution
1.0.0 '0.0.0' Fail (major version numbers differ)
1.0 '1.2' Fail (zero is lesser then two)
1.0.2 '1.0.3' Fail (two is lesser then three)
1.0 '1.0' Success
1.1 '1.0' Success (one is greater then zero)
1.0.0 '1.0' Success (missing number is zero)
1.0 '1.0.0' Success (missing number is zero)
RUN_SHELL expr [OUTPUT_TO var] [INPUT_STRING expr] [EXPECTING_EXIT_CODE expr] [IGNORE_EXIT_CODE]

Run shell command. Expression given as a first argument is expected to leave more then one string in stack: RUN_SHELL ( echo abc ) will run command echo with argument abc, but RUN_SHELL "echo abc" will run command echo abc with no arguments (and most likely fail).

This command will fail if launched command exits with code different from zero. EXPECTING_EXIT_CODE and IGNORE_EXIT_CODE prefixes override this behavior: first will make hoodospel expect fail if exit code is different from the one from the prefix argument, first will make hoodospel not fail regardless of exit code.

If OUTPUT_TO string was specified then launched command output will be assigned to given variable.

If INPUT_STRING string was specified then launched command will receive given string in the stdin.

CHANGE_DIRECTORY_TO expr
Change current directory to the given one.
SET var TO expr
Set given variable value to given value. Expression must leave only one value in the stack. Can also be used to set environment variables, but in this case expression must leave only one string value.
DELETE TYPE expr
Delete given filesystem object. TYPE may be FILE, DIRECTORY and EMPTY_DIRECTORY. Expression must leave exactly one string value in the stack.
COPY TYPE expr (TO expr | TO_DIRECTORY expr | HERE)
MOVE TYPE expr (TO expr | TO_DIRECTORY expr | HERE)

Copy or move given filesystem object to given location. TYPE may be either FILE or DIRECTORY, other prefixes specify target location:

Prefix Description
TO COPY FILE a TO b copies file contents to file b
TO_DIRECTORY COPY FILE a TO_DIRECTORY d copies file contents to d/a
HERE COPY FILE d/a HERE copies file contents to file a

In all cases expressions must leave exactly one string value in the stack.

CREATE_DIRECTORY expr [RECURSIVE]
Create directory with given name. If RECURSIVE prefix is given then parent directories are also created if necessary.
SUBSTITUTE pattern WITH expr IN var [IGNORE_CASE] [REPLACE_ALL]
Substitute given pattern with given replacement string. Operates on a given variable, result is recorded back into it. IGNORE_CASE flag makes regex engine ignore case, REPLACE_ALL makes hoodospel replace all occurences of a pattern (it replaces only the first by default).
WRITE expr TO expr [TEMP_SUFFIX expr]
Write given string to given file. When TEMP_SUFFIX expression is given then in place of writing directly to a given file it will write to TO.TEMP_SUFFIX file and then rename file that was written to to TO.
READ expr TO var
Write given file contents to given variable.
QUESTION message RESULT_TO var TYPE [RESULT_FROM expr] [DEFAULT expr]

Ask user a question. The result is recorded to the given variable. Question is processed in the following order (assuming key is the first value in message stack):

  1. Check out whether there is answer file in the current directory: .hoodospel.ans. If there is one then it should have format “key \t string”. If there is one and it contains key then RESULT_TO variable is populated with the given answer. This answer is processed according to TYPE.
  2. Check out whether RESULT_FROM expression is not empty. If it is not it is proccessed according to given TYPE and used to populate RESULT_TO variable.
  3. Check out whether cmd:QUESTION:use_default option is true. If it is then DEFAULT is used to populate the variable. DEFAULT is processed according to TYPE as well.
  4. Last, if DEFAULT was not specified and other variants failed user is asked to answer the question. User answer is processed according to TYPE.

Possible types:

Type Description
BOOLEAN Transforms “yes”, “y”, “true” and “1” strings to 1 and “no”, “n”, “false” and “0” strings to 0.
STRING Takes string unmodified.

If cmd:QUESTION:write_answers option is true then this command also writes answer to .hoodospel.ans file.