View source for Develop:LavishScript:Getting Started

This tutorial will help bring you up to speed with LavishScript development.

So, by now you've read [[Develop:LavishScript]] and would like to get your feet wet and hands dirty. Let's go then. :)

== Consoles ==
An [[Inner Space]] Console window is your first, and most handy, point of entry to LavishScript. There is a Console in the main Inner Space program (called the Uplink) available through its right-click menu, or in-game available via hotkey. LavishScript Commands can be manually entered into the Console.

Open the Console in the main Inner Space program now. Type something in it, and press enter to see what happens. If what you've entered is not recognized as a command, the result is something like this:
 Unknown command 'something'

This time, type in "<tt>echo Hi</tt>" and press enter. Now, you see the result
 Hi

Isn't that great? That is how a LavishScript console operates. By now, you should be feeling like an expert on the use of a LavishScript Console! ... If only you knew what to do with it. Let's move on.

== Commands ==
Now that you know where to enter commands, it would really be helpful for you to know how to properly form commands, and what commands are actually available.

LavishScript commands have a fairly simple syntax. The first word is the command name, and any parameters can come after the command name, each separated by one or more spaces. If a parameter is to contain a space, it should be quoted using double quotes <tt>"like this"</tt>. And if a parameter is to contain a double quote, it should be escaped using a \ as is generally standard.

To help you understand how a command and its parameters are processed, LavishScript provides a "test" command which specifies each portion of the command entered. 

Enter the following command into a Console:
 test "like \" this"

And here's the output for this command:
 Console Command Tester
 Arguments: 2
 Argument 0: 'Test'
 Argument 1: 'like " this'

So as you can see this is represented as a series of "Arguments", with 0 being the name of the command, and 1 being the first parameter. Each piece is surrounded by single quotes in the output, so you can identify its beginning and end very specifically. The outer quotes from the command-line itself are automatically stripped and not included as part of the actual parameter. The escaped double quote no longer appears escaped, because the \ is stripped. The double quote is now simply part of the parameter.

Some commands, such as [https://www.lavishsoft.com/wiki/index.php/Command:Echo Echo], automatically concatenate parameters together. Try the following commands, and note the differences in output:
 echo One Two Three
 echo One  Two  Three
 echo "One  Two  Three"

Here's the output for you:
 One Two Three
 One Two Three
 One  Two  Three

I suspect that you guessed the output of the first and last lines, but perhaps were not sure of the middle line. In the middle line, three parameters are passed to Echo, and each are separated by "one or more spaces" as detailed above.

The last thing you will need to know about LavishScript commands is that a semi-colon can be used as a command splitter:
 echo Line one;echo Line two

Output:
 Line one
 Line two

=== What Commands are available? ===
Depending on the context, such as whether you're using a Console in the Inner Space main program or in a game window, different commands may be available. You can always enter "commands" in the Console for a list of currently available commands.

; Here's the most common sources of LavishScript commands
* [https://www.lavishsoft.com/wiki/index.php/LavishScript:Commands LavishScript Commands]
* [http://www.lavishsoft.com/wiki/index.php/IS:Uplink#Uplink_Specific_Commands Inner Space Uplink Commands] (main program)
* [http://www.lavishsoft.com/wiki/index.php/IS:Session#Session_Specific_Commands Inner Space Session Commands] (launched game client)
* [http://www.lavishsoft.com/wiki/index.php/ISKernel:Commands Inner Space Kernel Commands] (common between both Uplink and Session)

== Data Sequences ==
LavishScript provides a mechanism called Data Sequences to pull data from an object, and emplace it into the command-line. A Data Sequence looks like '''<tt>${This}</tt>'''. It begins with '''<tt>${</tt>''' and ends with '''<tt>}</tt>'''. Between the start and end markers is a sequence of object accesses, in this case just accessing an object called '''<tt>This</tt>'''. The resulting value from the Data Sequence replaces it, in place, in the command-line.

; Data Sequences have a few supported operations:
* '''Member''': A '''<tt>.</tt>''' specifies a Member access, like '''<tt>${This.Name}</tt>''' would access <tt>Name</tt> from <tt>This</tt>
* '''Method''': A '''<tt>:</tt>''' specifies a Method call, like '''<tt>${This:Clear}</tt>''' would call <tt>Clear</tt> on <tt>This</tt>. In contrast to Member accesses, Method calls do not result in a new object. This means '''<tt>${This:Clear:ChainsWork}</tt>''' calls <tt>Clear</tt> and then <tt>ChainsWork</tt> on <tt>This</tt>! And the resulting value (to be placed in the command-line) is the value of <tt>This</tt>.
* '''Index''': Brackets '''<tt>[</tt>''' and '''<tt>]</tt>''' specify the start and end of an Index, which is essentially a comma-separated list of parameters. Top-Level Objects, Members and Methods support this syntax. '''<tt>${This[12]}</tt>''' would pass a parameter "12" to the Top-Level Object <tt>This</tt>, and '''<tt>${This.Item[12]}</tt>''' would pass a parameter "12" to the <tt>Item</tt> Member of <tt>This</tt>
* '''Type Cast''': Parentheses '''<tt>(</tt>''' and '''<tt>)</tt>''' specify the start and end of a Type Cast. This causes LavishScript to interpret an object as a different type of object, and should be used with care: types that are not compatible with each other will cause crashes. '''<tt>${This.ItemCount(bool)}</tt>''' is a silly example, but would treat the value of <tt>${This.ItemCount}</tt> as a <tt>[[lavish:ObjectType:bool|bool]]</tt> for output, producing TRUE or FALSE.

; Data Sequences have some useful properties.
* The sequence is terminated, and produces a result of '''<tt>NULL</tt>''' if a requested object does not exist, OR if a Method call indicates that it failed. '''<tt>${This.Name}</tt>''' will be NULL if <tt>This</tt> does not exist, or if the <tt>Name</tt> Member does not exist.
* Because of the above, LavishScript has a type of object called '''<tt>exists</tt>''', which only produces a value of TRUE. To determine if a Method call succeeded or failed, or if a Member exists, use a Type Cast to <tt>exists</tt>, like '''<tt>${This:Clear(exists)}</tt>''' -- the result will be NULL for failure, or TRUE for success. Likewise, '''<tt>${This.Name(exists)}</tt>''' will indicate NULL or TRUE to specify whether <tt>This.Name</tt> produced a value.

=== Try it out ===
; Enter the following command in the Inner Space console:
 echo ${InnerSpace.Build}

The output will be your current Inner Space build number. :)

; Now let's try a Method. Enter the following command in the Inner Space console:
 echo ${System:SetClipboardText[Hello World!]}

This time, because we're using a Method, the output here is the value of System. That will be your Windows OS version, in my case it output '''Windows 10 Pro'''. But look, we used a Method called SetClipboardText. Press CTRL+V or use the Paste function somewhere, and see that it pastes "Hello World!"

=== Method-as-Command ===
In the last example, we called a Method as part of an Echo command. It probably occurs to you that if what you're looking to do is set the text on the clipboard, you probably don't need to echo the version of Windows at the time. LavishScript will allow you to use a Method call Data Sequence as your command itself, by ''not using'' the '''<tt>${}</tt>''' -- which is the code for in-place text replacement.

; So let's try this another time. Enter the following command in the Inner Space console:
 System:SetClipboardText[Hello World Paste 2.0!]

This time, no output is produced, and you can press Ctrl+V (or click Paste where available) to paste "Hello World Paste 2.0!"

== Scripts ==
Work in progress.

{{Module Development}}