.TH TEDIT 1 "December 12, 2025" "tedit 2.1.0" "User Commands"
.SH NAME
tedit - a minimal yet mighty command-line text editor
.SH SYNOPSIS
.B tedit
.RI [ file ]
.br
.B tedit
.RI [ options ]
.P
The repository also ships helper tools used for install/update/uninstall:
.P
.B tedit-install
.RI [ VERBOSE=1 ]
.br
.B tedit-update
.RI [ VERBOSE=1 ]
.br
.B tedit-uninstall
.RI [ --purge-user-data | --purge-repo | --purge ]
.RI [ -y | --yes ]
.SH DESCRIPTION
.B tedit
is a lightweight, command-line text editor inspired by
.BR ed (1)
and
.BR ex (1),
but enhanced with modern features such as syntax highlighting, undo/redo history,
atomic saves, backups, autosave snapshots, themes, and hooks.
.P
It provides a clean, scriptable command interface with familiar operations
for editing, searching, replacing, and filtering text ranges, all in a single
fast, portable C++17 binary.
.P
Per-user configuration and Lua plugins are stored under
.IR ~/tedit-config ,
keeping editor state and extensions self-contained in your home directory.
.SH FEATURES
.IP [bu] 2
Atomic file saves and optional backups for safety (write to a temporary file,
then \fBrename(2)\fR into place, with optional \fIfilename~\fR backup).
.IP [bu]
Crash recovery and autosave snapshots written periodically to files such as
\fI~/.tedit-recover-*\fR.
.IP [bu]
Undo/redo stack with up to 200 operations.
.IP [bu]
Syntax highlighting with auto-detection for C/C++, Python, Shell, Ruby, JS/TS,
HTML, CSS, JSON, and more. Highlighting can be toggled via
\fB:highlight on\fR/\fBoff\fR and overridden with
\fB:set lang <name>\fR.
.IP [bu]
Configurable themes and color schemes (e.g. \fBdefault\fR, \fBdark\fR,
\fBneon\fR, \fBmatrix\fR, \fBpaper\fR, \fByellow\fR, \fBiceberg\fR) using
\fB:theme <name>\fR for built-in themes, plus Lua-based themes loaded from
\fI~/tedit-config/themes/<name>.lua\fR.
.IP [bu]
Lua theme listing via \fB:lua-themes\fR, which shows all \fB*.lua\fR theme
files found under \fI~/tedit-config/themes\fR.
.IP [bu]
Command history and tab completion: first word completion for editor commands,
filesystem completion for paths, and directory-only completion for
.BR :cd .
.IP [bu]
Directory navigation and file listing via \fB:cd\fR, \fB:ls\fR, and \fB:pwd\fR.
.IP [bu]
Shell filters for piping text ranges through external commands.
.IP [bu]
Multiple buffers and diff viewing against the on-disk file.
.IP [bu]
Hooks for \fIon_save\fR and \fIon_quit\fR events.
.IP [bu]
Lua scripting and a simple plugin system loaded from
.IR ~/tedit-config/plugins .
.IP [bu]
Optional privileged saves via \fBdoas\fR, used as a fallback when a normal
atomic rename fails due to permissions.
.SH USAGE
Run
.B tedit
with a filename to open a file:
.PP
.RS
.EX
tedit notes.txt
.EE
.RE
.PP
Start without arguments to open an empty session:
.PP
.RS
.EX
tedit
.EE
.RE
.PP
Common editor commands:
.PP
.RS
.EX
:help              # list commands
:set number on     # show line numbers
:edit              # enter interactive edit mode for a specific line
:find text         # search
:repl old new      # replace
:theme neon        # change theme
:highlight on      # enable syntax highlighting
:lua-themes        # list available Lua themes
:lua tedit_echo("hi")   # run a small Lua snippet
:plugins           # list loaded Lua plugins
:wq                # save and quit
.EE
.RE
.PP
A typical workflow is to \fBcd\fR into a project directory and then run
.BR tedit ,
so that atomic saves stay on the same filesystem and filters, hooks, and
relative paths behave predictably.
.SH FILES
.IP "~/tedit-config/.teditrc"
Configuration file for preferences (theme, line numbers, autosave, wrapping,
etc.).
.IP "~/tedit-config/plugins"
Per-user Lua plugin directory. Any \fB*.lua\fR files in this directory are
loaded at startup; errors are reported in the editor.
.IP "~/tedit-config/themes"
Per-user Lua theme directory. Any \fB*.lua\fR files in this directory define
named themes that can be listed with \fB:lua-themes\fR and loaded with
\fB:theme <name>\fR.
.IP "~/.tedit/hooks/on_save"
User-defined script executed after each save.
.IP "~/.tedit/hooks/on_quit"
User-defined script executed on exit.
.IP "~/.tedit_banner"
Optional banner file printed on startup.
.IP "~/.tedit-recover-*"
Autosave recovery snapshots, used for crash recovery.
.SH TOOLS
The repository includes helper scripts with a cinematic progress bar and spinner.
These tools detect your package manager, install missing build dependencies, and
log verbosely to temporary files.
.TP
.B install.sh
Detects dependencies (\fBmake\fR, a C++17 compiler, etc.), builds, and installs
\fBtedit\fR automatically with a progress display. On systems using Gentoo,
shows a yellow note and may run an interactive \fBemerge\fR. Installs to
\fI/usr/local/bin\fR when run with privileges, or \fI~/.local/bin\fR without.
.TP
.B update.sh
Checks for git updates quietly; if none are available it prints exactly:
\fIUp to date.\fR
Otherwise it pulls (preferring rebase), rebuilds, reinstalls, and optionally
strips the binary. Local uncommitted changes are auto-stashed and restored.
.TP
.B uninstall.sh
Removes \fBtedit\fR, man pages, installer wrappers, PATH entries added by the
installer, and local build artifacts. Supports purge flags (see below).
.PP
The scripts write logs to:
.PP
.RS
.EX
/tmp/tedit-install.XXXXXX.log
/tmp/tedit-update.XXXXXX.log
/tmp/tedit-uninstall.XXXXXX.log
.EE
.RE
.PP
Set \fBVERBOSE=1\fR to stream command output instead of using the spinner.
.SH WRAPPERS
After running \fBinit.sh\fR once inside the repo, small wrapper commands are
installed to your PATH so you can run project tools from anywhere:
.PP
.RS
.EX
tedit-install
.ti +2
tedit-update
.ti +2
tedit-uninstall
.EE
.RE
.PP
Wrappers remember the repo location and \fBcd\fR into it before executing
\fBinstall.sh\fR/\fBupdate.sh\fR/\fBuninstall.sh\fR, keeping builds predictable.
.PP
If a wrapper loses track of the repo, you can point it at the correct clone by
creating a marker file or using an environment variable:
.PP
.RS
.EX
# One-time marker (replace with your absolute repo path):

sudo mkdir -p /usr/local/share/tedit
printf '%s\n' "/path/to/tedit" | sudo tee /usr/local/share/tedit/repo >/dev/null

# Per-call override:

TEDIT_REPO="/path/to/tedit" sudo tedit-update
.EE
.RE
.SH UNINSTALL FLAGS
.TP
.B --purge-user-data
Remove \fI~/tedit-config/.teditrc\fR, \fI~/.tedit_banner\fR, \fI~/.tedit/hooks\fR, and
\fI~/.tedit-recover-*\fR.
.TP
.B --purge-repo
Remove the current git repository directory (asks for confirmation unless
\fB--yes\fR is provided).
.TP
.B --purge
Do both \fB--purge-user-data\fR and \fB--purge-repo\fR.
.TP
.B -y, --yes
Assume "yes" to prompts (non-interactive).
.SH CONFIGURATION
Configuration options are set in \fI~/tedit-config/.teditrc\fR:
.PP
.EX
theme=neon
highlight=on
number=on
backup=on
autosave=120
wrap=on
truncate=off
alias    dd      delete 1-$
alias    wq!     wq
.EE
.SH LUA INTEGRATION AND PLUGINS
.B tedit
embeds Lua for lightweight scripting and extension. If built with Lua support,
the following commands are available from the editor prompt:
.TP
.B :lua \fICODE\fR
Execute an inline Lua snippet.
.TP
.B :luafile \fIPATH\fR
Load and execute a Lua script from the given path.
.TP
.B :plugins
List the names of successfully loaded Lua plugins.
.TP
.B :reload-plugins
Rescan and reload \fB*.lua\fR files from the plugin directory.
.TP
.B :lua-themes
List available Lua theme files (by name) from \fI~/tedit-config/themes\fR.
.PP
Plugins are simple Lua files placed under
.IR ~/tedit-config/plugins .
At startup,
.B tedit
will attempt to load each \fB*.lua\fR file once; any error messages are printed
inside the editor.
.PP
Lua-based themes are stored separately under
.IR ~/tedit-config/themes .
Each theme file typically returns or defines a Lua table describing colors and
is loaded on demand via \fB:theme <name>\fR rather than at startup.
.PP
A few helper functions are exposed to Lua:
.IP \[bu] 2
\fBtedit_command(str)\fR – run an editor command as if it was typed at the
tedit prompt.
.IP \[bu]
\fBtedit_echo(str)\fR – print a message using the editor's accent color.
.IP \[bu]
\fBtedit_print(line)\fR – print a specific line from the current buffer.
.PP
Lua plugins and themes run with the same privileges as your user account and
can execute arbitrary code (including shell commands and file I/O). Treat
third-party Lua code as untrusted unless you have reviewed it. \fBtedit\fR
performs a lightweight scan for obviously dangerous patterns (such as
\fBos.execute\fR, \fBio.popen\fR, \fBdofile\fR, and similar) when loading
plugins, but this is only a convenience warning, not a security guarantee.
.SH ENVIRONMENT
.TP
.B TEDIT_REPO
Absolute path to the \fBtedit\fR git repository. If set, wrappers and tools
will use this path to locate the source when running from arbitrary directories.
.TP
.B ZDOTDIR
If set, \fI$ZDOTDIR/.zprofile\fR may be updated by the installer when adding
\fI~/.local/bin\fR to PATH for user installs.
.TP
.B VERBOSE
When set to a non-empty value (for example \fBVERBOSE=1\fR), the installer,
updater, and uninstaller scripts stream command output instead of using the
spinner-style UI. Logs are still written under \fI/tmp\fR as described in
the TOOLS section.
.SH PRIVILEGED SAVES
.B tedit
performs saves by writing to a temporary file and then calling
.BR rename (2)
for an atomic replace.
If saving fails due to permissions, \fBtedit\fR can fall back to writing a
temporary file and using \fBdoas mv\fR to move it into place. Configure
\fIdoas.conf\fR accordingly, or run \fBtedit\fR as root when editing system
files.
.SH EXIT STATUS
.TP
.B 0
Successful completion.
.TP
.B 1
An error occurred (file not found, permission denied, build failure, etc.).
.SH AUTHOR
Written by Robert (aka RobertFlexx).
.SH HOMEPAGE
Project page and source code:
.UR https://github.com/RobertFlexx/tedit
.UE
.SH SEE ALSO
.BR ed (1),
.BR ex (1),
.BR doas (1),
.BR sudo (8),
.BR lua (1),
.BR sh (1),
.BR make (1),
.BR git (1)
.SH LICENSE
BSD 3-Clause License. You are free to use, modify, and redistribute provided the
copyright notice is retained.