cmd/dynamo-browse
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions

Added site to this repo and Gitlab to build it

Browse source
This commit is contained in:
Leon Mika 2025-10-26 09:25:36 +11:00
parent 8dafa6fa8f
commit c474b18232
50 changed files with 1812 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

150
_site/content/docs/reference/commands.md Normal file
View file

@ -0,0 +1,150 @@
# Commands
## clone
```
:clone
```
Copies the currently selected item to a new item, which will appear at the bottom of the table.
Cloning an item will prompt for a new partition key and sort key but will not check for duplicates.
## del-attr
```
:del-attr <attribute>
```
Alias: `da`
Deletes _attribute_ from the currently selected item; or if there are any marked items, the marked items.
## delete
```
:delete
```
Deletes the marked items. Unlike the other commands that modify items, this command will be executed on
the table straight away.
## echo
```
:echo [message ...]
```
Displays _message_ in the status bar. Mainly used for debugging.
## export
```
:export [-all] <filename>
```
Writes the currently loaded items as a CSV file to _filename_.
Only string, numerical, and boolean values will be written to the export; all other value types will be
black. Exporting will honour the columns currently visible in the table. Filtered items will also be included
in the exported file.
When called with the `-all` flag, any subsequent pages will be included in the export. If invoked after running
a query, all items returned from that query will be exported to file.
## mark
```
:mark [all | none | toggle] [-where <expr>]
```
Mark the rows in the following way:
- `all`: will mark all rows. This is the default when invoked without an argument.
- `none`: will unmark all rows.
- `toggle`: will toggle all marked and unmarked rows.
Adding the `-where` option would only select rows that match the given query expression.
## new-item
```
:new-item
```
Creates a new item. When executed, the value for the partition key and sort key will be prompted.
The new item will not be written to the table until it is committed with the `put` command.
## put
```
:put
```
Alias: `w`
Commits all new and modified items to the table.
## quit
```
:quit
```
Alias: `q`
Quits Dynamo-Browse.
## rebind
```
:rebind <bindingName> <key>
```
Rebinds the action with _bindingName_ to _key_. This will replace any existing binding for that action.
See [Key Bindings](#key-bindings) with "Show binding names" checked to see available binding names.
## set
```
:set <name> [value]
```
Set the value of a setting. Flag setting types can be enabled without any value. See [Settings](#settings) for possible setting values.
## set-attr
```
:set-attr [type] <attributeName>
```
Alias: `sa`
Modifies the value of _attribute_ of the currently selected item; or if there are any marked items, the marked items.
The value of _type_ can be use to specify the type of the attribute. It can be one of the following (case insensitive):
- `-S`: string value
- `-N`: number value
- `-BOOL`: boolean value
- `-NULL`: null value
- `-TO`: value of an expression
If unset, the attribute type will not be changed. _type_ must be set if multiple items have been marked.
## table
```
:table
```
Select the table to display.
## unmark
```
:unmark
```
Unmark all marked items. This is essentially an alias for `mark none`.

189
_site/content/docs/reference/key-bindings.md Normal file
View file

@ -0,0 +1,189 @@
# Key Bindings
<div data-controller="keybindings">
<label>
<input type="checkbox" id="show-kb-binding-names"
data-keybindings-target="showBindingNames" data-action="keybindings#bindingNamesChanged"> Show binding names
</label>
<table class="key-bindings" data-keybindings-target="keyBindingTable">
<thead>
<tr>
<th class="kb-key-binding" style="text-align:left">Key</th>
<th class="kb-binding-name" style="text-align:left">Binding Name</th>
<th style="text-align:left">Action</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="2">Main View Mode</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&uarr;</kbd>/<kbd>i</kbd></td>
<td class="kb-binding-name">table.move-up</td>
<td>Move selection up</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&darr;</kbd>/<kbd>k</kbd></td>
<td class="kb-binding-name">table.move-down</td>
<td>Move selection down</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>PgUp</kbd>/<kbd>&#8679;I</kbd></td>
<td class="kb-binding-name">table.page-up</td>
<td>Page up</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>PgDn</kbd>/<kbd>&#8679;K</kbd></td>
<td class="kb-binding-name">table.page-down</td>
<td>Page down</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>Home</kbd>/<kbd>0</kbd></td>
<td class="kb-binding-name">table.goto-top</td>
<td>Move selection to first item</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>End</kbd>/<kbd>$</kbd></td>
<td class="kb-binding-name">table.goto-bottom</td>
<td>Move selection to last item</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&larr;</kbd>/<kbd>j</kbd></td>
<td class="kb-binding-name">table.move-left</td>
<td>Scroll displayed columns left</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&rarr;</kbd>/<kbd>l</kbd></td>
<td class="kb-binding-name">table.move-right</td>
<td>Scroll displayed columns right</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>Backspace</kbd></td>
<td class="kb-binding-name">view.view-back</td>
<td>Go back</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>\</kbd></td>
<td class="kb-binding-name">view.view-forward</td>
<td>Go forward</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>w</kbd></td>
<td class="kb-binding-name">view.cycle-layout-forward</td>
<td>Cycle forward through layout</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&#8679;W</kbd></td>
<td class="kb-binding-name">view.cycle-layout-backwards</td>
<td>Cycle backwards through layout</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>m</kbd></td>
<td class="kb-binding-name">view.mark</td>
<td>Mark/unmark currently selected item</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>M</kbd></td>
<td class="kb-binding-name">view.toggle-marked-items</td>
<td>Toggle marked/unmarked items</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>c</kbd></td>
<td class="kb-binding-name">view.copy-item-to-clipboard</td>
<td>Copy displayed item to pasteboard</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>C</kbd></td>
<td class="kb-binding-name">view.copy-table-to-clipboard</td>
<td>Copy displayed table to pasteboard as a CSV</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>/</kbd></td>
<td class="kb-binding-name">view.prompt-for-filter</td>
<td>Filter</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>?</kbd></td>
<td class="kb-binding-name">view.prompt-for-query</td>
<td>Run scan/query</td>
</tr>
<tr class="kb-binding-name">
<td class="kb-key-binding"></td>
<td class="kb-binding-name">view.prompt-for-table</td>
<td>Select table</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>R</kbd></td>
<td class="kb-binding-name">view.rescan</td>
<td>Rerun last scan/query</td>
</tr>
<tr class="kb-binding-name">
<td class="kb-key-binding"><kbd>&gt;</kbd></td>
<td class="kb-binding-name">view.fetch-next-page</td>
<td>Fetch the next page of results</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>:</kbd></td>
<td class="kb-binding-name">view.prompt-for-command</td>
<td>Enter command</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>f</td>
<td class="kb-binding-name">view.show-fields-popup</td>
<td>Show fields popup</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>^C</kbd></td>
<td class="kb-binding-name">view.cancel-running-job</td>
<td>Cancel running operation</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>^C</kbd>/<kbd>Esc</kbd></td>
<td class="kb-binding-name">view.quit</td>
<td>Quit</td>
</tr>
<tr>
<td colspan="2">Field Popup Mode</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&#8679;I</kbd></td>
<td class="kb-binding-name">fields-popup.shift-column-left</td>
<td>Shift selected column left</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&#8679;K</kbd></td>
<td class="kb-binding-name">fields-popup.shift-column-right</td>
<td>Shift selected column right</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>Space</kbd></td>
<td class="kb-binding-name">fields-popup.toggle-column-visible</td>
<td>Toggle selected column visible</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>a</kbd></td>
<td class="kb-binding-name">fields-popup.add-column</td>
<td>Add new column</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>d</kbd></td>
<td class="kb-binding-name">fields-popup.delete-column</td>
<td>Delete selected column</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>&#8679;R</kbd></td>
<td class="kb-binding-name">fields-popup.reset-columns</td>
<td>Reset columns to that of the result-set</td>
</tr>
<tr>
<td class="kb-key-binding"><kbd>^C</kbd>/<kbd>Esc</kbd></td>
<td class="kb-binding-name">fields-popup.close</td>
<td>Close field popup</td>
</tr>
</tbody>
</table>
</div>

49
_site/content/docs/reference/launch-flags.md Normal file
View file

@ -0,0 +1,49 @@
# Launch Flags
## -debug
```
-debug <filename>
```
Enable debug logs, which will be written to _filename_.
## -default-limit
```
-default-limit <int>
```
Sets the default limit of queries or scans. The default is 1,000 items.
## -local
```
-local [host]:<port>
```
Connect to a local DynamoDB service listening on _host_:_port_. The default _host_ is `localhost`.
## -ro
```
-ro
```
Enable read-only mode.
## -t
```
-t <tableName>
```
Open the table _tableName_, instead of prompting for a table.
## -w
```
-w <workspaceFile>
```
Use _workspaceFile_ as the workspace file. If unset, a temporary file will be used for the workspace.

251
_site/content/docs/reference/query-expressions.md Normal file
View file

@ -0,0 +1,251 @@
# Query Expression
Query expressions are used to select rows of a table. When executed as a query (i.e. by pressing <kbd>?</kbd>),
they will be translated into query or table scans that will run over the DynamoDB table in AWS.
They work similar to the "where" clause in PartiQL except that they only require Query and Scan permission
on the AWS table and do not require "select" clauses.
Such expressions can also be used in other areas of Dynamo-Browse, such as populating the value of new columns.
## Names And Values
A query expressions support the following literals:
- Strings: `"Hello"`
- Integers: `123`
- Boolean: `true` or `false`
Field names are represented as regular identifiers, such as `pk` or `address`.
## Equality
To select rows with a field that equals a given value, use the `=` operator:
```
pk = "something"
```
Either operand will can be an identifier, placeholder, or value that resolves to any type.
The result will be true if both the LHS and RHS equal the same type and value. If the types differ or
the values differ, the result will be false. The field types can be different, but will always produce false.
The compliment is the `!=` operator:
```
pk != "not this"
```
## Numerical Comparison
The operands `<`, `<=`, `>`, `>=` can be used to compare numerical fields and values:
```
three < 5 // true
three <= 3 // true
three > 12 // false
three >= 1 // true
```
To verify that a number exists within a range, use the `between` operand:
```
three between 1 and 5 // true
```
## Prefix Operator
To select rows with a field that starts with a given substring, use the `^=` operator:
```
pk ^= "some"
```
This is equivalent to using the [begins_with](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html) function in AWS query expressions.
## Logical Operators
The logical operators `and`, `or` and `not` can be used to express conjunctions, disjunctions and logical negation
between multiple expressions:
```
pk = "this" and sk = "that"
pk != "that" and count > 123
not count = 21
```
The order of precedence of these operators, from lowest to highest, is `or`, `and`, then `not`. This differs
from AWS, in which all operators have the same precedence. For example, the query:
```
pk="this" or pk="that" and sk="foo"
```
is equivalent to:
```
pk="this" or (pk="that" and sk="foo")
```
The order can be overridden using brackets:
```
(pk="this" or pk="that") and sk="foo"
```
{{< hint info >}}
If a query expression is of the form `pk = <val>` or `pk = <val> and sk <op> <val>`,
where:
- _pk_ and _sk_ are the partition and sort keys of the base table or a GSI,
- _val_ resolves to a constant value, and,
- _op_ is either `=`, `^=`, `<`, `<=`, `>`, `>=`, or `between`
the expression will be executed as a Query call. Unlike expressions on the AWS Query API method itself,
the order of the `pk` and `sk` subexpressions can be swapped.
Other expressions are supported but they will be executed as a table Scan.
{{< /hint >}}
## The `in` Operator
The `in` operator can be used to determine if a value exists in a collection:
```
three in (1, 2, 3, 4, 5)
name in ("Tom", "Dick", "Harry")
```
The result will be a boolean, which will be true if the value of the LHS equals any of the items within the RHS.
The collection can be one or more fixed set of values within parenthesis separated by commas. A single
value present within parenthesis is equivalent to the equality test:
```
three in (3) // equivalent to: three = 3
```
The right hand side can also be a subexpression without parenthesis that will resolve to either a string,
list or map. The operand will behave differently based on the RHS type:
- If the RHS is a string, the result will be true if the LHS is a substring of the RHS (equivalent to the `contains` AWS conditional expressions function)
- If the RHS is a list, the result will be true if the LHS equals any of the items of the list
- If the RHS is a map, the result will be true if the LHS appears as a key of the map
The compliment operand is `not in`:
```
three not in (6, 7, 8, 9)
```
## The `is` Operator
The `is` operator can be used to assert the value type. The RHS operand is a string which is to represent an AWS
DynamoDB item attribute type, for example `S` for strings, `N` for numbers, etc.
```
"hello" is "S" // true
123 is "N" // true
"hello" is "N" // false
```
This is equivalent to the `attribute_type` AWS conditional expressions function.
The special value `any` can be used to check that a field is set, regardless of type:
```
pk is "any" // true
```
This is equivalent to the `attribute_exists` AWS conditional expressions function.
The compliment operand is `not is`. Using it with the "any" special value (`not is "any"`) is equivalent to the
`attribute_not_exists` AWS conditional expressions function.
## The `using` Options
A query that is to be executed on the actual table in AWS will go though a short planning phase to determine
whether it's possible to invoke the expression as a `Query` call. If the attributes map to partition and sort keys
of either the main table, or exactly one GSI associated with the table, the expression will be executed as a Query
over the table or the GSI found with those attributes.
In cases where multiple GSI candidates exist on the base table, the query will fail with the following error:
```
multiple plans with index found. Specify index or scan with 'using' clause
```
In these cases, the index will need to be specified with the `using` keyword with the `index` option:
```
address="something" using index("specific-gsi-name")
```
The `using` keyword can also be used to force the expression to run as a table scan,
even if the query can be invoked using a Query call over the base table or GSI:
```
address="something" using scan
```
## Builtin Functions
Query expressions support a number of builtin functions.
### The `marked` function
```
marked(fieldname)
```
The `marked` function will return a list of field values of all marked rows of the current result set. The
items will appear in the list as they appear in the result set. The _fieldname_ currently only supports top-level fields.
If no fields are marked, the empty list is returned.
```
marked("city")
```
### The `range` function
```
range(from, to)
```
The `range` function will return a list of integers between _from_ and _to_ inclusive. Non integers will be truncated
to integers, and the step is always be 1.
```
range(2, 5) // [2, 3, 4, 5]
three in range(2, 5) // true
```
### The `size` function
```
size(v)
```
The `size` function will return the number of items of a list or map, or the length of a string.
{{< hint info >}}
The `size` function is equivalent to the `size` AWS conditional expressions function, and as such is the
only function that is included as is in the generated Query or Scan expression. All other functions are evaluated
prior to making the Query or Scan AWS call.
{{</hint>}}
## Placeholders
In some circumstances, such as the [session.query](/docs/reference/script-api/#session-query) method, it's possible to use a placeholder as a field or value. To expand a placeholder to an identifier, use the `:` prefix. To expanded the placeholder as a value, use the `$` prefix. For example, the expression `:key = $value` in the following script:
```
out := session.query(":key = $value", {
table: "some-table",
args: {
key: "pk",
value: "value"
}
}
```
Is equivalent to the query `pk = "hello"`, as the placeholder `:key` is expanded to an identifier and `$value` is expanded
to a value, in this case a string.

5
_site/content/docs/reference/script-api.md Normal file
View file

@ -0,0 +1,5 @@
---
title: "Script API"
type: script-api
---
# Script API

21
_site/content/docs/reference/settings.md Normal file
View file

@ -0,0 +1,21 @@
# Settings
## default-limit
- Type: int
- Default: `1000`
The maximum number of rows returned from a query or scan.
## ro
- Type: flag
Enable read-only mode. When enabled, all modification operations are disabled, and will fail with a `Read-only mode` error.
The `rw` setting will disable read-only mode.
## rw
- Type: flag
Disable read-only mode. The `ro` setting will enable read-only mode.