User’s Guide to Rendition Script
*BEFORE READING: A great reference to read before this document is the instruction overview. This will provide an overview of all the instructions included in Rendition Script along with a description of the instruction, a list of required parameters, and descriptions of the parameters. When mentioning instructions in this document, it is assumed you have read this overview or that you have a reasonable knowledge about the instructions. Also, it is encouraged to use the User Calculator which was developed for the purpose of learning the language. This way you can test things out as you learn them. The best way to learn this, or any other language, is to look at examples and experiment.
·
What is Rendition Script?
Rendition Script is a programming language that is unique from other languages. While most languages are designed for the programmer, Rendition Script is designed for the user. It is a way for programmers to make their applications customizable to the highest degree or to allow users to process data fed to them from the application (images, videos, audio, etc.).
· Broad applications of Rendition Script
There are unlimited applications for Rendition Script. Here are some broad examples:
§ Process data fed to the user from the application
§ Create an interface for the user to control the application
§ Create windows executables or HTML documents that visually allow anyone to enter data, press a button, and display output from the processed input
· Specific applications of Rendition Script
Here are some specific examples of applications for Rendition Script. Please remember that these are just a few examples and the possibilities are endless:
§ Image Script is one example of an application for Rendition Script. It uses Rendition Script to allow the user to manipulate image data by creating their own Rendition scripts.
§ Graph Script applies Rendition Script in a similar way Image Script. The difference is that instead of the scripts controlling image data, they are used to create graphical algorithms (an example would be the formula for a line: y = mx + b).
§ Visual Rendition Script is an IDE for Rendition Script. It allows users to create their own windows executables with buttons, check boxes, edit boxes, etc. The controls interact with each other via Rendition Script. Program layouts can be saved as both workspaces and templates.
§ Another way for a programmer to implement Rendition Script would be to expose an interface to the user so they can call procedures (functions, sub routines, etc.) that the programmer has written. The user could call a series of procedures with parameters at a specified time interval, or at the click of a button.
· Basic syntax of a Rendition script
A Rendition script is composed of any number of lines and is case sensitive (meaning “test” is different than “Test”). Each line contains an instruction along with an arbitrary amount of parameters separated by commas. Here is a diagram of one of the most basic Rendition scripts:
As you can see, “move” is the instruction in this simple script. “input” and “output” are the parameters for the “move” instruction which requires two parameters. What this simple script will do is take whatever value is in input, and make output have that same value.
Other instructions follow the same
rules except some may take zero parameters (such as “exit”), some may take
three (such as “add”), and some may take an optional amount of parameters. For
example, the “list” instruction requires one parameter for the name, and all
parameters after that are optional and will be added to the list. Here are some
examples:
§ list mylist à Creates a list with no current values included (values may be added / removed later in the script)
§ list mylist, 5 à Creates a list with the value of five included
§ list mylist, 5, 10, 15 à Creates a list with the values of five, ten, and fifteen included
Lines may also be blank or have comments declared by the “//” token. Here is an example that uses blank lines and comments:
memory x, 5
memory y, 0
//Make y
equal 5. This is a comment. You can put anything here and it will be ignored by
Rendition Script!!*&%#,,,,
move x, y
In Rendition Script, each line is processed separately so instructions can not span multiple lines. Here is an example:
This is incorrect:
add 10, 5,
output
This is correct:
add 10, 5, output
When using instructions, remember that you may use variables (described below) as parameters. Sometimes variables are actually required as a parameter (such as in the “add” instruction where the last parameter must be a variable to hold the result of the two added numbers). To find out if a variable is required, read the instruction overview or use the dynamic help provided in most Rendition Script applications.
·
Declaring
variables in Rendition Script
There are two types of variables in Rendition Script.
§
Memory
This is the least complex type of variable and is declared by the “memory” instruction. This variable will hold one decimal value (such as 0, 5, -1.543435).
§
List
This type of variable is slightly more complex. It is declared by the “list” instruction. This variable will hold an infinite amount of decimal values (at least as much as your available RAM can hold). There are special instructions designed just for this type of variable:
1. “append” : This will add the specified values to a list
2. “remove” : This will remove whatever value is contained at the specified index
3. “clear” : This will remove all values from a list
4. “count” : This will set the value of the specified variable to the number of items a list contains
It is important to understand how the values in a list are organized. Every item that is added to a list is given an index. The tricky part is that this index starts at zero. So the first item you add to a list has an index of zero, the second value has an index of one, etc. It is important to know the index of a value in a list when using the “remove” instruction and when using a list as a parameter that requires just one decimal value.
Here are some scripts that show how to use variables as parameters in instructions:
list x, 5, 10, 0
add x[0], x[1], x[2]
*This will add 5 and 10 and store the result (15) in x[2] (which currently equals zero).
memory x, 5
memory y, 10
memory z, 0
add x, y, z
*This will make z equal 15.
memory x, 5
memory y, 10
add x, y, x
*This will make x equal 15. Notice that x is used twice, which is fine.
memory x, 0
add 5, 10, x
*This will make x equal 15.
list x, 5
memory y, 0
add x[0], 10, y
*This will add 5 and 10 and store the result (15) in y.
·
Static
Variables
When you declare a variable, the value is set back to its default value each time the script is run. This is fine for most applications, but you may find the need for static variables, which retain their value until the script is recompiled, in an application such as Image Script. To make a variable static, simply put the “static” keyword before a variable declaration. Here is a script that keeps track of how many pixels have been processed in Image Script:
static memory
pixel_number, 0
add pixel_number, 1,
pixel_number
add input,
pixel_number, output
Without the “static” keyword, the value of pixel_number would always be 0 or 1. Also, a static variable must be initialized with a constant, or if it is a list, with constants. Here is an example:
This is incorrect:
memory x, 10
static memory y, x
This is correct:
memory x, 10
static memory y, 10
·
Using
input from the application
There are multiple ways to use input that the application has provided you with. The most basic way is to use the “input” variable. This is a reserved variable (meaning you can not create a variable with the name of “input”). It holds only one decimal number. This is usually the most important piece of information that the application provides you with. The second way to use input is with the “inputEx” list variable. This is a way to expose large amounts of data. The third way is with the “external” instruction. It takes one parameter which is the name that must correspond to the applications implementation. This is a user friendly method since you know what data you are working with (unlike “inputEx”). Here is an example of using input:
memory x, 0
external position, 0
add input, position,
x
add input,
inputEx[1], x
*Note that the application must implement the “position” variable. Also, remember that you can not assign a value to any of the input variables. For example, this would NOT be valid: “move 5, input”
·
Giving output
to the application
There are two ways to assign output. By using the “output” variable, you may assign one decimal number. By using the “outputEx” list variable, you may assign an infinite amount of decimal numbers. Here is an example of using output:
memory x, 100
move input, output
append outputEx, 100
*Remember that you can not read from the output variables. For example, this would NOT be valid: “move output, x”
·
Branching
instructions
Branching instructions are instructions that are executed based on conditions. For example, an “if” block of code is not executed if the condition is not true. A “for” block of code only executes if the code block has been run under (in some cases, above) a certain number of times. Here is the syntax for a branching instruction:
(if, for, etc.) param1, param2, …
{
//Code goes here
}
*Notice the brackets. Code inside these brackets is executed based on the instruction.
·
External
procedures (Advanced Topic)
External procedures are procedures provided to you by the application. The most common use is to interact with the user interface of the application or to call procedures at different time intervals (used with timers which are covered below). To declare an external procedure, use the “external_procedure” instruction. It takes an infinite amount of parameters that tell what parameters are required by the procedure (the first parameter is the name of the procedure and the rest of the parameters are either “memory” or “list” depending on the type of variable the external procedure calls for). To call the function, treat it as any other Rendition Script instruction. To explain this, there will be a reference to C# code. If you do not know the C# language, don’t worry, just know that you are using this instruction to interact with the application. Here is an example:
Here is a procedure written by the programmer in C#. This procedure must have a return type of void and have parameters of type double or ArrayList:
void UpdateScore(double
score, double[] other_scores)
{
playerscore.Text = score;
foreach(double x in other_scores)
computerscores.Items.Add(x);
}
*C# Code
*It is not important to know exactly what this code is doing, just how the code is interacting with the parameters (“score” and “other_scores”). When other languages use the variable type of “double”, it is equivalent to Rendition Script’s “memory” type. Rendition Script’s “list” type is equivalent to an array of “doubles” in other languages.
Now to call the above procedure in a Rendition Script, use the following code:
memory score, 25
list
other_scores, 5, 10, 15
external_procedure UpdateScore, memory, list
UpdateScore score, other_scores
*It is critical to note that only C# applications support “list” as a parameter. It should be made clear to you by the application of whether “list” may be used.
·
Using
timers and external procedures
Use timers to execute an arbitrary number of external procedures at a specified interval of time. You can NOT have Rendition Script instructions inside timer blocks, only external procedures provided by the application (but you can call external procedures outside of timer blocks). This is because the timer blocks run on separate threads than the rest of the script so they will not be synchronized with the rest of the script. Here is an example:
external_procedure
update
timer 1000, 0
{
update
}
*This script will call the update procedure every second
·
Controlling
your script
There are four instructions dedicated to controlling your script; “exit”, “info”, “error” and “instruction”. Use “exit” to stop further execution of the script but all output values will be retained. Use “info” to bring up a message box displaying information. The “error” instruction will do the same as “info” except the message box will have an error icon. Finally, use “instruction” to create your own instruction. Read below to learn more about creating your own instructions.
·
Creating
your own instructions
Creating your own instruction can
be compared to creating procedures (also called functions, routines, etc.) in
other languages. Give your instruction a name and parameters of either “memory”
or “list”. The parameters for “instruction” are a bit different than other
parameters. For each parameter besides the name, you need a value type and a
name to refer to the variable in the instruction. Notice in the example below
that the names “source” and “destination” are used for the names of the
parameters of the instruction. Use brackets to encase the code you want to
execute for the instruction. To use your instruction, use it as any other
instruction, just make sure the name is not already
taken or there will be an error. Here is an example of creating and using an
instruction. Note that the square brackets provide information for the
instruction used by Rendition Script’s dynamic help. The first line is the description, the following lines are descriptions of the
parameters:
[Get the
highest value from a list and store it in a variable]
[The list
to search for the highest value]
[The
variable to store the highest value]
instruction
GetHighestValue, list source, memory destination
{
memory c, 0
memory i, 0
//Make ”c” equal the number of
items in “source”
count source, c
//This variable will hold the highest value in the “source”
list
memory highest, 0
//Go through each item in the list and see if it is higher
than the current high value
for
i, <, c, 1
{
if source[i], >, highest
{
move source[i], highest
}
}
//Now return the highest value in
the list
move
highest, destination
}
//Now we
are using the instruction
memory h, 0
list x, 10, 15, 5
GetHighestValue
x, h