Run the Interactive Editor¶

CLI Commands¶

There are lots of CLI commands, but the most interesting one might be running the interactive editor, dob edit, which we’ll document in the following sections.

But first, if you’d like to see a list of all dob commands and global options, use the CLI. Run the command:

$ dob --help

All of the individual CLI commands are well documented in the CLI itself.

For instance, to get help on the export command, run:

$ dob export --help

You’ll find other commands for managing the configuration, printing reports, exporting Facts, adding new Facts from the CLI, and more.

Because all the CLI commands except for the interactive editor are documented in the CLI, we’ll focus here on describing how to use the interactive editor. We’ll leave it as an exercise for the user to read the CLI help.

Interactive Editor¶

Run dob edit to fire up the editor.

$ dob edit

The editor will take over your terminal and look something like this (but nicer):

╭────────────────────────────────────────────────────────────────────────────────╮
│             Thu 16 Apr 2020 ◐ 02:13 PM — 03:52 PM                              │
╰────────────────────────────────────────────────────────────────────────────────╯

  duration........... :  1 hour  39 minutes
  start.............. : 2020-04-16 14:13:49
  end................ : 2020-04-16 15:52:50 <now>
  activity........... : Documentation
  category........... : dob Development
  tags............... : #readme

┌────────────────────────────────────────────────────────────────────────────────┐
│Working on the "Interactive Editor" help.                                       │
│                                                                                │
│                                                                                │
│                                                                                │
│                                                                                │
│                                                                                │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘
Fact ID #22619                              [?]: Help / [C-S]: Save / [C-Q]: Quit

You can press ? in the app to see a short list of commands and keys.

But a more complete list of editor commands is actually in the config — because all of the key bindings in the editor are configurable!

Set your own keybindings¶

To see the list of editor commands and their keybindings, look under the editor-keys section, e.g.,:

$ dob config show editor-keys
+-------------+-----------------------+----------------------+----------------------+
|   Section   |         Name          |   Value <Default>    |         Help         |
+=============+=======================+======================+======================+
| editor-keys | focus_next            | tab                  | Switch to Next       |
|             |                       |                      | Widget (description  |
|             |                       |                      | → start time → end   |
|             |                       |                      | time → [repeats])    |
+-------------+-----------------------+----------------------+----------------------+
| editor-keys | focus_previous        | s-tab                | Switch to Previous   |
|             |                       |                      | Widget (description  |
|             |                       |                      | → end time → start   |
|             |                       |                      | time → [repeats])    |

In this snippet, you’ll see that Tab is mapped to the focus_next command, and that Shift-Tab is mapped to focus_previous.

Note, too, that dob supports multiple mappings to the same command.

For example, in Vim, there are multiple undo command mappings, which dob emulates:
```
$ dob config get editor-keys undo_command
[["c-z"], ["u"]]
```
By default, both Ctrl-z and u are mapped to undo, just like in Vim.
If you want to use multiple mappings, express the value as a JSON-encoded array of arrays.

Why an array of arrays? Because dob supports multiple keypress bindings.

For instance, the command to copy the Activity from the current Fact is A followed by Ctrl-c, which is expressed as an array within an array:
```
$ dob config get editor-keys fact_copy_activity
[["A", "c-c"]]
```
Note that the single outer array contains one inner array with two elements, which represent the two-key mapping.
Finally, be aware that Alt-key (or Option-key) mappings are indicated using a two-key mapping sequence with ‘escape’ as the first element, e.g., pressing Alt-left (the Alt key and the left arrow key simultaneously) looks like this:
```
[["escape", "left"]]
```
In dob, by default, the J key is also mapped to the same command, so the actual config entry looks like this:
```
$ dob config get editor-keys jump_day_dec
[["J"], ["escape", "left"]]
```

Show all editor commands and keybindings¶

If you’d like to page the (long) config show output, you could, say, pipe it to less, or you could specify a global CLI option, --pager.

For example, these two commands are essentially equivalent:

$ dob config show editor-keys | less

$ dob --pager config show editor-keys