Editing Engine:CCMD run

{{dev/uiccmd}}
Load and run script file. Run a named script file. Name must include extension.
<kua>run startup.cfg</kua>

== Arguments ==
* name - The name of the script file to load and run.

== Associations ==
* Is by default placed in the 'global' context.

== Details ==
The word "script" can be a very loose term in general, with lots of meanings. Here it can be even more confusing.

In Engine, the most basic type of script is comprised of a core set of facilities in the Data module, which are composed of vars, cmds, aliases, binds, and contexts, with a very basic syntax.

This very basic syntax structure however lends well to being flexible and extensible, and thus sometimes confusing. A complex base Engine script can interact with many different environments and contexts.

== Examples ==
=== Default values ===
For a script file named 'startup.cfg' which looks like:
<kua>
echo fred
lua print(1 + 3)
alias bob fred
var fred james
bob
</kua>
* Try to load a non-existent file.
<kua>
> run bob.cfg
Run failed: bob.cfg
</kua>
* Run the example script file.
<kua>
> run startup.cfg
fred
4
'fred' is 'james'
</kua>
: In this case: echos 'fred' to console, runs a Lua statement that adds '1 + 3' and prints the result, creates an alias 'bob', creates 'fred' variable that the alias 'bob' will show the value of, runs the 'bob' alias that effectively prints the value of 'fred' that is 'james'.

=== Multiline strings ===
Strings in the base scripting language are intrinsically multiline.
* For a script file named 'startup.cfg' which looks like:
<kua>
echo 'fred
bob'

alias bob "
    lua run '
        local a = 5
        print(a + 1 + 3)
    '
"
bob
</kua>
* Run the example script file.
<kua>
> run startup.cfg
fred
bob
9
</kua>
: Here the echo prints across two lines. An alias is created with an embedded block of lua that runs via the 'lua' context 'run' command, which uses single quotes to not conflict with the outer double quotes. Then bob is run and the whole thing prints 9.

== Script syntax ==
In the pseudo-syntax examples in these descriptions, a space ' ' is the same as any whitespace except newline, and all of the newline chars are represented by just '\n', to make easier to read. Text with no line '\n' delimiters is considered a single line. The examples are illustrative and not exact, the descriptions are correct.

Syntax:
<kua>command-name; command-name other-text; command-name other-text // comment text</kua>
Example:
<kua>print bob; bind U +attack // changing binding</kua>

=== Statements ===
:1. 'Statement' is a text block that begins with a command name, and is followed by any other text, and ends with line-end or semi-colon. A new statement can begin adjacent to the previous statements ending delimiter.
::<kua>statement[\n;]statement[\n;]...</kua>
:2. 'Command' names begin or end at white-space, semi-colon, or line-end, and end at comment start.
::<kua>command</kua>
::<kua>;command//comment</kua>
:3. 'Other text' starts after any white-space after command name, until semi-colon, line-end, or comment start.
::<kua>command other</kua>
::<kua>command other//comment</kua>
:4. Comment text starts with '//', placed anywhere on a line, and includes all text until line-end.
::<kua>command other//comment\n</kua>
:5. Comment text, empty statements or lines, or statements or lines with only white-space, will be skipped.
::<kua>;; ; //comment\n;</kua>
:6. Command names must be at least 2 and less than 63 characters. Statements with invalid command names will be skipped.
::<kua>co</kua>
::<kua>commandcommand...63</kua>
:7. 'Other text' may contain quoted text, where '<nowiki>'</nowiki>' or '"' or '`' are valid quote begin and end quote characters.
::<kua>command 'other' "text"</kua>
:8. If quoted text is found, any semi-colons, line-ends, or comment starts will be ignored, until next matching quote character.
:<kua>command 'other;' "//text"</kua>
<kua>command 'other
' "text"</kua>
:: In this case will be treated as one statement, where the statement does not end after the 'other' and the newline is included in the parameter, like 'other\n'.
:9. No other checking or processing is done on any 'other text' after the command name, and any actual meaning is context-dependent and determined when the actual statement is run.
::<kua>command other text</kua>
:10. If embedded in text a NULL, or '\0', or any character less than ' ', will be considered as a white-space character. This means that a '\0' delimits a command name, stays included in 'other text' as is, and is otherwise ignored. This also means that these characters cannot be used in command names.
::<kua>bob\0 other</kua>
::: command is 'bob' other text is '\0 other'
:11. Command names in this context can contain any character except white-space and ';' and cannot contain '//'. Command names can also have quote characters in the name and are not checked for closing quotes and treated as is as a part of the name. Valid command names: bob/"bob"/bob, "bob", "bob, bob".
::<kua>+zoom</kua>
:12. 'Executable statements' are composed of both the parsed 'command name' and 'other text' components, excluding comments

=== Parameters ===
'Statements' intrinsically contain only a 'command' and the optional 'other text'. A command can treat the 'other text' as a whole parameter, or as divided into multiple parameters.

Examples:
<kua>
> echo bob fred
bob fred
</kua>
: 'echo' takes the whole 'other text' as the value to print.
<kua>
> set bob fred james
> bob
'bob' is 'fred'
</kua>
: 'set' takes only the first two separated by space for the 'name' and 'value' parameters, and ignores james.
<kua>
> echo bob "fred" 1234
bob "fred" 1234
</kua>
: 'echo' still takes the whole 'other text' even with quotes.
<kua>
> set bob "fred james"
> bob
'bob' is 'fred james'
</kua>
: 'set' now treats james as part of the second parameter, and the quotes themselves are stripped.

==== Delimiters ====
:1. space - any whitespace
<kua>
> set bob fred
> bob
'bob' is 'fred'
</kua>
:2. single quotes - any text within a set of single quotes will be a single parameter, and the quotes will be stripped.
<kua>
> set bob 'fred james'
> bob
'bob' is 'fred james'
</kua>
:3. double quotes - any text within a set of double quotes will be a single parameter, and the quotes will be stripped.
<kua>
> set bob "fred james"
> bob
'bob' is 'fred james'
</kua>
:3. back tick - any text within a set of back ticks will be a single parameter, and the ticks will be stripped.
<kua>
> set bob `fred james`
> bob
'bob' is 'fred james'
</kua>
==== Special delimiters ====
:1. Back ticks surrounding text passed directly to a context will be stripped. Normally all text is passed verbatim, including quotes. Back ticks effectively treat the rest of the statement as a block for a multi-line statement. Quotes are not removed normally as they may be important to the context's command processing. Back ticks are special in that they will be removed from the start and end of the script statement. Without this special behavior, there would be no way to run a multi-line command block for an associated context, without switching to it first.
<kua>
> lua `print "bob"`
bob

> lua `
  print "bob"
  print "bob"
`
bob
bob

> lua '
  print "bob"
  print "bob"
'
Error in : [string "'print "bob"'"]:1: unexpected symbol near ''print "bob"'' (3)
</kua>

== More examples ==
Direct context with out back ticks:
<kua>
> lua print "bob"
bob
> lua 'print "bob"'
Error in : [string "'print "bob"'"]:1: unexpected symbol near ''print "bob"'' (3)
> lua run 'print "bob"' 
bob
</kua>
: When addressing the context directly, all of the 'other text' that is not the command simply gets passed to the context. At the top, print "bob" gets run in 'lua' context. The second fails as 'print "bob"' is not valid for the context or Lua. The third runs usingthe run command as a normal parameter to 'run'. While it will run multiline Lua scripts, text still won't be running as a set of context commands. 
<kua>
> lua `
  print "bob"
  print "bob"
`
bob
bob
</kua>
: Here effectively as a block inside 'lua'
<kua>
> context lua
> print "bob"
bob
> print "bob"
bob
> context global
</kua>
: And same thing but switching and executing and switching back.
<kua>
> notthere `
  print(1+2)
  print(1+2)
`
Unknown: notthere
</kua>
: The context did not exist and didn't run the block. In this case, guards against running commands in wrong context, if the context didn't exist at that time.
<kua>
> context notthere
> print(1+2)
Unknown: print(1+2)
> print(1+2)
Unknown: print(1+2)
> context global
</kua>
: This time commands are run in the unintended context.

== Notes ==
*