[Squirrel EES:Quickstart Guide]

[Tested only on Manjaro and Linux mint!]

Is a framework that uses its own syntax in order to call functions of a defined c# accessibility level with a specific type of structure. You can also compile and link C# scripts to squirrel with functions you created in order to call them. Squirrel contains its own memory and XML-database system. Each function call is done on an isolated thread.

!NOTE: Call the manual function in order to view all available manuals and runnable functions for squirrel. You may use the manual::*manual_name function to view a manual.

[General syntax]

Variables:

\* = Asterisk denotes a variable this refers to a defined variable that exists in the squirrel memory pool.

*'' = Denotes a value to use as a variable, This allows you to use values without adding them to the squirrel memory pool such as something that is temporary.

*f'' = Denotes a value variable which can be formatted. You may insert other variables into the current formatted value variable with the {(( ))} denotations.

(Example):

vardictionary::*store >> vardictionaryappend::*store, *'store_name', *'My computer store'

output::*f'Hello {((store[store_name]))}!

Arrays

Arrays can replace an existing variable and transport it's value into index 0 of the array or as an empty array. Arrays may initialize a new variable and set it as an array.

vararray::*name_or_existing, *if_existing_copy_value_into_new_array

Dictionary variables can be manipulated or gotten using the inbuilt functions or by using index notation with multiple-depth/dimensions '[][][]..':

output::*array[7][54][8][0]

Dictionaries

Dictionaries act equally to arrays, except that they are arrays with key:value items. It a dictionary replaces a current array, there is no option to copy the current variable's value into the dictionary that substitutes it.

vardictionary::*name_or_existing

Dictionary variables can be manipulated or gotten using the inbuilt functions or by using index notation with single-depth/dimension '[]':

output::*dictionary[key]

String escape sequences

Since certain symbols may be used for command execution, we have come up with some escape sequences that allow you to use those symbols within your strings of data similar to escape sequences in C such as ' for a single quote. Squirrel's escape sequences are abit different but the principal is the same. All escape sequences use the following format:

{&escapee}

where 'escapee' is a character denoting the type of escape.

Here they are:

• {&c} = ,
• {&v} = *
• {&q} = '
• {&r} = >>
• {&l} = <<
• {&d} = ::
• {&fl} = {((
• {&fr} = ))}

Multithread function calls:

Are made with the following syntax:

*return_var<<function::*var1, *var2...

The first variable is a return variable. Any variable that the function returns will be shifted left and stored there, if you would not like a return variable to be stored or the function you are calling does not return a variable you may ignore this section. 'function' denotes the name of the function to call. :: denotes that you are sending variables as agruments to the functions and subsequently all variables seperated by commas. any extra variables sent that do not interest the function call will be ignored such as a function call that requires 2 arguments but gets passed 5. The last 3 wil be ignored

(Example):

listvars

var::*var1

varset::*var1, *'Squirrels are SO misunderstood..'

Same thread function calls:

Squirrel allows you to run multiple functions in one single thread. Squirrels execution is always left to right. To shift execution right on the same thread consecutively use the >> symbol.

var::*name >> varset::*name, *'Richard Stallman' >> output::*f'Hi {((name))}!. Let us play the GNU SONG!' >> exit

All of the above functions will be executed one after the other. Without using >> functions are executed on seperate threads.

[Scripts]

Running Squirrel syntax scripts:

You may run external files as scripts which contain various squirrel function calls delimited by newlines. You may call a script by sending a path argument to the function 'scriptrun', it is reccomended to not use an extension for filenames:

scriptrun::*'/home/user/myscript', *false

You can also put other runscript calls inside of a script. *false (BOOL) is used to denote if all lines run on seperate threads or if every line is executed top down on a single thread.

WARNING! Currently all function calls in a script will be called on the thread of the initial runscript function call. Multithreading for scripts is not yet supported.

Compiling C# scripts (mono_legacy only):

You may compile a C# script and load it into squirrel by namespace and class. Be warned that Squirrel only supports loading one class at a time for each assembly load.

Syntax:

asmcompile::*path, *namespacedotclass, *reference, *reference...

Example:

asmcompile::*'/home/myhome/test.cs', *'test.Test', *'System.IO', *'System.Threading'

[Loading C# scripts (mono_legacy only)]

In order to use any compiled C# script we must load them into Squirrel. This will allow us to call any function within a class. Please note that loading a C# library only supports loading one class at a time from all assemblies, this means that in order to load multiple classes from one assembly is currently not possible.

Syntax:

asmload::*path, *namespacedotclass

Example:

asmload::*'/home/myhome/test.dll', *'test.Test'

Running C# script functions (mono_legacy only)

You may now run a compiled function within a loaded assembly. This will allow you to call a function or a chain of functions. The beuty is that the sourcecoude can be modified recompiled and run on the fly. The current assembly must be removed from memory before loading in the new instance.

Syntax:

asmcall::*path, *functionname, *arg, *arg...

[Processes]

Running external processes

Running and controlling external processes is important for various use cases. You cannot control a process that is already running. You may create a process, view its output, kill a process or kill all running processes. Processes can run fully controlled by Squirrel or can be started as a new seperate process outsode of Squirrel Input insertion is coming soon!

Starting an external process

Syntax:

process::*main_program_or_program_path, *arguments, *name, *isnotcontrolled

Example:

process::*'ping', *'127.0.0.1', *'mypingprocess', *false

This example will run a ping process with the argument of '127.0.0.1'. false denotes that you would like the process to be controlled by Squirrel.

Viewing process output

Viewing processoutput is important. By default processes have their own stdout instances so that they will not print their output onto the main stdout seperating output and evading clutter. In order to see a processes stdout you may call the 'processio' function.

Syntax:

processio::*name

Example

processio::*'mypingprocess'

[Databases:XMLDB]

Databases are based of the XML standard and are simple encrypted files on your hard drive for storing static data. Squirrel's XMLDB allows you to get, set and query data.

Creating a database:XMLDB

Syntax:

dbcreate::*dbpath, *password

Example:

dbcreate::*f'{((path))}/Databases/database.db', *'12345'

Opening a database:XMLDB

Databases can be opened by providing a path and a name which can be used to identify the database when working with it.

Syntax:

dbopen::*dbname, *dbpath, *password

Example:

dbopen::*'mydatabase', *f'{((path))}/Databases/database.db', *'12345'

Closing a database:XMLDB

Syntax:

dbclose::*dbname

Example:

dbclose::*'mydatabase'

Saving a database:XMLDB

Always remember to save changes before closing or reloading a database, if you do not all changes will be lost. It is reccomended to create a script that saves your database state every few minutes if the database is an active one.

Syntax:

dbsave::*dbname, *password

Example:

dbsave::*'mydatabase', *'12345'

Reloading a database::XMLDB

If you want to loose any changes made or want a fresh copy of a database in its previously last saved state you may reload a database.

Syntax:

dbreload::*dbname, *password

Example:

dbreload::*'mydatabase', *'12345'

Querying data in XMLDB

XMLDB is mostly reccomended as a static database for storing string data that you'd like to use later on. This can be HTML for a website which you can then process with formatted strings or image links. Data must be only in a string format. Saving images or videos may not work and will corrupt a database you may test it at your own perrill.

All data in XMLDB is represented by the following characteristics:

• tag : A group to which many data elements can belong to (Example: you as a person, a car or any class or classification of data)
• subtag : What does your data represent within the tag or classification of data (Example: your name or age)
• data : Contained data

Getting data:XMLDB

You may get data in XMLDB using either tags or/and subtags or/and data. If you do not have the value of one of them say you are fetching data relating to 'Tag:John Doe' but don't know what data is contained, you may pass the *null value as a parameter, all parameters are nullable. All queries return an array.

Syntax:

*return_var<<dbget::*dbname, *data|OR NULL, *tag|OR NULL, *subtag|OR NULL

Example:

*result<<dbget::*dbname, *null, *'first_name', *null

Getting all data:XMLDB

You may also get all available data from an XMLDB database, this will be returned as an array.

Syntax:

*return_var::*dbname

Setting data:XMLDB

You may insert but not update data in XMLDB, hence we reccomend using XMLDB mostly for static data such as containing a webpage.

Syntax:

dbset::*dbname, *data, *tag|OR NULL, *subtag|OR NULL

Example:

dbset::*dbname, *'<p>Welcome!</p>', *'www.mywebsite.com', *'HTML'

Deleting data:XMLDB

Data may be deleted in XMLDB using the query syntax allowing you to delete one or more elements partaining to a tag or subtag. Deleting all elements with a subtag deletes the subtag, deleting all elements with a tag deletes that tag.

Syntax:

dbdelete::*dbname, *data|OR NULL, *tag|OR NULL, *subtag|OR NULL

Example:

dbdelete::*dbname, *null, *'first_name', *'John Doe'

Updating data:XMLDB

Data just as it may be inserted it may also be updated:

dbupdate::*dbname, *tag, *subtag, *new_data

Listing all open databases:XMLDB

You may view a list of all open databases by using the following commands:

• listdbs
• ld

Editing data using an external editor

Data can be edited using an external editor of your choice. Each data entry will open a seperate tab or window depending on the editor:

xmldbedit::*dbname, *password, *string tag, *string editor_bin_name, *string subtag_or_null

[Databases:MYSQL]

It is imperative that you have already set up a database and a user for your MYSQL instance in order to use Squirrel with it. Squirrel has a limited number of functionalities it can perform with MYSQL at the moment. This will be expanded in future releases to include fullscale MYSQL integration.

Creating a new MYSQL connection string

You may create a mysql connection string on your own and store it in a variable, type it out as a value variable. Squirrel allows you to automatically create a new mysql connection string and store it within a Squirrel variable as a returnable variable.

Syntax:

*return_var<<mysqlcreatestring::*host|OR IP, *port|OR '3306', *database, *user, *password

Example:

result<<mysqlcreatestring::*'localhost', *'3306', *'mydatabase', *'user', *'12345'

Creating a new mysql table in the default format

You may create a new mysql table from squirrel in it's default format or so in the XMLDB format. In order to simplify the way squirrel databases store data squirrel will automatically generate specific columns:

• id : An identifier for every row
• tag : A group to which many data elements can belong to (Example: you as a person, a car or any class or classification of data)
• subtag : What does your data represent within the tag or classification of data (Example: your name or age)
• data : Contained data
• token : Contains a squirrel based token for creating user based applications. The token can be used to verify that the user belongs to a specific user