histui/documentation/specification.md

# CRITICAL NOTES
+ flex might be total overkill as scanf might entirely suffice

# Used technologies
+ C style C++ with pottential future "back" porting
+ flex history parsers
+ SQLite
+ ncurses
+ readline

# Rationale
### C/C++
+ fuck pust
### NCurses
+ i know nothing better that is:
- portable
- reliable
- C compatible
- anyway better than ncurses
### SQLite
+ sharing history between shell types could be desirable, this is the simplest approach
+ having our own storage means that we could support meta informations globally
which are not standard for every application
### Flex
+ its *actually* reusable
### Readline
+ we are not trying to replace it in anyways; it only makes sense

# CLI
histui \<verb\>
+ \<import\> \<file-1\>:\<file-2\> [format]
+ \<export\> \<file\>              [format]
+ \<tui\>    \<file\>              [options]
+ \<init\>   \<shell\>

## Import
Read history entries from \<file-1\> into
histuidb \<file-2\>.

Unless all lines are pure entry values,
a format will have to be specified.

If no files are specified,
precomposed formats shall be printed.
E.g. format for "Bash with timestamps".

## Export
Dump the contents of histuidb \<file\>
to stdout using [format].

## Init
Used for printing reasonable default configuration
for using histui with the selected shell.

The default configuration,
if possible should have the following features:
+ override history search with invoking histui
+ sync further commands a histuidb

If no shell is specified,
the available options shall be printed.

# TUI

$ histui tui [options]
--command   : start in search mode
--normal    : start in normal mode

+---+---------------+
| p |               |
| o |   listing     |
| s |               |
+---+---------------+
|       ruler       |
+-------------------+
|       input       |
+-------------------+

### Modes
+ the reason why we have modes is to make both
inspecting and selection entries,
and searching/filtering entries piss easy

##### Normal mode
The user may move up and down freely on the list
with any prefered binding (Vimlike by default),
or repeat a motion by specifying a repeat count
before any motion.

**\[repeat\]\<motion\>**

move around


**:<int>**

Jump to Nth entry.

#### Result stack
Everytime the user issues a search,
or inspects an item
the result stack is pushed.

The top search frame can/will be
overwritten.

The user may pop or clear by hand.

The result stack is NOT persistent between sessions.

#### Command mode
Every character entered narrows the list of results.
The user may use altered {ctrl+n} or special {arrow} keys
to navigate the results,
but may be unable to issue repeats or jumps.

#### Global input
Do note that these actions may have
different bindings in different modes.

**<inspect>**

Select an entry to load the context for.
Without filtering this is effectless,
however if the output was filtered,
the search results are overwritten
by the commands that were executed
in the same shell as this one.

**<clear>**

Clear any filtering or inspection.

**<pop>**

Pop result frame.

**<select>**

Echo entry value and exit with success.

## Format
```
%[flags][width]<specifier>
```

#### flags
-   : left-justify within [width]
\#  : relative (has effect on time specifiers)

#### width
+ number of characters to align to

#### specifiers
s   : history entry
n   : entry number
p   : shell id
a   : short weekday name
A   : full weekday name
u   : ISO 8601 decimal week day weekday (1-7)
b   : short month name
B   : full month name
C	: year (integer) devided by 100
d	: day of the month; 0 padded {"09"}
D   : short date ("MM/DD/YY")
H   : hour in 24h format {18}
I   : hour in 12h format {06}; 0 padded
r   : 12h time {12:38:21 PM}
R   : 24h time ("HH:MM")
S   : seconds; 0 padded {04}
M   : minutes; 0 padded {03}
T   : ISO 8601 time format ("HH:MM:SS")

# Environment
HISTUIHIST  : histuidb to be used