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

I GETTING STARTED

1. Introduction

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.

1.1. Hello, World!

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 + "!"

2. Author

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.

II LANGUAGE REFERENCE

3. Basic Syntax

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.

4. Variables

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} }

5. Constants

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.

6. Expressions

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"]

7. Control structures

7.1. if

if allows for conditional execution of instructions.

if <condition>
    (<instruction>)*
[elif <condition>
    (<instruction>)*]*
[else
    (<instruction>)*]
endif

else and elif blocks are optional.

7.2. while

while executes instructions as long as the while expression evaluates to non-zero value.

while <expression>
    (<instruction>)*
endwhile

7.3. for

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)

7.4. return

return immediately ends execution of function or script and return value specified by the return expression.

return <expression>

7.5. break

break terminates the nearest enclosing loop (for or while).

8. Functions

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)

9. Input/Output

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

10. Command line arguments

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

11. Modularity

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.

III AVAILABLE FUNCTIONS

12. General

12.1. int

int(x)

Returns x converted to an integer

Example:

    println int("12.7")

Result: 12

12.2. double

double(x)

Returns x converted to a double. double function correctly converts strings.

Example:

    double("1e-1")

Result: 0.1

12.3. string

string(x)

Returns x converted to a string.

12.4. typeof

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.

12.5. time

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

12.6. strtime

strtime(t)

Returns time value t converted to a string.

Example:

    println strtime(time())

12.7. size

size(l)

Returns size of list l.

Example:

    var l = {"a", "b"}
    println size(l)

Result: 2

12.8. exec

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%"))

12.9. start

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

12.10. range

range(from, to)

Produces a list containing integers from from to to.

12.11. mktime

mktime(year, month, day, hour, minutes, seconds)

Produces a time value from arguments or -1 in case of an error.

12.12. eval

eval(expr)

Evaluates expression expr.

Example:

    var a = 10
    println eval("a + 5")

Result: 15

12.13. defined

defined(varname)

Returns 1 if variable varname is defined.

12.14. localvars

localvars()

Returns list of all currently defined local variables.

12.15. globalvars

globalvars()

Returns list of all currently defined global variables.

Example:

    var allDefinedVars = localvars() + globalvars()

12.16. functions

functions()

Returns list of all currently defined functions.

12.17. setglobal

setglobal(varname, val)

Sets global variable varname to val. Use setblobal inside functions when there is a local variable with the same name.

12.18. clone

clone(var)

Returns a clone of variable var.

12.19. setprecision

setprecision(prec)

Sets floating-point display precision to prec.

12.20. setfloatdisplay

setfloatdisplay(type)

Sets floating-point display type: 0 - fixed, <>0 - scientific.

12.21. version

version()

Returns Irys interpreter version.

12.22. getenv

getenv(name)

Returns a value for variable name from the current environment. Returns NULL in case the variable is not defined.

12.23. setenv

setenv(name, value)

Sets value for variable name in the current environment. Returns 0 if successful or -1 in the case of an error.

13. Arrays and Maps

13.1. sort

sort(l)

Sorts list l.

13.2. arrayfind

arrayfind(l, v)

Returns position of value v in array l or -1 if v was not found.

13.3. arraydel

arraydel(l, pos)

Removes an element from array l at position pos.

13.4. arrayinsert

arrayinsert(l, pos, val)

Inserts value val at position pos in array l.

13.5. arrayset

arrayset(l, pos, val)

Sets value val at position pos in array l.

13.6. mapget

mapget(map, key)

Returns value associated with key or NULL if the key does not exist in the map.

13.7. mapset

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.

13.8. mapdel

mapdel(map, key)

Removes a key and the associated value from the map.

14. Strings

14.1. strlen

strlen(x)

Returns length of given string x.

Example:

    println strlen(string(100))

Result: 3

14.2. chr

chr(n)

Returns string containing one character which ASCII code is given by n.

Example:

    set newline = chr(13) + chr(10)

14.3. ord

ord(c)

Returns ASCII value of the first character of string c.

14.4. split

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}

14.5. substr

substr(str, off, cnt)

Returns part of string str starting from offset off which length is at most cnt characters.

14.6. find

find(str, pat)

Returns the lowest index of substring pat in string str or -1 if substring was not found.

14.7. findnext

findnext(str, pat, off)

Returns the lowest index of substring pat in string str or -1 if substring was not found.

14.8. rfind

rfind(str, pat)

Returns the highest index of substring pat in string str or -1 if substring was not found.

14.9. rfindnext

rfindnext(str, pat, off)

Returns the highest index of substring pat in string str or -1 if substring was not found.

14.10. replace

replace(str, src, dst)

Returns copy of string str in which all occurrences of substring src were replaced by string dst.

14.11. trim

trim(str)

Returns copy of string str in which all leading and trailing whitespace characters are removed.

14.12. ltrim

ltrim(str)

Returns copy of string str in which all leading whitespace characters are removed.

14.13. rtrim

rtrim(str)

Returns copy of string str in which all trailing whitespace characters are removed.

14.14. trimchrs

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

14.15. right

right(str, len)

Returns last len characters of string str.

14.16. left

left(str, len)

Returns first len characters of string str.

14.17. upper

upper(str)

Returns copy of string str in which all lower case letters are converted to upper case.

14.18. lower

lower(str)

Returns copy of string str in which all upper case letters are converted to lower case.

14.19. join

join(list, sep)

Returns concatenation of words in list with sep.

Example:

    var j = join({"A", "B", "C"}, "--")

Result: j = "A--B--C"

14.20. splitCSVRow

splitCSVRow(str)

Splits a line of CSV file str by comma (,) char and return list of result strings. Quotation marks are properly interpreted.

14.21. match

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*\\?;")

14.22. findpat

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

14.23. findpats

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}

15. Files

15.1. fopen

fopen(name, mode)

Returns file stream handle or NULL if an error occurred.

mode - "C"like open mode: r, w, a, ...

15.2. fclose

fclose(file)

Closes file stream.

15.3. fgetline

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)

15.4. freadlines

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:

15.5. fread

fread(file, count)

Reads count bytes from file stream and returns them as a string.

15.6. fwrite

fwrite(file, str)

Writes string str to file.

15.7. feof

feof(file)

Returns non zero if file stream reached end of file.

15.8. dir

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:\")

15.9. fsize

fsize(path)

Returns length of file specified by path.

15.10. isdir

isdir(path)

Returns nonzero if a file specified by path is a directory.

15.11. fexists

fexists(path)

Returns 1 if file or dir specified by path exists or 0 otherwise.

15.12. fstat

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.

15.13. chdir

chdir(path)

Changes the current working directory to path. Returns 0 if successful or -1 in the case of an error.

15.14. getcwd

getcwd()

Returns the current working directory.

15.15. ftell

ftell(file)

Returns the current position of a file.

15.16. fseek

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.

15.17. splitpath

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]

15.18. makepath

makepath(drive, dir, fname, ext)

Creates a path. NULL arguments are allowed.

Example:

    set path = makepath("C:", "\\winnt", "notepad", "exe")

16. Math

16.1. sin

sin(x)

Returns the sine of x.

16.2. cos

cos(x)

Returns the cosine of x.

16.3. sqrt

sqrt(x)

Returns the square-root of x or an indefinite if x is negative.

16.4. srand

srand(x)

Sets a random starting point to x.

16.5. rand

rand()

Returns a pseudorandom number in the range 0 to RAND_MAX.

16.6. pow

pow(x, y)

Returns x raised to the power of y.