Preliminaries
Before we dive into the description of the different building blocks of the ROLEG DSL,
it is helpful to make some general remarks about scripting. Feel free to skip this section if you have written code before.
In most programming languages, code is written in plain text, and the same is true for the ROLEG DSL.
As such, we will need a text processor that supports plain text (e.g. .txt files).
This means that we can not use programs like Microsoft Word. Fortunately, most operating systems come with a plain text processor.
For Windows, this is Notepad, and macOS comes with TextEdit. These programs do the job, but better options exist.
As you will have noticed, programs like Microsoft Word let you know when you spell something incorrectly or when you construct a sentence that is grammatically incorrect. The same concept can be applied to computer code. The ‘grammar’ or syntax of computer code needs to be absolutely perfect for it to work, and (free) text processors exist that help you write syntactically correct code. Unfortunately, these programs do not know about the specific syntactic rules of the ROLEG DSL. However, they do help you with general rules and standards in computer code. We will briefly illustrate some of these rules and standards and how an intelligent plain text editor helps implement them, such that coding ROLEG DSL files becomes as easy as possible.
Tip
From ROLEG DSL version 3 on, the Live Editor is available. This editor automatically applies good coding conventions such as closing brackets automatically and applying equal indent. We recommend you use this editor for the best results. For offline working, you can use the free text processor Atom or any other comparable program instead.
Browser usage
ROLEG works on most major browsers, like Firefox, Safari, Microsoft Edge and Google Chrome. However, we recommend both researchers and participants to use Google Chrome for maximum compatibility and performance. Not all features work equally well across browsers, although ROLEG remains functional on each. If you find a feature that does not work well based on the browser you use, please let us know at roleg@let.ru.nl.
Please note that ROLEG currently does not support participation on mobile phones or tablets. Therefore, it is
discouraged to conduct experiments on mobile devices, since certain features might not behave as they should. If you
decide to try and conduct experiences this way, you might experience issues especially with
media and speech blocks on mobile devices.
Closing brackets and parentheses
When defining an object in a programming language you will often have to use brackets and parentheses. An intelligent text editor will automatically include a closing bracket when you type the opening bracket. Again, this limits the amount of experiment breaking mistakes you can make. This looks something like this:
Consistent indentation
To make the structure of computer code more apparent, it is advised to indent everything that is contained within another object
(by pressing ‘tab’). For instance, both the title and the (to-be-written) info screen are defined within the experiment object.
As such they should both be indented by the same amount. Intelligent text editors will maintain the same indentation automatically.
So, when you press ‘Enter’ after defining the title of the experiment, you will be at the same indentation on the next line:
Comment usage
Most programming languages allow the use of comments. In a comment, you can use regular language to describe what
(a certain part of) the programming code is doing. Comments will not be visible to participants,
but they will help you (and other researchers) understand your code. Comments have to be demarcated using special characters.
Otherwise, the ROLEG DSL will try to interpret your comments as computer code.
Two types of comment are possible in ROLEG, both of which are illustrated in the code below.
/*
The first type of comment is demarcated by a forward slash followed by
an asterisk at the start of the comment and an asterisk followed by a
forward slash at the end of the comment. This makes it easy to add a
comment that spans multiple lines. Such comments are often used at the
start of script to briefly introduce the experiment/author/version.
*/
// The second type of comment is preceded by double forward slashes.
experiment {
// This type is used to annotate code with short descriptions
trial { // You can even add these comments after some code
response {
button
}
}
}
Quote usage
String values in the ROLEG DSL need to be surrounded by double quotes ". In the case you want to use this within the String value, you need to escape them by writing \" instead. Alternatively, you can surround the String value with single quotes ' and use double quotes within the String value without needing to escape them. In this case, you cannot use single quotes anymore freely and need to escape those instead using \' if so desired.
experiment {
trial {
stimulus {
// Here, we use the escape character \" to use double quotes within a String value
text = "Please press \"Continue\" when you are ready to proceed"
}
response {
button = "Continue"
}
}
trial {
stimulus {
// Here, we use single quotes to surround the String value, in order to freely use double quotes within
text = 'Please press "End Experiment" to finish'
}
response {
button = "End experiment"
}
}
}
Linebreaks
Linebreaks written in a String value in a ROLEG DSL are not reflected in the experiment presentation.
To present a linebreak in a displayed text, type \n instead. You can use this character to separate instructions into paragraphs, for example.
To write a linebreak inside a String that should not be shown in the experiment presentation, type \ followed by a linebreak. Using linebreaks only visible in the script can improve readability. If you write a linebreak in a String without the \ character prior, your DSL not valid.
You can combine these two characters to both present a linebreak to the participant and break up the String into
multiple lines in the DSL code, by typing \n\ followed by a linebreak.
If the width of a line of text exceeds the width of the participant's browser screen, the text will wrap around. If controlled linebreaks are important to your experiment, we recommend you place linebreaks manually and present the experiment fullscreen for a maximally wide browser window.
Tip
ROLEG also automatically removes any leading indentation when followed by the | character. This allows you to indent your text to keep it visually structured with the rest of your script, improving readability. Without using the | character, the leading indentation would be presented to the participant. See the code below for an example.
experiment {
trial {
stimulus {
text = "Welcome to this experiment.\n\nOnce you click the button below, the experiment will start."
}
response {
button
}
}
trial {
stimulus { // (1)
text = "\
|For very long texts, it might\
| become convenient to use the slash character to separate this text over\
| multiple lines in your code without showing this in the final experiment."
}
response {
button
}
}
trial {
stimulus {
text = "\
|You can also combine these two characters\n\
|to both use a linebreak in your editor and to present the linebreak to the participant."
}
response {
button
}
}
}
- Notice how the
|character is used to remove any leading whitespace per line.
Short DSL form
You can use the alternative member names and shorthand accessors of DSL blocks to write very succinct code. You can even combine this with the fact that ROLEG largely ignores linebreaks in your code.
Keep in mind, writing your code in this way can be at the expense of its legibility. In this manual, we will always include linebreaks, even if not required.
experiment {
t {
s { text = "Press 'Continue' to start the experiment" }
r { button }
}
}