From e935061b0e2df082df477a51476ae0e7c7f98cac Mon Sep 17 00:00:00 2001 From: Kayne Ruse Date: Sat, 22 Jul 2023 19:10:22 +1000 Subject: [PATCH] Tweaked the layout --- .../game-engine.md | 4 ++ getting-started/about-library.md | 15 +++-- getting-started/random-library.md | 9 ++- getting-started/runner-library.md | 17 ++--- getting-started/standard-library.md | 66 +++++++++---------- index.md | 23 +++---- 6 files changed, 68 insertions(+), 66 deletions(-) rename {getting-started => game-engine}/game-engine.md (96%) diff --git a/getting-started/game-engine.md b/game-engine/game-engine.md similarity index 96% rename from getting-started/game-engine.md rename to game-engine/game-engine.md index 50c213c..fa85d0b 100644 --- a/getting-started/game-engine.md +++ b/game-engine/game-engine.md @@ -1,3 +1,7 @@ +# Preface + +The game engine is incomplete and still evolving, as such this page should be considered outdated at all times... + # Game Engine The Toy programming langauge was designed from the beginning as an embedded scripting language for some kind of game engine. Different iterations have existed with different implementations, some of which could charitably be said to function. The current version, and the most stable and feature complete so far, has reached a point where it needs some kind of concrete engine to improve any further. diff --git a/getting-started/about-library.md b/getting-started/about-library.md index 6d74568..a2440c8 100644 --- a/getting-started/about-library.md +++ b/getting-started/about-library.md @@ -6,26 +6,27 @@ The about library can usually be accessed with the `import` keyword: ``` import about; -import about as about; //can easily be aliased +import about as about; //can be aliased ``` -## major +## Defined Variables + +### major This variable is the major version number of Toy at the time of compilation. -## minor +### minor This variable is the minor version number of Toy at the time of compilation. -## patch +### patch This variable is the patch version number of Toy at the time of compilation. -## build +### build This variable is a string representing the date and time that the interpreter was compiled. -## author +### author This variable contains the name of Toy's lead author, and his game studio. - diff --git a/getting-started/random-library.md b/getting-started/random-library.md index b5a13cb..5a95c52 100644 --- a/getting-started/random-library.md +++ b/getting-started/random-library.md @@ -13,19 +13,22 @@ var generator: opaque = createRandomGenerator(clock().hash()); The current implementation is minimal in nature, and will be expanded or replaced in future. -## createRandomGenerator(seed: int) +## Defined Functions + +### createRandomGenerator(seed: int): opaque This function creates a new generator opaque based on the given seed. The same seed will produce the same sequence of pseudorandom outputs from different generators using `generateRandomNumber`. Every generator must also be freed with `freeRandomGenerator`. -## generateRandomNumber(self: opaque) +### generateRandomNumber(self: opaque): int This function takes in a generator opaque, and returns a pseudorandom integer value. This function also mutates the generator's internal state. -## freeRandomGenerator(self: opaque) +### freeRandomGenerator(self: opaque) This function frees an existing generator opaque. +This function must be called on all generators before the program ends. diff --git a/getting-started/runner-library.md b/getting-started/runner-library.md index 34c54d7..57b7658 100644 --- a/getting-started/runner-library.md +++ b/getting-started/runner-library.md @@ -10,7 +10,9 @@ The runner library can usually be accessed with the `import` keyword: import runner; ``` -## loadScript(path: string) +## Defined Functions + +### loadScript(path: string): opaque This is used to load an external script into an opaque variable. @@ -22,7 +24,7 @@ This function does a lot of work: * It constructs and intializes an Interpreter * It packages it all into an opaque variable and returns it -## loadScriptBytecode(path: string) +### loadScriptBytecode(path: string): opaque This is used to load an external bytecode file into an opaque variable. @@ -34,11 +36,11 @@ This function does a lot of work: Note: This function resembles `loadScript()`, but skips the compilation step. -## runScript(self: opaque) +### runScript(self: opaque) This function executes an external script, which must first be loaded into an opaque variable with either `loadScript()` or `loadScriptBytecode()`. -## getScriptVar(self: opaque, name: string) +### getScriptVar(self: opaque, name: string): any This function retrieves a variable from the top level of a script's environment. @@ -46,15 +48,14 @@ This function retrieves a variable from the top level of a script's environment. This function retrieves a function from the top level of a script's environment, and calls it with `rest` as the argument list. -## resetScript(self: opaque) +### resetScript(self: opaque) This function resets the script so that it is no longer in a "dirty" state, and can be re-run using `runScript()`. -## freeScript(self: opaque) +### freeScript(self: opaque) This function frees a script's resources, cleaning up any memory that is no longer needed. Failing to call this will result in a memory leak. -## checkScriptDirty(self: opaque) +### checkScriptDirty(self: opaque): bool This function returns true of the script is "dirty", otherwise it returns false. - diff --git a/getting-started/standard-library.md b/getting-started/standard-library.md index b5d358c..ccfc8ce 100644 --- a/getting-started/standard-library.md +++ b/getting-started/standard-library.md @@ -8,14 +8,13 @@ The standard library can usually be accessed with the `import` keyword: import standard; ``` -# Misc. Utilities -
+## Defined Misc. Functions -## clock() +### clock(): string This function returns a string representation of the current timestamp. -## hash(self) +### hash(self: any): int This function returns a hashed value of `self`. @@ -28,53 +27,51 @@ This function uses the internal literal hashing algorithms. As such, the followi Any attempt to hash these will return -1, except `null` which returns 0. -# Maths Utilities -
+## Defined Maths Functions -## abs(self) +### abs(self): any This function returns the absolute value of any integer or float passed in. -## ceil(self): int +### ceil(self): int This function returns the value of any integer or float passed in, rounded up. -## floor(self): int +### floor(self): int This function returns the value of any integer or float passed in, rounded down. -## max(...) +### max(...): any This function returns the value of the highest integer or float passed in. It can take any number of arguments. -## min(...) +### min(...): any This function returns the value of the lowest integer or float passed in. It can take any number of arguments. -## round(self): int +### round(self): int This function returns the value of any integer or float passed in, rounded to the nearest whole number. -# Compound Utilities -
+## Defined Compound Functions -## concat(self, other) +### concat(self, other): any This function only works when self and other are matching compounds (both arrays, dictionaries or strings). It returns a new compound of that kind, with the content of `other` appended to the content of `self`. -## containsKey(self: dictionary, key) +### containsKey(self: dictionary, key): bool This function returns `true` if `self` contains the given `key`, otherwise it returns false. -## containsValue(self, value) +### containsValue(self, value): bool This function returns `true` if `self` contains the given `value`, otherwise it returns false. -## every(self, func: fn) +### every(self, func: fn): bool This function takes either an array or a dictionary as the `self` argument, and a function as `func`. The argument `func` must take two arguments - the first is the index/key of the array/dictionary, and the second is the value. The contents of `self` are passed into `func`, one element at a time, until `func` returns `false`, at which point this function returns `false`. Otherwise this function returns `true`. -## forEach(self, func: fn) +### forEach(self, func: fn) This function takes either an array or a dictionary as the `self` argument, and a function as `func`. The argument `func` must take two arguments - the first is the index/key of the array/dictionary, and the second is the value. The contents of `self` are passed into `func`, one element at a time. @@ -90,23 +87,23 @@ var a = [1, 3, 5]; a.forEach(p); //prints 1, 3, and 5 to stdout ``` -## filter(self, func: fn) +### filter(self, func: fn): any This function takes either an array or a dictionary as the `self` argument, and a function as `func`. The argument `func` must take two arguments - the first is the index/key of the array/dictionary, and the second is the value. The contents of `self` are passed into `func`, one element at a time, and the function returns a new compound for every element that `func` returned a truthy value for. -## getKeys(self: dictionary) +### getKeys(self: dictionary): [any] This function returns an array of all non-null keys stored within the dictionary. The order is undefined. -## getValues(self: dictionary) +### getValues(self: dictionary): [any] This function returns an array of all values with non-null keys stored within the dictionary. The order is undefined. -## indexOf(self: array, value) +### indexOf(self: array, value): int This function returns the first index within `self` that is equal to `value`, or `null` if none are found. -## map(self, func: fn) +### map(self, func: fn): any This function takes either an array or a dictionary as the `self` argument, and a function as `func`. The argument `func` must take two arguments - the first is the index/key of the array/dictionary, and the second is the value. It returns an array with the results of each call - the order of the results when called on a dictionary are undefined. @@ -122,7 +119,7 @@ var a = [1, 2, 3]; print a.map(increment); //prints [2,3,4]; ``` -## reduce(self, default, func: fn) +### reduce(self, default: any, func: fn): any This function takes either an array or a dictionary as the `self` argument, a default value, and a function as `func`. The argument `func` takes three arguments - the first is the accumulator, the second is the index/key and the third is the value. It applies the given function to every element of the array/dictionary, passing the result of each call as the accumulator to the next (the default value is used for the first call). Finally, the final value of the accumulator is returned to the caller. @@ -138,13 +135,13 @@ var a = [1, 2, 3, 4]; print a.reduce(0, f); //prints "10" ``` -## some(self, func: fn) +### some(self, func: fn): bool This function takes either an array or a dictionary as the `self` argument, and a function as `func`. The argument `func` must take two arguments - the first is the index/key of the array/dictionary, and the second is the value. The contents of `self` are passed into `func`, one element at a time, until `func` returns `true`, at which point this function returns `true`. Otherwise this function returns `false`. -## sort(self: array, func: fn) +### sort(self: array, func: fn) -This function takes an array as the `self` argument, and a comparison function as `func`. The argument `func` must take two arguments, and return a truthy or falsy value. The contents of the array in `self` are sorted based on the results of `func`, as though function were the less comparison function. +This function takes an array as the `self` argument, and a comparison function as `func`. The argument `func` must take two arguments, and return a truthy or falsy value. The contents of the array in `self` are sorted based on the results of `func`, as though the function were the less comparator function. ``` import compound; @@ -158,21 +155,21 @@ var a = [4, 1, 3, 2]; print a.sort(less); //prints "[1, 2, 3, 4]" ``` -## toLower(self: string) +### toLower(self: string): string This function returns a new string which is identical to the string `self`, except any uppercase letters are replaced with the corresponding lowercase letters. -## toString(self) +### toString(self): string This function returns a string representation of `self`. This is intended for arrays and dictionaries, but can theoretically work on any printable value. If the resulting string is longer than `TOY_MAX_STRING_LENGTH` - 1, then it is truncated. -## toUpper(self: string) +### toUpper(self: string):string This function returns a new string which is identical to the string `self`, except any lowercase letters are replaced with the corresponding uppercase letters. -## trim(self: string, trimChars: string = " \t\n\r") +### trim(self: string, trimChars: string = " \t\n\r"): string This function returns a new string which is identical to the string `self`, except any characters at the beginning or end of `self` which are present in the argument `trimChars` are removed. The argument `trimChars` is optional, and has the following characters as the default value: @@ -183,11 +180,10 @@ This function returns a new string which is identical to the string `self`, exce These characters used because they are the only control characters currently supported by Toy. -## trimBegin(self: string, trimChars: string = " \t\n\r") +### trimBegin(self: string, trimChars: string = " \t\n\r"): string This function is identical to `trim(self, trimChars)`, except it is only applied to the beginning of the first argument. -## trimEnd(self: string, trimChars: string = " \t\n\r") +### trimEnd(self: string, trimChars: string = " \t\n\r"): string This function is identical to `trim(self, trimChars)`, except it is only applied to the end of the first argument. - diff --git a/index.md b/index.md index 3f8690e..3451558 100644 --- a/index.md +++ b/index.md @@ -30,9 +30,7 @@ print tally(); //2 print tally(); //3 ``` -# Nifty Features - -
+## Nifty Features * Simple C-like syntax * Bytecode intermediate compilation @@ -43,9 +41,7 @@ print tally(); //3 * Can re-direct output, error and assertion failure messages * Open source under the zlib license -# Getting Started - -
+## Getting Started * [Quick Start Guide](getting-started/quick-start-guide) * [Types](getting-started/types) @@ -53,11 +49,8 @@ print tally(); //3 * [Standard Library](getting-started/standard-library) * [Random Library](getting-started/random-library) * [Runner Library](getting-started/runner-library) -* [Game Engine](getting-started/game-engine) -# Deep Dive - -
+## Deep Dive * [Theorizing Toy](deep-dive/theorizing-toy) * [Building Toy](deep-dive/building-toy) @@ -67,9 +60,7 @@ print tally(); //3 * [Testing Toy](deep-dive/testing-toy) * [Roadmap](deep-dive/roadmap) -# Public C API - -
+## Public C API * [repl_tools.h](c-api/repl_tools_h.md) * [toy.h](c-api/toy_h.md) @@ -86,3 +77,9 @@ print tally(); //3 * [toy_reffunction.h](c-api/toy_reffunction_h.md) * [toy_refstring.h](c-api/toy_refstring_h.md) * [toy_scope.h](c-api/toy_scope_h.md) + +## Game Engine + +Note: This section is incomplete. + +* [Game Engine](game-engine/game-engine.md)