# sued - shut up editor
> [!NOTE]
> This page is about sued as a text editor. For sued as a library, see
> [README.lib.md](README.lib.md).
sued is a minimalist line-based text editor written in [Rust](https://www.rust-lang.org/),
inspired by classical Unix text editors, such as the [ed](https://en.wikipedia.org/wiki/Ed_(software))
text editor from the '70s, and its descendants, such as [Vim](https://www.vim.org/),
while in part modernising those editors with features from the text editors and
IDEs of today.
Instead of providing you with a graphical interface like most text editors
nowadays, sued operates using a REPL-style interface, where you enter text,
run commands, and work with textual data, all in one command prompt
environment.
sued aims at bringing back the line editing styles of the past with the sort
of modern-ish features you would expect from a text editor today - where ed
had to be extremely minimalist to run on practically any Unix box under the
sun, sued has no such limitation. It takes full advantage of today's
computers' capabilities, all while staying as minimalist and distraction-free
as is reasonably possible.
```sued
sued v0.21.0-devel - in a world of vscode, be an ed
type ~cmds or ~help for commands, otherwise just start typing
opened file at strict.txt
17›~show
1│-- This is an excerpt of Michael Rosen's poem "Strict", used for testing sued. --
2│-- To listen to an official audio recording of "Strict", see https://www.youtube.com/watch?v=z1cfVQyrQ3Q. --
3│
4│You know people say to me:
5│"If that's true, how come you're here to tell the tale?"
6│Fair enough, and I'll tell you.
7│
8│It's because, when I was at school, we used to sit at desks.
9│We didn't sit 'round tables like you do now, we used to sit at desks, with lids.
10│And some of us figured out, what you had to do, was snatch a quick breath under
11│the desk lid when she wasn't looking!
12│
13│So once more, from the beginning...
14│
15│"Noooo BREATHING!"
16│
17›~point 12
set cursor position to 12
12›
13›~up
set cursor position to 12
12›
13›Wow. Thanks, Mike.
14›~show 12~16
12│
13│Wow. Thanks, Mike.
14│
15│
16│So once more, from the beginning...
14›~delete 14
deleted line 14
14›~show 12~16
12│
13│Wow. Thanks, Mike.
14│
15│So once more, from the beginning...
16│
14›~point end
set cursor position to 17
17›~show 15~17
15│So once more, from the beginning...
16│
17│"Noooo BREATHING!"
17›
18›
19›Actually I forgot how the poem goes.
20›I think they all went to the Science Museum after this.
21›Oh, no, wait, that was "The Outing".
22›~save
saved to strict.txt
22›~exit
```
## Obtaining
First of all, you need Cargo. If you don't have Cargo, [install Rust.](https://www.rust-lang.org/learn/get-started)
If you don't want to install Rust, frick off and use a different editor.
Run
```bash
# Make sure you specify `--features=repl` otherwise you won't be able to
# use the editor
cargo install sued --features=repl
```
and make sure that `~/.cargo/bin/` is in your PATH or you won't be able to run
it.
If you'd rather install from source:
```bash
git clone https://codeberg.org/AeriaVelocity/sued.git
cd sued
cargo install --path . --features=most # for info on feature flags, see below
```
## Configuration
sued is not configured through a configuration file (not right now, anyway).
Instead, you configure sued's features by enabling or disabling Cargo feature
flags.
By default, sued is minimally compiled and only includes sued as a library.
If you want sued as a text editor, enable the `editor` feature flag, which
automatically enables every editor command defined in the editor's `suedfn`
module, as well as the sued REPL.
If you don't want any commands, or you've defined your own and don't
need to rely on sued's built-in commands, append `--no-default-features` to
your Cargo command to disable sued's default editor commands.
### Feature flags
sued can be built with the following feature flags, organised by feature group.
This serves as a high-level overview of [Cargo.toml](https://codeberg.org/AeriaVelocity/sued/src/branch/main/Cargo.toml)'s
`[features]` section.
### core
`core` enables the core functionality of sued, consisting of the built-in editor
command groups. This group is enabled by default and can be disabled with
`--no-default-features`.
* `informational` - Enables commands that display information about the
buffer or the editor state.
* `inputoutput` - Allows you to actually interact with the buffer and
underlying file system.
* `cursor` - Enables commands used for positioning the buffer cursor, such as
moving it up or down, moving it to a specific point, or overtaking an existing
line.
* `transformations` - Enables commands that transform the contents of the
buffer on a grander scale than just typing in text.
* `shell` - Enables commands which allow you to run shell commands from within
the editor. This includes the `~runhere` command that sued is special for.
* `fun` - Enables commands that do nothing of importance and are purely there
for the funny.
### editor
This group pulls in `core` as a dependency (which doesn't matter much because
that's enabled anyway).
* `repl` - enables the REPL (read-eval-print loop), allowing the editor to be
interacted with and used. **sued must have this flag enabled to work as a text editor.**
### most
This group pulls in `editor` as a dependency.
* `startup` - Enables funny randomised messages which are printed at startup,
next to the sued version number.
* `history` - Enables command history, allowing you to recall previous commands
using the up and down arrow keys.
* `lua` - Enables the Lua bindings for sued, allowing users to evaluate Lua
commands inside the editor, or run the buffer contents or external Lua files,
using the file buffer contents as a global.
**Requires the development files for Lua 5.4 to build.**
### full
This group pulls in `most` as a dependency.
* `ffi` - enables the **experimental** Foreign Function Interface (FFI) bindings
for sued, allowing C programs to utilise sued as a library. The current
exposure to the FFI is still limited - commands can only be run on a predefined
and unchangeable file buffer.
This module has largely been superseded by sued's Lua integration, which is
a frick of a lot more stable and is included in `most`.
## Documentation
sued's documentation is present [online](https://aeriavelocity.codeberg.page/sued)
in the form of a man page-like website.
sued as a library's documentation is present [on docs.rs](https://docs.rs/sued),
in the standard Rust documentation format.
sued provides the `~doc` and `~help` command to pull up documentation on each
of its editor commands. For example, `~help save` will pull up information about
the `~save` command, and `~doc search` will pull up just the documentation
(which in sued's case means "long description") on the `~search` command.
You can also just read the source code yourself.
## Features
### Accelerated
sued is written in the Rust programming language, which is perfect for combining
modern niceties with the speed of native compilation, and without all the nasty
memory nasties that C can bring you.
Its speed, as a compiled line editor, is pretty damn fast. The time between
opening it up and getting some text edited is negligently small.
### Uncomplicated
sued is much more user-friendly than ed - it's a modeless editor, so there's no
complicated mode switching to keep in your head. You're always in "insert mode".
It also uses a simple command syntax, with whole words, like `~save`, `~show`
and `~open`, instead of using single letters or weird terminology.
Its error messages, despite being communicated concisely, are still informative
and use colloquial language, so they're pretty easy to understand.
### Lightweighted
Since sued doesn't need to load a web browser interface or bundle a web engine
or even display anything graphically, it's extremely lightweight as far as
modern text editors go.
Laptop user? Your battery will thank sued for not hogging its resources just
to write up that essay, or edit that program, or even just display that log file.
sued is designed from the outset to be a singular program that only handles the
task of editing text and nothing else - it doesn't bundle any Git functionality
or LSP client or AI code completion. If you want those features, you're expected
to use another program.
### Efficient
sued looks basic on the offset, but under the hood, it has support for regex
replacements, file searching, pretty-looking line numbers, and some other stuff.
sued's command set consists of various editing commands, such as `~show` to
display file contents, `~save` to save the current file, `~search` to search
for a string of text, `~point` to set the cursor position to a line, `~substitute`
to run a regex substitution on a line, etc.
If you need help or more info, sued, much like Emacs, is self-documenting.
Just type `~cmds` or `~help` in sued for a list of commands, then `~help [command]`
or `~doc [command]` to see that command's details and/or documentation.
### Integrated
Most text editors will boast stuff like VCS, LSP, debug tool, compiler,
interpreter, linter and built-in terminal integration, basically just providing
an entire development environment in one single application.
sued, however, is not one of those - it does one thing, and it does it well.
Instead of integrating stuff into its code, sued provides the `~run` and
`~runhere` commands to run a shell command as if you ran it in your terminal,
without ever having to leave sued, and when the command is done, you're
immediately back to editing.
`~runhere` in particular is special - it will have sued create a temporary file
and run the chosen command with that temporary file as an argument, and then
when that external program is done operating on the temporary file, it's read
and synchronised with the original buffer contents.
Writing a Python script? `~runhere python`. Want to check your Markdown file
is up to scratch? `~runhere markdownlint`. Need to hop to a more powerful
editor whenever you need that power? `~runhere vim`. It's that simple.
### No-nonsense
sued is designed to not get in your way. Error messages are useful but brief.
They're not ed levels of brief, but they're still pretty brief.
And there's no auto-save feature - your file is only saved when you enter the
`~save` command.
### Ubiquitous
Being a CLI app, you can run sued anywhere!
In your terminal, in VS Code, in Emacs, even inside Vim! And sued doesn't care
what OS it runs under. Windows, macOS, GNU/Linux, BusyBox/Linux, other kinds of
Linux, BSD, ChromeOS, Android, probably Xbox if you really wanted.
Wherever Rust goes, sued can go.
Plus, as of version 0.18.0, sued can be integrated as a Rust library with your
favourite Rust programs, so you can run sued's line editing commands in your own
software, even if that software uses a *completely* different user interface!
Check out the [sued as a library README](README.lib.md) for more details.
## Fun Facts
* sued was originally going to be written in Python. I decided on Rust because
I hated the way you're supposed to publish Python packages, especially
executables. (still love Python, though)
* sued is my first "serious" project, a project that I actually dedicate time
into, not just to build a cool editor, but also to learn proper Rust
programming techniques along the way. It outlasted my other attempts at making
text editors, such as [QVSED](https://github.com/AeriaVelocity/QVSED), which
I haven't even bothered to migrate over to Codeberg yet.
* The original concept for sued was just "ed, but with user-friendly error
messages and [Streakline](https://github.com/AeriaVelocity/Streakline)'s
tilde-prefixed commands". But that obviously wouldn't stick around with a mind
as hyperactive and overflowing as mine.
* sued was going to have a visual mode in version 0.22.0, which would allow the
user to interact with the editor using Vim-style editing commands. However,
I scrapped this idea, to avoid feature creep and overcomplication of the
editor. You can always just `~runhere vim` to open the current file in Vim -
it probably would have been better than "visued".
* sued went through three software licences - the [WTFPL](https://www.wtfpl.net/),
the [GNU GPL 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), and the
current choice, the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
I only switched to Apache so that sued as a library could integrate with any
software, regardless of licence, which GPL does not permit unless the software
it's being integrated into is also GPL.
* The whole reason I decided to allow sued to be used as a Rust library is so
that I could use sued's command set and editing features in my new graphical
text editor, [Astrion](https://codeberg.org/AeriaVelocity/Astrion). Which I
should probably hop back on the development train for.
## Legal
### Licence
sued is free. By that I mean libre. By that I mean open source. Actually that's
a contentious topic, but the fact remains that sued is free.
sued (including sued as a library) is distributed under the Apache License,
Version 2.0.
This licence was chosen so that sued as a library can integrate with any
software, proprietary or otherwise, even if that software uses a different
licence.
The Apache License 2.0 means you can do whatever you want with sued, including:
* using sued as a text editor for any purpose
* using sued as a library in any software, for any purpose
* distributing sued, either as an editor or a library, in any software,
for any purpose
However, you must accept:
* sued is distributed to you on an **"as-is"** basis with no warranties
* I can't be held liable for anything going wrong, whether it's a fault within,
arising from, or completely outside the software
* you do not receive trademark rights, so you cannot use the name "sued" in your
own projects without my explicit permission
* you do not use the name "sued" or my name to endorse your project or imply
I'm endorsing your project without my explicit permission
If distributing a modified version, you additionally must:
* credit me (Arsalan "Aeri" Kazmi/AeriaVelocity) as the original author
* state any changes made to sued's source code
* retain the Apache License 2.0 document in your version
* keep the copyright, patents and trademarks of the original version of sued
Linking sued as a library (statically through Cargo or otherwise, or dynamically
linking a shared library version) does not count as modification unless the
library itself is modified.
This is a brief summarisation of the licence document and may not hold up in
a proper legal context.
See [LICENSE.txt](LICENSE.txt) for the full document.
### Naming
The name of the project is **sued**, in lowercase (i.e. not "Sued"), and the
proper pronunciation is /suːɛd/ (su like "<ins>sue</ins>", ed like
"b<ins>ed</ins>")
On its own, "sued" should be used to refer to the text editor. If the specific
parts of sued you're using is clear from context (e.g. you're building a text
editor and basing it on sued as a library), it's okay to use "sued" on its
own.
If it's not clear from context, or people don't know what you're referring to,
you should call the editor "the sued text editor", or "sued" with this Codeberg
repository linked, i.e. `[sued](https://codeberg.org/AeriaVelocity/sued/)`.
If you're only using sued as a library (i.e. sued is in your Cargo dependencies
or you're linking it as a shared library), please call it "sued as a library"
instead. If that's too verbose, you can shorten it to "using sued".
For example:
> Foobar is a text editor built on [sued as a library](https://codeberg.org/AeriaVelocity/sued/tree/main/README.lib.md).
or
> Foobar is built using [sued](https://codeberg.org/AeriaVelocity/sued/tree/main/README.lib.md).
If you make a project based on sued as a library (i.e. an editor frontend or
your own custom editing commands), you're free to use the "sued" name in that
project.
For example, a reimplementation of Vim using sued as a library might be called
"visued".
However, you do so with the knowledge that it's not an endorsement of your
project, either by me or any future contributors.