Update platform files

Update platform files

Author: that-random-programmer

.vscode/settings.json

@@ -16,6 +16,7 @@
         "colorama",
         "colorchoice",
         "condv",
+        "corge",
         "ctypes",
         "datas",
         "endlocal",
@@ -25,7 +26,9 @@
         "FOPEN",
         "FREAD",
         "funcs",
+        "garply",
         "GETATTR",
+        "grault",
         "hibye",
         "hiddenimports",
         "hooksconfig",
@@ -43,13 +46,15 @@
         "modpath",
         "mypy",
         "noarchive",
+        "nostd",
         "Nuitka",
         "omvm",
         "onefile",
         "pathex",
         "peekable",
         "pefile",
         "pluggy",
+        "println",
         "pycache",
         "pygments",
         "pyinstaller",

specs/future/platform_files.md

@@ -1,33 +1,39 @@
 # The Platform File Specification (tentative)
 
-This document describes how **platform files** will work in a future version of OmniScript (v0.2.0 or v0.3.0)
+This document describes how **platform files** will work in a future version of OmniScript (v0.2.0 or v0.3.0).
+
+This is the second revision of this document.
 
 ## What are Platform Files
 
-Platfom Files will be a way to port OmniScript to a new runtime. They will describe where functions and runtime values will live, describe macros that can output completely custom bytecode, and also requirements.
+Platform Files will be a way to port OmniScript to a new runtime. They will describe where functions and runtime values will live, describe macros that can output completely custom bytecode, and also requirements.
 
-In other words, Platform Files are basically a blueprint for the compiler.
+In other words, Platform Files are basically a blueprint for the compiler, or a machine-readable spec.
 
 ## Syntax
 
 Here is some self-describing syntax
-<a id='syntax-ex'></a>
+
 ```omp
 @ver 1 # These are explained in the section `Version System`
 func foo(1) 13 # A function with one argument, living at index 13 in the builtin pool
 func bar(1, 3) # A function with 1 to 3 arguments, auto-incremented to 14
 @ver 2
 func baz(1, .) 16 # A function with 1 or more arguments at 16
 func qux(., 5) # A function with up to 5 arguments
-func quux(1) requires corge # A function which requires grault to work
+func quux(1) requires corge # A function which requires corge to work
 run grault 18 # A runtime value (similar to _name), which can perhaps change during runtime, at index 18
 attr garply(1) on str # A method for strings with one argument (syntax tentative)
 @ver 3
 attr waldo on str # An attribute for strings (syntax tentative)
+
+const TEST = 'any_type' # These get ignored by the version system, as it just replaces these with the actual value.
 # The macro syntax isn't developed yet 
 ```
 
-These rules will be stored in `.omp` files, and imported through `@platform <name>`. Note that these files have no implementation, just definitons.
+These rules will be stored in `.omp` files, and imported through `@platform <name>`. Note that these files have no implementation, just definitions.
+
+These can also be imported using a standard import, like `import std::random`, so that you can have FFI libraries that are just defined via platform files. They would be used as regular modules.
 
 The search paths will be the same as modules.
 
@@ -39,40 +45,76 @@ While the syntax hasn't been decided yet, here is how the versioning of these fi
 
 There will be 3 numbers: a file version, feature versions, and a used version.
 
-A set of symbols will get a feature version. For instance, lets say that in the example [here](#syntax-ex), the first 2 functions (`foo` and `bar`) will get a feature version of 1, the next 2 get 2, and so on. Note that the version and blocks will get decorated with a syntax similar to `@ver <num>`. 
+A set of symbols will get a feature version. For instance, lets say that in [this example](#syntax), the first 2 functions (`foo` and `bar`) will get a feature version of 1, the next 2 get 2, and so on. Note that the version and blocks will get decorated with a syntax similar to `@ver <num>`.
 
 The whole file will get a number as well, say 2.
 
 The compiler will parse the platform file, and see which items have been used. For instance, let's say we only used `foo` and `bar`. Since those have a number of `1`, the compiler will output a used version of `1`. On the other hand, if we also use `baz`, the compiler will output a used version of `2`, which will be found out with `max(<used versions>)`.
 
 When someone adds an item to the platform file, all what will happen is that they will decorate that new item with an ***incremented feature version***.
 
-When someone __removes__ an item, the whole platform file's version will get incremented.
+When someone **removes** an item, the whole platform file's version will get incremented.
+
+When someone **updates** an item with a different backend implementation, that specific item will get a new feature version that is 1 greater than the highest version.
+
+The runtime will receive the file version and used version. It will check if the file version is **equal to** it's stored supported version, and will check if the used version is **less than or equal to** it's stored version.
 
-The runtime will recieve the file version and used version. It will check if the file version is **equal to** it's stored supported version, and will check if the used version is **less than or equal to** it's stored version.
+The runtime would receive this structure (tentative):
 
-The runtime would recieve this structure (tentative):
 ``` omc
 .platform
 <name>.<file_version>.<used_version>
 ```
 
 A practical example would be:
 
-```
+```omc
 .platform
 prelude.1.4
 arduino.3.2
 ```
+
 (see [the next section](#refactors) for more info on `prelude`)
 
 If the runtime sees a platform or a version number it doesn't support, it will crash in a very similar fashion to how unsupported requirements crash. The VM will also emit an error code of `13` (CompatibilityError)
 
 The compiler will also detect env clashes (ex. `prelude` defines a function at idx `5`, but `arduino` also does the same)
 
+## Importing Platform Files
+
+Platform files can be used in 2 ways:
+
+### `@platform`
+
+This method allows one to use items directly.
+
+```omniscript
+@platform arduino
+
+pin_mode(13, HIGH)
+```
+
+If you use 2 platform files that have a symbol with the same name, the compiler will throw a warning. If you try using one of those, the compiler will error out.
+
+### `import`
+
+This method allows one to use a symbol as if it is in a library.
+
+This method will be used for certain libraries that should be implemented in a native language.
+
+If a library can be implemented in OmniScript, but could also seek performance gains in native code, there would be 2 suffixes:
+
+- `_uni`: Implemented in OmniScript. Hence, it is *uni*versal, working on (almost) all runtimes, provided they support any requirements used by it.
+- `_native`: Implemented in the runtime's language, so it would only work on platforms that adhere to that platform file.
+
+```omniscript
+import std::json_native
+json_native::load("{'foo': 'bar'}")
+```
+
 ## Refactors
 
-There really is going to be one refactor, and it's for the good, which is replacing the hardcoded indexes for the prelude (`print()` (to be renamed `println()`), `input()`, etc.) to a platform file.
+There really is going to be one refactor, and it's for the good, which is replacing the hardcoded indexes for the prelude (`println()`, `input()`, etc.) to a platform file.
 
 In order to disable the `prelude.omp` file, you will add `@nostd` to your script.