A runner to execute ink script from a story. More...

#include <runner.h>

Public Types
using	line_type = std::string

Public Member Functions
virtual void	set_rng_seed (uint32_t seed)=0
	Sets seed for PRNG used in runner.

virtual bool	move_to (hash_t path)=0
	Moves the runner to the specified path.

virtual bool	can_continue () const =0
	Can the runner continue?

virtual const char *	getline_alloc ()=0
	Continue execution until the next newline, then allocate a c-style string with the output.

virtual snapshot *	create_snapshot () const =0
	creates a snapshot containing the runner, globals and all other runners connected to the globals.

virtual line_type	getline ()=0
	Execute the next line of the script.

virtual line_type	getall ()=0
	Execute the script until the next choice or the end of the script.

virtual void	getline (std::ostream &)=0
	Gets the next line of output using C++ STL string.

virtual void	getall (std::ostream &)=0
	Gets all the text until the next choice or end.

virtual const choice *	begin () const =0
	Choice iterator.

virtual const choice *	end () const =0
	Terminal choice iterator.

virtual void	choose (size_t index)=0
	Make a choice.

virtual bool	has_tags () const =0
	Check if the current line has any tags.

virtual size_t	num_tags () const =0
	Returns the number of tags on the current line.

virtual const char *	get_tag (size_t index) const =0
	Access a tag by index.

virtual bool	has_global_tags () const =0
	Check if the there are global tags.

virtual size_t	num_global_tags () const =0
	Get Number of global tags.

virtual const char *	get_global_tag (size_t index) const =0
	Access a global tag by index.

virtual bool	has_knot_tags () const =0
	Check if there are knot/stitch tags.

virtual size_t	num_knot_tags () const =0
	Get Number of knot/stitch tags.

virtual const char *	get_knot_tag (size_t index) const =0
	Access a knot/stitch tag by index.

virtual hash_t	get_current_knot () const =0
	Get hash of current knot/stitch name.

template<typename F >
void	bind (hash_t name, F function, bool lookaheadSafe=false)
	Binds an external callable to the runtime.

template<typename F >
void	bind (const char *name, F function, bool lookaheadSafe=false)
	Binds an external callable to the runtime.

template<typename D >
void	bind_delegate (hash_t name, D functionDelegate, bool lookaheadSafe)
	bind and unreal delegate

	operator bool () const
	Shortcut for checking if the runner can continue.

bool	has_choices () const
	Checks if we're currently facing any choices.

size_t	num_choices () const
	Returns the number of choices currently available.

const choice *	get_choice (size_t index) const
	Gets a choice.

const choice *	operator[] (size_t index)
	Shorcut for accessing a choice.

Detailed Description

A runner to execute ink script from a story.

An independent runner which can execute ink script from a story independent of other runners. Think of the ink story object like an executable file and the runners as 'threads' (not to be confused with ink threads, which are a language feature). Runners track their own instruction pointer, choice list, temporary variables, callstack, etc. They can either be started with their own globals store, or can share one with other runner instances.

See also: globals; story

Member Function Documentation

◆ begin()

virtual const choice * ink::runtime::runner_interface::begin ( ) const

pure virtual

Choice iterator.

Iterates over choices the runner is currently facing.

See also: end

Returns: constant iterator to the first choice

◆ bind() [1/2]

template<typename F >

void ink::runtime::runner_interface::bind	(	const char *	name,
		F	function,
		bool	lookaheadSafe = false )

inline

Binds an external callable to the runtime.

Given a name and a callable object, register this function to be called back from the ink runtime.

Parameters

name	name string
function	callable
lookaheadSafe	if false stop glue lookahead if encounter this function this prevents double execution of external functions but can lead to missing glues

◆ bind() [2/2]

template<typename F >

void ink::runtime::runner_interface::bind	(	hash_t	name,
		F	function,
		bool	lookaheadSafe = false )

inline

Binds an external callable to the runtime.

Given a name and a callable object, register this function to be called back from the ink runtime.

beside an exact signature match, the function can also have one of the following signatures:

void(size_t argl, const ink::runtime::value* argv)

ink::runtime::value(size_t argl, const ink::runtime::value* argv) this provides a generic way to bind functions with abitrary length

Parameters

name	name hash
function	callable
lookaheadSafe	if false stop glue lookahead if encounter this function this prevents double execution of external functions but can lead to missing glues

◆ bind_delegate()

template<typename D >

void ink::runtime::runner_interface::bind_delegate	(	hash_t	name,
		D	functionDelegate,
		bool	lookaheadSafe )

inline

bind and unreal delegate

Parameters

name	hash of external function name in ink script
functionDelegate
lookaheadSafe	bind()

◆ can_continue()

virtual bool ink::runtime::runner_interface::can_continue ( ) const

pure virtual

Can the runner continue?

Checks if the runner can continue execution. If it can't, we are either at a choice or are out of content.

See also: continue; has_choices

Returns: Can continue be called

◆ choose()

virtual void ink::runtime::runner_interface::choose ( size_t index )

pure virtual

Make a choice.

Takes the choice at the given index and moves the instruction pointer to that branch.

Parameters

index index of the choice to make

◆ create_snapshot()

virtual snapshot * ink::runtime::runner_interface::create_snapshot ( ) const

pure virtual

creates a snapshot containing the runner, globals and all other runners connected to the globals.

See also: story::new_runner_from_snapshot, story::new_globals_from_snapshot

◆ end()

virtual const choice * ink::runtime::runner_interface::end ( ) const

pure virtual

Terminal choice iterator.

Pointer past the last choice the runner is currently facing.

See also: begin

Returns: end iterator

◆ get_choice()

const choice * ink::runtime::runner_interface::get_choice ( size_t index ) const

Gets a choice.

Returns the choice object at a given index

See also: num_choices

Parameters

index index of the choice to access

Returns: choice object with info on the choice

◆ get_current_knot()

virtual hash_t ink::runtime::runner_interface::get_current_knot ( ) const

pure virtual

Get hash of current knot/stitch name.

Returns: hash of current knot/stitch name

See also: ink::hash_string()

◆ get_global_tag()

virtual const char * ink::runtime::runner_interface::get_global_tag ( size_t index ) const

pure virtual

Access a global tag by index.

Global tags are placed at the top of the script instead of above or next to the current line. For tags related to the current line, use

See also: get_tag

Parameters

index tag id to fetch [0;num_global_tags())

Returns: pointer to the tag string memory or nullptr if the index is invalid

See also: has_global_tags num_global_tags get_tag get_knot_tag

◆ get_knot_tag()

virtual const char * ink::runtime::runner_interface::get_knot_tag ( size_t index ) const

pure virtual

Access a knot/stitch tag by index.

Knot stitch tags are placed at the top of a knot/stitch.

Parameters

index tag id to fetch [0;num_knot_tags())

Returns: pointor to tag string memory or nullptr if the index is invalid

See also: has_knot_tag num_knot_tags get_global_tag get_tag

◆ get_tag()

virtual const char * ink::runtime::runner_interface::get_tag ( size_t index ) const

pure virtual

Access a tag by index.

Note that this method only allows the retrieval of tags attached to the current line. For tags at the top of the script, use get_global_tag()

Parameters

index tag id to fetch [0;num_tags())

Returns: pointer to the tag string memory or nullptr if the index is invalid

See also: has_tags num_tags get_global_tag get_knot_tag

◆ getall() [1/2]

virtual line_type ink::runtime::runner_interface::getall ( )

pure virtual

Execute the script until the next choice or the end of the script.

Continue execution until the next choice or the story ends, then returns the output as an STL C++ std::string or Unreal's FString.

Returns: string with the next line of output

◆ getall() [2/2]

virtual void ink::runtime::runner_interface::getall ( std::ostream & )

pure virtual

Gets all the text until the next choice or end.

Continue execution until the next choice or the story ends, then return the output to an STL C++ std::ostream. Requires INK_ENABLE_STL

◆ getline() [1/2]

virtual line_type ink::runtime::runner_interface::getline ( )

pure virtual

Execute the next line of the script.

Continue execution until the next newline, then returns the output as an STL C++ std::string or Unreal's FString.

Returns: string with the next line of output

◆ getline() [2/2]

virtual void ink::runtime::runner_interface::getline ( std::ostream & )

pure virtual

Gets the next line of output using C++ STL string.

Continue execution until the next newline, then return the output to an STL C++ std::ostream. Requires INK_ENABLE_STL

◆ getline_alloc()

virtual const char * ink::runtime::runner_interface::getline_alloc ( )

pure virtual

Continue execution until the next newline, then allocate a c-style string with the output.

This allocated string is managed by the runtime and will be deleted at the next choose() or getline()

Returns: allocated c-style string with the output of a single line of execution

◆ has_choices()

bool ink::runtime::runner_interface::has_choices ( ) const

inline

Checks if we're currently facing any choices.

Returns: are there any choices available

◆ has_global_tags()

virtual bool ink::runtime::runner_interface::has_global_tags ( ) const

pure virtual

Check if the there are global tags.

Returns: ture if there are global tags. @info global tags are also assoziated to the first line in the knot/stitch

See also: num_global_tags get_global_tags has_tags has_knot_tags

◆ has_knot_tags()

virtual bool ink::runtime::runner_interface::has_knot_tags ( ) const

pure virtual

Check if there are knot/stitch tags.

@info knot/stitch tags are also assoziated to the first line in the knot/stitch

Returns: true if there are knot/stitch tags.

See also: num_knot_tags get_knot_tag has_global_tags has_tags

◆ has_tags()

virtual bool ink::runtime::runner_interface::has_tags ( ) const

pure virtual

Check if the current line has any tags.

Excludes global tags.

Returns: true if the line has tags, false if not

See also: num_tags get_tag has_global_tags has_knot_tags

◆ move_to()

virtual bool ink::runtime::runner_interface::move_to ( hash_t path )

pure virtual

Moves the runner to the specified path.

Clears any execution context and moves the runner to the content at the specified path.

Parameters

path	path to search and move execution to

Returns: If the path was found

◆ num_choices()

size_t ink::runtime::runner_interface::num_choices ( ) const

Returns the number of choices currently available.

Returns: number of choices

◆ num_global_tags()

virtual size_t ink::runtime::runner_interface::num_global_tags ( ) const

pure virtual

Get Number of global tags.

@info global tags are also assoziated to the first line in the knot/stitch

See also: has_global_tags get_global_tags num_knot_tags num_tags

Returns: the number of tags at the top of the document.

◆ num_knot_tags()

virtual size_t ink::runtime::runner_interface::num_knot_tags ( ) const

pure virtual

Get Number of knot/stitch tags.

@info knot/stitch tags are also assoziated to the first line in the knot/stitch

Returns: number of tags at the top of a knot/stitch

See also: has_knot_tags get_knot_tag num_global_tags num_tags

◆ num_tags()

virtual size_t ink::runtime::runner_interface::num_tags ( ) const

pure virtual

Returns the number of tags on the current line.

Excludes global tags.

See also: get_tag has_tags num_global_tags num_knot_tags

◆ operator bool()

ink::runtime::runner_interface::operator bool ( ) const

inline

Shortcut for checking if the runner can continue.

See also: can_continue

◆ operator[]()

const choice * ink::runtime::runner_interface::operator[] ( size_t index )

inline

Shorcut for accessing a choice.

See also: get_choice

Parameters

index index of the choice to access

Returns: choice object with info on the choice

◆ set_rng_seed()

virtual void ink::runtime::runner_interface::set_rng_seed ( uint32_t seed )

pure virtual

Sets seed for PRNG used in runner.

Else runner is started with the current time as seed.

Parameters

seed	seed to use for PRNG

The documentation for this class was generated from the following file:

inkcpp/include/runner.h

Public Types

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ bind() [1/2]

◆ bind() [2/2]

◆ bind_delegate()

◆ can_continue()

◆ choose()

◆ create_snapshot()

◆ end()

◆ get_choice()

◆ get_current_knot()

◆ get_global_tag()

◆ get_knot_tag()

◆ get_tag()

◆ getall() [1/2]

◆ getall() [2/2]

◆ getline() [1/2]

◆ getline() [2/2]

◆ getline_alloc()

◆ has_choices()

◆ has_global_tags()

◆ has_knot_tags()

◆ has_tags()

◆ move_to()

◆ num_choices()

◆ num_global_tags()

◆ num_knot_tags()

◆ num_tags()

◆ operator bool()

◆ operator[]()

◆ set_rng_seed()