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:

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:

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

Usage:

    core.parse_sequence("sub:foo_sequence arg1,arg2")
parse_args(args)
Parse sequence arguments.

Parameters:

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:

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
generated by LDoc 1.4.6 Last updated 2021-04-08 08:59:59