From 73cc70358020538b13f2d5cf4e81426b13bbb85a Mon Sep 17 00:00:00 2001 From: Nathanael Sensfelder Date: Sun, 24 Jan 2021 22:08:56 +0100 Subject: ... --- content/fate_v1/aliases/default.md | 42 ----- content/fate_v1/computations/_index.md | 2 +- content/fate_v1/computations/basics/_index.md | 145 ++++++++++++++++ content/fate_v1/computations/bools/_index.md | 56 ++++++ content/fate_v1/computations/maths/_index.md | 58 +++++++ content/fate_v1/declarations/_index.md | 6 - content/fate_v1/declarations/events/_index.md | 18 -- content/fate_v1/declarations/files/_index.md | 48 ----- content/fate_v1/declarations/sequences/_index.md | 113 ------------ .../fate_v1/declarations/text_effects/_index.md | 31 ---- content/fate_v1/declarations/types/_index.md | 66 ------- content/fate_v1/declarations/variables/_index.md | 72 -------- content/fate_v1/extensions/_index.md | 5 - content/fate_v1/files/_index.md | 50 ++++++ content/fate_v1/instructions/_index.md | 2 +- content/fate_v1/notations/_index.md | 3 +- content/fate_v1/sequences/_index.md | 115 ++++++++++++ content/fate_v1/text_effects/_index.md | 32 ++++ content/fate_v1/types/_index.md | 193 +++++++++++++++++++++ content/fate_v1/variables/_index.md | 73 ++++++++ 20 files changed, 725 insertions(+), 405 deletions(-) delete mode 100644 content/fate_v1/aliases/default.md create mode 100644 content/fate_v1/computations/basics/_index.md create mode 100644 content/fate_v1/computations/bools/_index.md create mode 100644 content/fate_v1/computations/maths/_index.md delete mode 100644 content/fate_v1/declarations/_index.md delete mode 100644 content/fate_v1/declarations/events/_index.md delete mode 100644 content/fate_v1/declarations/files/_index.md delete mode 100644 content/fate_v1/declarations/sequences/_index.md delete mode 100644 content/fate_v1/declarations/text_effects/_index.md delete mode 100644 content/fate_v1/declarations/types/_index.md delete mode 100644 content/fate_v1/declarations/variables/_index.md delete mode 100644 content/fate_v1/extensions/_index.md create mode 100644 content/fate_v1/files/_index.md create mode 100644 content/fate_v1/sequences/_index.md create mode 100644 content/fate_v1/text_effects/_index.md create mode 100644 content/fate_v1/types/_index.md create mode 100644 content/fate_v1/variables/_index.md diff --git a/content/fate_v1/aliases/default.md b/content/fate_v1/aliases/default.md deleted file mode 100644 index 1247545..0000000 --- a/content/fate_v1/aliases/default.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Aliases -weight: 4 ---- -Nearly all computations and instructions have aliases, making it easier to -write in the language when not used to it. This page provides most of them. As -a general rule, all underscores (`_`) are optional, all `declare` can be -replaced by `define` and `def`. - -* `abs`: `absolute`. -* `and`: `/\`. -* `>=`: `greater_equal_than`, `ge`. -* `/`: `divide`, `div`. -* `=`: `==`, `equals`, `eq`. -* `declare_alias_type`: `declare_sub_type`, `typedef`. -* `declare_structure_type`: `declare_structure`, `declare_dict_type`, - `declare_dict`. -* `declare_event_type`: `declare_event`. -* `declare_sequence`: `declare_seq`, `declare_procedure`, `declare_proc`. -* `ignore_error`: `ignore_warning`. -* `free`: `release`, `destroy`. -* `implies`: `=>`, `->`. -* `is_member`: `contains`, `has`. -* `=<`: `<=`, `lower_equal_than`, `le`. -* `<`: `lower_than`, `lt`. -* `-`: `minus` -* `min`: `minimum`. -* `max`: `maximum`. -* `eval`: `evaluate`. -* `%`: `mod`, `modulo`. -* `new`: `reserve`, `create`. -* `not`: `~`, `!`. -* `add_element`: `add`. -* `one_in`: `exactly_one_in`, `exactly_one`, `one`. -* `remove_at`: `remove_element_at`, `remove_elem_at`. -* `set`: `set_value`, `set_val`, `set_variable`, `set_var`. -* `var`: `variable`. -* `visit`: `call`, `call_sequence`, `call_procedure`, `call_seq`, `call_proc`, - `visit_sequence`, `visit_procedure`, `visit_seq`, `visit_proc`. -* `jump_to`: `continue_as`, `continue_to`, `continue_with`, `jump`, `go_to`, - `exec`. And you can suffix `_proc`, `_procedure`, `_seq`, or `_sequence` to - any of these. diff --git a/content/fate_v1/computations/_index.md b/content/fate_v1/computations/_index.md index 9b835de..175d039 100644 --- a/content/fate_v1/computations/_index.md +++ b/content/fate_v1/computations/_index.md @@ -1,6 +1,6 @@ --- title: Computations -weight: 3 +weight: 4 --- Computations are operations returning values. They do not modify the memory. diff --git a/content/fate_v1/computations/basics/_index.md b/content/fate_v1/computations/basics/_index.md new file mode 100644 index 0000000..e8a8816 --- /dev/null +++ b/content/fate_v1/computations/basics/_index.md @@ -0,0 +1,145 @@ +--- +title: Computations +weight: 2 +--- +Computations are values. They may read from the memory, but do not modify it +(with a single exception). + +### TEXT +{{< fatecode >}}(text [C0 = COMPUTATION] ... [CN = COMPUTATION]){{< /fatecode >}} + +Returns a `text` node containing the text representation of `C0` ... `CN`. + +### VARIABLE | REFERENCE +{{< fatecode >}}(var {String}){{< /fatecode >}} + +Returns the value of the variable `{String}`, or a reference to it if +applicable. Structure members can be accessed by using `.` in `{String}`. + +### SEQUENCE | PROCEDURE +{{< fatecode >}}(sequence {String}){{< /fatecode >}} + +Returns a `[SEQUENCE]` value corresponding to the sequence named `{String}`. +Said sequence can be defined at a later point. + +### STRUCTURE FIELD ACCESS +{{< fatecode >}}{Structure Var Name}.{Field Name}{{< /fatecode >}} +{{< fatecode >}}(field {String} [STRUCTURE VAR]){{< /fatecode >}} + +Accesses the `{String}` field of the structure `[STRUCTURE VAR]`. Using `.` to +access fields is recommended over the use of this operator. + +### STRUCTURE FIELD VALUE +{{< fatecode >}}(get_field {String} [STRUCTURE]){{< /fatecode >}} +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]`. + +### CAST +{{< fatecode >}}(cast [TYPE] [COMPUTATION*]){{< /fatecode >}} + +Transforms `[COMPUTATION*]` into a value of type `[TYPE]`. Note that the variable +shorthand cannot be used for `[COMPUTATION*]`. The following type changes are +allowed: +* `[FLOAT]` to `[FLOAT]`, `[INT]`, and `[STRING]`. +* `[INT]` to `[FLOAT]`, `[INT]`, and `[STRING]`. +* `[BOOL]` to `[BOOL]` and `[STRING]`. +* `[STRING]` to `[BOOL]` (`true` and `false`), `[FLOAT]`, `[INT]`, and`[STRING]`. + +### RANDOM NUMBER +{{< fatecode >}}(rand [I0 = INT] [IN = INT]){{< /fatecode >}} + +Returns a random number between `I0` and `IN` (inclusive). + +## Basic Operators +### BOOL OPERATORS +{{< fatecode >}}(and [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}} + +Standard conjunction (minimum of 2 arguments). + +{{< fatecode >}}(or [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}} + +Standard disjunction (minimum of 2 arguments). + +{{< fatecode >}}(not [BOOL]){{< /fatecode >}} + +Standard negation. + +{{< fatecode >}}(implies [B0 = BOOL] [B1 = BOOL]){{< /fatecode >}} + +Standard implication. + + +{{< fatecode >}}(one_in [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}} + +true if, and only if, exactly one of the operands is true. + +### MATH OPERATORS +All operands must be of the same type, which is also the type returned by the +operation. + +{{< fatecode >}}(+ [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Standard addition (minimum of 2 arguments). + +{{< fatecode >}}(- [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Standard substraction (minimum of 2 arguments). + +{{< fatecode >}}(* [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Standard multiplication (minimum of 2 arguments). + +{{< fatecode >}}(/ [N0 = NUMBER] [N1 = NUMBER]){{< /fatecode >}} + +Standard division. Note that a division on integers is indeed a integer +division. + +{{< fatecode >}}(^ [N0 = NUMBER] [N1 = NUMBER]){{< /fatecode >}} + +Standard exponentiation. + +{{< fatecode >}}(% [I0 = INT] [I1 = INT]){{< /fatecode >}} + +Standard modulo operation. + +{{< fatecode >}}(min [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Lowest value among the operands. + +{{< fatecode >}}(max [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Highest value among the operands. + +{{< fatecode >}}(clamp [N0 = NUMBER] [N1 = NUMBER] [N2 = NUMBER]){{< /fatecode >}} + +Equivalent to `(max N0 (min N1 N2))`. + + +{{< fatecode >}}(abs [NUMBER]){{< /fatecode >}} + +Positive value of `[NUMBER]`. + +### COMPARISON OPERATORS +{{< fatecode >}}(= [C0 = COMPUTATION] ... [CN = COMPUTATION]){{< /fatecode >}} + +True if, and only if, all operands are equal. + +{{< fatecode >}}(< [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is strictly lower than `C1`. + +{{< fatecode >}}(=< [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is lower or equal to/than `C1`. + +{{< fatecode >}}(> [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is strictly higher than `C1`. + +{{< fatecode >}}(>= [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is higher or equal to/than `C1`. diff --git a/content/fate_v1/computations/bools/_index.md b/content/fate_v1/computations/bools/_index.md new file mode 100644 index 0000000..6a31042 --- /dev/null +++ b/content/fate_v1/computations/bools/_index.md @@ -0,0 +1,56 @@ +--- +title: Booleans +weight: 2 +--- + +All arguments are assumed to be of the same type. + +### Conjunction +{{< fatecode >}}(and [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}} + +Standard conjunction (minimum of 2 arguments). + +### Disjunction +{{< fatecode >}}(or [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}} + +Standard disjunction (minimum of 2 arguments). + +### Negation +{{< fatecode >}}(not [BOOL]){{< /fatecode >}} + +Standard negation. + +### Implication +{{< fatecode >}}(implies [B0 = BOOL] [B1 = BOOL]){{< /fatecode >}} + +Standard implication. + +### Exclusivity +{{< fatecode >}}(one_in [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}} + +true if, and only if, exactly one of the operands is true. There needs to be at +least one argument. + +### Equality +{{< fatecode >}}(= [C0 = COMPUTATION*] ... [CN = COMPUTATION*]){{< /fatecode >}} +True if, and only if, all operands are equal. Takes at least 2 arguments. + +### Strictly less than +{{< fatecode >}}(< [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is strictly lower than `C1`. + +### Less than +{{< fatecode >}}(=< [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is lower or equal to/than `C1`. + +### Strictly more than +{{< fatecode >}}(> [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is strictly higher than `C1`. + +### More than +{{< fatecode >}}(>= [C0 = COMPARABLE] [C1 = COMPARABLE]){{< /fatecode >}} + +True if, and only if, `C0` is higher or equal to/than `C1`. diff --git a/content/fate_v1/computations/maths/_index.md b/content/fate_v1/computations/maths/_index.md new file mode 100644 index 0000000..ef0783b --- /dev/null +++ b/content/fate_v1/computations/maths/_index.md @@ -0,0 +1,58 @@ +--- +title: Mathematics +weight: 1 +--- + +All operands must be of the same type, which is also the type returned by the +operation. + +### Addition +{{< fatecode >}}(+ [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Standard addition (minimum of 2 arguments). + +### Substraction +{{< fatecode >}}(- [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Standard substraction (minimum of 2 arguments). + +### Multiplication +{{< fatecode >}}(* [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Standard multiplication (minimum of 2 arguments). + +### Division +{{< fatecode >}}(/ [N0 = NUMBER] [N1 = NUMBER]){{< /fatecode >}} + +Standard division. Note that a division on integers is indeed an integer +division. + +### Exponent +{{< fatecode >}}(^ [N0 = NUMBER] [N1 = NUMBER]){{< /fatecode >}} + +Standard exponentiation. + +### Modulo +{{< fatecode >}}(% [I0 = INT] [I1 = INT]){{< /fatecode >}} + +Standard modulo operation. + +### Minimum +{{< fatecode >}}(min [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Lowest value among the operands (minimum of 2 arguments). + +### Maximum +{{< fatecode >}}(max [N0 = NUMBER] ... [NN = NUMBER]){{< /fatecode >}} + +Highest value among the operands (minimum of 2 arguments). + +### Clamp +{{< fatecode >}}(clamp [N0 = NUMBER] [N1 = NUMBER] [N2 = NUMBER]){{< /fatecode >}} + +Equivalent to `(max N0 (min N1 N2))`. + +### Absolute +{{< fatecode >}}(abs [NUMBER]){{< /fatecode >}} + +Positive value of `[NUMBER]`. diff --git a/content/fate_v1/declarations/_index.md b/content/fate_v1/declarations/_index.md deleted file mode 100644 index 97a982e..0000000 --- a/content/fate_v1/declarations/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Declarations" -menuTitle: "Declarations" -chapter: true -weight: 2 ---- diff --git a/content/fate_v1/declarations/events/_index.md b/content/fate_v1/declarations/events/_index.md deleted file mode 100644 index 0c00d52..0000000 --- a/content/fate_v1/declarations/events/_index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Events ---- -Events are how a Fate narrative can communicate to the interpreter that -something which cannot be expressed in Fate needs to be performed. The execution -is paused until the event is resolved by the interpreter. To avoid mistakes, any -event type must be declared before use. - -#### EVENT -{{< fatecode >}}(declare_event_type {string} [C0 = TYPE] ... [CN = TYPE]){{< /fatecode >}} -**Effect:** An event with the name `{string}` and taking parameters of types -`[C0]`, ..., `[CN]` can be used. - -## Examples -* `(declare_event_type user_string_input text (ptr string))` -* `(declare_event_type wait int)` -* `(declare_event_type set_background_to string)` -* `(declare_event_type rumble)` diff --git a/content/fate_v1/declarations/files/_index.md b/content/fate_v1/declarations/files/_index.md deleted file mode 100644 index 05c6836..0000000 --- a/content/fate_v1/declarations/files/_index.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: File Management ---- -Fate narratives have one main file, but this file can use the contents of other -files, and these files in turn can also use the contents of other files. Three -issues arise then: some things must be declared before they are used, nothing -should be declared multiple times, and where are the files? - -The absolute path to each file is computed in order to detect whether it has -already been loaded. The given paths are expected to be relative. They are then -resolved by attempting access from the following, in order: the current file's -directory; the include directories passed as parameter to the executable; the -calling executable's directory. - -Dependency cycles will raise compiling errors. - -The first "instruction" on each file must be `(fate_version 1)`. Values cannot -be placed before either, obviously. - -{{< fatecode >}}(require {string}){{< /fatecode >}} - -**Effect:** If the file at `{string}` has not yet been loaded, load it. - -{{< fatecode >}}(include {string}){{< /fatecode >}} - -**Effect:** Load the `{string}`, even if it has already been loaded. - -#### Examples -* `(require bonus_sequence.fate)` -* `(include types/plant.fate)` -* `(require ../guild/merchants.fate)` -* `(include ../what/../are/../you/../doing/../there.fate)` -* `(require oh/../oh/../oh/../this_is_fine.fate)` - -Example of Fate file: -{{< fatecode >}};;; A story of great importance -(fate_version 1) - -(require include/events.fate) -(require include/text_effects.fate) - -(require scenes/the_holiday_forest.fate) - -`Twas a long time ago... Longer now that it seems... In a place that can't be -referenced here because I'm pretty sure the transcript is copyrighted. - -(jump_to not_the_tree_door_i_would_have_chosen) -{{< /fatecode >}} diff --git a/content/fate_v1/declarations/sequences/_index.md b/content/fate_v1/declarations/sequences/_index.md deleted file mode 100644 index a2fbcb1..0000000 --- a/content/fate_v1/declarations/sequences/_index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Sequences and Procedures ---- -Sequences and procedures are the same thing. These are named lists of -instructions and values, which can be called upon at any point where -instructions can be used. They can take parameters. - -Procedures do not return values. It is however possible to emulate something -similar, by passing a pointer as a parameter and storing a "return" value into -it. - -These are also intended to be used to describe scenes. - -The execution of a sequence can be terminated by using the `(done)` -instruction. The execution of the narrative can be terminated by using the -`(end)` instruction. - -Any value not part of an instruction will simply be displayed when it is -reached during the procedure's execution. - -Sequences can be used before their definition, the compiler will raise an error -if the use ends up being incorrect. - -Execution of a sequence can be started in two ways: `(call sequence_name)` will -execute the sequence then continue with the execution of the current -instruction list; `(jump_to sequence_name)` will replace the current -instruction list by the execution of the sequence. If one were to ignore -variables, the `(jump_to sequence_name)` instruction is similar to performing -`(call sequence_name) (done)`. - -{{< fatecode >}}(define_sequence {String} (([C0 = TYPE] {V0 = String}) ... ([CN = TYPE] {VN = String})) [I0 = INSTRUCTIONS|VALUE] ... [IM = INSTRUCTIONS|VALUE]){{< /fatecode >}} -**Effect:** Defines the sequence `{String}`, with variables `V0` ... `VN` of types `C0` ...`CN` as parameters, and instructions `I0` ... `IM` as content. - -**Acceptable Aliases:** `declare_sequence`, `def_seq`, `define_procedure`, `declare_procedure`, `def_proc`. - -#### Examples -{{< fatecode >}}(define_sequence in_your_room () - (ifelse - (is_member visited_your_room progress) - (text_effect narrator - You room is still a mess. You don't have time to clean things up, - though. - ) - (text_effect narrator - You room is a mess. You recall having been through every drawer while - preparing your bag yesterday. While still unclear on how you are - supposed to pack all the necessary things for what promises to be at - least a year-long journey inside a small backpack, you cannot avoid - but wasting more time contemplating the piles of items that didn't - make the cut. - ) - ) - (add visited_your_room progress) - (player_choice - ( - ( Look for healing items ) - (jump_to look_for_healing_items) - ) - ( - ( No time! Let's go adventuring! ) - (jump_to leave_your_room) - ) - ) -) -{{< /fatecode >}} - -{{< fatecode >}}(define_sequence index_of_loop - ( - ((ptr int) result_holder) - ((list int) collection) - (int target) - ) - (local int collection_size) - (local int i) - - (set collection_size (size collection)) - - (for (set i 0) (< (var i) (var collection_size)) (set i (+ (var i) 1)) - (if (= (access collection (var i)) (var target)) - ( - (set (at result_holder) (var i)) - (done) - ) - ) - ) - (set (at result_holder) -1) -) -{{< /fatecode >}} - - -{{< fatecode >}}(define_sequence index_of_jump - ( - ((ptr int) result_holder) - ((list int) collection) - (int target) - (int i) - (int collection_size) - ) - (ifelse (= (var i) (var collection_size)) - (set (at result_holder) -1) - (ifelse (= (access collection (var i)) (var target)) - (set (at result_holder) (var i)) - (jump index_of_jump - (var result_holder) - (var collection) - (var target) - (+ (var i) 1) - (var collection_size) - ) - ) - ) -) -{{< /fatecode >}} diff --git a/content/fate_v1/declarations/text_effects/_index.md b/content/fate_v1/declarations/text_effects/_index.md deleted file mode 100644 index fd3742d..0000000 --- a/content/fate_v1/declarations/text_effects/_index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Text Effects ---- -Text effects are attributes that can be given to text elements. The -effects themselves can take parameters. To avoid errors that would be difficult -to detect, Tonkadur expects text effects to be declared before being used. -Note that multiple text effects can be applied to the same text elements, -so there is no need to create text effects that combine other text effects. - -Two text effects cannot have the same name, even if their parameter types -differ. - -Because text effects are handled by the interpreter, it is recommended to -overlay their use by lambda functions. This way, each interpreter can simply -expose its available text effects in a file, and the definition of the lambda -functions can thus be changed according to which interpreter is used without -having to go through the whole document. Furthermore, the name of text effects -exposed by the interpreter might not match the name that would make the most -sense to use within the narrative. - -### TEXT EFFECT -{{< fatecode >}}(declare_text_effect {Identifier} [T0 = TYPE] ... [TN = TYPE]){{< /fatecode >}} -Declares the text effect `{Identifier}`, with parameters of type `[T0]` ... -`[TN]`. - -## Examples -* `(declare_text_effect bold)` -* `(declare_text_effect speaker string)` -* `(declare_text_effect color int int int)` -* `(declare_text_effect font string)` -* `(declare_text_effect speaker_emotion string int)` diff --git a/content/fate_v1/declarations/types/_index.md b/content/fate_v1/declarations/types/_index.md deleted file mode 100644 index 5844895..0000000 --- a/content/fate_v1/declarations/types/_index.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Types ---- -Fate is a strongly typed language. - -## Base Types -There are a few base types already defined: - -* `int`: an integer, which is a number *without* fractional component (e.g. `-3`, `0`, `3`). -* `float`: a number *with* a fractional component (e.g. `-3.14`, `0.0`, `3.9931`). -* `bool`: a Boolean (i.e. `(true)` or `(false)`). -* `string`: a list of characters, not including newlines (e.g. `bob`, - `something else`, `日本のもの`, or `الاشياء العربية`). This cannot include - computations: only hardcoded strings. `(lp)` will be substituted by a `(` and - `(rp)` by a `)`, letting you use parentheses in a string. - -* `text`: a list of computations, interpreted as text, which may have - attributes. - -Pointers are also available: -* `(ptr [TYPE])`: a pointer to a memory element of type `[TYPE]` (e.g. `(ptr int)`, `(ptr (ptr string))`). -If you are not familiar with pointers, a pointer is a value corresponding to an address containing a memory element. -Accessing the value of the pointer yields the address, accessing the value pointed to by the value of the pointer yields the memory element. -Pointers to pointers can be made, in which case that memory element is also an address to yet another memory element. -Pointers still have to point to a definite type. Unlike in C, you cannot create a pointer to an unspecified type. - -Two collection types are available: -* `(list [TYPE])` -* `(set [COMPARABLE TYPE])` - -Lambda computations are available: -* `(lambda [R = TYPE] ([A0 = TYPE] ... [AN = TYPE]))` is a type corresponding - to a lambda function returning a value of type `R` and taking parameters of - types `A0` ... `AN`. - -Procedures/sequences can be stored for future reference: -* `(sequence ([A0 = TYPE] ... [AN = TYPE]))` is a type corresponding - to a procedure/sequence taking parameters of types `A0` ... `AN`. - -### Common Type Groupings -* `[NUMBER]` corresponds to `int`, `float`. -* `[COLLECTION]` corresponds to `(list [TYPE])` and `(set [COMPARABLE TYPE])`. -* `[PRIMITIVE]` `int`, `float`, `bool`, `string`, `text`. -* `[COMPARABLE]` corresponds to `int`, `float`, `bool`, `string`, `text`, - and `(ptr [TYPE])`. This indicates types for which operators such as `<` are - defined. - -## Defining Your Own Types - -### Aliasing -{{< fatecode >}}(declare_alias_type [TYPE] {String}){{< /fatecode >}}. -**Effect:** Declares the type `{String}`. If `[TYPE]` is not a `[PRIMITIVE]`, - `[TYPE]` and `{String}` are now two equivalent types. If `[TYPE]` is a - `[PRIMITIVE]`, `{String}` is a subtype of `[TYPE]`. - -### Structures -{{< fatecode >}}(declare_structure_type {String} ([T0 = TYPE] {F0 = String}) ... ([TN = TYPE] {fn = String})){{< /fatecode >}}. - -## Examples - -{{< fatecode >}}(define_structure_type player - (creature creature) - ((list (ptr item)) inventory) - (int money) -) -{{< /fatecode >}} diff --git a/content/fate_v1/declarations/variables/_index.md b/content/fate_v1/declarations/variables/_index.md deleted file mode 100644 index 153135c..0000000 --- a/content/fate_v1/declarations/variables/_index.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Variables ---- -Variables are what hold values. Each variable has a type, which cannot be -changed. - -There are two variable scopes: local and global. A global variable can only be -declared outside of any sequence. A local variable can also be declared within a -sequence. Local variables can only be accessed within their context. In effect, -a local variable declared outside of a sequence cannot be accessed in any -sequence, and local variables cannot be accessed within lambda functions. Local -variables can override global variables within their context. - -The sole exception to accessing a local variable outside its context is done -through the use of pointers. Local variables live as long as the context -that declared them does. Accessed one through a pointer past that point is -likely to result in a runtime error and is, in any case, not to be done. - -Each sequence and lambda function defines its own context and thus does not -share local variable with the others. Instructions which themselves contain -instructions define hierarchies. Local variables defined within a hierarchical -level can be accessed in that level and inner level, but are not shared with -outer levels. For example: - -{{< fatecode >}}(if_else (var my_test) - ( - (local int my_var) ;; my_var (a) - (set my_var 32) - ) - ( - ;; my_var (a) is not defined here. - (local int my_var) ;; my_var (b) - (set my_var 42) - (if (var my_other_test) - ( - (local int my_other_var) - ;; Both my_other_var and my_var (b) are defined here - ) - ) - ;; only my_var (b) is defined here - ) -) -{{< /fatecode >}} - -Generic instruction lists do not generate a new level of hierarchy: - -{{< fatecode >}}( - (local int my_var) -) -;; my_var is still defined. -{{< /fatecode >}} - -### LOCAL VARIABLE -{{< fatecode >}}(local [TYPE] {Identifier}){{< /fatecode >}} -Declares the local variable `{Identifier}` of type `[TYPE]`. - -### GLOBAL VARIABLE -{{< fatecode >}}(global [TYPE] {Identifier}){{< /fatecode >}} -Declares the global variable `{Identifier}` of type `[TYPE]`. - -## Example -{{< fatecode >}}(local string name_of_dog) - -(global (ptr int) index_of_result) - -;; Here is an amusing use of variables: -(global int something_unexpected) -(local int something_unexpected) -;; something_unexpected will not be the same variable within processes (which -;; will use the global variable) and outside of them (which will use the local -;; variable). For code readability reasons, I do not recommend doing this. -{{< /fatecode >}} diff --git a/content/fate_v1/extensions/_index.md b/content/fate_v1/extensions/_index.md deleted file mode 100644 index 6189745..0000000 --- a/content/fate_v1/extensions/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Extensions -weight: 6 ---- -This page not available yet, sorry. diff --git a/content/fate_v1/files/_index.md b/content/fate_v1/files/_index.md new file mode 100644 index 0000000..25d818e --- /dev/null +++ b/content/fate_v1/files/_index.md @@ -0,0 +1,50 @@ +--- +title: File Management +menuTitle: Files +weight: 7 +--- +Fate narratives have one main file, but this file can use the contents of other +files, and these files in turn can also use the contents of other files. Three +issues arise then: some things must be declared before they are used, nothing +should be declared multiple times, and where are the files? + +The absolute path to each file is computed in order to detect whether it has +already been loaded. The given paths are expected to be relative. They are then +resolved by attempting access from the following, in order: the current file's +directory; the include directories passed as parameter to the executable; the +calling executable's directory. + +Dependency cycles will raise compiling errors. + +The first "instruction" on each file must be `(fate_version 1)`. Values cannot +be placed before either, obviously. + +{{< fatecode >}}(require {string}){{< /fatecode >}} + +**Effect:** If the file at `{string}` has not yet been loaded, load it. + +{{< fatecode >}}(include {string}){{< /fatecode >}} + +**Effect:** Load the `{string}`, even if it has already been loaded. + +#### Examples +* `(require bonus_sequence.fate)` +* `(include types/plant.fate)` +* `(require ../guild/merchants.fate)` +* `(include ../what/../are/../you/../doing/../there.fate)` +* `(require oh/../oh/../oh/../this_is_fine.fate)` + +Example of Fate file: +{{< fatecode >}};;; A story of great importance +(fate_version 1) + +(require include/events.fate) +(require include/text_effects.fate) + +(require scenes/the_holiday_forest.fate) + +`Twas a long time ago... Longer now that it seems... In a place that can't be +referenced here because I'm pretty sure the transcript is copyrighted. + +(jump_to not_the_tree_door_i_would_have_chosen) +{{< /fatecode >}} diff --git a/content/fate_v1/instructions/_index.md b/content/fate_v1/instructions/_index.md index 3f86e2e..21c2103 100644 --- a/content/fate_v1/instructions/_index.md +++ b/content/fate_v1/instructions/_index.md @@ -1,6 +1,6 @@ --- title: Instructions -weight: 4 +weight: 5 --- 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/notations/_index.md b/content/fate_v1/notations/_index.md index 320bdbe..a29a58b 100644 --- a/content/fate_v1/notations/_index.md +++ b/content/fate_v1/notations/_index.md @@ -1,6 +1,5 @@ --- -title: "Notations" -menuTitle: "Notations" +title: Notations weight: 1 --- diff --git a/content/fate_v1/sequences/_index.md b/content/fate_v1/sequences/_index.md new file mode 100644 index 0000000..6b2bafe --- /dev/null +++ b/content/fate_v1/sequences/_index.md @@ -0,0 +1,115 @@ +--- +title: Sequences and Procedures +menuTitle: Sequences +weight: 6 +--- +Sequences and procedures are the same thing. These are named lists of +instructions and values, which can be called upon at any point where +instructions can be used. They can take parameters. + +Procedures do not return values. It is however possible to emulate something +similar, by passing a pointer as a parameter and storing a "return" value into +it. + +These are also intended to be used to describe scenes. + +The execution of a sequence can be terminated by using the `(done)` +instruction. The execution of the narrative can be terminated by using the +`(end)` instruction. + +Any value not part of an instruction will simply be displayed when it is +reached during the procedure's execution. + +Sequences can be used before their definition, the compiler will raise an error +if the use ends up being incorrect. + +Execution of a sequence can be started in two ways: `(call sequence_name)` will +execute the sequence then continue with the execution of the current +instruction list; `(jump_to sequence_name)` will replace the current +instruction list by the execution of the sequence. If one were to ignore +variables, the `(jump_to sequence_name)` instruction is similar to performing +`(call sequence_name) (done)`. + +{{< fatecode >}}(define_sequence {String} (([C0 = TYPE] {V0 = String}) ... ([CN = TYPE] {VN = String})) [I0 = INSTRUCTIONS|VALUE] ... [IM = INSTRUCTIONS|VALUE]){{< /fatecode >}} +**Effect:** Defines the sequence `{String}`, with variables `V0` ... `VN` of types `C0` ...`CN` as parameters, and instructions `I0` ... `IM` as content. + +**Acceptable Aliases:** `declare_sequence`, `def_seq`, `define_procedure`, `declare_procedure`, `def_proc`. + +#### Examples +{{< fatecode >}}(define_sequence in_your_room () + (ifelse + (is_member visited_your_room progress) + (text_effect narrator + You room is still a mess. You don't have time to clean things up, + though. + ) + (text_effect narrator + You room is a mess. You recall having been through every drawer while + preparing your bag yesterday. While still unclear on how you are + supposed to pack all the necessary things for what promises to be at + least a year-long journey inside a small backpack, you cannot avoid + but wasting more time contemplating the piles of items that didn't + make the cut. + ) + ) + (add visited_your_room progress) + (player_choice + ( + ( Look for healing items ) + (jump_to look_for_healing_items) + ) + ( + ( No time! Let's go adventuring! ) + (jump_to leave_your_room) + ) + ) +) +{{< /fatecode >}} + +{{< fatecode >}}(define_sequence index_of_loop + ( + ((ptr int) result_holder) + ((list int) collection) + (int target) + ) + (local int collection_size) + (local int i) + + (set collection_size (size collection)) + + (for (set i 0) (< (var i) (var collection_size)) (set i (+ (var i) 1)) + (if (= (access collection (var i)) (var target)) + ( + (set (at result_holder) (var i)) + (done) + ) + ) + ) + (set (at result_holder) -1) +) +{{< /fatecode >}} + + +{{< fatecode >}}(define_sequence index_of_jump + ( + ((ptr int) result_holder) + ((list int) collection) + (int target) + (int i) + (int collection_size) + ) + (ifelse (= (var i) (var collection_size)) + (set (at result_holder) -1) + (ifelse (= (access collection (var i)) (var target)) + (set (at result_holder) (var i)) + (jump index_of_jump + (var result_holder) + (var collection) + (var target) + (+ (var i) 1) + (var collection_size) + ) + ) + ) +) +{{< /fatecode >}} diff --git a/content/fate_v1/text_effects/_index.md b/content/fate_v1/text_effects/_index.md new file mode 100644 index 0000000..63876e8 --- /dev/null +++ b/content/fate_v1/text_effects/_index.md @@ -0,0 +1,32 @@ +--- +title: Text Effects +weight: 8 +--- +Text effects are attributes that can be given to text elements. The +effects themselves can take parameters. To avoid errors that would be difficult +to detect, Tonkadur expects text effects to be declared before being used. +Note that multiple text effects can be applied to the same text elements, +so there is no need to create text effects that combine other text effects. + +Two text effects cannot have the same name, even if their parameter types +differ. + +Because text effects are handled by the interpreter, it is recommended to +overlay their use by lambda functions. This way, each interpreter can simply +expose its available text effects in a file, and the definition of the lambda +functions can thus be changed according to which interpreter is used without +having to go through the whole document. Furthermore, the name of text effects +exposed by the interpreter might not match the name that would make the most +sense to use within the narrative. + +### TEXT EFFECT +{{< fatecode >}}(declare_text_effect {Identifier} [T0 = TYPE] ... [TN = TYPE]){{< /fatecode >}} +Declares the text effect `{Identifier}`, with parameters of type `[T0]` ... +`[TN]`. + +## Examples +* `(declare_text_effect bold)` +* `(declare_text_effect speaker string)` +* `(declare_text_effect color int int int)` +* `(declare_text_effect font string)` +* `(declare_text_effect speaker_emotion string int)` diff --git a/content/fate_v1/types/_index.md b/content/fate_v1/types/_index.md new file mode 100644 index 0000000..b778383 --- /dev/null +++ b/content/fate_v1/types/_index.md @@ -0,0 +1,193 @@ +--- +title: Types +weight: 2 +--- + +Fate is a strongly typed language. All values have a well defined type. All +variables and parameters are assigned a type which cannot be changed. + +### Numbers +There are two types corresponding to numbers: `int` and `float`. + +The `int` type corresponds to an integer, which is a number *without* +fractional component. Examples of `[INT]` values include: +* {{< fatecode >}}42{{< /fatecode >}} +* {{< fatecode >}}-4{{< /fatecode >}} +* {{< fatecode >}}(+ 63 -5 1 8 9 (- 22 0 1 3)){{< /fatecode >}} +* {{< fatecode >}}(/ 3 2){{< /fatecode >}} + +The `float` type corresponds to a number *with* a fractional component. Examples +of `[FLOAT]` values include: +* {{< fatecode >}}42.0{{< /fatecode >}} +* {{< fatecode >}}69.4201773{{< /fatecode >}} +* {{< fatecode >}}(+ 63.25 9.8 0.2224 (- 0.11 0.9 .99993)){{< /fatecode >}} +* {{< fatecode >}}(/ 3.0 2.0){{< /fatecode >}} + +This documentation uses the `[NUMBER]` notation to indicate values that can +be either `[FLOAT]` or `[INT]`. + +### Booleans +The `bool` type corresponds to Booleans. This type only accepts two values: +`(true)` and `(false)`. + +Examples of `[BOOL]` values include: +* {{< fatecode >}}(true){{< /fatecode >}} +* {{< fatecode >}}(and (false) (true) (false)){{< /fatecode >}} +* {{< fatecode >}}(or (false) (true) (false)){{< /fatecode >}} +* {{< fatecode >}}(one_in (false) (true) (false)){{< /fatecode >}} + +### Texts and Strings +Things get a bit more complicated when handling texts and strings. There are two +types here `string` and `text`. + +The `string` type corresponds to string constants. Nothing can be added to a +`string` value. Its use is fairly limited. The main point of the `string` type +being that it is comparable and thus a good way to handle tags (e.g. testing +for player progress by having a set of `[STRING]` values corresponding to what +has been done so far). + +Examples of `[STRING]` include: +* {{< fatecode >}}something like this{{< /fatecode >}} +* {{< fatecode >}}日本のもの{{< /fatecode >}} +* {{< fatecode >}}لاشياء العربية{{< /fatecode >}} +* {{< fatecode >}}There are forty two (lp)42(rp) things there...{{< /fatecode >}} +* {{< fatecode >}}9 + x = 3 is an equation.{{< /fatecode >}} + +The `text` corresponds to trees of computations interpreted as text and to which +attributes can be added. In simpler terms: it's text. If the use of comparable +values is not needed, `text` is the type to use for text. +Examples of `[TEXT]` include: +* Every example of `[STRING]`. +* {{< fatecode >}}There are (+ 32 44 11 4) eggs in that basket.{{< /fatecode >}} +* {{< fatecode >}}There are (text_effect italics (+ 32 44 11 4) eggs) in that basket!{{< /fatecode >}} +* {{< fatecode >}}There are (text_effect italics (+ 32 44 11 4) (text_effect bold eggs)) in that basket!{{< /fatecode >}} +* {{< fatecode >}}(newline)- This!{{< /fatecode >}} + +### Pointers +A pointer is a value corresponding to the address of a memory element. +Accessing the value of the pointer yields the address, accessing the value +pointed to by the value of the pointer yields the memory element. Pointers +still have to point to a specific type: unlike in C, you cannot create a pointer +to an unspecified type. + +In effect, a pointer to a memory element of type `{TYPE}` is written as +`(ptr {TYPE})`. + +Examples of pointer types: +* {{< fatecode >}}(ptr int){{< /fatecode >}} +* {{< fatecode >}}(ptr (ptr int)){{< /fatecode >}} +* {{< fatecode >}}(ptr text){{< /fatecode >}} +* {{< fatecode >}}(ptr (cons int sequence)){{< /fatecode >}} + +### Collections +Collections are memory elements containing any number of elements of a given +type. Two types of collections are available in Fate: lists and sets. + +Lists are basic collections in which the order of the elements is fully +controlled by the user. The `(list {TYPE})` type indicates a list of `{TYPE}`. + +Examples of list types: +* {{< fatecode >}}(list int){{< /fatecode >}} +* {{< fatecode >}}(list (list (ptr int))){{< /fatecode >}} +* {{< fatecode >}}(list (cons (list int) (set int))){{< /fatecode >}} + +Examples of lists: +* {{< fatecode >}}(range 0 10 1){{< /fatecode >}} +* {{< fatecode >}}(add 0 1 2 3 4 (default (list int))){< /fatecode >}} +* {{< fatecode >}}(add_all (range 0 10 1) (range -10 -1 1)){{< /fatecode >}} + +Sets are collections of elements with a comparable type. The comparables types, +noted `[COMPARABLE]` are `int`, `float`, `bool`, `string`, `sequence`, `lambda`, +and `ptr`. This corresponds to types for which operators such as `<` are +defined. Sets cannot have duplicate members, and their elements are ordered in +a specific way in order to more quickly test if a value is present. the +`(set {COMPARABLE TYPE})` indicates a set of elements of type +`{COMPARABLE TYPE}`. + +Examples of set types: +* {{< fatecode >}}(set int){{< /fatecode >}} +* {{< fatecode >}}(set (lambda int (int (list text)))){{< /fatecode >}} +* {{< fatecode >}}(set string){{< /fatecode >}} + +Examples of sets: +* {{< fatecode >}}(add 6 1 4 2 900 (default (set int))){< /fatecode >}} +* {{< fatecode >}}(add_all (range 0 10 1) (set int)){{< /fatecode >}} + +### Lambda Expressions +Lambda expressions are similar to a computation that is stored for later use. +This can have different uses, such as applying the same computation on a +collection of elements or storing a recurrent computation with a value that +changes over time. + +The lambda expression itself is a computation, so it has a type (not to be +confused with the type of value returned by the expression when it is computed). + +Lambda expression types are noted +`(lambda {R = TYPE} ({A0 = TYPE} ... {AN = TYPE}))`, with `{R}` being the type +of value returned by the expression and `{A0}` ... `{AN}` being the type of +each of its parameters. + +Examples of lambda expression types: +* {{< fatecode >}}(lambda int ()){{< /fatecode >}} +* {{< fatecode >}}(lambda int (int (list text))){{< /fatecode >}} +* {{< fatecode >}}(lambda (lambda int ()) (int string)){{< /fatecode >}} + +Examples of lambda expressions: +* {{< fatecode >}}(lambda ((int i)) (+ i 1)){{< /fatecode >}} +* {{< fatecode >}}(lambda ((int i) (int j)) (max j (+ i 2))){{< /fatecode >}} +* {{< fatecode >}}(lambda + ((string s) (int i) (int j)) + (if (= (var s) zero) + 0 + (* j (+ i 2)) + ) +){{< /fatecode >}} + +### Sequences and Procedures +It is possible to use values that correspond to a sequence or a procedure. +The type `(sequence ({A0 = TYPE} ... {AN = TYPE}))` corresponds to a sequence +or procedure taking parameters of types `{A0}` ... `{AN}`. + +Examples of procedure types: +* {{< fatecode >}}(sequence ()){{< /fatecode >}} +* {{< fatecode >}}(sequence (int int)){{< /fatecode >}} +* {{< fatecode >}}(sequence (float string int)){{< /fatecode >}} + +Examples of computations returning a sequence or procedure value: +* {{< fatecode >}}(sequence my_seq_name){{< /fatecode >}} +* {{< fatecode >}}(sequence my_other_seq_name){{< /fatecode >}} + +### Common Type Groupings +* `[NUMBER]` corresponds to `[INT]` or `[FLOAT]`. +* `[COLLECTION]` corresponds to `[LIST]` or `[set]`. +* `[PRIMITIVE]` corresponds to `[INT]`, `[FLOAT]`, `[BOOL]`, `[STRING]`, + or `[TEXT]`. +* `[COMPARABLE]` corresponds to `[INT]`, `[FLOAT]`, `[BOOL]`, `[STRING]`, + `[SEQUENCE]`, `[LAMBDA]`, or `[PTR]`. + +## Defining Your Own Types + +### Aliasing +{{< fatecode >}}(declare_alias_type {TYPE} {IDENTIFIER}){{< /fatecode >}}. +**Effect:** Declares the type `{IDENTIFIER}`. + +* If `{TYPE}` is not a `[PRIMITIVE]`: `{TYPE}` and `{IDENTIFIER}` are now two + equivalent types. + +* If `{TYPE}` is a `[PRIMITIVE]`, `{IDENTIFIER}` is a subtype of `{TYPE}`. Given + `T0` and `T1` two types, such that `T1` is a subtype of `T0`, `T1` can be used + as a `T0`, but `T0` cannot be used as `T1`. + +### Structures +{{< fatecode >}}(declare_structure_type {IDENTIFIER} + ({T0 = TYPE} {F0 = IDENTIFIER}) + ... + ({TN = TYPE} {FN = IDENTIFIER}) +){{< /fatecode >}}. + +{{< fatecode >}}(define_structure_type player + (creature creature) + ((list (ptr item)) inventory) + (int money) +) +{{< /fatecode >}} diff --git a/content/fate_v1/variables/_index.md b/content/fate_v1/variables/_index.md new file mode 100644 index 0000000..a182dd0 --- /dev/null +++ b/content/fate_v1/variables/_index.md @@ -0,0 +1,73 @@ +--- +title: Variables +weight: 3 +--- +Variables are what hold values. Each variable has a type, which cannot be +changed. + +There are two variable scopes: local and global. A global variable can only be +declared outside of any sequence. A local variable can also be declared within a +sequence. Local variables can only be accessed within their context. In effect, +a local variable declared outside of a sequence cannot be accessed in any +sequence, and local variables cannot be accessed within lambda functions. Local +variables can override global variables within their context. + +The sole exception to accessing a local variable outside its context is done +through the use of pointers. Local variables live as long as the context +that declared them does. Accessed one through a pointer past that point is +likely to result in a runtime error and is, in any case, not to be done. + +Each sequence and lambda function defines its own context and thus does not +share local variable with the others. Instructions which themselves contain +instructions define hierarchies. Local variables defined within a hierarchical +level can be accessed in that level and inner level, but are not shared with +outer levels. For example: + +{{< fatecode >}}(if_else (var my_test) + ( + (local int my_var) ;; my_var (a) + (set my_var 32) + ) + ( + ;; my_var (a) is not defined here. + (local int my_var) ;; my_var (b) + (set my_var 42) + (if (var my_other_test) + ( + (local int my_other_var) + ;; Both my_other_var and my_var (b) are defined here + ) + ) + ;; only my_var (b) is defined here + ) +) +{{< /fatecode >}} + +Generic instruction lists do not generate a new level of hierarchy: + +{{< fatecode >}}( + (local int my_var) +) +;; my_var is still defined. +{{< /fatecode >}} + +### LOCAL VARIABLE +{{< fatecode >}}(local [TYPE] {Identifier}){{< /fatecode >}} +Declares the local variable `{Identifier}` of type `[TYPE]`. + +### GLOBAL VARIABLE +{{< fatecode >}}(global [TYPE] {Identifier}){{< /fatecode >}} +Declares the global variable `{Identifier}` of type `[TYPE]`. + +## Example +{{< fatecode >}}(local string name_of_dog) + +(global (ptr int) index_of_result) + +;; Here is an amusing use of variables: +(global int something_unexpected) +(local int something_unexpected) +;; something_unexpected will not be the same variable within processes (which +;; will use the global variable) and outside of them (which will use the local +;; variable). For code readability reasons, I do not recommend doing this. +{{< /fatecode >}} -- cgit v1.2.3-70-g09d2