[−][src]Struct inkling::Story
Story with knots, diverts, choices and possibly lots of text.
Methods
impl Story
[src]
pub fn start(&mut self) -> Result<(), InklingError>
[src]
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>
[src]
&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 thestart
method was called on the story.
pub fn make_choice(&mut self, selection: usize) -> Result<(), InklingError>
[src]
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>
[src]
&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>
[src]
&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>
[src]
&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>
[src]
&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>
[src]
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>
[src]
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>
[src]
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>
[src]
&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.VariableTypeChange
: if the existing variable has a different type to the input variable.
Trait Implementations
Auto Trait Implementations
impl !Sync for Story
impl Unpin for Story
impl !Send for Story
impl !UnwindSafe for Story
impl !RefUnwindSafe for Story
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,