# sued as a library
> [!NOTE]
> This page is about sued as a text editing library. For sued as a text editor,
> see [README.md](README.md).
sued is a stateless vector-oriented command-based text editor written in Rust,
with focus on speed, simplicity, ease of use and staying the hell out of your
way. And now, it's a library!
As of version 0.18.0, the [sued text editor](README.md) can be integrated into
your own programs as a vector-based text editing library.
## Usage
### Installing sued as a library
```bash
cargo add sued
```
### Using sued in your program
Let's say, for the sake of argument, you're making a silly little program
about cake.
There are *two main ways* to utilise sued as a library - the low-level way
through **direct functions** via the `suedfn` module, and the high-level way via
**processing sued commands** through the editor's own `process_command`
function.
#### suedfn (Direct sued Functions)
The `suedfn` module allows you to run sued's commands directly, although this
typically requires working with `Vec<String>` (not `Vec<&str>`), which can be
cumbersome but effective if all you need is the functionality.
It's a bit like writing a program by manually typing out all the ones and zeroes
in a hex editor. It's possible, sure, and fast if you know what you're doing,
but it's cumbersome and difficult and... why don't you just use a programming
language? (Or in sued's case, why not just use `process_command`?)
It's what the text editor side of sued uses to work as a text editor, but
it's not very comfortable for integration as a library. Regardless, here's how
you can access sued's functions directly, with `suedfn`:
```rust
use sued::{ExitStatus, suedfn};
fn main() {
let cakes: Vec<String> = vec![
"chocolate".to_string(),
"vanilla".to_string(),
"strawberry".to_string()
];
let mut cake = String::new();
println!("Welcome to the Cake Shop!");
loop {
println!("Please choose a cake from our list:");
// sued uses one-based indices, not zero-based
suedfn::show(&cakes, 1, cakes.len(), true);
std::io::stdin().read_line(&mut cake).unwrap();
let cake = cake.trim();
let cake = cake.to_lowercase();
match cake.as_str() {
"chocolate" | "vanilla" | "strawberry" => {
println!("You ordered a {} cake.", cake);
break;
}
"exit" => {
println!("Thanks for visiting the Cake Shop!");
break;
}
_ => {
println!("We don't stock that cake. Please try again.");
}
}
}
let receipt: Vec<String> = vec![
"== Order ==".to_string(),
format!("Cake: {}", cake).to_string(),
"== Total ==".to_string(),
"£19.99".to_string()
];
println!("{:?}", receipt);
suedfn::save(&receipt, "receipt.txt");
println!("Thanks for visiting the Cake Shop!");
}
```
That works, but you may as well be manipulating the text directly. It's useful,
sure, but it's not very comprehensive and doesn't give you the proper sued
experience. You really might as well be using [regex](https://github.com/rust-lang/regex)
or [sd](https://github.com/chmln/sd) or... really just anything that's on the
[Text processing](https://lib.rs/text-processing) list on the lib.rs website.
#### `process_command` (Parsing sued Commands)
Now we move onto the real meat and potatoes - processing sued's commands
through the editor's very own `process_command` function! This allows you to
enter sued commands as `Vec<&str>` lines, which will then be parsed and
processed by the editor.
But you probably don't want to write `Vec<Vec<&str>>`s every time you just want
to represent some commands, so there's an easy way to use a simple `Vec<&str>`
instead - through the `vecify_command` function. This will split a `&str` into
a `Vec<&str>` for you, so you can iterate over a `Vec<&str>` and pass each
command through `process_command`.
Here's how you can use `process_command` and `vecify_command` to do things the
sued way:
```rust
use sued::{FileBuffer, process_command, vecify_command};
fn main() {
// FileBuffer MUST be mutable, since `process_command` expects a mutable reference.
let mut cakes: FileBuffer = FileBuffer {
contents: vec!["chocolate".to_string(), "vanilla".to_string(), "strawberry".to_string()],
file_path: None,
};
let mut cake = String::new();
println!("Welcome to the Cake Shop!");
loop {
println!("Please choose a cake from our list:");
process_command(vecify_command("show"), &mut cakes);
std::io::stdin().read_line(&mut cake).unwrap();
let cake = cake.trim();
let cake = cake.to_lowercase();
match cake.as_str() {
"chocolate" | "vanilla" | "strawberry" => {
println!("You ordered a {} cake.", cake);
break;
}
"exit" => {
println!("Thanks for visiting the Cake Shop!");
break;
}
_ => {
println!("We don't stock that cake. Please try again.");
}
}
}
let mut receipt: FileBuffer = FileBuffer {
contents: vec![
"== Order ==".to_string(),
format!("Cake: {}", cake).to_string(),
"== Total ==".to_string(),
"£19.99".to_string()
],
file_path: Some("receipt.txt".to_string())
};
println!("{}", receipt);
process_command(vecify_command("save receipt.txt"), &mut receipt);
println!("Thanks for visiting the Cake Shop!");
}
```
This code is much more in-line with why `sued` is even a library in the first
place - **to provide the functions and features of the [sued text editor](README.md)
into other text editors or other programs that work with text.**
This is just a simple example, but you can do so much more with this - wherever
you edit text, you can probably integrate sued somewhere in there.
## Why?
I started a new text editor project, [Astrion](https://codeberg.org/AeriaVelocity/astrion),
and I wanted to see if I could integrate sued into it. Since sued's code is
very lightweight, it wasn't hard to just refactor its text editing capabilities
into a library that I could use in other projects.
So, here you go! sued as a library. Thanks and have fun.
## Licence
sued is licensed under the GNU GPL v3, same as its text editor side.