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,
    line_buffer: &mut LineBuffer
) -> Result<Prompt, InklingError>

Start walking through the story while reading all lines into the supplied buffer.

Returns either when the story reached an end or when a set of choices was encountered, which requires the user to select one. Continue the story with resume_with_choice.

Notes

The input line buffer is not cleared before reading new lines into it.

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(&mut line_buffer);

assert_eq!(line_buffer.last().unwrap().text, "on the empty sky.\n");

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

Resume the story with a choice from the given set.

The story continues until it reaches a dead end or another set of choices is encountered.

Notes

The input line buffer is not cleared before reading new lines into it.

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.
";

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

if let Prompt::Choice(choices) = story.start(&mut line_buffer).unwrap() {
    story.resume_with_choice(0, &mut line_buffer);
}

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

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.

The story will not resume automatically after the move. To do this, use the resume method whenever you are ready.

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.
";

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

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

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

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

Resume the story after a move.

Starts walking through the story from the knot and stitch that the story was moved to. Works exactly like start, except that this cannot be called before the story has been started (mirroring how start cannot be called on a story in progress).

Examples

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");

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");

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);

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));

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");

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());

Trying to assign another type of variable yields an error:

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

Trait Implementations

impl Debug for Story

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

Formats the value using the given formatter.