| summaryrefslogtreecommitdiff |
diff options
| -rw-r--r-- | config.toml | 2 | ||||
| -rw-r--r-- | content/fate_v1/_index.md | 187 | ||||
| -rw-r--r-- | content/fate_v1/computations/_index.md | 8 | ||||
| -rw-r--r-- | content/fate_v1/computations/addresses/_index.md (renamed from content/fate_v1/computations/references/_index.md) | 2 | ||||
| -rw-r--r-- | content/fate_v1/declarations/_index.md | 2 | ||||
| -rw-r--r-- | content/fate_v1/extensions/_index.md | 2 | ||||
| -rw-r--r-- | content/fate_v1/instructions/_index.md | 2 | ||||
| -rw-r--r-- | content/fate_v1/instructions/addresses/_index.md (renamed from content/fate_v1/instructions/references/_index.md) | 2 | ||||
| -rw-r--r-- | content/fate_v1/instructions/player_choices/_index.md | 4 | ||||
| -rw-r--r-- | content/fate_v1/notations/_index.md | 118 | ||||
| -rw-r--r-- | content/setup/_index.md | 2 | ||||
| -rw-r--r-- | content/wyrd_v1/computations/_index.md | 4 | ||||
| -rw-r--r-- | static/css/collapse.css | 19 |
13 files changed, 187 insertions, 167 deletions
diff --git a/config.toml b/config.toml index 05b4ec1..2eb15bb 100644 --- a/config.toml +++ b/config.toml @@ -4,7 +4,7 @@ title = "Tonkadur" theme = "hugo-theme-learn" [params] - custom_css = ["css/prism.css"] + custom_css = ["css/prism.css", "css/collapse.css"] disableShortcutsTitle=true disableInlineCopyToClipBoard=true themeVariant = "glauque" diff --git a/content/fate_v1/_index.md b/content/fate_v1/_index.md index 29e595d..3f20dc4 100644 --- a/content/fate_v1/_index.md +++ b/content/fate_v1/_index.md @@ -9,155 +9,38 @@ meant to provide the writer with as many tools as possible, so that they do not feel constrained by the limitations of the language, nor find writing complex narratives tedious. -## A few warnings first - -Fate uses strong typing. This is intended to make detection of mistakes easier, -but may lead to some frustrations for authors only used to languages using -dynamic typing. - -Fate does not have any special features for multi-seating/multi-player -narratives. This is by design, as adding proper support for this would make the -underlying language more complex, and thus would make it harder to create an -interpreter for it. This is however something considered for an extension -(see -[this GitHub issue about it](https://github.com/nsensfel/tonkadur/issues/5)). - -You'll need to learn parentheses management, if you make anything complex. Fate -uses a LISP inspired syntax, so parentheses are everywhere. The syntax gives you -free reign over indentation, but so many parentheses does require at least some -discipline in order to be readable. - -Fate is meant to be compiled. This does add an extra step to your existing -process. - -Fate is very much a new language. There isn't many (any?) tools for it. - -If for some reason you want to perform memory allocation, there is no automatic -garbage collection, so you will have to free whatever you allocate. - -In what may seem weird for narrative scripting, Fate does not feature string -manipulation operations. Strings can be made into rich text, with complex -attributes, but you will not be able to use things like regular expressions -(or anything other than simple concatenation, really) with just the base -language. This is because of these operations would need to be implemented -directly by the interpreter anyway, and their use isn't actually common in -a narrative description, which would make requiring support for them of -any Tonkadur interpreter problematic. - -## Some nice features - -If you haven't closed the tab yet, here are some reasons why you *might* want -to use Fate. - -It *is* a LISP inspired syntax. If that's what you like, you might even enjoy -this take on it. There's no fiddling with indentation, no wondering what symbol -does what. It's all about parentheses indicating something is performed on a -list of other things. It's not a purely functional language, though. In fact, -it's a mix of both declarative and imperative programming: sequences (or -procedures) are imperative. Computations are functional. There are lambda -functions, but they're strongly typed. Collections and structures can only be -modified through specific instructions, so it's not quite really a LISP-like -language. - -There are pointers. Oh, come on, it's a plus, *right?* This makes it a lot -easier to refer to things. There's no pointer arithmetic, so you don't have to -worry about the scary stuff. Also, this lets you allocate memory, which is -useful when you want a unspecified amount of distinct instances of something. -Want to describe a story where the player can push a button as many time as -they choose, create a clone of a creature every time they do so, yet let them -fight any of these creature as their distinct instance? Well, with memory -allocation and pointers, it's easily done. Didn't you know? When writing a -narrative, the RAM's the limit. So yeah, maybe don't forget to `free` the -thousands of monster the player will no doubt create. - -You can do recursion. Wait! I *am* listing the nice features! Do people really -not like recursion and pointers? Oh, well... Still, you can do recursions with -both procedures and lambda functions. Not a fan of recursion? That's alright, -you also have imperative loops: `for`, `while`, `do_while`, and even -`for_each`. - -## The basics - -#### Procedures (or Sequences) and Instructions -Procedures are lists of instructions and things to display. Instructions can be -applied to values, but they themselves do not return any value. Any value not -part of an instruction found in a procedure is displayed. Any value being part -of an instruction is **not** displayed. - -One way to think about it is to consider procedures as being actually two types -of things: sequences and procedures. A sequence is then a scene in the story, -and a procedure is just a construct called upon to perform instructions. - -Procedures can take arguments. Values are passed by copy. - -Procedures can be called in two ways: a `call` or a `jump`. A `call` will -perform the procedure before continuing with the current sequence of -instructions. A `jump` will perform the procedure **instead of** the -**current** sequence of instructions. - -Procedures can be called before their definition. The compiler will simply tell -you if the definition ends up being incompatible or missing. - -#### Computations -Computations are operations returning a value. Computations do not modify -anything, they simply return the result of an operation. - -A special type of computation, called *lambda function*, allows the creation of -a computation that will be performed only when called upon. Those can take -parameters. What's the use of something as advanced in a narrative scripting -language? It's convenient when you want to express something like a character's -name who depends on what the player figured out. Sure, you *could* make each -instance of the name feature a series of tests to find which value to use, or -you could just use a lambda function and just put -`(eval name_of_mysterious_character)` to get the right value. - -One last thing about lambda functions, which really are the only potentially -complicated thing about computations: these *are* computations, so you can use -them as such. They also cannot modify anything, as they only contain -computations and not instructions. - -#### Declarations and First Level Instructions -Declarations and First Level Instructions are a special type of instruction -which can only be done from outside a procedure. This distinction means that, -for example, you cannot define a procedure from within a procedure. - -#### Events -Sometimes, you might need to communicate something to the interpreter which -cannot be expressed in Fate. For example, you might want to say: "pause for 30 -seconds", or "play this music". This kind of thing has been considered to not -be generic enough to mandate every interpreter supports it. Instead, events are -used. - -Events are first declared, by being given a name and a list of types -corresponding to the parameters they take. Then, the `(event ...)` instruction -can be used to indicate that a certain event should occur. This will pause the -execution, and make the interpreter react to the event before continuing. - -The effect of an event is purely the interpreter's responsibility. It cannot be -described in Fate. Thus, you will need to refer to the interpreter you use to -see what events are available. - -#### Types -The basic `string`, `int`, `float`, and `bool` types are what one would expect. - -`text` corresponds to text with decorations, see the text effect sub-section. - -Two collection types are available: `(list [TYPE])` is a list of `[TYPE]` -elements, and `(set [COMPARABLE])` is a set of `[COMPARABLE]` elements. - -`(ptr [TYPE])` is an address to a value of type `[TYPE]`. - -Structures can be defined. They may contain other structures, but cannot be -recursive: only already defined types can be used. Pointers cannot be used to -resolve this conundrum in this version of Fate, but it may be added in the next -version (see [this GitHub -issue](https://github.com/nsensfel/tonkadur/issues/6)). - -#### Player Choices -Inputs from the players are limited to the `(player_choice ...)` instruction. -It presents the player with `text` options to choose from, which execute -an associated list of instructions if chosen. - -More complicated inputs, such as retrieving a `string` or an `int` from the -player require the definition and use of events. - +To write in Fate, simply open your favorite text editor and create a new file +that starts with the following line: +{{< fatecode >}}(fate_version 1){{< /fatecode >}} + +Before going any further into the documentation, you should familiarize yourself +with the [notations](/fate_v1/notations/). + +Fate files are composed of three types of constructs: +* [Computations](/fate_v1/computations/), operations that do not modify the + memory and return a value. +* [Instructions](/fate_v1/instructions/), constructs that can modify the memory + but do not return any values. +* [Declarations](/fate_v1/declarations/), special instructions that are + performed during compilation instead of during the execution. + +Other concepts in Fate include: +* [Variables](/fate_v1/declarations/variables/): named memory element. +* [Types](/fate_v1/declarations/types/): every memory element is assigned a + specific type. Fate uses static and strong typing, meaning that types are + determined at compilation time and typing +* [Procedures/Sequences](/fate_v1/declarations/sequences/): named list of + instructions, which can take parameters. +* [Lambda Functions](/fate_v1/computations/lambda_functions/): computations + which are not performed immediately but are instead stored for future use. +* [Addresses/Pointers](/fate_v1/computations/addresses/): value that + corresponds to a memory element (not to be confused with the value *of* that + memory element). +* Conditionals: selection of + [computations](/fate_v1/computations/conditionals/) or + [instructions](/fate_v1/instructions/conditionals/) depending on a + computation. +* [Loops](/fate_v1/instructions/loops/): repetition of instructions controlled + by computations. +* [Choices](/fate_v1/instructions/player_choices/): prompt the user to select an + option. diff --git a/content/fate_v1/computations/_index.md b/content/fate_v1/computations/_index.md index e8a8816..9b835de 100644 --- a/content/fate_v1/computations/_index.md +++ b/content/fate_v1/computations/_index.md @@ -1,9 +1,8 @@ --- title: Computations -weight: 2 +weight: 3 --- -Computations are values. They may read from the memory, but do not modify it -(with a single exception). +Computations are operations returning values. They do not modify the memory. ### TEXT {{< fatecode >}}(text [C0 = COMPUTATION] ... [CN = COMPUTATION]){{< /fatecode >}} @@ -36,7 +35,8 @@ Returns the value of the `{String}` field of the structure `[STRUCTURE]`. ### TEMPORARY VARIABLES {{< fatecode >}}(let (({V0 = String} [C0 = COMPUTATION]) ... ({VN = String} [CN = COMPUTATION])) [R = COMPUTATION]){{< /fatecode >}} -Defines a hierarchical level and local variables `V0` ... `VN` with values `C0` ... `CN`, and returns the value of `[R]`. +Defines a hierarchical level and local variables `{V0}` ... `{VN}` with values +`[C0]` ... `[CN]`, and returns the value of `[R]`. ### CAST {{< fatecode >}}(cast [TYPE] [COMPUTATION*]){{< /fatecode >}} diff --git a/content/fate_v1/computations/references/_index.md b/content/fate_v1/computations/addresses/_index.md index ba5716a..aafd0f1 100644 --- a/content/fate_v1/computations/references/_index.md +++ b/content/fate_v1/computations/addresses/_index.md @@ -1,5 +1,5 @@ --- -title: References +title: Addresses --- ### VALUE ACCESS {{< fatecode >}}(at [ADDRESS]){{< /fatecode >}} diff --git a/content/fate_v1/declarations/_index.md b/content/fate_v1/declarations/_index.md index c079924..97a982e 100644 --- a/content/fate_v1/declarations/_index.md +++ b/content/fate_v1/declarations/_index.md @@ -2,5 +2,5 @@ title: "Declarations" menuTitle: "Declarations" chapter: true -weight: 1 +weight: 2 --- diff --git a/content/fate_v1/extensions/_index.md b/content/fate_v1/extensions/_index.md index c0598ea..6189745 100644 --- a/content/fate_v1/extensions/_index.md +++ b/content/fate_v1/extensions/_index.md @@ -1,5 +1,5 @@ --- title: Extensions -weight: 5 +weight: 6 --- This page not available yet, sorry. diff --git a/content/fate_v1/instructions/_index.md b/content/fate_v1/instructions/_index.md index 95ee992..3f86e2e 100644 --- a/content/fate_v1/instructions/_index.md +++ b/content/fate_v1/instructions/_index.md @@ -1,6 +1,6 @@ --- title: Instructions -weight: 3 +weight: 4 --- Instructions do not return values, but modify the memory in some way or interact with the interpreter. Computations are valid instructions, and will be diff --git a/content/fate_v1/instructions/references/_index.md b/content/fate_v1/instructions/addresses/_index.md index 9beb132..e296f2c 100644 --- a/content/fate_v1/instructions/references/_index.md +++ b/content/fate_v1/instructions/addresses/_index.md @@ -1,5 +1,5 @@ --- -title: References +title: Addresses --- ### DE-ALLOCATION {{< fatecode >}}(free [POINTER]){{< /fatecode >}} diff --git a/content/fate_v1/instructions/player_choices/_index.md b/content/fate_v1/instructions/player_choices/_index.md index a0dba20..4aea5a0 100644 --- a/content/fate_v1/instructions/player_choices/_index.md +++ b/content/fate_v1/instructions/player_choices/_index.md @@ -2,13 +2,13 @@ title: Player Choices --- Player choices are the main way to interact with the user, by presenting them -with a list of `[RICH TEXT]` choices, and executing a list of instructions +with a list of `[TEXT]` choices, and executing a list of instructions associated to the choice they have made. ### CHOICE OPTION {{< fatecode >}}([TEXT] [I0 = INSTRUCTION] ... [IN = INSTRUCTION]){{< /fatecode >}} -Adds a choice showing `[RICH TEXT]` to the user, and executing `[I0]` ... `[IN]` +Adds a choice showing `[TEXT]` to the user, and executing `[I0]` ... `[IN]` if chosen. ### CHOICE PROMPT diff --git a/content/fate_v1/notations/_index.md b/content/fate_v1/notations/_index.md new file mode 100644 index 0000000..320bdbe --- /dev/null +++ b/content/fate_v1/notations/_index.md @@ -0,0 +1,118 @@ +--- +title: "Notations" +menuTitle: "Notations" +weight: 1 +--- + +This page explains the notations used on this documentation, as well as some +basics of Fate syntax. + +Fate uses a LISP inspired syntax, meaning that parentheses have a special +importance and that everything uses a prefix notation. Basically, everything +follows a `(O A B C D)` form, where `O` is being applied to `A`, `B`, `C`, and +`D`. + +Valid separators are spaces, tabs, and line returns. Having multiple separators +between two elements is the same as having a single one. + +### Comments +Comments are line without anything but any number of separators before `;;`. +Every that follows the `;;` on that line is considered to be a comment. +{{< fatecode >}};; You can comment here +(fate_version 1) + ;; Separators before the ';;' are also okay. +something ;; This is not a comment, since the line contains something else. +;; Multi line +;; comments need a ';;' on +;; every line. +(end) +{{< /fatecode >}} + +### Literals +A literal is a hard-coded string. Basically, writing `42` corresponds to a +literal of value `42`. A literal is any non-empty hard-coded string not +containing a separator, nor any parentheses. + +This documentation uses `{` and `}` to denote literal values. + +Fate is pretty strict with typing, so literals have to have a type. The rule is +as follows: does Java parses the literal as an integer? If so, it's an `{INT}`; +otherwise, if it parses as a float? If so, it's a `{FLOAT}`; otherwise, it's a +`{STRING}`. + +Now, the rules about separators and parentheses being absent in literals is a +bit problematic for strings. To remedy this: +* Writing `(lp)` counts as writing the literal `(`. +* Writing `(rp)` counts as writing the literal `)`. +* Writing `(sp)` counts as writing the literal ` ` (space). + +Thus, you cannot write: +{{< fatecode >}}This is not valid (because of parentheses).{{< /fatecode >}} + +But you can write: +{{< fatecode >}}This is valid (lp)because of parentheses(rp).{{< /fatecode >}} +And it will be a bunch of `{STRING}` literals. + +### Identifier +`{IDENTIFIER}`: Non-empty string literal without space characters, `.`, `)`, +or `(`. Line returns and tabs are considered to be space characters. Strings +that correspond to valid numbers (e.g. `42`) are likely to cause issues and +should thus be avoided. + +Examples of valid identifiers: +* {{< fatecode >}}i{{< /fatecode >}} +* {{< fatecode >}}what-kind_ofMonsterIS#THIS?{{< /fatecode >}} +* {{< fatecode >}}変数{{< /fatecode >}} +* {{< fatecode >}}80x9!{{< /fatecode >}} +* {{< fatecode >}}pseudo::namespacing<$confusion>**a**{{< /fatecode >}} + + +### Value +`[INT]`: Computation (or literal) returning a value of type `INT`. Similarly, +`[STRING]` would indicate the same for a value of type `STRING`. + +`[COMPUTATION]`: Any computation, the accepted type being determined by +something else. + +Variable names can be used directly when a computation is expected. Since this +would cause issues when `[STRING]` values can also be used, this feature is not +always available. Cases where this feature is not available are suffixed with +a `*`. For example, `[COMPUTATION*]` means that writing `my_var` is interpreted +as the `[STRING]` literal `my_var`, and to get the value of a variable, you +would need to write something like `(var my_var)`. `[STRING]` automatically +implies `[STRING*]`. + +If need be, `(string {STRING})` + +Examples of valid value: +* Values for `[INT]`: + * {{< fatecode >}}42{{< /fatecode >}} + * {{< fatecode >}}(+ 2 100 11 0 3 9){{< /fatecode >}} + * {{< fatecode >}}my_int_var{{< /fatecode >}} +* Values for `[STRING]`: + * {{< fatecode >}}(string 42){{< /fatecode >}} + * {{< fatecode >}}Just some random words...{{< /fatecode >}} + * {{< fatecode >}}not_my_var{{< /fatecode >}} + * {{< fatecode >}}(var my_string_var){{< /fatecode >}} + +### Disambiguation and variadic operators +In Fate, the computation to obtain a random integer is as follows: +{{< fatecode >}}(rand [INT] [INT]){{< /fatecode >}} +This notation makes it difficult to document what each `[INT]` corresponds to. +To remedy this, names are given to each instance: +{{< fatecode >}}(rand [I0 = INT] [I1 = INT]){{< /fatecode >}} +Now, `[I0]` refers to the first `[INT]` value, and `[I1]` to the second one. + +Some operators can take a variable number of parameters. For example, the +documentation for the logical conjunction computation is: +{{< fatecode >}}(and [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}} +The `...` indicate that there can be any number of instances of the type of parameter +that just preceded. In this example, `[B0 = BOOL] ...` indicates that there +can be any number of `[BOOL]` parameters. The parameter `[BN = BOOL]` is part +of the `...` notation and simply indicates that the documentation considers that +there are `N + 1` parameters. Thus, here, the documentation would allow: +* {{< fatecode >}}(and){{< /fatecode >}} +* {{< fatecode >}}(and (true)){{< /fatecode >}} +* {{< fatecode >}}(and (true) (false)){{< /fatecode >}} +* {{< fatecode >}}(and (true) (false) (false)){{< /fatecode >}} +* {{< fatecode >}}(and (true) (false) (false) (true)){{< /fatecode >}} diff --git a/content/setup/_index.md b/content/setup/_index.md index a9cb42c..275e809 100644 --- a/content/setup/_index.md +++ b/content/setup/_index.md @@ -43,7 +43,7 @@ A Wyrd interpreter keeps track of: of any Wyrd type. * **The Program Counter:** an integer corresponding to the next Wyrd instruction to execute. -* **Available Choices:** A list of `RICH_TEXT`. +* **Available Choices:** A list of `TEXT`. * **Last Chosen Choice:** Index of the last chosen choice. * **The Code:** A list of instructions. diff --git a/content/wyrd_v1/computations/_index.md b/content/wyrd_v1/computations/_index.md index bf7992d..bc30f12 100644 --- a/content/wyrd_v1/computations/_index.md +++ b/content/wyrd_v1/computations/_index.md @@ -88,10 +88,10 @@ type `[TYPE]`. {{< fatecode >}}(newline){{< /fatecode >}} Returns a `TEXT` value corresponding to a newline. -{{< fatecode >}}(rich_text [S0 = STRING] ... [SN = STRING]){{< /fatecode >}} +{{< fatecode >}}(text [S0 = STRING] ... [SN = STRING]){{< /fatecode >}} Returns a single value `[TEXT]` representing the elements `S0` ... `S1`. -{{< fatecode >}}(add_rich_text_effect ({string} [V0 = COMPUTATION] ... [VN = COMPUTATION]) [TEXT]){{< /fatecode >}} +{{< fatecode >}}(add_text_effect ({string} [V0 = COMPUTATION] ... [VN = COMPUTATION]) [TEXT]){{< /fatecode >}} Returns a `[TEXT]` value of `[TEXT]` with the given effect enabled. ## LAST USER CHOICE diff --git a/static/css/collapse.css b/static/css/collapse.css new file mode 100644 index 0000000..6c3e926 --- /dev/null +++ b/static/css/collapse.css @@ -0,0 +1,19 @@ +#sidebar .topics ul li +{ + display: none; +} + +#sidebar .topics>ul>li +{ + display: block; +} + +#sidebar .topics .parent>ul>li +{ + display: block; +} + +#sidebar .topics .active>ul>li +{ + display: block; +} |