                          ################################################
                          # Lithium Client Scripting Language Revision 2 #
                          #   Documentation - 12/30/2001 by dataspy      #
                          #             Revised by Olympus               #
                          ################################################



#########
# History
#
# version 1 rev 2 = First public release
#


##################
# Upcoming Features
#
# - floating point variables
# - do {} while loops
# - case statements
# - more API/math/string functions
#


###########
#  Contents
# 1- General Information
# 2- Standard script syntax
# 3- Variables
# 4- Conditions
# 5- Loops
# 6- API Functions
# 7- Math Functions
# 8- String Functions


####
#  1
     General Information
    
    The usage and syntax of the Lithium scripting language was based
    around simplicity and usefulness.  For this reason, you will see
    a unique syntax possibly combining elements from an array of 
    several other languages.

    The scripting engine parses code line by line, and never stops
    even if an error occurs. (If you fuck up your script coding, it's 
    not Lithium's responsibility to deal with it.)

    Note: For you c/c++ coders out there, there is no need for a ';' 
          after commands, just a new line :)


####
#  2
    Standard script syntax
    
  # One command per line.

  # Code comments (ignored by the interpreter):
                                               !! comment goes here

  # Sub commands are placed inside parenthesis:
                               command (subcommand sparam1 sparam2) param2

  # To call a function:
                       call function_name param1 param2 .....

  # Functions cannot return values as of yet, but functions can place
    data in unique public variables upon completion


  # Alias - defines an alias

    Syntax:
           alias <string name>
             commands...
           end

  # Unalias - undefines a previously defined alias
   
    Syntax:
           unalias <string name>

  # Callalias - calls a prviously defined alias
    
    Syntax:
           callalias <string name>

####
#  3
    Variables
    
    Variables are stored in a global array, indicated by their name (str)
    and their type (ltInteger or ltString).  This way, variables of
    functions can easily accessed and used by other functions. For this 
    reason, variables must be freed when usage is complete, or they will
    remain in the global array wasting memory.

  # Declaration
    
    str $my_string
    int $my_integer

    Note: Variable names must be preceded by a dollar sign '$'
          Variables arent case sensitive
          Variables are automatically initalized to 0 for ints, and "" for strings

  # Freeing
   
    free $var_name

  # Assignment

    To set a variable to a value use:
                                     set $var_name value
                                           or
                                     set $var_name (mult $value 1)

    For example:
                str $name
                set $name "Lithium owns us all"

    The variable '$name' now has a value of "Lithium owns us all"

    The synatx is identical for integers, eg:
                                             int $magic_number
                                             set $magic_number 1337

    The variable '$magic_number' now has a value of 1337

    Note: Though set $mystring blah is valid, it is better practice to do set $mystring "blah"

  # Retrevial

    To retreive the value of a variable use:
                                            (get $var_name)

    For example, with our previously declared variable '$name':
                                                               messagebox (get $name)
   
    Would display a Message Box with the text "Lithium owns us all"

    Note: messagebox ($name) would display a msgbox with the text "$name"




####
#  4
    Conditions

    The following conditions are valid for use throughout, and when evaluated are true or false.

  # Equal
            ==

    Example: 
             a == b
             True if a is equal to b, otherwise false

  # Not equal
             !=
    Example: 
             a != b
             True if a is not equal to b, otherwise false


    The following conditions are valid for use only with integers, and when evaluated are true or false.

  # Lessthan or equal to
            <=

    Example: 
             a <= b
             True if a is less than or equal to b, otherwise false

  # Greater than or equal to
            >=

    Example: 
             a >= b
             True if a is greater than or equal to b, otherwise false

  # Less than
            <

    Example: 
             a < b
             True if a is less than b, otherwise false

  # Greater than
            >

    Example: 
             a > b
             True if a is greater than b, otherwise false


    Note: Lithium will convert a string to a int in a comparison 
          for you, so the following is valid:
                                             5 == "5"

          Comparison of strings is case sensitive



####
#  5
    Loops and if/else

    Note: Lithium scripting language supports nested if/else and loops

  # While

    The while loop continues to execute the commands inside the loop while the condition is true.

    Syntax:
           while condition
             commands....
           end

    Example:
            int $my_int
            while $my_int < 10
              messagebox (get $my_int)
              inc $my_int 1             
            end

    Would display ten message boxes with the text being the numbers 0 to 9

  # for

    The for loop continues to execute the commands inside the loop while the variable increments automatically

    Syntax:
           for variable from to
             commands....
           end

    Example:
            for $i 0 10
              messagebox (get $i)
            end

    Would display eleven message boxes with the text being the numbers 0 to 10

  # If / else

    The if / else syntax is used to execute conditional statments.

    Syntax:
           if condition
             commands.....
           else
             commands....
           end

           if condition
             commands.....
           end

    You can also nest if / else comamnds, example:
                                                  if condition
                                                    commands.....
                                                  else
                                                    if condition
                                                       commands.....
                                                    end
                                                  end


####
#  6
    API Functions


  # connect - Connects the client to a lithium server

    Syntax:
           connect <string ip_and_port>

    Example:
            connect "127.0.0.1:31415"

  # disconnect - Disconnects the client from the currently connected lithium server

    Syntax:
           disconnect

  # reconnect - Reconnects the client to the previously connected lithium server

    Syntax:
           reconnect

  # printline - prints a line to the lithium client console window

    Syntax:
           printline <string text>

    Example:
            printline "hello world"

  # exit - Exits the lithium client

    Syntax:
           exit

  # playsound - plays a sound asynchronously

    Syntax:
           playsound <string file>

    Example:
            playsound "connected.wav"

  # execute - opens a file with the default viewer

    Syntax:
           execute <string file> <optional string params>

    Example:
            execute "http://www.lithiumrat.org"

  # call - executes a specified function inside a lithium script

    Syntax:
           call <string file> <string function_name>

    Example:
            call "my_script.lfs" "CoolFunction"

  # sendmsg - sends a messsage to the lithium server

    Syntax:
           sendmsg <integer type_number> <optional string param1> <optional string param2> .....

    Example:
            sendmsg 13

  # messagebox - displays a messagebox with the specified text

    Syntax:
           messagebox <string text>

    Example:
            messagebox "Lithium owns us all"

  # confirmbox - displays a box with the specified text and a "yes" and a "no" button. 
 
    Syntax:
           confirmbox <string question>
           set $variable (confirmbox  <string question>)
           if (confirmbox <string question>) == 1

    Example:
            if (confirmbox "Does lithium own?") == 1
              messagebox "Correct!"
            end

  # warningbox - displays a warning messagebox with the specified text

    Syntax:
           warningbox <string text>

    Example:
            warningbox "Your president is an idiot"

  # errorbox - displays a error messagebox with the specified text

    Syntax:
           errorbox <string text>

    Example:
            errorbox "Access violation. RAPE!"

  # inputbox - displays a input box

    Syntax:
           inputbox <string text>

    Example:
           set $variable (inputbox "How old are you")
                          or
           messagebox (inputbox "How old are you")

  # show - shows a specified window in the lithium client

    Syntax:
           show <string window_name>

    Example:
            show "clienttree"

  # hide - hides a specified window in the lithium client

    Syntax:
           hide <string window_name>

    Example:
            hide "clienttree"
  
    Valid Window Names: "Main", "AddressBook", "ClientTree", "Scanner",
      "ServerPlugins", "Services", "ConnectedClients", "MessageBox",
      "RegistryExplorer", "TaskManager", "NetworkShares", "DriveList",
      "FileSearch", "FileExplorer"                 

  # cset - Sets the specified client option to the specified value

    Syntax:
           cset <string value_name> <value>

    Example:
            cset username "EliteOne"

  # pshow - shows a specified window in a client plugin

    Syntax:
           pshow <string plugin_name> <string window_name>
    
    Example:
            pshow "Screen Capture v1.00" "main"


####
#  7
    Math functions

  # Randint - generates a random number

    Syntax:
           randint <integer max>

    Example:
            set $random (randint 5)
            set $random (randint (get $my_int))

  # inc - increments a variable integer by the specified amount

    Syntax:
           inc <integer variable> <integer amount>

    Example:
            inc $my_int 5
            inc $my_int 1

  # dec - decreases a variable integer by the specified amount and returns the new value of decremented variable(s)

    Syntax:
           dec <integer variable> <integer amount>

    Example:
            dec $my_int 5
            dec $my_int 1
            set $small_random (dec $my_int (randint (get $my_int))) /* lol */

  # add - adds two variables and returns the result

    Syntax:
           add <integer variable_one> <integer variable_two>

    Example:
            set $my_int (add $my_int 5)
            !! Same as inc $my_int 5

 # sub - subtracts variable two from variable one

    Syntax:
           sub <integer variable_one> <integer variable_two>

    Example:
            sub $my_int 3
            set $my_new_var (sub $my_int 1)

 # mult - multiplies two values and returns the result

    Syntax:
           mult <integer $variable_one> <integer $variable_two>

    Example:
            mult 5 5 
            !! Returns 25

 # div - divides value_two into value_one and returns the result

    Syntax:
           div <integer $variable_one> <integer $variable_two>

    Example:
            div 25 5 
            !! Returns 5

 # sitos - returns a short integer as a 2 byte string
  
    Syntax:
           sitos <integer value>
 
 # stosi - returns a 2 byte string as a short integer

    Syntax:
           stosi <string value>

 # ctos - returns a long integer as a 4 byte string

    Syntax:
           ctos <integer value>

 # stoc - returns a 4 byte string as a long integer

    Syntax:
           stoc <string value>


####
#  8
    String functions

  # strcopy - copies <LEN> characters from <SRC> starting from <IDX> places, to <DEST>

    Syntax:
           strcopy <string $dest> <string $src> <int idx> <int len>

    Example:
            str $source
            str $destination
            
            set $source "Hello World From Lithium"

            strcopy $destination $source 6 10

            !! Now $destination is "World From"

  # strlen - returns the length of a string

    Syntax:
           strlen <string $variable>


  # strconcat - Concatenates all specified strings and returns the result

    Syntax:
           strconcat <string variable_one> <string variable_two> <string variable_three>

    Example:
            strconcat "Hello" " world"
            !! Would return "Hello world"


  # strpos - returns the first position of <SUBSTR> inside <STRING>

    Syntax:
           strpos <string $search_in> <string $look_for>


    Example:
            strpos "Search me, im clean!" "me"
            !! would return 8



