slidescript/docs/README.txt

===============
= SlideScript =
===============

A simple, user friendly scripting language for the average person. SS is meant to
be simple, and work as its documented as. SS is a bin tool to say the
least and is a helpful *nix userland tool in the CLI. Not only is SS a box full
of useful tools, it can also be used as a fully functional shell in a *nix like
environment!

===============
=  Compiling  =
===============

First, clone the repository:
$ git clone https://notabug.org/Pentium44/SlideScript

Next, time to compile slidescript. Out the box, slidescript will compile on GNU/Linux
distributions. ***NOTE*** If compiling on OSX/BSD/Android (and GNU/linux using clang), 
please uncomment "#define BSD" in src/inc/config.h

$ make

And install to the system

$ sudo make install

Testing SlideScript is very easy, you will find a nice test script in docs/examples
of the source tree. Execute functions.ss (./functions.ss from command line) and make sure
SS processes the script!

===============
=Documentation=
===============
Here is a list of functions and features that SlideScript comes with 
at this moment!

Commenting! Examples: 
    * # Comment is real in this one

Comp, loop, if, and ifn functions:
    * comp: "1" "1" -> compares integer 1 and 1 -> returns true
    * comp: "true" "false" -> compares string true and false -> returns false
    * loop: 3; print "Hello world!" -> Will loop print "Hello world!" 3 times.
    * if: true; print "True!" -> Prints "True!"
    * ifn: false; print "False!" -> Prints "False!"

Read, write, and cat(enate) functions. Examples:
    * write "file.txt" "This will be written to file.txt"
    * read "file.txt"
    * cat "file.txt" "Data to write to end of file.txt"

Basic math expressions
    * calc "45 / 5" or calc "255.3 * 442.77"
    * Of course addition and subtraction as well

Time example:
    * time

Isdir and isfile function, example:
    * isdir "examples/" -> returns 0 for not, 1 for is
    * isfile "examples/functions.ss" -> returns 1, its there

File manipulation functions
    * move "file1" "file2" -> Renames/moves file1 to file2 (mv alias)
    * chdir "/home/user" -> Changes directory to /home/user (cd alias)
    * backdir -> Moves you back one directory (..)
    * showpath -> Returns current working directory (pwd alias)
    * showdir -> Lists current directory (ls alias)
    * showdir "/" -> lists '/'
    * mkfile "file.txt" -> creates empty 'file.txt' (touch alias)
    * mkdir "testing/" -> creates directory 'testing'
    * mkfile "testing/file.txt" -> creates directory 'testing', and creates 'file.txt'

Slidescript compression functions, example:
    * compress "filename" -> compresses "filename" into "filename.lz"
    * decompress "filename.lz" -> decompresses 'filename.lz'

Print example:
    * print "Hi everyone!"

Sleep (Zzz) example (sleeps for 2 seconds):
    * sleep 2

Search functions (similar to grep, not as powerful), example:
    * search "README.txt" "SlideScript" -> returns each line that 'SlideScript' is found on

Variable setting and passing
    * filename=file.txt -> filename
    * filedata=File '%filename%' is being moved to moo -> %filename% is populated as file.txt
    * write "%filename%" "%filedata%" -> writes filedata contents to file.txt as expected.
    * unset "filename" -> Removes variable data from session memory to be redefinied / reused.

Decoding and encoding strings
    * encode "Regular string" -> Converts to encrypted string 'Uhjvqds#xuulqj'
    * decode "Uhjvqds#xuulqj" -> Converts back to 'Regular string'

MD5 file checking
    * md5 "file.txt" -> outputs filename and md5 hash

Layered piping
    * md5 "file.txt" | encrypt "%PIPE%"  | write "file.txt.md5.enc" "%PIPE%" -> writes output of md5 to file.txt.md5

Networking functions
    * netlisten "<port>" "<search>" "<respond>" -> listens on <port> and replies <respond> on <search> found from outside
    * nettoss "<address>" "<port>" "<data>" -> binds to outside server at <address>:<port> and pushes <data> thus, disconnecting
    * nethttp "<port>" "<forkval>" -> throws up a web server on <port> in the current working directory, 
                                      forkval (0 or 1, 0 don't fork into background / 1 do).

Backquoted function parsing within variables, also works within most major functions
    * curtime=`time` -> Will set curtime value to return of time at the time of parse.
    * print "%curtime%" -> Prints the variable value of curtime, same operation as function time, but good for timing scripts


This will change rapidly as of currently, slidescript is in beavy development! To get the feel of the scripting,
the best bet is to take a look at some of the slidescript examples in 'examples/'

functions.ss -> displays most basic functions
net-http.ss -> displays built in http web server
net-listen.ss -> displays slidescript's raw listen socket
net-toss.ss -> displays the 'client side' networking function.

===============
=  Todo list  =
===============

This section will obviously expand and adapt to the direction of the language. This is going to change rapidly.

- More networking function flexibility
- Micro text editor
- IRC server, bot, and client built in <--- in progress, will be possible with network functions
- Probably more stuff!

===============
=    Done     =
===============

List of finished features, in a rough summary.

- Added help, and version functions
- Simple syntax checking and error reporting, its a lazy language, syntax can sway.
- Most syntax errors will produce warnings instead of terminating process
- Up to 32 layer function piping
- Support for linux system calls
- Network listen socket, toss function
- Builtin HTTP server for disposeable use, can be ran in the foreground or forked into the background 
- Read and write from file
- Lots of simple but useful functions
- Shebang handling
- Variable support
- If, ifn, loop, and comp statements
- PATH variable support
- Calls system executables if not known as a SS function! (its a shell too!)
- Web server additions (pulled from chttpd)

===============
=  Changelog  =
===============

Changes between version bumps in SlideScript. Hoping to have a lightweight top-down scripting language
by V1.0.0 release! From there it will be molding and preserving the art.
V0.7.2
    * Bug fixes
    * Integrated PATH variables into slidescript for the sake of a useable shell
    * Allow for external programs to be ran from slidescript if no functions found (shell)

V0.7.1
    * Removed tar sources from SlideScript, does it need to create tar packages. (You can use system utils)
    * Reworked compress / decompress for single file operations. Great for resources FOR slidescript (assets)
    * Working on the lexer engine for line parsing and cleaner syntax.

V0.7.0
   * Ditched old LZ77 example code, and went with a more polished LZ78 ()
   * Converted dynamic memory management layer into LZ78 engine and tar code.
   * Compress & Decompress are both fully functioning.
   * Tidies, and polishing (pushing more for that full lenguage)

V0.6.0
   * Multiple dynamic memory bug fixes, SlideScript is 99% dynamic on memory use
   * Included if, and ifn functions for comp, isfile, isdir, etc return values.
   * Incorporated unset function to wipe variable data within the same session.
   * Additions to help command
   * Code cleanup
   * Fixed large bug when attempting to use multiple variables within one function.
   * Fixed compile warnings on some systems
   * Fixed system uncompatibility for Windows systems, should work cross-compiled!

V0.5.4
   * Added memory management framework for dynamic memory handling
   * tar.c cleanup
   * fflush additions for telnet usage of SS.

V0.5.3
   * Added version, and help command

V0.5.2
   * Bugfixes and tweaks
   * Added loop and comp(are) statements

V0.5.1
   * Compression and decompression bugfixes
   * System working functions (move, chdir, and showpath)
   * General clean, removed bins/ until language stabilizes

V0.5.0
   * Interactive mode gives users prompt on call to slidescript (Thanks OldCoder!)
   * Added showdir (alias ls)
   * Added compress / decompress functions (WIP, slow LZ77 algorithm)
   * Multiple bug fixes
   * Shell like interactive behavior

V0.4.5
   * Multiple bug fixes in not setting null byte to dynamic mem before strcat is used
   * Function isfile, as well as mkfile and mkdir are added
   * Added grep like function, search!
   * Cleanup code

V0.4.4
   * Softened the kill program errors, added warn functions behind the scenes
   * Added backquote function processing in variables
   * Fixed bug in read not displaying multi-line files
   * Fixed bug in write not finding first quote syntax
   * Added function isdir, and cat(enate) function. NOT cat as in linux env.
   * Code clean-up

V0.4.0
   * Added calc function for floating math equations
   * Cleaned up some more syntax handling, as well as bugs
   * Added structured and savable multi-layer piping up to 32 functions deep

V0.3.3
   * Added first networking functions: netlisten, nettoss, nethttp.
   * Embedded web server functionality
   * Cleaned up code
   * Improved syntax handling on functions

V0.3.0
   * Added simple 2 layer function piping for more useful tasks
   * Fixed a couple core dump bugs
   * Now reads files into memory, and then forces text files through SS, allows for in file variables
   * Added "md5" functionality
   * Multi-formal working syntax

V0.2.1
   * Added "decrypt" decode function
   * Added "encrypt" encode function
   * Added system "exec" function
   * Added basic syntax handling, for a more uniform language

V0.2.0
   * Added "delete" function
   * Added embedded variable handling to SS functions (variables can be used like everywhere!)
   * Added linux system calls via exec
   * Some cleaning up.

V0.1.1
   * Added variable handling with a buffer size of 2KB per variable, and cap of 2048 variables.
   * Now operates under the shebang!

===============
=Contributions=
===============

Robert (OldCoder) Kiraly -> shebang support, string manipulation, and memory management
(C) Copyright 2014-2022 Chris Dorman, some rights reserved (GPLv2)