This is the portable version of the TeaScript (Standard) Host Application for Windows (64 bit). (Minimum: Windows 10 19H2)
The purpose is to run and execute script files written in the TeaScript language.

Please, read also the LICENSE.TXT and COPYRIGHT.TXT for usage conditions and permissions.

You don't need to install the software before usage. 
But for convenience reasons an installation instruction is provided below.


Table of Contents
==================================
- Usage without installation
- Manual installation
- Windows and Unicode
- TeaScript programming
- Contact / Support
- Core Library
- Known Issues



=== Usage without installation ===
----------------------------------

First you must unpack all files (the complete package) to any destination. Then

a) Double click the TeaScript.exe for launch the interactive shell.
   Ctrl+C will quit the application, or when type :q and pressing enter.
   
   :help <enter> will show a list of internal commands, e.g., use :ls vars for list all 
   variables and functions available in the toplevel scope.
   
   Entered text without a starting colon will be interpreted as TeaScript syntax and will be parsed + evaluated.
   
b) Open a command line, change into the directory where TeaScript.exe is located and invoke it with a filename which shall 
   be executed, e.g.:
   TeaScript.exe examples\corelibrary_test01.tea
   
   HINT: You can also use the "open_command_line.cmd" file to open a command line window at the correct place.
   Just double click it.
   


=== Manual installation ===
---------------------------

When doing a manual installation you are able to run and execute TeaScript files (*.tea) via double click
as well as to pass arbitrary parameters to TeaScript files.

1. Copy the complete unpacked TeaScript folder to "C:\Program Files\"
2. Browse to an .tea file (e.g. in the provided example folder), right click on it and choose "open with". 
   Then browse to the TeaScript.exe under "C:\Program Files\TeaScript\" and select "TeaScript.exe".
3. Add the following key to the Windows registry:
   HKEY_CURRENT_USER\SOFTWARE\Classes\Applications\TeaScript.exe\shell\open\command
   (Default): "C:\Program Files\TeaScript\TeaScript.exe" "%1" %*
  
   NOTE: the missing double quotes around %* are intended. It must be exactly like that. If you change it, it will not work!
   You can use the provided "add_tea_files_to_registry.reg" to add the registry key.
   
After that you can invoke TeaScript files like the following example (passing 2 parameters to the script):

examples\gcd.tea 42 18

If you see the output 6 everything is working correctly.


=== Windows and Unicode ===
------------------------------

Some notes to Windows and Unicode support.

TeaScript itself is fully supporting the complete range of Unicode and uses only UTF-8 encoded strings.

The Windows Terminal Applications still have some trouble when it comes to Unicode support.
If you use the classical Command Prompt (cmd.exe) you must ensure to use a proper font, e.g. "SimSun-ExtB".

Nevertheless, even then not all Unicode glyphs can be displayed. For that you must use the 
"Windows Terminal" application (from MS Store) with either the PowerShell or the classical Command Prompt.

The PowerShell might be needed to tweaked prior using Unicode with the following command:
$OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding

There is one left known issue regarding Unicode support in TeaScript under Windows. See section "Known Issues".

Personal advice: The best experience I got with Windows Terminal combined with Command Prompt inside.

You can test unicode support with TeaScript on your system with the example script files:
utf8_test.tea
argout_test.tea


=== TeaScript programming === 
-----------------------------

Information about how to program TeaScript can be found on the webpage:
https://tea-age.solutions

Also you may have a look at the provided example script files.


=== Contact / Support ===
-------------------------

This software is a pre-release.
The behavior, API/ABI, command line arguments, contents of the package,
usage conditions + permissions and any other aspects of the software and the package may change 
in a non backwards compatible or a non upgradeable way without prior notice with any new (pre-)release.

If you encounter bugs or problems, have feature wishes or any other question you may contact:

contact |at| tea-age.solutions


New versions, the source code of the TeaScript C++ Library, the TeaScript Host Application as well as 
eventually used other (A)GPL software are made available here:
https://tea-age.solutions/downloads/


=== Core Library ===
--------------------

Some (incomplete and probably outdated) documentation about the provided standard Core Library.
(On https://tea-age.solutions you will find published source code of the Core Library part written in TeaScript)

HINT: in interactive shell use command ':ls vars' for get a complete list of all present toplevel 
      variables and functions.

Variable Name           : Type              --> docu
-------------------------------------------------------------------------------------------
_version_major          :  i64              --> major version of TeaScript
_version_minor          :  i64              --> minor version of TeaScript
_version_patch          :  i64              --> patch version of TeaScript
_version_combined_number:  i64              --> combined version number for easily compare versions.
_version_build_date_time:  String           --> build date and time as string
_api_version            :  i64              --> version of Core Library API.
_init_core_stamp        :  f64              --> time stamp in fractional seconds from an unspecified time point during program start.
_core_config            :  i64              --> combined enum teascript::config::eConfig value used for boostrap the CoreLibrary.
_exit_success           :  i64              --> exit code for indicating success (used especially for exit/_exit)
_exit_failure           :  i64              --> exit code for indicating failure (used especially for exit/_exit)
void                    : NaV (Not a Value) --> Convenience for can write 'return void' if function shall return nothing.
PI                      :  f64              --> The constant number PI


Func Name               : Signature         --> docu
-------------------------------------------------------------------------------------------
_out                    : void ( String )   --> prints param1 (String) to stdout
_err                    : void ( String )   --> prints param1 (String) to stderr
print                   : void ( Any )      --> prints param to stdout, will do to-string conversion of the parameter.
println                 : void ( Any )      --> prints param + line feed to stdout, will do to-string conversion of the parameter.
readline                : String ( void )   --> read line from stdin (and blocks until line finished), 
                                                returns the read line without line feed.
_exit                   : void ( i64 )      --> exits the script (with stack unwinding/scope cleanup) with param1 exit code. 
                                                (this function never returns!)
exit                    : void ( Any )      --> same as _exit but will do to-number conversion on the parameter.
_strtonum               : i64|Bool ( String ) --> converts a String to i64. Returns Bool(false) on error. 
                                                This works only with real String parameters. alternative for '+str'.
_strtonumex             : i64|f64|Bool (String) --> converts a String to i64 or f64, Bool(false) on error. 
                                                This works only with real String objects.
_numtostr               : String ( i64 )    --> converts a i64 to String. this works only with real i64 parameters. 
                                                Alternative for 'num % ""'
_f64toi64               : i64 (f64)         --> converts a f64 to i64. same effect as trunc() but yields a i64.
to_string               : String (val: Any) --> converts val to string (note: if val is an integer _numtostr is an alternative)
to_number               : i64|f64|Bool (Any)--> converts val to a Number. returns Bool(false) on error. 
                                                (note: if val is a String _strtonum / _strtonumex is an alternative)
_eval                   : Any ( String )    --> parses and evaluates the string as TeaScript code and returns its result.
eval_file               : Any ( String )    --> parses and evaluates the content of the file and returns its result. 
                                                All defined functions and variables in the top level scope will stay available.
fail                    : void ( void )     --> exits the script (with stack unwinding/scope cleanup) with 
                                                error_code _exit_failure (this function never returns!)
fail_with_error         : void ( i64 )      --> exits the script (with stack unwinding/scope cleanup) with the i64 error_code. 
                                                (this function never returns!)
fail_with_message       : void ( String, i64 )  --> prints String to stderr, exits the script (with stack unwinding/scope cleanup) 
                                                with the i64 error_code. (this function never returns!)
clock                   : f64 ( void )      --> gets the local wall clock time of the current day in (fractional) seconds as f64.
clock_utc               : f64 ( void )      --> gets the UTC time of the current day in (fractional) seconds as f64. 
                                                (note: This UTC time is with leap seconds!)
_timestamp              : f64 ( void )      --> gets the elapsed time in (fractional) seconds as f64 from an unspecified 
                                                time point during program start. Time is monotonic increasing.
sleep                   : void ( i64 )      --> sleeps (at least) for given amount of seconds.
random                  : i64 ( i64, i64 )  --> creates a random number in between [start,end]. start, end must be >= 0 and <= UINT_MAX.

min                     : Any ( Any, Any )  --> returns the minimum of a and b
max                     : Any ( Any, Any )  --> returns the maximum of a and b
clamp                   : Any ( val: Any, low: Any, high: Any ) --> returns low if val is less than low, high if val is greater
                                                than high, otherwise val. garbage in, garbage out.
swap                    : Any ( Any, Any )  --> swaps the values of a and b (a and b are passed via shared assign)
abs                     : Number ( Number ) --> returns the absolute value of n (as same type as n). n must be a Number.
trunc                   : f64 ( Number )    --> rounds the given Number towards zero as f64. 
                                                e.g. 1.9 will yield 1.0, -2.9 will yield -2.0.
floor                   : f64 ( Number )    --> rounds down the given Number to next smaller integer as f64. 
                                                e.g. 1.9 will yield 1.0, -2.1 will yield -3.0
ceil                    : f64 ( Number )    --> rounds up the given Number to next greater integer as f64. 
                                                e.g. 1.1 will yield 2.0, -1.9 will yield -1.0
round                   : f64 ( Number )    --> rounds up or down the given Number to nearest integer as f64.
                                                e.g. 1.1 will yield 1.0, 1.6 as well as 1.5 will yield 2.0
pow                     : f64 ( Any, i64 )  --> computes power of input with integer exponent. if exp is a float it will get truncated. 
                                                returns a f64. (will do to-number conversion on input)
sqrt                    : f64 ( Any )       --> computes the square root of given input (will do to-number conversion on input).
timevals                : Bool ( t: f64, HH: i64, MM: i64, S: i64, ms: i64 ) --> computes the hour, minute, second 
                                                and (optionally) millisecond part of given time in seconds (e.g. from clock())
                                                note: hours can be greater than 23/24, it will not be cut at day boundary!
timetostr               : Bool|String ( t, with_ms: Bool ) --> builds a 24 hour wall clock string with the 
                                                format HH:MM:SS.mmm (milliseconds are optional)
                                                note: if t is greater than 24 hours it will not be cut.
rolldice                : i64 ( eyes: i64 ) --> randomly rolls the dice and returns the result.                                                   

=== Tuple helper functions ===
_tuple_create           : Tuple ( ... )     --> creates a tuple from the passed parameters. 
                                                parameter count is variable and type Any.
_tuple_size             : i64 ( Tuple )     --> returns the element count of the Tuple
_tuple_same_types       : Bool ( Tuple, Tuple ) --> checks whether the 2 tuples have the same types in exactly the same order 
                                                (and with same names).
_tuple_val              : Any ( Tuple, i64 ) --> returns the value at given index.
_tuple_named_val        : Any ( Tuple, String ) --> returns the value with given name (or throws).
_tuple_set              : void ( Tuple, i64, Any ) --> sets the value at given index or throws if index not exist.
_tuple_named_set        : void ( Tuple, String, Any ) --> set the value with given name (or throws).
_tuple_append           : void ( Tuple, Any ) --> appends new value to the end as new element.
_tuple_named_append     : Bool ( Tuple, String, Any ) --> appends new value with given name to the end as new element 
                                                if the name not exist yet.
_tuple_insert           : void ( Tuple, i64, Any ) --> inserts new value at given index.
_tuple_named_insert     : void ( Tuple, i64, String, Any ) --> inserts a value with given name at given index.
_tuple_remove           : Bool ( Tuple, i64 ) --> removes element at given index, returns whether an element has been removed.
_tuple_named_remove     : Bool ( Tuple, String ) --> removes element with given name, returns whether an element has been removed.
_tuple_index_of         : i64 ( Tuple, String ) --> returns the index of the element with given name or -1
_tuple_name_of          : String ( Tuple, i64 ) --> returns the name of the element with given idx (or throws)
_tuple_swap             : void ( Tuple, i64, i64 ) --> swaps elements of given indices
tuple_print             : void ( Tuple, String, i64 ) --> prints (recursively) all (named) elements, for debugging 
                                                (String param is the "root" name, last param is for max nesting level)

=== "minimalistic string support" ===
_strlen                 : i64 ( String )    --> returns the length of the string in bytes (excluding the ending 0).
_strglyphs              : i64 ( String )    --> returns the utf-8 (Unicode) glyph count of the string (excluding the ending 0).
_strat                  : String ( String, i64 ) --> returns a substring of one character at given position. 
                                                empty string if out of range.
_substr                 : String ( String, from: i64, count: i64 ) --> returns a substring [from, from+count). 
                                                count -1 means until end of string. returns empty string on invalid arguments.
_strfind                : i64 ( String, substring: String, offset: i64 ) --> searches for substring from offset and 
                                                returns found pos of first occurrence. -1 if not found.
_strfindreverse         : i64 ( String, substring: String, offset: i64 ) --> searches for substring from behind from offset and 
                                                returns found pos of first occurrence. -1 if not found.
_strreplacepos          : Bool ( str: String, start: i64, count: i64, new: String ) --> replaces the section [start, start+count) 
                                                in str with new. returns false on error, e.g. start is out of range.
strreplacefirst         : Bool ( str: String, what: String, new: String, offset: i64 := 0 ) --> replaces first occurrence of what
                                                with new starting from offset. returns true if a replacement happen.
strreplacelast          : Bool ( str: String, what: String, new: String, offset: i64 := 0 ) --> replaces last occurrence of what 
                                                with new starting from offset. returns true if a replacement happen.
strtrim                 : Bool ( str: String, set: String, leading: Bool, trailing: Bool ) --> trims the string if it starts or ends 
                                                with characters in given set. note: set must be ASCII only!

=== "minimalistic (text) file io support" ===
NOTE: text files must be UTF-8 encoded. Pathes can be relative to "cwd" or absolute.

cwd                     : String ( void )   --> returns the current working directory as String
change_cwd              : Bool ( String )   --> changes the current working dir
tempdir                 : String ( void )   --> returns configured temp directory as String
path_exists             : Bool ( String )   --> returns whether path in String exists as directory or file.
file_exists             : Bool ( String )   --> returns whether the given file exists.
file_size               : i64 ( String )    --> returns file size in bytes. -1 on error / file not exists / is not a file.
last_modified           : String ( String ) --> returns the last modified time as String for the given path or empty string 
                                                if not exists/error.
create_dir              : Bool ( String, Bool )  --> creates directories for path in String. Bool == true means recursively.
path_delete             : Bool ( String )   --> deletes(!) file or (empty) directory.
file_copy               : Bool ( file: String, dest_dir: String, overwrite: Bool ) --> copies file to dest_dir if not exist 
                                                or overwrite is true.
file_copy_newer         : Bool ( file: String, dest_dir: String ) --> copies file to dest_dir if not exist 
                                                or file is newer as the file in dest_dir.
readtextfile            : String|Bool ( String ) --> reads the content of an UTF-8 text file and returns it in a String. 
                                                An optional BOM is removed.
writetextfile           : Bool ( file: String, str: String, overwrite: Bool, bom: Bool )  --> writes the content of String to 
                                                text file. An optional UTF-8 BOM can be written (last Bool param). 
                                                overwrite indicates if a prior existing file shall be overwritten (old content destroyed!)

readdirfirst            : Tuple ( String )  --> returns the first direntry of given path (see direntry for details)
readdirnext             : Tuple ( Tuple )   --> returns the next direntry of given direntry (see direntry for details)

=== the direntry tuple ===
On Error or if directory is empty or if there are no more entries to iterate over the tuple has the following elements:
valid                   : Bool              --> here false always.
error                   : i64               --> if greater 0 it is the reported error code from std::filesystem / the OS.
path                    : String            --> the path which was investigated / tried to investigate.

In all other states the tuple has the following elements:
valid                   : Bool              --> here true always.
name                    : String            --> the name of the entry.
size                    : i64               --> the file size (for directories always 0)
last_modified           : String            --> last modified date/time as String with format "%F %T" (perfectly sortable)
is_file                 : Bool              --> true if entry is file, false otherwise.
is_dir                  : Bool              --> true if entry is directory, false otherwise.
path                    : String            --> the absolute and canonical path of the entry.
_handle                 : Passthrough       --> instance of std::filesystem::directory_iterator as Passthrough value.


=== TOML Support ===
readtomlstring          : Tuple ( String )  --> creates a named tuple from the given TOML formatted string (or false on error).
readtomlfile            : Tuple ( String )  --> creates a named tuple from the given TOML formatted file (or false on error).


=== Known Issues ===
--------------------

Please see Known_Issues.txt


