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

Trait Implementations

impl Debug for Story

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

Formats the value using the given formatter.