Merge remote-tracking branch 'origin/master'

Author: Moderocky

README.md

@@ -37,6 +37,53 @@ For clarity: SkriptLang's Skript implementation will be referred to as 'original
 
 Skript is designed to be beginner-friendly. Ideally, a user with no experience should be able to read Skript code and understand its function. All instructions are written in basic English, avoiding niche programming terms and symbols wherever possible.
 
+## Using ByteSkript
+
+ByteSkript provides **three** different executable Jar files for different purposes.
+
+Running these for the first time will create special folders in the run directory.
+
+| Name         | Purpose                                                                                                                                                                                                            |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `skript/`    | <p>This is where you can write your script files, with the extension <code>.bsk</code>.<br>All <code>.bsk</code> files in this directory and its subfolders will be compiled/loaded.</p>                           |
+| `resources/` | <p>This is where you can put non-script files that you need in your output jar.<br>This is only used by the jar builder.</p>                                                                                       |
+| `compiled/`  | <p>If you are compiling your scripts to <code>.class</code> or <code>.jar</code> files, the output will go here.<br>This folder is never emptied, so make sure to delete any old versions before re-compiling.</p> |
+
+### SkriptLoader
+
+This is the simplest resource, used for loading (and running) user-created script files.
+
+Raw script files can be written and placed in the `skript/` folder. All scripts will be loaded internally, but no classes or jar files will be written.
+
+The `on [script] load` event will be triggered for each script as an entry point.
+
+{% hint style="success" %}
+The ByteSkript compilers, language specification and compile-time API are available in this resource, so advanced scripts may use dynamic loading to load extra skript code written at runtime!
+{% endhint %}
+
+### SkriptClassCompiler
+
+This resource is used for generating compiled JVM `.class` files for each script in the `skript/` folder. The classes produced by this are not directly executable, but may be useful for sharing and special loading.
+
+The compiled scripts will **not** be loaded or run.
+
+### SkriptJarBuilder
+
+This resource builds an executable jar containing all of the user-created scripts, resources and the ByteSkript runtime (`skript` namespace and functions.)
+
+\
+This output jar can be run with `java -jar JarName.jar` and is distributable - it does not need anything as a dependency.
+
+When executing this jar, all scripts will be loaded and the `on [script] load` event will be triggered for each script as an entry point.
+
+{% hint style="danger" %}
+The ByteSkript standard compiler and compile-time API are **not** added to the output jar.
+{% endhint %}
+
+{% hint style="success" %}
+The dynamic function on-the-fly compiler **is** available in this jar, so dynamic function calls are available.
+{% endhint %}
+
 ## Language Libraries
 
 Due to its fixed nature, the Skript language has always relied on third-party add-ons to add new syntax and functionality for specific areas.

SUMMARY.md

@@ -22,6 +22,8 @@
   * [Generic Effects](structures/effects/generic-effects.md)
 * [Expressions](structures/expressions/README.md)
   * [Variables](structures/expressions/variables.md)
+  * [Simple Expressions](structures/expressions/simple-expressions.md)
+  * [I/O Expressions](structures/expressions/i-o-expressions.md)
 
 ## namespaces
 

structures/expressions/i-o-expressions.md

@@ -0,0 +1,74 @@
+---
+description: >-
+  A set of expressions related to input/output using files, streams, readers and
+  sockets.
+---
+
+# I/O Expressions
+
+Some of these expressions are quite advanced and may be dangerous for beginners.
+
+{% hint style="info" %}
+Accessing files can be quite slow as it relies on the machine's file system.
+
+To avoid the program slowing down it may be preferable to access files on a background process.
+{% endhint %}
+
+### File Expressions
+
+`[a] new file at %String%`
+
+Creates a new file at the given path. Returns that file object.
+
+`[the] file at %String%`
+
+Retrieves the existing file at the given path. Returns that file object. This may be `null` if the file does not exist.
+
+`%File% is [a] file`
+
+Whether the file is a file (not a folder.)
+
+`%File% is [a] folder`
+
+Whether the file is a folder (not a file.)
+
+```clike
+set {file} to a new file at "test.txt"
+set {file} to the file at "test.txt"
+assert {file} is a file
+```
+
+### File Properties
+
+| Property   | Description                 |
+| ---------- | --------------------------- |
+| `reader`   | The file's input stream.    |
+| `writer`   | The file's output stream.   |
+| `contents` | The file's string contents. |
+| `name`     | The file name.              |
+| `path`     | The file path.              |
+
+```clike
+set {file} to a new file at "test.txt"
+assert name of {file} is "test.txt"
+set the contents of {file} to "hello there"
+assert the contents of {file} is "hello there"
+```
+
+### Stream Properties
+
+| Property | Description                         |
+| -------- | ----------------------------------- |
+| `all`    | The input stream's entire contents. |
+| `line`   | The input stream's next line.       |
+
+```clike
+set {file} to a new file at "test.txt"
+set {writer} to writer of {file}
+write "general kenobi" to {writer}
+close {writer} // make sure to close streams when finished
+set {reader} to reader of {file}
+set {line} to line of {reader}
+assert {line} is "general kenobi"
+close {reader} // make sure to close streams when finished
+```