README.md

# README.md

__aestel__

A collection of Lua terminal utilities.

## An Aestel?

The aestel project is named for the Old English _æstel_, a wax  
tablet used for recording and preserving knowledge.

__aestel__ is a collection of lightweight, modular utilities for  
terminal-based workflow, productivity, knowledge management, and  
system administration.

## Project Structure

The utilities are ports of the author's shell scripts to Lua. At  
present they include the following scripts.

    browsefilies.lua     Directory browsing and file opening
    launchprogram.lua    Menu-driven program launcher
    setbackground.lua    Background setting utility

The utilities are scripts written in Lua that rely on a shared set  
of Lua modules.

     browse.lua       Browsing directory structure and content.
     colors.lua       Shared ANSI color constants.
     display.lua      Shared terminal output display.
     input.lua        Shared low-level terminal input utilities.
     menu.lua         Rendering and navigating menus.
     opener.lua       Opening files based on MIME type.

- bin/: User-facing scripts (browsefiles, launchprogram, etc.)
- aestel/: Shared Lua modules providing the core UI/navigation primitives
- man/: Manual pages for the utilities

## Scripting Language Dependencies

- Lua 5.4
- LuaFileSystem (lfs)

### Preferred Program Dependencies

Aestel is designed to be modular. The following programs are used  
by default for their alignment with the author's design values  
(written in C, minimal, and Unix-compliant):

- Terminal Emulator: [st](https://st.suckless.org)
- Text Editor: [vis](https://github.com/martanne/vis), and,
- Background Setter: [bgs](https://github.com/Gottox/bgs).

These programs are not strictly required. Users may substitute their  
preferred programs. Note that doing so will require modification of  
the relevant Lua script or module source code.

## Install

Install the libraries, binaries, and manual pages. Note that root  
privileges are not required as the default destination `~/.local/`  
directory.

```
make install
```

## Uninstall

Remove the libraries, binaries, and manual pages.

```
make uninstall
```

## Configuration

Configuration of the user's configuration file for the user's  
interactive shell is required for scripts to exit to the current  
working directory. The author uses the Almquist Shell and places  
the following in `~/.ashrc` file.

```
browsefiles() {
    local target
    target=$(command browsefiles "$@")
    [ -n "$target" ] && [ -d "$target" ] && cd "$target"
}

setbackground() {
    local target
    target=$(command setbackground "$@")
    [ -n "$target" ] && [ -d "$target" ] && cd "$target"
}
```