sued - shut up editor

[!NOTE] This page is about sued as a text editor. For sued as a library, see README.lib.md.

sued is a minimalist line-based text editor written in Rust, inspired by classical Unix text editors, such as the ed text editor from the '70s, and its descendants, such as Vim, 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 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. If you don't want to install Rust, frick off and use a different editor.

Run

# 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:

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'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 in the form of a man page-like website.

sued as a library's documentation is present on docs.rs, 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 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, 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'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, the GNU GPL 3.0, and the current choice, the Apache 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. 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
• 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

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 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 "sue", ed like

"bed")

Please only call the project "sued" if you're referring to the complete package - comprised of sued's text editing components and sued as a library.

If you're strictly referring to sued's text editing components (such as the REPL and everything as part of main.rs but not lib.rs or any other module), please explicitly refer to it as "sued's text editing components". The name "sued" on its own should be reserved for the complete package.

If you're only using sued as a library (i.e. sued is in your Cargo dependencies or you're dynamically linking a shared library you compiled yourself), please call it "sued as a library" or "suedlib" instead.

For example, you might say:

Foobar is a text editing utility built on sued as a library.

or

Foobar is built using suedlib.

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".