Scrawl

Rust library that opens a user's text editor and returns the results as a string. Can be used to open and edit exisiting files, or just as a scratch space for input. Useful for having a user edit text inline with a CLI program a la git commit -m

Built for my new (under development) daily journaling program in Rust: Echo

Quick Start

use scrawl;

fn main() {
    // Open an empty buffer with the user's preferred text editor
    let output = scrawl::new()?;
    println!("User Input: {}", output);

    // Open a buffer with text from a string in the text editor
    let output = scrawl::with("Favorite color: ")?;
    println!("{}", output);

    // Open a buffer with text from a file in the text editor
    let output = scrawl::open("survey.txt")?;
    println!("{}", output);

    // Open a file for direct editing in the text editor
    let output = scrawl::edit("README.md")?;
    println!("{}", output);
}

Editor Struct

The Editor struct allows you to set certain options before opening the editor. It also allows you resuse these settings instead of having to build them each time you want to use an editor. Run edit() on the struct to open the buffer.

use scrawl::editor::Editor;

fn main() {
    let editor = Editor::new()
                        .contents("My favorite color is: ")
                        .extension(".txt")
                        .trim(true);

    let fave_color = editor.edit().unwrap();

    /* Change the prompt, keep other settings the same */
    editor.contents("My favorite bird is: ");
    let fave_bird = editor.edit().unwrap();

    println!("About Me:\n{}\n{}", fave_color, fave_bird);
}

If you want to open a one off editor without using settings, see the Functions section below.

Settings

Editor

You can set a preferred text editor for the user. Otherwise, $VISUAL, $EDITOR or "textpad.exe"/"vi" is used as a fallback if none is set.

let output = Editor::new().editor("vim").edit()?;

File

You can set a file from which the text buffer will be seeded. If the file has an extension, this will also set the extension of the temporary buffer. This will not modify the file.

let output = Editor::new().file("my_survey.txt").edit()?;

Contents

You can use a string to seed the text buffer.

let output = Editor::new().contents("Favorite Number: ").edit()?;

Extension

Set the extension of the temporary file created as a buffer. Useful for hinting to text editors which syntax highlighting to use.

let output = Editor::new().extension(".rs").edit()?;

Trim

Trim leading and trailing whitespace from the result. Enabled by default.

let output = Editor::new().trim(false).edit()?;

Edit Directly

If file is set, this will open that file for editing (instead of a temporary file) and any changes made will be reflected to that file. Disabled by default.

let output = Editor::new().file("lib.rs").edit_directly(true).edit()?;

Functions

These functions are provided for convenience. Useful for prototyping, or if you don't want to build and maintain a struct just to open an editor.

New

Open an empty text buffer in the user's preferred editor. Returns a Result with the contents of the buffer.

use scrawl;

fn main() {
    let output = match scrawl::new(path) {
        Ok(s) => s,
        Err(e) => e.to_string()
    };
    println!("{}", output);
}

With

Open an text buffer with the contents of the String slice in the user's preferred editor. Returns a Result with the contents of the buffer.

use scrawl;

fn main() {
    let output = match scrawl::with("Hello World!") {
        Ok(s) => s,
        Err(e) => e.to_string()
    };
    println!("{}", output);
}

Open

Open opens a text buffer in an editor with the contents of the file specified. This does not edit the contents of the file. Returns a Result with the contents of the buffer.

use scrawl;
use std::path::Path;

fn main() {
    let path = Path::new("hello.txt");
    let output = match scrawl::open(path) {
         Ok(s) => s,
         Err(e) => e.to_string()
    };
    println!("{}", output);
}

Edit

Edit opens a text buffer in an editor with the contents of the file specified. This does edit the contents of the file. Returns a Result with the contents of the buffer.

use scrawl;
use std::path::Path;

fn main() {
    let path = Path::new("hello.txt");
    let output = match scrawl::edit(path) {
         Ok(s) => s,
         Err(e) => e.to_string()
    };
    println!("{}", output);
}