TIRC scripting language

trampknowledgeΛογισμικό & κατασκευή λογ/κού

4 Νοε 2013 (πριν από 3 χρόνια και 7 μήνες)

63 εμφανίσεις

TIRC scripting language
TIRC language version: 0.4
This document assumes you already got some
basic
knowledge of programming and scripting,
especially for C like languages.
Language syntax
TIRC script is a type-less language, which means it does not differentiate between integers and
strings.
Defining meta-data of the script
All scripts that you load into TIRC, should always begin with a
script
block.
Code comments begin with semi-colon.
script scriptname {
; Defining a custom command.
; First parameter is the name of the command (here: /mycmd)
; Second parameter is what function to redirect to, functions are
; covered later.
command mycmd myfunction

; Defining an event and assign a function to it.
; First parameter is what event (events is covered later).
; Second is what function to run the event on.
event start on_start
; Defining a timer.
; First parameter defines an unique ID to the timer.
; Second parameter binds the timer to a function.
; To use the timer, see further down, on «commands»
timer timer-id function
}
Code 1: The script block
Inside there you can define events, custom commands, timers and include other files (to be done).
Functions
A function is defined within a
function
block
function myfunction() {
echo Hello there!
}
Code 2: A function
Here we got a function with no parameters.
To call a function from a command, you have to link a command name to this function, in the
script

section. An example of that is already given in
Code 1
.
Within a function you can run any commands.
To run a function instead of a command, prefix the function name first.
function foo() {
echo bar
}
function anotherfunc() {
echo This is a test!
$foo
; Both $foo and $foo() is valid to use.
}
Code 3: Using functions inside a function
Variables
Variables can contain temporary data.
They disappear when end of function is reached.
All variables must be prepended with a percent sign.
We use the keyword
var
to set or update a variable.
function vartest() {
var %myVar This is the content!
echo %myVar
}
Code 4: Variables
If you add the keyword
VARTABLE
in your script, you will get a table of variables and it's content at

that point in the function, written out to your standard cout. This will usually be the
command/terminal if you launch TIRC from there.
This is mostly for debugging purposes if the variables go postal for some reason.
Functions with parameters
A parameter is data you send into a function. This is data that should be used to produce a result of
the function, or make the function do anything useful.
However, it's not always you need a function with parameters.
When defining parameters to a function, we use variables as the parameter definition.
function vartest2(%mypara) {
echo %mypara
}
Code 5: Variables as function parameters
The following code is a working example where we define a command named /mycmd and links it
to the function MyFunction.
If you now write
/mycmd Hello World!
It'll /echo out the Hello World! -text.
script test1 {
command mycmd MyFunction
}
function MyFunction(%text) {
echo %text
}
Code 6: Working function example
Events
An 'event' will run a given function when something happens in TIRC.
Following list is a few basic events, to provide an example:

Start

Exit

Connect(%server, %port)

Disconnect(%server, %port)

Join(%channel, %nickname)

Part(%channel, %nickname, %message)

Quit(%nickname, %message)

Msg(%nickname, %target, %message)
Some events need a function with parameters. Those are defined in the list at previous page.
The MSG event combines both private and channel messages.
To differentiate between a channel msg and a private message, you can check if %target is equal to
your nickname – if it is equal, it's a private msg.
Using
IF
will be covered later.
The following example shows how to use
Start
event and the
Join
event.
script test2 {
event start on_start
event join on_join
}
function on_start() {
echo Welcome to TIRC! This is an example script running.
}
function on_join(%channel, %nickname) {
; Kinda useless, but as an example, it's good.
echo %nickname joined %channel ! :D
}
Code 7: Using events
IF statements
The
IF
statements in TIRC script is currently very basic.
There's no AND or OR operators (yet).
Function iftest() {
var %vara 5
var %test 8
if (%vara == %test) {
echo yay
}
if (%vara != %test) echo This is possible too.
}
Code 8: IF expressions
Currently supported operators
Operator
Function
= =
Equals
! =
Not equal
>
Greater than
<
Less than
>=
Greater than or equal
<=
Less than or equal
TIRC also support && and || operators (AND / OR)
if ((%a == 123) && (%b <= 4)) { .. }
Code 9: AND example
Increment and decrement
You might increment and decrement variables with number-only content.
Use the keywords
inc
and
dec
for this task
function incdectest() {
; Set variable %a to be 4
var %a 4
inc %a
; Increment by 1, %a now equals to 5
inc %a 5
; Increment by 5, %a now equals to 10
dec %a
; Decrement by 1, %a now equals to 9
dec %a 8
; Decrement by 8, %a now equals to 1
}
Code 10: Increment and decrement examples
Containers
Containers in TIRC is more like «global» variables inside a script, making data accessible by other
functions.
wcon id data
Write data to container with name «id».
If the container does not exist, it'll be created.
dcon id
Delete any content of container
«id».
If it doesn't exist, it'll be ignored.
con id %var
Read out any content from container «id», storing it to %var.
If the container doesn't exist, %var will be set to empty.
Control codes
Control codes is a way of make bold, underlined and colored text when you type text in a chat
window.
On some system the control code letters will either appear as a space, as a square character or
similar.
CTRL + B
gives a bold text after that control code, and end bold text with same key stroke.
CTRL + U
gives underlined text
CTRL + K

is colored text.
You specify a color by adding the number 0 – 15 after control letter.
You might also add a comma and add another color code, for background color.
Color table
0 White
1 Black
2 Blue
3 Green
4 Bright Red
5 Red
6 Magenta
7 Brown
8 Yellow
9 Bright Green
10 Cyan/Turquoise
11 Bright Cyan
12 Bright Blue
13 Bright Magenta
14 Dark Gray
15 Light Gray
Commands
Commands with red text is not yet implemented and are still on the to-do list.
/timer id msec
Activate the timer ID with «msec» milliseconds.
This timer will run until it's stopped.
/stimer id
Stops the timer ID.
/window [di] @name
Create a custom window. The name must be prepended with an at-sign @.
By default (no switches), you'll get a text window without input text box.
Switches
d
Create a window for drawing.
i
Add an text-input box.
/paintdot @window x y size color
Draw a dot in the specified drawing window at X and Y.
The size is the radius measured in pixles.
Color is the 0-15 control color codes you get from CTRL+K.
/paintline @window x1 y1 x2 y2 size color
The size is width in pixles.
/painttext @window x y color font fontsize text
Font-size is defined in pixles.
/socket [lc] socket_name hostname port
Open a TCP socket, or listen to a port.
The socket name MUST be unique, or else it'll be discarded. It's purpose is to identify which socket
you want to write to or receive from.
When receiving data you must use the «sockread» event:
script socktest {
event sockread on_sockread
}
function on_sockread(%sockname, %data) {
; Do something useful here.
}
Code 11: Socket read example (This might change!)
For listening sockets, there's the «newsocket» event, that runs when new connections come in.
script socktest2 {
event newsocket on_newsocket
event sockread on_sockread
}
function on_newsocket(%sockname, %ip) {
; %sockname contains the listening sockets name.
; %ip is the connecting IP
}
function on_sockread(%sockname, %data) {
; Do something useful here.
}
Code 12: Listening socket (This might change!)
Switches
l
Listen to the given port. Do not specify «hostname» if you specify the
l
-switch! Port only.
c
Close the given socket name. Cannot be combined with any other switches!
/sockwrite socket_name data
Send (text) data to the socket_name.
Currently' there's no support for binary writing.
/sockrename socket sockname
This one accepts a client connection from a listening socket.
First parameter is the socket name for the listening socket, while the second parameter is the name
you set for the new incoming connection.
/sockclose socket
This declines the incoming connection on the given listening socket.