====== sense ======

The sense global table contains information and utilities relevant to the environment of the executing Sense package.

===== info =====

The info field contains a [[senses:types:sense|sense]] type table containing information about the entrypoint Sense package.

===== config =====

The config field contains a function that provides access to runtime configuration values, with the ability to fall back to a default value.

==== Syntax ====

  config(name: string, fallback: any = nil): (value: any)

==== Arguments ====

  - The first argument may contain the name of the configuration value, the runtime will likely prepend a prefix or otherwise isolate the storage to prevent the package from values not intended for it.
  - The second argument may contain any arbitrary value that should be returned if the runtime does not have anything to return instead.

==== Returns ====

  - The first return value will be the configuration value provided by the runtime, or the fallback argument value.

===== dataPath =====

The dataPath field contains a function that will provide a filesystem path to a location that the Sense package may write any arbitrary data to. The root directory is ensured to exist before the path is returned, anything beyond that is under the jurisdiction of the Sense itself. Pay attention when working with subdirectories!

==== Syntax ====

  dataPath(name: string|nil = nil): (path: string)

==== Arguments ====

  - The first argument may contain an optional string value of a path to be appended to the root data path. This will also normalise the path separators (e.g. use ''\'' instead of ''/'' on Windows).

==== Returns ====

  - The first return value will be the root data path, with name argument append if it is a valid path string.

===== srcPath =====

The srcPath field contains a function that will provide a filesystem path to a location within the package directory of the entrypoint Sense package. If the name variable is specified, the target file MUST exist, otherwise an empty string is returned. The package directory is not meant to be written into, for storing data, please use dataPath() instead!

==== Syntax ====

  srcPath(name: string|nil = nil): (path: string)

==== Arguments ====

  - The first argument is an optional string value of a path to be appended to the source path. This will also normalise the path separators (e.g. use ''\'' instead of ''/'' on Windows). The path MUST exist, otherwise the return value is discarded entirely.

==== Returns ====

  - The first return value will be the source path, with name argument append if it is an existent path string.

===== vars =====

The vars field contains a table with functions providing access to non-volatile arbitrary variable storage. This is backed by an SQLite database, and is ideal for values that are on their own relatively immutable such as simple values or cache storage. For anything more involved, you should use a file at a path provided by dataPath(). Much like config values, the runtime will provide a certain form of isolation to prevent different Senses from reading each other's variables.

==== get ====

The get field contains a function that allows you to retrieve a variable from storage.

=== Syntax ===

  get(name: string): (value: any)

=== Arguments ===

  - The first argument should contain the name of the variable that is to be read.

=== Returns ===

  - The first return value will either be the value stored, or ''nil'' as a fallback.

==== changed ====

The changed field contains a function that will return the timestamp of when the value was last changed as an amount of milliseconds since January 1st, 1970 at 12:00 AM UTC.

=== Syntax ===

  changed(name: string): (timestamp: number)

=== Arguments ===

  - The first argument should contain the name of the variable that is to be dated.

=== Returns ===

  - The first return value will either be the numeric timestamp, or ''0'' if no value is stored.

==== set ====

The set field contains a function allowing you to store a value to a non-volatile variable. If a variable with the same name is already stored, it will be overwritten.

=== Syntax ===

  set(name: string, value: any): ()

=== Arguments ===

  - The first argument should contain the name of the variable that should be assigned.
  - The second argument should contain the value that should be stored. If ''nil'', this will behave the same as the delete function.

=== Returns ===

//This function does not return any values.//

==== delete ====

This field contains a function that will delete a function from non-volatile storage. If not variable with the given name exists, the call will be ignored.

=== Syntax ===

  delete(name: string): ()

=== Arguments ===

  - The first argument should contain the name of the variable that is to be deleted.

=== Returns ===

//This function does not return any values.//