Module `core`

Core functions.

This module provides the lower-level functionality for Jester -- storage, management of sequences, etc. Unless you're developing a module or doing something very advanced, you probably don't need to be familiar with this functionality -- it just works. :)

The Developer documentation has more information about the core functionality, and how it pertains to writing modules.

Info:

Copyright: 2011-2015 Chad Phillips
Author: Chad Phillips

Functions

bootstrap(config, profile, sequence, sequence_args)	Bootstrap the Jester environment.
init_modules(modules)	Initialize modules.
init_channel()	Initialize the channel namespace.
init_stacks(stacks)	Initialize the specified stacks.
init_profile(profile_name)	Initialize the specified profile.
init_storage(area)	Initialize a storage area.
reset_stack(name)	Empties the specified stack.
queue_sequence(sequence)	Queues a sequence to be the next one run.
load_sequence(name, arguments)	Loads the specified sequence into separate environment.
get_storage(area, key, default)	Get the value for a key in a storage area.
set_storage(area, key, value)	Set a key/value pair in a storage area.
clear_storage(area, key)	Clear a key in a storage area, or the whole storage area.
parse_sequence(sequence)	Parse a sequence.
parse_args(args)	Parse sequence arguments.
main()	Main entry point for a call to Jester.
run_sequence_loop(loop_type)	Runs the specified sequence loop.
execute_sequences()	Main loop for executing sequences.
refresh_current_sequence()	Reloads the current sequence file, refreshing all variables.
load_action()	Loads the action from the current global sequence stack and position.
set_keys(action, sequence)	Sets the key map for the specified action/sequence combination.
key_handler(session, input_type, data)	Global key handler for all key press events in Jester.
run_action(action)	Runs a loaded action.
load_action_handler(action)	Loads the correct handler for the passed action.
ready()	Determines if Jester is still in a ready state.
actionable_key()	Determines if a key was pressed that will result in some action by core.
wait(milliseconds)	Stream silence for a specified number of milliseconds.
log(msg, prefix, level)	Log to FreeSWITCH console or stdout depending on the environment.
debug_log(msg)	Conditional debug logger.
trim(s)	Trims whitespace from either end of a string.
get_variable(chan_var, default)	Wrapper to grab session variables.
set_variable(chan_var, value, default)	Wrapper to set session variables.
debug_dump(var, recursive, prefix)	Dumps values to console.

Tables

keys	Table of information for current key map.
key_pressed	Table of information for the pressed key.
channel	Internal storage for channel data.
profile	Currently loaded profile.

Fields

conf	Global configuration table.
is_freeswitch	Boolean indicating if the script was called from within FreeSWITCH.
initial_args	List of the initial arguments passed to Jester.
action_map	Lightweight map of all actions that can be called.
exiting	Boolean indicating if Jester is in the exiting state.
hungup	Boolean indicating if Jester is in the hungup state.

Functions

bootstrap(config, profile, sequence, sequence_args)

Bootstrap the Jester environment.

Parameters:

config tab The global configuration.
profile tab The profile configuration, see the {@02-Profiles.md|profile documentation}.
sequence string The sequence name to initialize with.
sequence_args string Arguments for the initial sequence.

Usage:

core.bootstrap(conf, "someprofile", "somesequence", "arg1,arg2")

init_modules(modules)

Initialize modules.

Modules and custom scripts can call this function to load additional modules.

Parameters:

modules tab List of module names to initialize.

Usage:

core.init_modules({"foo_module", "bar_module"})

init_channel()

Initialize the channel namespace.

This holds all the stacks and storage for a Jester run.

Usage:

core.init_channel()

init_stacks(stacks)

Initialize the specified stacks.

Ensures passed stacks are in their proper initial state.

Parameters:

stacks tab List of stacks to init.

Usage:

init_stacks({"run_actions", "executed_sequences"})

init_profile(profile_name)

Initialize the specified profile.

Loads the provided profile as the current active profile in Jester core.

Parameters:

profile_name string The name of the profile to load, see Profiles.

Usage:

core.init_profile("demo")

init_storage(area)

Initialize a storage area.

Parameters:

area string The name of the storage area.

Usage:

core.init_storage("foo")

reset_stack(name)

Empties the specified stack.

Can also be used to initialize a stack.

Parameters:

name string The name of the stack.

Usage:

core.reset_stack("sequence");

queue_sequence(sequence)

Queues a sequence to be the next one run.

The sequence is queued in the current sequence loop, at the current sequence stack position.

Parameters:

sequence string The full sequence name command, including arguments.

Usage:

core.queue_sequence("sub:foo_sequence arg1,arg2")

load_sequence(name, arguments)

Loads the specified sequence into separate environment.

This allows special variables to be injected in the global namespace of the sequence, as well as allowing control over which global Lua functionality is exposed.

Parameters:

name string The sequence name.
arguments tab List of passed arguments.

Returns:

The loaded sequence function if it can be loaded, nil otherwise.

Usage:

core.load_sequence("foo_sequence", {"arg1", "arg2" })

get_storage(area, key, default)

Get the value for a key in a storage area.

Parameters:

area string The storage area.
key string The storage key.
default The default value for the key if none is found in storage.

Returns:

The value stored in the key of the storage area, or the default value if none is found.

Usage:

core.get_storage("foo_area", "bar_key", "default_value")

set_storage(area, key, value)

Set a key/value pair in a storage area.

Parameters:

area string The storage area.
key string The storage key.
value The storage value.

Usage:

core.set_storage("foo_area", "bar_key", "baz_value")

clear_storage(area, key)

Clear a key in a storage area, or the whole storage area.

Parameters:

area string The storage area.
key string The storage key. If not provided, the entire storage area is cleared.

Usage:

core.clear_storage("foo_area", "bar_key")

parse_sequence(sequence)

Parse a sequence.

Parameters:

sequence string The full sequence name command, including arguments.

Returns:

sequence type, one of "subsequence", "top_sequence", "up_sequence", "".
sequence name
arguments, as a string

Usage:

core.parse_sequence("sub:foo_sequence arg1,arg2")

parse_args(args)

Parse sequence arguments.

Parameters:

args string Arguments.

Returns:

An ordered list of arguments.

Usage:

core.parse_args("arg1,arg2")

main()

Main entry point for a call to Jester.

Call this after bootstrap, to execute all sequences loops in succession.

Usage:

core.main()

run_sequence_loop(loop_type)

Runs the specified sequence loop.

Parameters:

loop_type string The sequence loop name.

Usage:

core.run_sequence_loop("active")

execute_sequences()

Main loop for executing sequences.

This loops until there are no more sequences to run. If Jester is not in the exiting or hungup state, the loop terminates when the user hangs up.

Usage:

core.execute_sequences()

refresh_current_sequence()

Reloads the current sequence file, refreshing all variables.

Usage:

core.refresh_current_sequence()

load_action()

Loads the action from the current global sequence stack and position.

Usage:

core.load_action()

set_keys(action, sequence)

Sets the key map for the specified action/sequence combination.

Parameters:

action tab The action table.
sequence tab The sequence table.

Usage:

core.set_keys(action, sequence)

key_handler(session, input_type, data)

Global key handler for all key press events in Jester.

Parameters:

session The session object.
input_type string The type of input data.
data tab The input data.

run_action(action)

Runs a loaded action.

If the action is not an ad hoc action, the global sequence stack is referenced.

Parameters:

action tab The action table.

Usage:

core.run_action(action)

load_action_handler(action)

Loads the correct handler for the passed action.

The default handler is used if none is specified.

Parameters:

action tab The action table.

Usage:

core.load_action_handler(action)

ready()

Determines if Jester is still in a ready state.

Unlike session:ready(), this ready check returns true if Jester is in either its exit or hungup states as well.

Do use this if you want to loop until Jester finishes, don't use this if you want to loop until the call hangs up.

Usage:

core.ready()

actionable_key()

Determines if a key was pressed that will result in some action by core.

Modules can call this function to check for valid key presses, to break out of loops, etc.

Usage:

core.actionable_key()

wait(milliseconds)

Stream silence for a specified number of milliseconds.

Parameters:

milliseconds int Number of milliseconds to wait.

Usage:

core.wait(1000)

log(msg, prefix, level)

Log to FreeSWITCH console or stdout depending on the environment.

Parameters:

msg string The message to log.
prefix string Prefix the message with this string.
level string Log level.

Usage:

core.log("Some message", "CUSTOM LOG", "info")

debug_log(msg)

Conditional debug logger.

Extra arguments are substituted for placeholders using string.format.

Parameters:

msg string The message to log.

Usage:

core.debug_log("Hello %s", name)

trim(s)

Trims whitespace from either end of a string.

Parameters:

s string String to trim.

Returns:

The trimmed string.

get_variable(chan_var, default)

Wrapper to grab session variables.

Parameters:

chan_var string The name of the channel variable.
default The default value for the variable if none is found on the channel.

Returns:

The value stored in the channel variable, or the default value if none is found.

Usage:

core.get_variable("some_channel_var", "default_value")

set_variable(chan_var, value, default)

Wrapper to set session variables.

Parameters:

chan_var string The name of the channel variable.
value string The value of the channel variable.
default string The default value for the variable if none is provided by the value argument.

Returns:

The value stored in the channel variable, or the default value if none is found.

Usage:

core.get_variable("some_channel_var", "some_value", "default_value")

debug_dump(var, recursive, prefix)

Dumps values to console.

Parameters:

var Variable to dump.
recursive bool Dump tables recursively. Default false.
prefix string Prefix dumped values with this string, default is no prefix.

Usage:

core.debug_dump(profile, true, "PROFILE: ")

Tables

keys

Table of information for current key map.

key_pressed

Table of information for the pressed key.

channel

Internal storage for channel data.

Stores various channel-specific data for the duration of a single call to the Jester core engine.

Fields:

stack Maintain the different stacks in Jester core.
storage Persistant storage areas.

profile

Currently loaded profile.

Set up access to channel variables, storage, global configs, and initial arguments.

Listed fields are accessible as environment-level variables from within the profile.

Fields:

global tab Global configuration.
args func Access to arguments passed when Jester was invoked.
storage func Access to storage areas.
variable func Access to FreeSWITCH channel variables.
debug_dump func Access to the debug_dump function.

Fields

conf

Global configuration table.

As configured in core.conf.

conf

is_freeswitch

Boolean indicating if the script was called from within FreeSWITCH.

is_freeswitch

initial_args

List of the initial arguments passed to Jester.

initial_args

action_map

Lightweight map of all actions that can be called.

action_map

exiting

Boolean indicating if Jester is in the exiting state.

exiting

hungup

Boolean indicating if Jester is in the hungup state.

hungup

Jester

Contents

Modules

Scripts

Topics

Examples

Module core

Info:

Functions

Tables

Fields

Functions

Parameters:

Usage:

Parameters:

Usage:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Usage:

Parameters:

Usage:

Usage:

Usage:

Usage:

Parameters:

Usage:

Parameters:

Parameters:

Usage:

Parameters:

Usage:

Usage:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Tables

Fields:

Fields:

Fields

Module `core`