Script API

Script API #

Module: ext #

Provides access to the extension points scripts can used to extend the functionality of Dynamo-Browse.

This module is only available for scripts loaded using the load-script command.

ext.command #

ext.command(name, fn)

Defines a new command, which can be invoked by entering name within the main view mode. The parameter fn must be a function, which will be executed when the name command is entered while in view mode.

The command can accept arguments, which will be passed in to the parameters of fn. The number of command arguments must match the number of parameters, except for any function arguments with a default value.

Example

ext.command("add", func(x, y) {
  sum := x + y
  ui.print("x + y = ", sum)
})

ext.key_binding #

ext.key_binding(name, options, fn)

Defines a new key binding, which can be invoked while viewing the table.

The name parameter defines the binding name. The binding names will be prefixed with ext.<script_basename>. This name can be used with the rebind command.

The option parameter defines a map of options. The only valid option is default, which is the default key to use for this binding. If unset, the binding will have no key binding and can only be bound using the rebind command.

The fn parameter is the function that will be invoked when the key is pressed. It must accept no parameters.

Example

// Script name: sayhello.tm
//
// This binding can be rebound with the command "rebind ext.sayhello.hello <key>"
ext.key_binding("hello", {"default": "H"}, func() {
  ui.print("Hello")
})
ext.related_items(table, fn)

Defines a “related item” for a table. These act as quick jumps between tables. When the user presses Shift+O, all the related item functions that match the given table will be evaluated. Each one is to return zero or more related queries, which are presented to the user as a list. When the user selects one, the query will be evaluated and the result set will be shown.

The table parameter is the name of the table of the related items managed by this function. If the last character of the table is *, then table will be treated as a name prefix.

The fn will produce a list of queries that are related to a given item. The function takes the currently selected item as the argument, and is expected to produce a list of maps, with each map having the following fields:

  • label: The label to use for the picker option
  • query: The query expression that will run when the option is chosen
  • table: The table to run the query over. If not set, the current table will be used
  • args: A map of query placeholder values
  • on_select: An optional function that will run in place of a predefined query. If set, the query field will be ignored.

Example

ext.related_items("user-account", func(item) {
  return [
    {
      "label": "Customer",
      "table": "billing",
      "query": "email=$email",
      "args": {"email": item.attr("email")},
    },
  ]
})	    

Type: item #

A single record from a DynamoDB table.

Item values are converted to tamarin types using the following:

Attribute Type Tamarin Type
S string
N int, float [1]
BOOL bool
NULL nil
L list
M map
SS set, with string values
NS set, with number values

Notes:

  • [1]: int will be used if the value can be parsed as an integer, otherwise it will be returned as a float.
  • Byte array (B or BS) values are currently not supported.

item.attr #

item.attr(expression)
Returns the attribute value from the query expression.

item.delete_attr #

item.delete_attr(expression)
Delete the attribute.

item.index #

item.index
Returns the index of this item within the result set.

item.resultset #

item.resultset
Returns the result-set this item is a member of.

item.set_attr #

item.set_attr(expression, value)
Sets the value of the attribute.

Type: resultset #

Holds a collection of items returned from a query, or presented to a user.

A specific item of a result-set can be retrived using the subscript option. For example, result[21] will return the 21st item of the result-set from the first item. A negative index can be used to retrieve an item from the last item.

There is no guarantee to the ordering of items within the result-set, although items are usually ordered based on the partition and sort key.

resultset.length #

resultset.length
Returns the number of items within the result set.

resultset.table #

resultset.table
Returns information about the table this result set belongs to.

Module: session #

Provides access to the currently viewed table and result-set.

session.current_table #

session.current_table()
Returns information about the currently displayed table. This will be returned as a table object. If no table is displayed, this function will return nil.

session.query #

session.query(expression, [options])

Executes a query against a DynamoDB table. This returns a resultset if the query was successful. A query with no results will be an empty result-set.

The expression is the query expression to execute. This is similar to the type of expressions entered after pression ?.

The options map can contain the following key/value pairs:

  • table: the DynamoDB table to execute the query against. Default is the currently displayed table.
  • args: A map containing names and values that can be used as placeholders in the query expression.

Example

out := session.query("pk = $key", {
  table: "some-table",
  args: {
    key: "my partition key"
  }
}
session.set_result_set(out.unwrap())

session.resultset #

session.resultset

Returns the currently displayed result set. This is the set of items that are shown to the user in the items table. This will be returned as a resultset object.

Note that this only contains the items of the current result set that exists in memory. As such, it will be capped to the configured query limit.

session.selected_item #

session.selected_item()
Returns the item currently highlighted in the items table. This will be returned as an item object. If no item is highlighted, it will return nil.

session.set_result_set #

session.set_result_set(new_result_set)

Replaces the currently displayed result-set with a new one. This can be used alongside the query function to display the results of a query.

Changing the displayed result-set will trigger a redraw of the viewport and will push a new history record to the backstack. Therefore, it’s not recommended to call this method too often during a script execution session. At most once with the final result-set you’d like to show the user is considered best practice.

Type: table #

Provides information about a DynamoDB table.

table.gsis #

table.gsis
Returns a list of the GSIs used by this table. The elements of the list will have the type table_index

table.keys #

table.keys

Returns the keys of the table. This will be returned as a map with the following names:

  • hash: the attribute name of the partition (hash) key
  • range: the attribute name of the sort (range) key, or nil if one is not defined.

table.name #

table.name
Returns the name of the table.

Type: table_index #

Provides information about an DynamoDB index.

table_index.keys #

table_index.keys

Returns the keys of the index. This will be returned as a map with the following names:

  • hash: the attribute name of the partition (hash) key
  • range: the attribute name of the sort (range) key, or nil if one is not defined.

table_index.name #

table_index.name
Returns the name of the index.

Module: ui #

Provides control over the user interface.

ui.print #

ui.print(args...)
Displays a message in the status bar.

ui.prompt #

ui.prompt(message)

Request a line of input from the user, using message as the prompt.

This function will return the user’s input as a string, or nil if the user cancels the prompt by pressing Esc

Example

line := ui.prompt("What is your name? ")
ui.print("Hello, ", line)