...HEADmaster

4 files changed, 235 insertions, 8 deletions

diff --git a/content/wyrd_v1/computation/_index.md b/content/wyrd_v1/computation/_index.md
index d0462a0..af00546 100644
--- a/content/wyrd_v1/computation/_index.md
+++ b/content/wyrd_v1/computation/_index.md
@@ -5,6 +5,7 @@ weight: 3
 ---
 This page presents all the `<Computation>`s that can be performed in Wyrd.
 `<Computation>`s do not modify the memory, but they always return a `<Value>`.
+Be careful not to modify the memory through reference when computing values.
 
 **Shortcut to each `<Computation>`:**
 * [`(add_text_effect {name: String} {parameters: <Computation> List} {values: <Computation> list})`](#add_text_effect)
@@ -103,77 +104,195 @@ The following conversions are expected to be available:
 ### constant
 `(constant {type: String} {value: String})`
 
+Constant value.
+
 **Parameters:**
+* `type` is a `{String}` indicating the type the other parameter should be
+   converted to.
+* `value` is a `{String}` representation of the value that should be returned.
 
 **Process:**
+* Parse the value of `value` according to `type`.
+* Return the corresponding `<Value>`.
+
+**Notes:**
+The `type` parameter can take the following values: `"string"`, `"float"`,
+   `"int"`, and `"bool"`.
 
 ### get_allocable_address
 `(get_allocable_address)`
 
+Get an allocable address.
+
 **Process:**
+* Return an `<PointerValue>` corresponding to an unused address.
+
+**Notes:**
+Process when using the suggested `<State>` definition:
+* If the `<State>`'s `freed_addresses` collection has elements, return a
+`<PointerValue>` corresponding to one of its elements.
+* Otherwise, create a string `addr` corresponding to `".alloc."` to which the
+   `<State>`'s `allocated_data` integer has been added then return a new
+   `<PointerValue>` with a singleton list containing `addr`.
+As a reminder, `<State>` is not modified by the procedure.
 
 ### if_else
 `(if_else <condition: Computation> <if_true: Computation> <if_false: Computation>)`
 
 **Parameters:**
+* `condition` is a `<Computation>` that will indicate which other computation to
+   consider.
+* `if_true` is a `<Computation>` that will be considered only if the `condition`
+   is verified.
+* `if_false` is a `<Computation>` that will be considered only if the `condition`
+   is not verified.
 
 **Process:**
+* Compute the `<BoolValue>` resulting from `condition`.
+* Interpret this `<BoolValue>` as a `{Boolean}`.
+* If it yielded `TRUE`, compute and return the `<Value>` resulting from
+  `if_true`, otherwise, compute and return the `<Value>` resulting from
+  `if_false`.
 
 ### last_choice_index
 `(last_choice_index)`
 
+Get the index of the user's last chosen option.
+
 **Process:**
+* Return an `<IntValue>` corresponding to the `<State>`'s `last_choice_index`.
 
 ### newline
 `(newline)`
 
+Return a newline value.
+
 **Process:**
+* Return a `<TextValue>` corresponding to a newline.
 
 ### Unary operation
 `(operation {operator: String} <x: Computation>)`
 
-**Parameters:**
-
-**Process:**
+Interpret as `(operation operator x (BoolValue FALSE))`. It is recommended to
+have the parser do that conversion automatically.
 
 ### operation
 `(operation {operator: String} <x: Computation> <y: Computation>)`
 
+Performs a basic operation.
+
 **Parameters:**
+* `operator` is the name of the operation.
+* `x` is the first operand.
+* `y` is the second operand.
 
 **Process:**
+* Compute `<val_x: Value>` and `<val_y: Value>`, the `<Values>` corresponding to
+   `x` and `y`, respectively.
+* See the *Notes* below for which operators are expected.
+* Return the result of the operation.
+
+**Notes:**
+`val_x` and `val_y` always have the same type. If the returned value is a
+number, it has the same type as `val_x` and `val_y`. Number types are
+`<FloatValue>` and `<IntValue>`. Comparable types are `<FloatType>`,
+`<IntValue>`, `<StringType>`, `<BoolType>`, and `<PointerType>`.
+
+*Operands are numbers, returns number*:
+* `divide`, returning the value corresponding to `val_x` divided by `val_y`.
+   This is an integer division if and only if `val_x` is an integer.
+* `minus`, returning the value corresponding to `val_x` minus `val_y`.
+* `plus`, returning the value corresponding to `val_x` plus `val_y`.
+* `power`, returning the value corresponding to `val_x` to the power `val_y`.
+* `times`, returning the value corresponding to `val_x` times `val_y`.
+
+*Operands are `<IntValue>`s, returns `<IntValue>`:*
+* `modulo`, returning the value corresponding to `val_x` modulo `val_y`.
+
+*Operands are `<BoolValue>`s, returns `<BoolValue>`:*
+* `and`, returning `(BoolValue TRUE)` if both `val_x` and `val_y` are
+  `(BoolValue TRUE)`, `(BoolValue FALSE)` otherwise. Do not evaluate `val_y` if
+  `val_x` yielded `(BoolBalue FALSE)` (lazy evaluation).
+* `not`, returning `(BoolValue TRUE)` if `val_x` is `(BoolValue FALSE)`.
+   Otherwise, return `(BoolValue FALSE)`.
+
+*Operands are comparable, returns `<BoolValue>`:*
+* `less_than` returning `(BoolValue TRUE)` if `val_x` is less than `val_y` and
+  `(BoolType FALSE)` otherwise.  `(BoolType FALSE)` is less than
+  `(BoolType TRUE)`. `<PointerValue>`s can be compared by comparing the strings
+  corresponding to having joined all elements in their respective string lists.
+
+*Operands can be any type, returns `<BoolValue>`:*
+* `equals` returns `(BoolValue TRUE)` if `val_x` has the same value as `val_y`,
+  `(BoolType FALSE)` otherwise.  Be sure to compare values and not identity
+  (value vs reference).
 
 ### relative_address
 `(relative_address <target: Computation> <extra: Computation>)`
 
+Appends to an address.
+
 **Parameters:**
+* `target` is a `<Computation>` that will yield the base address to extend.
+* `extra` is a `<Computation>` corresponding to the `<StringValue>` element to
+  add to the address.
 
 **Process:**
+* Compute the `<PointerValue>` corresponding to `target`.
+* Compute the `<StringValue>` corresponding to `extra`.
+* Return a new `<PointerValue>` corresponding to the previous `<PointerValue>`,
+   but with its list of strings now having been extended by the addition of the
+   string equivalent to that `<StringValue>`.
 
 ### size
 `(size <target: Computation>)`
 
+Computes the size of a list.
+
 **Parameters:**
+* `target` is a `<Computation>` that will yield a `<PointerValue>` pointing to
+   a `<ListValue>`.
 
 **Process:**
+* Compute the `<PointerValue>` yielded by `target`.
+* Return a new `<IntValue>` corresponding to the number of elements in the
+   `<ListValue>` pointed to by that `<PointerValue>`.
 
 ### text
 `(text {values: <Computation> List})`
 
+Merges a list of text values into a single one.
+
 **Parameters:**
+* `values` is a list of `<Computation>`s that will yield `<TextValue>`s.
 
 **Process:**
+* Compute the `<Value>` corresponding ot each element of `values`.
+* Return a new `<TextValue>` corresponding to these `<Values>` appended one
+  after the next.
 
 ### value_of
 `(value_of <target: Computation>)`
 
+Retries the value from memory.
+
 **Parameters:**
+* `target` is a `<Computation>` that will yield the address of the memory
+   element to get the value of.
 
 **Process:**
+* Compute the value of `target`.
+* Return the `<Value>` pointed to by `target` in the `<State>`'s `memory`.
 
 ### extra_computation
 `({extra_computation} {parameters: <Computation> List})`
 
+Performs non-standard computation.
+
 **Parameters:**
+* `extra_computation` is the name of the extra computation.
+* `parameters` is a list of parameters for this computation call.
 
 **Process:**
+* Undetermined. This is where you choose the process according to the value of
+   `extra_computation` so that you can add non-standard computations.
diff --git a/content/wyrd_v1/input/_index.md b/content/wyrd_v1/input/_index.md
index d6bbc87..bc5b22f 100644
--- a/content/wyrd_v1/input/_index.md
+++ b/content/wyrd_v1/input/_index.md
@@ -3,3 +3,71 @@ menuTitle: <Input>
 title: Input
 weight: 6
 ---
+
+Following an `<Instruction>` having set the `<State>`'s
+`last_instruction_effect` to
+`(MUST_PROMPT_COMMAND <IntValue> <IntValue> <TextValue>)`,
+`(MUST_PROMPT_INTEGER <IntValue> <IntValue> <TextValue>)`,
+`(MUST_PROMPT_FLOAT <FloatValue> <FloatValue> <TextValue>)`,
+`(MUST_PROMPT_STRING <IntValue> <IntValue> <TextValue>)`,
+or `(MUST_INPUT_CHOICE)`, it is necessary
+for the user to provide an input prior to further `<Instruction>`s being
+executed.  The information provided in the `<InstructionResult>` is expected
+to be sufficient for the interpreter to ensure the user input is valid.
+Providing invalid inputs to the `<State>` will result in undefined (and most
+likely problematic) behaviors.
+
+Thus, the `<State>` should expect to accept the following types of inputs:
+### An `{Integer}` prompt answer
+This follows a
+`(MUST_PROMPT_INTEGER <IntValue> <IntValue> <TextValue>)`
+`<InstructionResult>`.
+* Interpret the `<State>`'s `memorized_target` as a
+   `<PointerValue>` address.
+* Update the `<Value>` pointed to by this address in the `<State>`'s memory
+   so that it becomes an `<IntValue>` corresponding to the user's input.
+* Set the `<State>`'s `last_instruction_effect` to `(MUST_CONTINUE)`.
+* Proceed with the execution.
+
+### A `{Float}` prompt answer
+This follows a
+`(MUST_PROMPT_FLOAT <FloatValue> <FloatValue> <TextValue>)`
+`<InstructionResult>`.
+* Interpret the `<State>`'s `memorized_target` as a
+   `<PointerValue>` address.
+* Update the `<Value>` pointed to by this address in the `<State>`'s memory
+   so that it becomes an `<FloatValue>` corresponding to the user's input.
+* Set the `<State>`'s `last_instruction_effect` to `(MUST_CONTINUE)`.
+* Proceed with the execution.
+
+### A `{String}` prompt answer
+This follows a
+`(MUST_PROMPT_STRING <IntValue> <IntValue> <TextValue>)`
+`<InstructionResult>`.
+* Interpret the `<State>`'s `memorized_target` as a
+   `<PointerValue>` address.
+* Update the `<Value>` pointed to by this address in the `<State>`'s memory
+   so that it becomes an `<StringValue>` corresponding to the user's input.
+* Set the `<State>`'s `last_instruction_effect` to `(MUST_CONTINUE)`.
+* Proceed with the execution.
+
+### A `{{String} List}` prompt answer
+This follows a
+`(MUST_PROMPT_COMMAND <IntValue> <IntValue> <TextValue>)` `<InstructionResult>`.
+* Interpret the `<State>`'s `memorized_target` as a
+   `<PointerValue>` address.
+* Convert the user input to a `<ListValue>`: For each element of value
+`{s: String}` and index `{i: Integer}`, the `<ListValue>` contains
+`{{c_i: String} -> <c_s: StringValue>}` where `c_i` is a `{String}`
+corresponding to `i` and `c_s` a `<StringValue>` corresponding to `s`.
+* Update the `<Value>` pointed to by this address in the `<State>`'s memory
+   so that it becomes the aforementioned `<ListValue>`.
+* Set the `<State>`'s `last_instruction_effect` to `(MUST_CONTINUE)`.
+* Proceed with the execution.
+
+### An `{Integer}` choice answer
+This follows a `(MUST_INPUT_CHOICE)` `<InstructionResult>`.
+* Set the `<State>`'s `last_choice_index` to the input `{Integer}`.
+* Empty the `<State>`'s `available_options` list.
+* Set the `<State>`'s `last_instruction_effect` to `(MUST_CONTINUE)`.
+* Proceed with the execution.
diff --git a/content/wyrd_v1/instruction_result/_index.md b/content/wyrd_v1/instruction_result/_index.md
index b77b496..ac585fc 100644
--- a/content/wyrd_v1/instruction_result/_index.md
+++ b/content/wyrd_v1/instruction_result/_index.md
@@ -3,3 +3,38 @@ menuTitle: <InstructionResult>
 title: Instruction Result
 weight: 5
 ---
+Following the execution of an `<Instruction>`, the `<State>` will see its
+`last_instruction_effect` be set to one of the following values:
+
+* `(MUST_CONTINUE)`, indicating that the next `<Instruction>` should be
+  executed.
+* `(MUST_END)`, indicating that the story has ended. No further `<Instruction>`s
+   should be executed.
+* `(MUST_PROMPT_COMMAND <min: IntValue> <max: IntValue> <msg: TextValue>)`,
+   indicating that an input should be given before executing further
+   `<Instruction>`s. In this case, the execution should be done only after the
+   user has seen `msg` and input a command (space separated list of strings)
+   totaling between `min` and `max` characters (spaces included).
+* `(MUST_PROMPT_FLOAT <min: FloatValue> <max: FloatValue> <msg: TextValue>))`,
+   indicating that an input should be given before executing further
+   `<Instruction>`s. In this case, the execution should be done only after the
+   user has seen `msg` and input a float value included between `min` and `max`.
+* `(MUST_PROMPT_INTEGER <min: IntValue> <max: IntValue> <msg: TextValue>))`,
+   indicating that an input should be given before executing further
+   `<Instruction>`s. In this case, the execution should be done only after the
+   user has seen `msg` and input an integer value included between `min` and
+   `max`.
+* `(MUST_PROMPT_STRING <min: IntValue> <max: IntValue> <msg: TextValue>)`
+   indicating that an input should be given before executing further
+   `<Instruction>`s. In this case, the execution should be done only after the
+   user has seen `msg` and input a string totaling between `min` and `max`
+   characters.
+* `(MUST_PROMPT_CHOICE)`
+   indicating that an input should be given before executing further
+   `<Instruction>`s. In this case, the execution should be done only after the
+   user has chosen an option between the ones listed in the `<State>`'s
+   `available_options`.
+* `(MUST_DISPLAY <msg: TextValue>)`, indicating that `msg` should be displayed
+   before further `<Instruction>`s are executed.
+* `(MUST_DISPLAY_ERROR <msg: TextValue>)`, indicating that `msg` should be
+   displayed as an error message before further `<Instruction>`s are executed.
diff --git a/content/wyrd_v1/value/_index.md b/content/wyrd_v1/value/_index.md
index 18e2a6a..8ff8290 100644
--- a/content/wyrd_v1/value/_index.md
+++ b/content/wyrd_v1/value/_index.md
@@ -4,8 +4,13 @@ title: Value
 weight: 4
 ---
 
-`{Integer}` and `{Float}` are meant to represent the largest available integer
-and float point value types available in the interpreter's language. This is not
-mandatory, but be especially wary of using too small a type for `{Integer}`, as
-the `<State>` `program_counter` value will need to be able to be as big as there
-are instructions in the program.
+This page describes the types of values used in Wyrd.
+
+Note that `{Integer}` and `{Float}` are meant to represent the largest available
+integer and float point value types available in the interpreter's language.
+This is not mandatory, but be especially wary of using too small a type for
+`{Integer}`, as the `<State>` `program_counter` value will need to be able to
+be as big as there are instructions in the program.
+
+{{< svg "static/images/wyrd_values.drawio.svg" "500px" >}}
+