Irys
A free general-purpose scripting language
(c)2005-2006 by Ireneusz Kulaga
Download: http://sourceforge.net/projects/irys/files
Table of contents
I GETTING STARTED
1. Introduction
1.1. Hello, World!
2. Author
II LANGUAGE REFERENCE
3. Basic Syntax
4. Variables
5. Constants
6. Expressions
7. Control structures
7.1. if
7.2. while
7.3. for
7.4. return
7.5. break
8. Functions
9. Input/Output
10. Command line arguments
11. Modularity
III AVAILABLE FUNCTIONS
12. General
12.1. int
12.2. double
12.3. string
12.4. typeof
12.5. time
12.6. strtime
12.7. size
12.8. exec
12.9. start
12.10. range
12.11. mktime
12.12. eval
12.13. defined
12.14. localvars
12.15. globalvars
12.16. functions
12.17. setglobal
12.18. clone
12.19. setprecision
12.20. setfloatdisplay
12.21. version
12.22. getenv
12.23. setenv
13. Arrays and Maps
13.1. sort
13.2. arrayfind
13.3. arraydel
13.4. arrayinsert
13.5. arrayset
13.6. mapget
13.7. mapset
13.8. mapdel
14. Strings
14.1. strlen
14.2. chr
14.3. ord
14.4. split
14.5. substr
14.6. find
14.7. findnext
14.8. rfind
14.9. rfindnext
14.10. replace
14.11. trim
14.12. ltrim
14.13. rtrim
14.14. trimchrs
14.15. right
14.16. left
14.17. upper
14.18. lower
14.19. join
14.20. splitCSVRow
14.21. match
14.22. findpat
14.23. findpats
15. Files
15.1. fopen
15.2. fclose
15.3. fgetline
15.4. freadlines
15.5. fread
15.6. fwrite
15.7. feof
15.8. dir
15.9. fsize
15.10. isdir
15.11. fexists
15.12. fstat
15.13. chdir
15.14. getcwd
15.15. ftell
15.16. fseek
15.17. splitpath
15.18. makepath
16. Math
16.1. sin
16.2. cos
16.3. sqrt
16.4. srand
16.5. rand
16.6. pow
Irys (formerly called Redo) is a free general-purpose scripting language. It interprets script file passed as an argument for Irys.exe binary or reads and executes user commands interactively from standard input. No special installation steps are required to use Irys.
Usually Irys is started from command line in the following way:
c:\>Irys.exe [<script_file> [args]]
If no script file is passed Irys starts in the interactive mode.
It prompts for commands with ">" prompt. To allow multi-line commands
like if...endif the commands are executed after first empty line.
To get more information about available functions please type "help" in the interactive mode.
Hello, World! example 1:
say "Hello, World!"
Hello, World! example 2:
var name
print "Enter your name: "
get name
say "Hello, ", name, "!"
Hello, World! example 3:
var name
while strlen(name) == 0
print "Enter your name: "
get name
endwhile
say "Hello, " + name + "!"
Irys was written by Ireneusz Kułaga. Please use following e-mail address: iiron(at)wp.pl to contact me.
Irys was written mainly for fun. The aim was to make hand-coded parser in C++ and the simplest possible scripting language interpreter. However, I successfully use Irys at my daily work.
Please note that every Irys instruction is one logical line of the script file.
Physical lines can be joined into logical lines using backslash character (\), e.g.:
set a = 10 *\
20
set a = "Text in\
2 lines"
Irys supports one-line comments. Comment line must start with '#' letter.
Variables do NOT have to be explicitly declared using var
instruction. Variable name is case sensitive.
Use var instruction to define both scalar variables and dynamic arrays. Irys supports 3 scalar value types:
string values, integer values and floating point values (doubles). Uninitialized variable defaults to NULL.
Syntax: var <varname> [ = <expr> ] (,<varname> [ = <expr> ])*
Use set instruction to set variable or an element of list.
Syntax: set <varname> = <expression>
set <listname>[<position_expression>] = <expression>
To simply add a new element to a dynamic array leave position_expression empty:
set <listname>[] = <expression>
Irys supports curly braces {} and colons construct for creating an array and initializing its elements.
Variables are assigned by value except for strings and arrays.
A hexadecimal number is denoted by the leading characters 0x
or 0X followed by digits and the letters a-f
or A-F.
Example:
var a
# a equals NULL
set a = "abc"
set a = 10
set a = .25
set a = 0xFFFE
var b = 10, c = .25
var l
set l[0] = "a"
set l[1] = "b"
# push back new element:
set l[] = 10
set a = l[0] + l[1]
# now a equals "ab"
var ll
set ll[] = l
set a = ll[0][0]
# now a equals "a"
var z = {1, "abc", rand()}
var y = {10, 20, {30, 40}}[2][1]
# now y equals 40
set a = 10 * {1, 2, 3}[1]
# now a equals 20
Square brackets [] can be used for obtaining a single character of string on the specified position. Example:
var a = "abcdef"
var b = a[1]
# b equals "b"
var f = a[-1]
# f equals "f"
Use unset command to delete variable(s).
Syntax: unset <varname> (,<varname>)*
Use inc command to efficienlty increment the value of variable.
Syntax: inc <varname>
Use dec command to efficienlty decrement the value of variable.
Syntax: dec <varname>
Maps
The mapping type is suported by Irys indirectly. A map is represented by an ordered array of key-value pairs. A key-value pair is simply an array containing 2 elements. An empty map should be defined just like an empty array, i.e.:
var m = {}
To set an element in the map please use mapset function, e.g.:
mapset(m, "a", 10)
To get an element from the map please use mapget function, e.g.:
var value = mapget(m, "a")
To remove a key and the associated value from the map please use mapdel function, e.g.:
mapdel(m, "a")
Since map in Irys is an ordinary array of arrays it is possible to iterate through all elements using for control structure, e.g.:
for kv in m
println "key: ", kv[0], ", value: ", kv[1]
endfor
It is also possible to initialize map but the keys must be in the ascending order, e.g.:
var m = { {"a", 10}, {"b", 15}, {"c", 20} }
There are following predefined read-only variables available: NULL, TRUE, FALSE, NEWLINE, PROGDIR, INT_MAX, INT_MIN and RAND_MAX.
TRUE equals 1, FALSE equals 0.
RAND_MAX is the maximum value that the rand function can return.
PROGDIR is the directory where irys.exe is located.
This variable is used by import command when searching files.
Following arithmetic operators are available: +, -, %, * and /.
Following comparison operators are available: ==, !=, <, >, <=, >=.
Following logical operators are available: !, &&, ||.
Following bitwise operators are available: &, |.
Strings can be concatenated using + operator. A string can be duplicated number of times using * operator.
Example:
println "=" * 20
Result:
====================
Following array operators are available: +, ==, !=.
Example:
println {1, 2} == {1, 2}
# Result: 1
println {1, 2} != {}
# Result: 1
println {1, 2} + {3, 4}
# Result: [1, 2, 3, 4]
println {1, 2} + 3 + "a"
# Result: [1, 2, 3, "a"]
if allows for conditional execution of instructions.
if <condition>
(<instruction>)*
[elif <condition>
(<instruction>)*]*
[else
(<instruction>)*]
endif
else and elif blocks are optional.
while executes instructions as long as the while expression evaluates to non-zero value.
while <expression>
(<instruction>)*
endwhile
for interates over the items of a list.
for <varname> in <list_expr>
(<instruction>)*
endfor
Example:
for i in {2, 4, 6, 8, 10}
println i
endfor
Use range(from, to) function to iterate over range of integers.
Example:
for n in range(1,10)
println n
endfor
The use of range in for structure gives the best loop performance.
For sructure can as well iterate over a text file.
Example:
var f = fopen("example.txt", "r")
for line in f
println line
endfor
fclose(f)
return immediately ends execution of function or script and return value specified by the return expression.
return <expression>
break terminates the nearest enclosing loop (for or while).
A function may be defined using def instruction.
def <procname>( [<argname> (,<argname>)*] )
enddef
Example:
def sum(v1, v2)
return v1 + v2
enddef
println "1 + 2 = ", sum(1, 2)
For handling of standard input and output streams use print,
println, say, get
and getline instructions.
print prints its arguments to standard output stream
print <expression> (,<expression>)*
println behaves the same as print but, additionally, prints new line character after last argument.
Use getline to read a line from standard input stream to a Irys variable.
getline <varname>
say is a synonym of println and
get is a synonym of getline.
Use setprecision and setfloatdisplay to control precision and display type of floating-point numbers
Command line arguments passed to Irys.exe are available as list
ARGV. Number of arguments passed is stored in variable
ARGC.
Example:
println "Number of arguments: ", ARGC
for i in range(0, ARGC - 1)
println "ARGV[", i ,"] = ", ARGV[i]
endfor
From any position within Irys script it is possible to load and interpret another script file
using include command. This allows among other things to have files containing
defintions of common and reusable functions.
include <name_expression>
Example:
var INC_DIR = "c:\include\"
include INC_DIR + "math.irys"
include INC_DIR + "string.irys"
PROGDIR predefined variable points to the directory where irys.exe is located.
The content of this variable is used by import command when searching files.
Example:
include "tools.irys"
If there is no "tools.irys" file in the current working directory the file is also
searched in the directory pointed by PROGDIR variable.
int(x)
Returns x converted to an integer
Example:
println int("12.7")
Result: 12
double(x)
Returns x converted to a double. double function correctly converts strings.
Example:
double("1e-1")
Result: 0.1
string(x)
Returns x converted to a string.
typeof(x)
Returns type of x.
Example:
var a, b, c
set a = "abc"
set b = 10
set c = 5.5
print "Type of a is ", typeof(a), "."
print "Type of b is ", typeof(b), "."
print "Type of c is ", typeof(c), "."
Result:
Type of a is string.
Type of b is int.
Type of c is double.
time()
Returns current system time in seconds as a double
Example:
var i = 0, start = time()
while i < 100000
set i = i + 1
endwhile
println "Time elapsed: ", time() - start
strtime(t)
Returns time value t converted to a string.
Example:
println strtime(time())
size(l)
Returns size of list l.
Example:
var l = {"a", "b"}
println size(l)
Result: 2
exec(path)
Executes a command and returns its output as a string.
Example:
# print the 4th line of output of dir command:
println split(exec("dir"), "\n")[3]
# get environment variable "OS"
var os = trim(exec("echo %OS%"))
start(path)
Executes a command and returns the exit code.
Example:
var result, cmd
print "Enter command name to be executed (e.g. notepad.exe): "
getline cmd
set result = start(cmd)
println "Result = ", result
range(from, to)
Produces a list containing integers from from to to.
mktime(year, month, day, hour, minutes, seconds)
Produces a time value from arguments or -1 in case of an error.
eval(expr)
Evaluates expression expr.
Example:
var a = 10
println eval("a + 5")
Result: 15
defined(varname)
Returns 1 if variable varname is defined.
localvars()
Returns list of all currently defined local variables.
globalvars()
Returns list of all currently defined global variables.
Example:
var allDefinedVars = localvars() + globalvars()
functions()
Returns list of all currently defined functions.
setglobal(varname, val)
Sets global variable varname to val. Use setblobal
inside functions when there is a local variable with the same name.
clone(var)
Returns a clone of variable var.
setprecision(prec)
Sets floating-point display precision to prec.
setfloatdisplay(type)
Sets floating-point display type: 0 - fixed, <>0 - scientific.
version()
Returns Irys interpreter version.
getenv(name)
Returns a value for variable name from the current environment.
Returns NULL in case the variable is not defined.
setenv(name, value)
Sets value for variable name in the current environment.
Returns 0 if successful or -1 in the case of an error.
sort(l)
Sorts list l.
arrayfind(l, v)
Returns position of value v in array l or -1
if v was not found.
arraydel(l, pos)
Removes an element from array l at position pos.
arrayinsert(l, pos, val)
Inserts value val at position pos in array l.
arrayset(l, pos, val)
Sets value val at position pos in array l.
mapget(map, key)
Returns value associated with key or NULL if the key
does not exist in the map.
mapset(map, key, val)
Sets value val for the key in the map.
map must be of array type. E.g. an empty map may be initialized by
var d = {} command.
mapdel(map, key)
Removes a key and the associated value from the map.
strlen(x)
Returns length of given string x.
Example:
println strlen(string(100))
Result: 3
chr(n)
Returns string containing one character which ASCII code is given by n.
Example:
set newline = chr(13) + chr(10)
ord(c)
Returns ASCII value of the first character of string c.
split(str, sep)
splits string str by separator chars in string sep
and returns list of result strings.
Example:
var l = split("a,b,c,d,e,f", ",")
println l
Result: {a, b, c, d, e, f}
substr(str, off, cnt)
Returns part of string str starting from offset off
which length is at most cnt characters.
find(str, pat)
Returns the lowest index of substring pat in string str
or -1 if substring was not found.
findnext(str, pat, off)
Returns the lowest index of substring pat in string str
or -1 if substring was not found.
rfind(str, pat)
Returns the highest index of substring pat in string str
or -1 if substring was not found.
rfindnext(str, pat, off)
Returns the highest index of substring pat in string str
or -1 if substring was not found.
replace(str, src, dst)
Returns copy of string str in which all occurrences
of substring src were replaced by string dst.
trim(str)
Returns copy of string str in which all leading and trailing whitespace
characters are removed.
ltrim(str)
Returns copy of string str in which all leading whitespace characters
are removed.
rtrim(str)
Returns copy of string str in which all trailing whitespace
characters are removed.
trimchrs(str, chars)
Returns copy of string str in which all leading and trailing
characters chars are removed.
Example:
say trimchrs("=== 12.8 ===", " =")
Result: 12.8
right(str, len)
Returns last len characters of string str.
left(str, len)
Returns first len characters of string str.
upper(str)
Returns copy of string str in which all lower case letters
are converted to upper case.
lower(str)
Returns copy of string str in which all upper case letters
are converted to lower case.
join(list, sep)
Returns concatenation of words in list with sep.
Example:
var j = join({"A", "B", "C"}, "--")
Result: j = "A--B--C"
splitCSVRow(str)
Splits a line of CSV file str by comma (,) char and return list
of result strings. Quotation marks are properly interpreted.
match(str, pat)
Match is a simple text matching function based on wildcards.
Following metacharacters are allowed in the pattern:
* matches any zero or more characters
? matches any single character
\* matches asterisk (*) character
\? matches question mark (?) character
\d matches one digit character
\D matches one non-digit character
\s matches one whitespace character
\S matches one non-whitespace character
\w matches one alphabetic character
\W matches one non-alphabetic character
Example:
say match("abc.txt", "*.txt")
say match("abcd?;", "a*\\?;")
findpat(str, pat, off)
Finds pattern in a string starting from offset off.
Following metacharacters are allowed in the pattern:
* matches any zero or more characters
? matches any single character
\* matches asterisk (*) character
\? matches question mark (?) character
\d matches one digit character
\D matches one non-digit character
\s matches one whitespace character
\S matches one non-whitespace character
\w matches one alphabetic character
\W matches one non-alphabetic character
If the pattern was found a list is returned with position, length and value of the finding.
NULL is returned in case the pattern was not found.
Example:
1) findpat("abcdef", "b*e", 0)
2) findpat("abcdef", "?c?", 0)
3) findpat("abcdef", "c??h", 0)
Result:
1) {1, 4, bcde}
2) {1, 3, bcd}
3) NULL
findpats(str, pat)
Finds all occurrences of pattern in a string.
Following metacharacters are allowed in the pattern:
* matches any zero or more characters
? matches any single character
\* matches asterisk (*) character
\? matches question mark (?) character
\d matches one digit character
\D matches one non-digit character
\s matches one whitespace character
\S matches one non-whitespace character
\w matches one alphabetic character
\W matches one non-alphabetic character
The findings are reurned as a list. If the pattern was not found an empty list is returned.
Example:
findpats("yy: a20x a30x b20z", "a*x")
Result: {a20x, a30x}
fopen(name, mode)
Returns file stream handle or NULL if an error occurred.
mode - "C"like open mode: r, w, a, ...
fclose(file)
Closes file stream.
fgetline(file)
Returns one line read from file stream.
Example:
var f, line
set f = fopen("c:\example.txt", "r")
if f == NULL
println "Error! File was not opened."
return 100
endif
while feof(f) == 0
set line = fgetline(f)
println line
endwhile
fclose(f)
freadlines(name)
Returns array of lines read from file or NULL in case of an error
Example:
for line in freadlines("c:\\example.txt")
say line
endfor
Result:
fread(file, count)
Reads count bytes from file stream and returns them as a string.
fwrite(file, str)
Writes string str to file.
feof(file)
Returns non zero if file stream reached end of file.
dir(path)
Returns list containing all entries of the directory specified by path.
Example:
# recursively list subdirectories encountered
proc list(path)
var d = dir(path)
for f in d
if f != "." && f != ".."
println path + "\" + f
if isdir(path + "\" + f)
list(path + "\" + f)
endif
endif
endfor
endproc
list("c:\")
fsize(path)
Returns length of file specified by path.
isdir(path)
Returns nonzero if a file specified by path is a directory.
fexists(path)
Returns 1 if file or dir specified by path exists or 0 otherwise.
fstat(path)
Returns a list with file or directory inforation or -1 in case of an error. The list contains following elements: last access time, creation time, modification time, size, mode, device number.
chdir(path)
Changes the current working directory to path.
Returns 0 if successful or -1 in the case of an error.
getcwd()
Returns the current working directory.
ftell(file)
Returns the current position of a file.
fseek(file, offset, origin)
Moves the file pointer to a specified location. Origin may be: 0 - beginning of file, 1 - current position, 2 - end of file. Returns 0 if successful.
splitpath(path)
Breaks a path into its four components: drive, dir, file name and extension.
Example:
set items = splitpath("c:\winnt\notepad.exe")
say "Drive: ", items[0]
say "Dir: ", items[1]
say "File: ", items[2]
say "Ext: ", items[3]
makepath(drive, dir, fname, ext)
Creates a path. NULL arguments are allowed.
Example:
set path = makepath("C:", "\\winnt", "notepad", "exe")
sin(x)
Returns the sine of x.
cos(x)
Returns the cosine of x.
sqrt(x)
Returns the square-root of x or an indefinite if x is negative.
srand(x)
Sets a random starting point to x.
rand()
Returns a pseudorandom number in the range 0 to RAND_MAX.
pow(x, y)
Returns x raised to the power of y.