Groovy overview



Groovy is the scripting language used by the scripts that run on SexScripts. One difference between groovy and other scripting languages used by other Script based teasers (like the one cybermistress'd used), is that groovy is a general propose scripting language. That means groovy is more powerful than other scripting languages in the sense that if you know how to do it, you can practically do whatever you imagine in your script.

This chapter describes how to write groovy code to be executed in a script for SexScripts software. Dominating this language gives you enough power to make whatever you want to in your script, and control every aspect of it. So if you're planning to do some advanced and complicated script, is strongly recommended to learn how to write groovy pieces of code so you can benefit from it.



Every groovy piece of code consist of a set of instructions, called statements. You can separate the statements with a ';' symbol if you want, to make your script more readable. All statements in a groovy piece of code must be in separated lines so you cannot put two statements on the same line. So the global structure of every groovy piece of code is:

<statement>
<statement>
<statement>

Where <statement> is one possible groovy statement. There are a number of different types of statements, which will be discussed below.



Variables

Like any programming language groovy contains variables. If you have used variables in ssScriptMaker you should be used to the idea of a variable. Variables are locations to the memory of the computer that can store data, for example, a number or a text. They have a name so that you can refer to them. To use a variable you must declare it first, with the special word def followed by the name of the variable. To name a variable you can only use letters, numbers, and the underscore symbol '_'. The name of a variable cannot contain any space and must begin with a letter. Note that in groovy lower case letters are not the same as upper case letters, so the name 'index' is different to 'Index'. You can declare more than one variable in a def statement separating the names of the variables by commas. Here are some examples of variables declarations:

def seconds
def x, y
def loopsCount



Values

In groovy, a value, also called literal, is a specific data that can be stored in a variable. Every value in groovy must be of one of the below types:

-An integer number. To write it we simply write the integer number (eg 6, 0, -789, 3256, -9, 45, …)

-A real number. To write it we write it with the period and its decimal part (eg 6.0, 0.0, -547.98, 3.1416, …)

-A character. A value of this type represents a single character, that can be a letter, a digit, or any other symbol that can be typed. To write them we close the character between single quotes (eg 'a', 'B', '8', ';' 'z', ' ', '%', …). There exist also special characters called escape characters, that are the following: '\n' is a new line character, '\r' is a carriage return character, '\t' is a tab character, '\\' is a single backslash, '\'' is a single quote, '\”' is a double quote, '\b' is a backspace character, '\0' is the null character.

-A character string. We are going to refer to these values as strings. They are a concatenation of any number of character values. They can be used to represent text values. To write them type all the characters of the string between double quotes. You can also use escape characters. (eg “Hello World!”, “this is a string”, “line 1\nline 2\nline 3”, …)

-A boolean. A value of this type represents a logical value that can only be one of the two special values true or false.

-null. The special word null isn't actually a type of a value. It is a special value to indicate the absence of any value.



Assignments

An assignment stores a value in a variable. It has the form:

<variable> = <expression>

Where <variable> is the name of a declared variable and <expression> can be a simple value but can also be more complicated. You can also assign a value to a variable when declaring it. Rather than assigning a value to a variable, if the variable already is storing a value, one can also add the value to the current value of the variable using +=. Similar, you can subtract it using -=, multiply it using *= or divide it using /=. You can also use ++ as a shortcut of of += 1 and –- as a shortcut of -= 1

At the end of this piece of code:

def x
def y = 6
def z = 2
x = 3
y += 4
x++
z *= 8

The variable x will be storing 4, y will be storing 10 and z will be storing 16.



Expressions

In groovy an expression can be as simple as a single value, or can be more complicated using operators with values. Operators are special symbols that take one or two values and return a single value as a result. The operators that take only one value are called unary operators, and the operators that take two values are called binary operators. To use a unary operator write its symbol to the left of the value to operate. To use binary operators write its symbol between the two values to operate.

The following unary operators exist:

- : negates a numeric value.

! : Boolean not. turns boolean value true into false and false into true.



Also, the following binary operators exist:

&& : Boolean and. Takes two boolean values and returns true if the two values are true; returns false otherwise.

|| : Boolean or. Takes two boolean values and returns true if at least one of them is true; returns false otherwise.

== : Returns true if the values are equals, or false otherwise.

!= : Returns true if the values aren't equals, or false otherwise.

< : Returns true if the value to the left is smaller than the value to the right, or false otherwise.

> : Returns true if the value to the left is larger than the value to the right, or false otherwise.

<= : Returns true if the value to the left is smaller or equal to the value to the right, or false otherwise.

>= : Returns true if the value to the left is larger or equal to the value to the right, or false otherwise.

+: Takes two numeric values and returns their addition. It can also take a string with another string or any other value and returns a string resulting of its concatenation.

- : Takes two numeric values and returns their subtraction.

* : Takes two numeric values and returns their multiplication.

/ : Takes two numeric values and returns their division.

% : Modulo. Takes two numeric values and returns the remainder of their integer division.



Instead of values, the operators can also take variables, sub-expressions placed between brackets, or functions that return a value to operate. Later we'll see how functions work. Here are an example of assignments of expressions:

def x = 23
def str = “Hello world”
def y = x-8
x *= y%2
x = 23*( (2+4) / y )
str = “Hello ” + “world”
def b = (x < 5) && !(x==2 || x==4)
b = !b || (str != null)



Lists

In groovy, lists are variables that instead of storing one single value, store a list of values. The values stored in a list doesn't need to be of the same type. The number of values a list stores it's called its size. So a list of size 4 will store 4 values. To define a variable as a list we must assign it a list value. A list value is represented by all the elements it contains separated by commas and placed between square brackets. For example, [1, 2, 3] represents a list of size 3 with the numeric values 1, 2, 3 in it. [] represents an empty list, of size 0. Once we have a list, we can access the values stored in it with an index, indicating it at the right of the array and placed between square brackets, for example, myList[2] will reference the value indexed by 2 of the list myList. All the indexes in a list of size X go from 0 to X-1 inclusive. We can assign values to an indexed position in the list like if it was a variable, and can also use it like a variable in expressions.

Here is an example of a declaration of a list an access to its positions:

def list = [ -8, 2, “xyz”, true ]
list[0] = 'a'
list[2] = abcd”
list[3] = false
def b = !list[3] && (list[1] <= 5)

b will be true if this piece of code is executed.



The size of lists isn't a fixed number, it can vary by adding and/or removing values from the list. To add new elements at the end of a list you can use the binary operator << , or the binary operator + , or the list function add(e). To add a new element to the list at a specified index you can use the list function add(index, e). By adding an element at a specified index, all the elements that go from the element that was originally at that index to the end of the list shift their positions by one to the right. You can also use the + operator between two lists to concatenate them. To remove an element from the list you can use the operator - , or the list function remove(e). To remove an element at a given index from the list you can use the list function remove(index). When an element is removed from the list, all the elements to its right shift their position by one to the left. Finally, if you wish to know the current size of a list you can use the list function size(). Let's see an example of all this:

def list = []
def size1 = list.size()
list = ['a', 2, 3, false, 'c']
list[3] = true
def size2 = list.size()
list = list – 'c'
list.remove(true)
list.remove(0)
def size3 = list.size()
list = list + [6,7]
list = list << “hello”
list.add(2,'x')
def size4 = list.size()

When this code ends its executions the variable size1 will be 0, the variable size2 will be 5, the variable size3 will be 2, the variable size4 will be 6, and the list will be [2, 3, 'x', 6, 7, “hello”].



If statement

An if statement has the form:

if (<expression>) <statement>

or the form:

if (<expression>) <statement> else <statement>

The expression will be evaluated and it must return a boolean value. If the value is false the statement after else will be executed, otherwise (true) the other statement is executed. If you do not add an else case and the expression returns false, no statement will be executed.



The statements here can also be blocks. A block is a set of statements placed into curly brackets ({ }). So the if statement can also have the form:

if (<expression>)
{
<statement>
<statement>
<statement>
...
}

or the form:

if (<expression>)
{
<statement>
<statement>
<statement>
...
}
else
{
<statement>
<statement>
<statement>
...
}

Then if the expression is evaluated false all the statements in the else block will be executed, otherwise all the statements in the other block will be executed. And if there isn't any else case and the expression is evaluated false, no block will be executed.



Here's an example. Let's assume that variable seconds stores th number of seconds it took the slave to perform some action, and the variable score stores a score of how well the slave's behaving. The following code update the slave's score according to how long it took to realize the task:

if (seconds <= 75) score += 5 else score -= 5



While statement

A while statement has the form:

while (<expression>) <statement>

As long as the expression is true, the statement (which can also be a block) is executed. Be careful with your while loops. You can easily make them loop forever, in which case your script will hang and not react to any user input anymore.

Here's an example. In this example some functions of the SexScripts API are used. Take a look to that section if you aren't used to a function from this example. The following code will ask the slave the same question until it is correctly answered.

def question = "How a slave should always be?"
def answer1 = "Sitting on the sofa"
def answer2 = "kneeling before your feet"
while (getBoolean(question, answer1, answer2)) {
show("Wrong. Try again...")
wait(3.0)
}
show("Correct!")
wait(3.0)



For statement

A for statement has the form:

for (<statement1>; <expression>; <statement2>) <statement3>

This works as follows. First statement1 is executed. Then the expression is evaluated. If it is true, statement3 (which can also be a block) is executed; then statement2 and then the expression is evaluated again. This continues until the expression is false.

This may sound complicated. You should interpret this as follows. The first statement initializes the for-loop. The expression tests whether the loop should be ended. Statement2 is the step statement that goes to the next loop evaluation.

The most common use is to have a counter run through some range.

And here comes the example. This time the following code ask the slave to select some options and counts how many options the slave's selected:

def message = "Select all the practices you've ever done"
def texts = ["anal", "deepthroating", "threesome", "bdsm", "bondage"]
def defVal = [false, false, false, false, false]
def answer = getBooleans(message, texts, defVal)
def count = 0
for (def i=0; i<answer.size(); i++) {
if (answer[i]) count++
}
if (count < 5) show("Only "+count+"?")
else show("That's fine.")
wait(4.0)



Functions

A function is some piece of code encapsulated that can help to keep your script clean, or to perform some features you will need. To call a function from groovy code you will have to write the function name followed by zero or more parameters between brackets, separated by commas:

<function>(<param1>, <param2>, ...)

There are two types of functions. First of all, SexScripts has an API with a collection of built-in functions, to control all aspects of your script. Secondly, any function you create or import into your script can be used.

Note that for a function without arguments you still need to use the brackets. Some functions return values and can be used in expressions. Others simply execute commands.



Comments

A comment is some text that will be totally ignored by the script when executing, but for programmers they're still there and can be useful. You can add comments to your pieces of code. This will help to understand what's going on at some point in your code. Everything on a line after // is ignored. You can also make a multi-line comment by placing the text between / * and */.



Example:

def x = 5 // This is a line comment
// This is another line comment
/*
And this
is a
multi-line
comment
*/



Java Objects

Apart from groovy constructions and statements, you can also use all the java Objects you want to from the java standard libraries. It's out the scope of this little introduction to script programming to explain how works every standard java Object and how to use them in your script, but if you're interested you can search for the java reference and documentation online and learn how to use them. As an example, here you can see how to use the java Date Object to retrieve the current date into a variable:

def date = (new Date()).format(“dd/MM/yyyy”)



The little introduction of groovy explained in this section is only a very little part of the whole groovy world. You can search for more tutorials online if you're interested in going deeper with this language.



return to the contents page