Struct inkling::Story

pub struct Story { /* fields omitted */ }

Story with knots, diverts, choices and possibly lots of text.

Methods

impl Story

pub fn start(&mut self) -> Result<(), InklingError>

Mark the story as being ready to start the text flow processing.

Must be called before the first call to resume.

Examples

// From ‘A Wizard of Earthsea’ by Ursula K. Le Guin
let content = "\
Only in silence the word,
only in dark the light,
only in dying life:
bright the hawk’s flight
on the empty sky.
";

let mut story: Story = read_story_from_string(content).unwrap();
let mut line_buffer = Vec::new();

story.start();
story.resume(&mut line_buffer);

assert_eq!(line_buffer[0].text, "Only in silence the word,\n");

Errors

• StartOnStoryInProgress: if called twice for the same story.

pub fn resume(
    &mut self,
    line_buffer: &mut LineBuffer
) -> Result<Prompt, InklingError>

Resume the story text flow while reading all encountered lines into the supplied buffer.

Should be called to resume the flow after the story has been started with start, a choice was made with make_choice or the move_to method was called to change the story location.

Returns either when the story reached an end or when a set of choices was encountered, which requires the user to select one. Make a choice by calling make_choice.

Notes

This method does not clear the input line_buffer vector before reading more lines into it. Clearing that buffer has to be done by the caller.

Examples

Starting the story processing

story.start();
story.resume(&mut line_buffer);

assert_eq!(line_buffer[0].text, "Only in silence the word,\n");
assert_eq!(line_buffer[1].text, "only in dark the light,\n");
assert_eq!(line_buffer[2].text, "only in dying life:\n");
assert_eq!(line_buffer[3].text, "bright the hawk’s flight\n");
assert_eq!(line_buffer[4].text, "on the empty sky.\n");

Making a choice and resuming the flow

let content = "\
The next destination in our strenuous journey was ...
*   Rabat[]!
*   Addis Ababa[]!
";

// ... setup

line_buffer.clear();
story.make_choice(0).unwrap();
story.resume(&mut line_buffer).unwrap();

assert_eq!(&line_buffer[0].text, "Rabat!\n");

Moving to a new knot

story.move_to("mirandas_den", Some("meeting")).unwrap();
story.resume(&mut line_buffer).unwrap();

assert_eq!(&line_buffer[0].text, "Miranda was waiting in her office.\n");

Errors

• ResumeBeforeStart: if called before the start method was called on the story.

pub fn make_choice(&mut self, selection: usize) -> Result<(), InklingError>

Make a choice from a given set of options.

The selection index corresponds to the index in the list of choices that was previously returned when the branching point was reached. This list can be retrieved again by calling resume on the story before making a choice: once a choice has been successfully made, a call to resume will continue the text flow from that branch.

Examples

let content = "\
Just as Nancy picked the old diary up from the table she heard
the door behind her creak open. Someone’s coming!

*   She spun around to face the danger head on.
    Her heart was racing as the door slowly swung open and the black
    cat from the garden swept in.
    “Miao!”
*   In one smooth motion she hid behind the large curtain.
    A familiar “meow” coming from the room filled her with relief.
    That barely lasted a moment before the dusty curtains made her
    sneeze, awakening the house keeper sleeping in the neighbouring room.
";

// ... setup

if let Prompt::Choice(choices) = story.resume(&mut line_buffer).unwrap() {
    story.make_choice(0).unwrap();
    story.resume(&mut line_buffer);
}

assert_eq!(line_buffer.last().unwrap().text, "“Miao!”\n");

Errors

• MadeChoiceWithoutChoice: if the story is not currently at a branching point.

pub fn move_to(
    &mut self,
    knot: &str,
    stitch: Option<&str>
) -> Result<(), InklingError>

Move the story to another knot or stitch.

A move can be performed at any time, before or after starting the story. It simply updates the current internal address in the story to the given address. If no stitch name is given the default stitch from the root will be selected.

After moving to a new location, call resume to continue the text flow from that point.

Examples

// From ‘Purge’ by Sofi Oksanen
let content = "\
May, 1949
For the free Estonia!

=== chapter_one ===
1992, western Estonia
Aliide Truu stared at the fly and the fly stared right back at her.
";

// ... setup

// Let’s skip ahead!
story.move_to("chapter_one", None).unwrap();
story.start().unwrap();
story.resume(&mut line_buffer).unwrap();

assert_eq!(&line_buffer[0].text, "1992, western Estonia\n");

Errors

• InvalidAddress: if the knot or stitch name does not specify an existing location in the story.

pub fn get_current_location(
    &self
) -> Result<(String, Option<String>), InklingError>

Get the knot and stitch (if applicable) that the story is at currently.

Examples

let content = "\
=== gesichts_apartment ===
= dream
Gesicht wakes up from a nightmare. Something horrible is afoot.
";

let mut story = read_story_from_string(content).unwrap();
story.move_to("gesichts_apartment", None).unwrap();

let (knot, stitch) = story.get_current_location().unwrap();

assert_eq!(&knot, "gesichts_apartment");
assert_eq!(&stitch.unwrap(), "dream");

pub fn get_knot_tags(
    &self,
    knot_name: &str
) -> Result<Vec<String>, InklingError>

Get the tags associated with the given knot.

Returns an error if no knot with the given name exists in the story.

Examples

// From ‘Sanshirō’ by Natsume Sōseki
let content = "\
=== tokyo ===
# weather: hot
# sound: crowds
Tokyo was full of things that startled Sanshirō.
";

let story = read_story_from_string(content).unwrap();
let tags = story.get_knot_tags("tokyo").unwrap();

assert_eq!(&tags[0], "weather: hot");
assert_eq!(&tags[1], "sound: crowds");

Errors

• InvalidAddress: if the name does not refer to a knot that exists in the story.

pub fn get_num_visited(
    &self,
    knot: &str,
    stitch: Option<&str>
) -> Result<u32, InklingError>

Get the number of times a knot or stitch has been visited so far.

Examples

let num_visited = story.get_num_visited("depths", None).unwrap();
assert_eq!(num_visited, 2);

Errors

• InvalidAddress: if the knot or stitch name does not specify an existing location in the story.

pub fn get_story_tags(&self) -> Vec<String>

Retrieve the global tags associated with the story.

Example

let content = "\
# title: inkling
# author: Petter Johansson
";

let story = read_story_from_string(content).unwrap();

let tags = story.get_story_tags();
assert_eq!(&tags[0], "title: inkling");
assert_eq!(&tags[1], "author: Petter Johansson");

pub fn get_variable(&self, name: &str) -> Result<Variable, InklingError>

Retrieve the value of a global variable.

Examples

let content = "\
VAR books_in_library = 3
VAR title = \"A Momentuous Spectacle\"
";

let story = read_story_from_string(content).unwrap();

assert_eq!(story.get_variable("books_in_library").unwrap(), Variable::Int(3));

Errors

• InvalidVariable: if the name does not refer to a global variable that exists in the story.

pub fn get_variable_as_string(&self, name: &str) -> Result<String, InklingError>

Retrieve the value of a global variable in its string representation.

Will return an error if the variable contains a Divert value, which cannot be printed as text.

Examples

assert_eq!(&story.get_variable_as_string("title").unwrap(), "A Momentuous Spectacle");

Errors

• InvalidVariable: if the name does not refer to a global variable that exists in the story.

pub fn set_variable<T: Into<Variable>>(
    &mut self,
    name: &str,
    value: T
) -> Result<(), InklingError>

Set the value of an existing global variable.

New variables cannot be created using this method. They have to be defined in the Ink script file.

The assignment is type checked: a variable of integer type cannot be changed to contain a decimal number, a string, or anything else. An error will be returned if this is attempted.

Note that this method accepts values which implement Into<Variable>. This is implemented for integers, floating point numbers, booleans and string representations, so those can be used without a lot of typing.

Examples

Fully specifying variable type

let content = "\
VAR hunted_by_police = false
VAR num_passengers = 0
VAR price_of_ticket = 7.50
";

let mut story = read_story_from_string(content).unwrap();

assert!(story.set_variable("num_passengers", Variable::Int(5)).is_ok());

Inferring type from input

assert!(story.set_variable("price_of_ticket", 3.75).is_ok());

Invalid assignment of different type

assert!(story.set_variable("hunted_by_police", 10).is_err());

Errors

• InvalidVariable: if the name does not refer to a global variable that exists in the story.
• VariableError: if the existing variable has a different type to the input variable.

Trait Implementations

impl Debug for Story

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.