Module conciliator::edit

source ·
Expand description

Edit text using $EDITOR

Claw::edit will open the user’s text editor with a temporary file containing some text for the user to edit. After the editor exits, the file is read and its content returned. Optionally, the content may be parsed and validated, such that any errors (i.e. TOML syntax errors) are reported to the user immediately and they are given the option to try again, until either the validation succeeds or the user aborts the procedure.

§Edit & Editable

The Edit trait defines how (if at all) a type is serialized before and deserialized / validated after editing.
This crate provides 2 implementations: plain text editing on &str simply returning the string as the user has edited it, as well as the structured TomlEditor, which serializes and then parses the item to be edited using serde and toml.

Editable serves as a “proxy” for Edit (it could have been called IntoEdit). This way, any type can use a wrapper like TomlEditor instead of implementing Edit itself without forcing you to explicitly specify the wrapper every time.
To make this even easier, the edit_as_toml macro implements Editable for any T: Serialize + DeserializeOwned.
Obviously, any type that is Edit directly is also Editable.

§Editor Program

If the $EDITOR environment variable is set, it is used as the command to launch the editor (with the first and only argument being the path of the temporary file). Otherwise, the user is given the option to specify a command to use. If refused, this method returns Edited::Cancelled.

Notably, only a value that is an executable in the users $PATH will work. This excludes aliases and commands with arguments like subl -w because that would require going through the shell. If you encounter the error No such file or directory (os error 2), this may be the reason.

§Security

Claw::edit should under no circumstances be used in a process (i.e. setuid executables) with elevated privileges that the user does not otherwise have access to.

§Examples

Plain text:

use conciliator::{Conciliator, edit::Edited};
let con = conciliator::init();
match con.edit("Test123 :^)") { 
    Edited::Ok(s) => con.status(format!("Edited:\n{s}")),
    Edited::Cancelled => con.info("Edit aborted!"), 
    Edited::Err(e) => con.error(format!("{e:?}")) 
};

Using TOML:

use serde::{Serialize, Deserialize};
use conciliator::{Conciliator, edit::{Edited, edit_as_toml}};
let con = conciliator::init();
 
#[derive(Debug, Serialize, Deserialize)]
struct Entry {
    id: usize,
    name: String
}
edit_as_toml!(Entry);
 
let entry = Entry {id: 3, name: "Entry".to_owned()};
 
match con.edit(entry) {
    Edited::Ok(s) => con.status(format!("Edited entry:\n{s:?}")),
    Edited::Cancelled => con.info("Edit aborted!"),
    Edited::Err(e) => con.error(format!("{e:?}"))
};

Macros§

Structs§

Enums§

Traits§