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 #

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:

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)

item.delete_attr #

item.delete_attr(expression)

item.index #

item.index

item.resultset #

item.resultset

item.set_attr #

item.set_attr(expression, value)

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

resultset.table #

resultset.table

Module: session #

session.current_table #

session.current_table()

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()

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 #

table.gsis #

table.gsis

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

Type: table_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

Module: ui #

ui.print #

ui.print(args...)

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)