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§
- Implement
Editable
for a typeT: Serialize + DeserializeOwned
Structs§
- Wrapper type to
Edit
something using TOML
Enums§
- Errors encountered during
Claw::edit
- Outcome of the
Claw::edit
function