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

Updated the documentation
Some checks failed
ci / Build (push) Failing after 3m41s
Details
Release / Build (push) Failing after 3m41s
Details
Release / Site (push) Has been skipped
Details
Release / Release (push) Has been skipped
Details

Browse source
This commit is contained in:
Leon Mika 2025-11-15 11:34:07 +11:00
parent 4cb66f52fe
commit b4cee0e2e5
31 changed files with 267 additions and 296 deletions
Download patch file Download diff file Expand all files Collapse all files

31
_site/content/_index.md
View file

@ -1,7 +1,6 @@
+++
title = "Dynamo-Browse"
bookToc = false
+++
---
weight: 10
---
<div class="site-header">
<img src="/images/dynamo-browse/dynamo-browse-logo.png">
@ -17,15 +16,31 @@ With it, you can quickly connect to and browse the contents of a DynamoDB table
in your AWS account or local machine. There are some basic facilities for
editing as well.
## Getting Started
Instructions for installing Dynamo-Browse can be found on the [Downloads page](/download).
This video gives a brief introduction of how to use Dynamo-Browse to view the items of a DynamoDB table:
{{< youtube cQnTIg1_tfg >}}
More information about the tool can be found within the [Dynamo-Browse user manual](/docs).
## Download
Binary packages for MacOS and Linux can be [found at Forgejo](https://lmika.dev/cmd/dynamo-browse/releases).
### MacOS Using Homebrew
If you have Homebrew, you can install Dynamo-Browse using the following command:
```
brew tap lmika/dynamo-browse https://lmika.dev/casks/dynamo-browse
brew install dynamo-browse
```
### Go
If you have Go installed, you can install Dynamo-Browse using the following command:
```
go install lmika.dev/cmd/dynamo-browse/cmd/dynamo-browse@latest
```

35
_site/content/docs/_index.md
View file

@ -1,35 +0,0 @@
# User Guide
## Table Of Contents
- [Launching and Quitting](/docs/launching)
- [Selecting a Table](/docs/launching#selecting-a-table)
- [Selecting a Workspace](/docs/launching#selecting-a-workspace)
- [Quitting](/docs/launching#quitting)
- [Getting Around](/docs/getting-around)
- [The Back-stack](/docs/getting-around#the-back-stack)
- [Adjusting The Layout](/docs/getting-around#adjusting-the-layout)
- [Adjusting The Displayed Columns](/docs/getting-around#adjusting-the-displayed-columns)
- [Entering Commands](/docs/getting-around#entering-commands)
- [Filtering and Querying](/docs/filtering-querying)
- [Filtering](/docs/filtering-querying#filtering)
- [Querying](/docs/filtering-querying#querying)
- [Editing Items](/docs/editing-items)
- [Marking Items](/docs/editing-items#marking-items)
- [Modifying Attributes](/docs/editing-items#modifying-attributes)
- [Deleting Attributes](/docs/editing-items#deleting-attributes)
- [Adding Items](/docs/editing-items#adding-items)
- [Deleting Items](/docs/editing-items#deleting-items)
- [Committing Changes](/docs/editing-items#committing-changes)
- [Backing Out of Changes](/docs/editing-items#backing-out-of-changes)
- [Customising Dynamo-Browse](/docs/customising)
- [The RC File](/docs/customising#rc-file)
- [Rebinding Keys](/docs/customising#rebinding-keys)
References
- [Key Bindings](/docs/reference/key-bindings)
- [Commands](/docs/reference/commands)
- [Query Expressions](/docs/reference/query-expressions)
- [Launch Flags](/docs/reference/launch-flags)
- [Settings](/docs/reference/settings)

4
_site/content/docs/reference/_index.md Normal file
View file

@ -0,0 +1,4 @@
---
bookFlatSection: true
weight: 40
---

13
_site/content/docs/reference/commands.md
View file

@ -1,5 +1,12 @@
---
title: Commands
weight: 20
---
# Commands
These commands are meant for general, interactive use. For additional commands meant for defining
extensions, see [Extensions](/docs/reference/extensions/).
## clone
```
@ -40,7 +47,7 @@ Displays _message_ in the status bar. Mainly used for debugging.
## export
```
:export [-all] <filename>
:export <filename> [-all]
```
Writes the currently loaded items as a CSV file to _filename_.
@ -105,7 +112,7 @@ Quits Dynamo-Browse.
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-opt
```
:set <name> [value]
@ -116,7 +123,7 @@ Set the value of a setting. Flag setting types can be enabled without any value
## set-attr
```
:set-attr [type] <attributeName>
:set-attr <attributeName> [type]
```
Alias: `sa`

7
_site/content/docs/reference/extensions.md Normal file
View file

@ -0,0 +1,7 @@
---
title: "Extensions"
type: script-api
weight: 60
draft: true
---
# Extensions

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

@ -1,3 +1,7 @@
---
title: Key Bindings
weight: 10
---
# Key Bindings
<div data-controller="keybindings">

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

@ -1,3 +1,7 @@
---
title: Launch Flags
weight: 40
---
# Launch Flags
## -debug

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

@ -1,3 +1,7 @@
---
title: Query Expressions
weight: 30
---
# Query Expression
Query expressions are used to select rows of a table. When executed as a query (i.e. by pressing <kbd>?</kbd>),

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

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

4
_site/content/docs/reference/settings.md
View file

@ -1,3 +1,7 @@
---
title: Settings
weight: 50
---
# Settings
## default-limit

103
_site/content/docs/scripting.md
View file

@ -1,103 +0,0 @@
---
title: "Scripting"
---
# Scripting
Scripts can be used to automate certain tasks with Dynamo-Browse. They can also be used to define
new commands or key bindings.
## Scripting Basics
Dynamo-Browse scripts are written using the [Tamarin](https://cloudcmds.github.io/tamarin/) scripting language,
which looks a lot like [Go](https://go.dev). All features of the language are available in Dynamo-Browse.
The typical "hello world" script for Dynamo-Browse is below:
```
ui.print("Hello, world")
```
This uses the [ui](/docs/reference/script-api/#module-ui) package, which is the package used to interact with
the Dynamo-Browse user interface.
A full list of supported packages can be found in the [Script API](/docs/reference/script-api/) reference, along
with the builtins and packages supported by Tamarin itself.
{{<hint info>}}
**Note:** the [ext](/docs/reference/script-api/#module-ext) package is only available to Extension Scripts.
{{</hint>}}
To execute this script, use the `run-script` command:
```
run-script /path/to/script/hello.tm
```
You'll see that the message "Hello, world" will appear in the status bar of Dynamo-Browse.
<!-- TODO: Screenshot -->
Any `print` or `printf` messages will be written to the debug log with the prefix `script <filename>`. The
debug log is turned off by default, but it can be enabled using the [-debug](/docs/reference/launch-flags/#-debug) flag on launch.
Scripts loaded using the `run-script` command are for ad-hoc automation tasks that are not necessarily designed for
repeated use. These ad-hoc scripts are executed, then immediately unloaded, and are not generally allowed to extend
Dynamo-Browse. In order to do so, you will need to write an Extension Script.
## Extension Scripts
Extension scripts are scripts designed to extend Dynamo-Browse in some way, such as with new commands or key bindings.
They are traditionally loaded on startup and exist in the predefined "script" directory. They are usually designed for
repeated operations, including those that can be bound to command name or keys.
The following is an example script which will define a "goto" command. When invoked, the script will prompt the
user for the value of the partition key. It will then perform a query over the currently viewed table for any rows with
that partition key. If no error occurred, the results of the query will be shown to the user.
```
// Define a new "goto" command, which can be invoked when the user presses ':' and types in 'goto'
ext.command("goto", func() {
// Use the information of the current table to get the name of the partition key.
pkName := session.current_table().keys["partition"]
// Prompt the user for the value to go to. The user can press Esc, which will cancel
// the input and return 'nil'.
keyVal := ui.prompt(pkName + "? ")
if keyVal == nil {
return nil
}
// Run a query over the DynamoDB table for any rows with the partition key. Notice
// the use of the 'args' option, and the presence of both the name prefix (':key')
// and value prefix ('$val').
res := session.query(":key = $val", {
args: {
key: pkName,
val: keyVal,
},
})
// The query method will return either an error or a result. If it's an error, print
// a notice and exist.
if res.is_err() {
ui.print("Can't goto: " + res.err_msg())
return nil
}
// If no error, unwrap the result object to get the result-set returned from the query.
// Then change the current result-set to this one. This will change the result-set the
// user is currently seeing.
session.set_result_set(res.unwrap())
})
```
To load an extension script, use the `load-script` command:
```
load-script script.tm
```
The script must exist in the "script" directory, which by default is:
```
$HOME/.config/audax/dynamo-browse/scripts
```

4
_site/content/docs/user-guide/_index.md Normal file
View file

@ -0,0 +1,4 @@
---
bookFlatSection: true
weight: 30
---

27
_site/content/docs/customising.md → _site/content/docs/user-guide/customising.md
View file

@ -1,22 +1,24 @@
---
title: Customising Dynamo-Browse
weight: 50
---
# Customising Dynamo-Browse
Some commands can be used to customise Dynamo-Browse, such as modify key bindings.
The effect of these commands will only be applied for the duration of the session: they are currently not
tracked within the workspace file. So in order to keep customisations across relaunches, these commands
tracked within the workspace file. To keep customisations across relaunches, these commands
can be added to an RC file.
## The RC File
## RC Files
The RC file is a text file containing commands that will be executed by Dynamo-Browse upon launch.
By default, the RC file is located at the following path:
RC files are text files containing commands that will be executed by Dynamo-Browse upon launch.
By default, RC files are located in `$HOME/.config/dynamo-browse/` and have the suffix `.ucl`. For example:
```
$HOME/.config/audax/dynamo-browse/init.rc
$HOME/.config/dynamo-browse/init.ucl
```
This file is primarily intended for commands that customise Dynamo-Browse in a particular way, but any
command can be entered here. If this file is found, Dynamo-Browse will invoke each command before loading
or prompting the table.
Any number of RC files can be present in this directory, and they are executed in lexicographical order.
## Rebinding Keys
@ -38,4 +40,11 @@ At the moment each binding name can only be mapped to a single key. It's also c
to setup bindings for commands. These may be supported in the future.
A list of available binding names can be found the the [reference](/docs/reference/key-bindings)
(check the "Show binding names" checkbox). Note that some bindings may not have default key bindings.
(check the "Show binding names" checkbox). Note that some bindings may not have default key bindings.
## Extensions
The RC files are primarily intended for commands that customise Dynamo-Browse in a particular way, but any
command can be entered here, including those for defining new commands or running predefined queries. These
are generally known as extensions, although act as any other RC file located within that directory. More
information on extensions can be found in the [reference](/docs/reference/script-api).

4
_site/content/docs/editing-items.md → _site/content/docs/user-guide/editing-items.md
View file

@ -1,3 +1,7 @@
---
title: Editing Items
weight: 40
---
# Editing Items
Dynamo-Browse offers some basic facilities for editing items — such as creating items, deleting items,

25
_site/content/docs/filtering-querying.md → _site/content/docs/user-guide/filtering-querying.md
View file

@ -1,4 +1,8 @@
# Querying And Viewing Results
---
title: Querying and Filtering Results
weight: 30
---
# Querying and Filtering Results
## Querying
@ -8,7 +12,24 @@
A query or scan over the table can be performed by entering a _Query Expression_.
Query expressions are a built-in expression language which translates to either a DynamoDB query
or scan, depending on the expression. Details about the Query Expression language can be found in the
or scan, depending on the expression.
Query expressions are entered as expressions, with most being of the form `attribute operator value`.
For example, the expression for selecting records where `color` equals `red` is:
```
color = "red"
```
The `color` attribute can either be a partition key, sort key, or a regular attribute. Dynamo Browse
will do it's best to run the query as a DynamoDB query if possible. Usually query expressions of the
form `pk = <something>` or `pk = <something> and sk <comparison> <something>` where `pk` is a partition key,
`sk` is the sort key, and `<comparison>` is one of the [equality](/docs/reference/query-expressions/#equality),
[numerical comparison](/docs/reference/query-expressions/#numerical-comparison), or
[prefix operator](/docs/reference/query-expressions/#prefix-operator), will be executed as queries.
Other expressions will be executed as scans.
Details about the Query Expression language can be found in the
[Query Expressions references](/docs/reference/query-expressions/).
To run a query, press <kbd>?</kbd>, and enter the query expression.

4
_site/content/docs/getting-around.md → _site/content/docs/user-guide/getting-around.md
View file

@ -1,3 +1,7 @@
---
title: Getting Around
weight: 20
---
# Getting Around
After selecting a table, Dynamo-Browse will perform a scan and present the results in the default view mode.

6
_site/content/docs/launching.md → _site/content/docs/user-guide/launching.md
View file

@ -1,4 +1,8 @@
# Launching And Quitting
---
title: Launching and Quitting
weight: 10
---
# Launching and Quitting
To launch Dynamo-Browse, run the following command at the terminal:

17
_site/content/download.md
View file

@ -1,19 +1,8 @@
+++
layout = "single"
+++
---
weight: 20
---
# Download
Binary packages can be [download from GitHub](https://github.com/lmika/audax/releases/latest).
## MacOS Using Homebrew
If you have Homebrew, you can install using the following command:
```
brew tap lmika/audax
brew install audax
```
## Linux

25
_site/content/menu/index.md
View file

@ -1,25 +0,0 @@
+++
headless = true
+++
- [Download]({{< relref "/download" >}})
- [Releases](https://github.com/lmika/audax/releases)
- [Github](https://github.com/lmika/audax)
<br>
[**User Guide**]({{< relref "/docs" >}})
- [Launching]({{< relref "/docs/launching" >}})
- [Getting Around]({{< relref "/docs/getting-around" >}})
- [Filtering And Querying]({{< relref "/docs/filtering-querying" >}})
- [Editing Items]({{< relref "/docs/editing-items" >}})
- [Customising]({{< relref "/docs/customising" >}})
- [Scripting]({{< relref "/docs/scripting" >}})
<br>
**References**
- [Key Bindings]({{< relref "/docs/reference/key-bindings" >}})
- [Commands]({{< relref "/docs/reference/commands" >}})
- [Query Expressions]({{< relref "/docs/reference/query-expressions" >}})
- [Launch Flags]({{< relref "/docs/reference/launch-flags" >}})
- [Settings]({{< relref "/docs/reference/settings" >}})
- [Script API]({{< relref "/docs/reference/script-api" >}})
<br>