fzf_wrapped/

lib.rs

//! # fzf-wrapper
//!
//! A library for integrating the `fzf` cli tool into your rust program!
//!
//! This library provides bindings for integrating the `fzf` cli program into your rust
//! projects.
//!
//! **NOTE** this does mean that the end user must have `fzf` installed on their system.
//!
//! #### fzf version
//! 
//! This crate was developed with `fzf` v0.40.0 in mind, however there should be no reason why it
//! shouldn't work above it, and most of the features should work below it. If your program relies
//! on v0.40.0 features, it might be a good idea to check the version of `fzf` your program has
//! access to
//!
//! ## Example
//!
//! Say we're wanting to get the user to select their favourite colour using the power of fuzzy
//! finding. First we'd create a list of colours, which will be a collection we'll pass to `fzf`
//!
//! ```rust
//! let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//! ```
//!
//! The next step is to construct an instance of [`Fzf`] and start it:
//!
//! ```rust
//! let mut fzf = Fzf::default();
//!
//! fzf.run().expect("Failed to start fzf");
//! ```
//!
//! The code above fetches the default [`Fzf`] configuration, which runs `fzf` with no arguments,
//! and then calls the `run()` method. This displays `fzf` to the user.
//!
//! At the moment all that will be displayed is a blank screen, as we haven't actually told `fzf`
//! to display anything. There are two ways to do this, the `add_item()` method, and the
//! `add_items()` method. They are both nearly identical, with the only difference being that
//! `add_items()` takes a [`Vec`] of [`String`]'s as items, and passes them one by one to
//! `add_item()`.
//!
//! ```rust
//! # let mut fzf = Fzf::default();
//! # fzf.run().expect("Failed to start fzf");
//! fzf.add_items(colours).expect("Failed to add items");
//! ```
//!
//! The only thing left to do is to get what the user selected! This will be returned as an
//! [`Option`] containing `None` if the user exited `fzf`, or `Some(String)` with the string being
//! the item they selected. To get the output we simply call the `output()` method, which will
//! blocks execution until the user selects an item with `fzf`
//!
//! ```rust
//! # let mut fzf = Fzf::default();
//! # fzf.run().expect("Failed to start fzf");
//! # fzf.add_items(colours).expect("Failed to add items");
//! let users_selection = fzf.output().expect("Failed to get the user's output");
//! ```
//!
//! The code in it's entirety looks like the following. 
//! 
//! ```rust
//! use fzf_wrapped::Fzf;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!     
//!     let mut fzf = Fzf::default();
//!     fzf.run().expect("Failed to start fzf");
//!
//!     fzf.add_items(colours).expect("Failed to add items");
//!
//!     let users_selection = fzf.output().expect("Failed to get the user's output");
//! }
//! ```
//!
//! This operation of using `fzf` to select from a predetermined [`Vec`] of items is so common that
//! a helper function exists to streamline the work involved. Using it, the code looks like the 
//! following:
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!     
//!     let users_selection = run_with_output(Fzf::default(), colours).expect("Something went wrong!");
//! }
//! ```
//!
//! ## Running `fzf` with arguments
//!
//! Now, our favourite color picker program is pretty cool, but our `fzf` interface is a bit
//! confusing, how are our user's supposed to know what they're picking?
//!
//! Thankfully `fzf` provides many different ways to customize it, many of which have been
//! implemented in this library. So far we have been calling the [`Fzf`] structs default
//! implementation, however we can build more complex instances using [`FzfBuilder`]. 
//!
//! We can use two different ways to get an [`FzfBuilder`], either through it's own `new()` method,
//! or the `builder()` method on [`Fzf`]. Let's switch out the default call for a builder call.
//!
//! ```rust
//! let fzf = Fzf::builder().build().unwrap();
//!
//! let users_selection = run_with_output(fzf, colours).expect("Something went wrong!");
//! ```
//!
//! **NOTE**: It is safe to unwrap the `build()` call, as every field has a default implementation.
//!
//! If we run the program now, we'll notice... nothing has changed. This is because the `default()`
//! method calls the exact line of code we just replaced it with.
//!
//! Let's make things interesting! First we should probably give the finder a label. Without a 
//! border, the label won't show so lets give it a border too! 
//!
//! ### Adding a border and border label
//!
//! If you were using `fzf` straight from the command line, you would pass it the `--border` flag
//! with the name of one of the supported types of borders, however this can lead to errors if the
//! border doesn't exist. For this reason, `fzf-wrapped` makes use of enums to ensure that these
//! choices are always valid! For example, to choose a border we'd call the `border()` method on
//! our [`FzfBuilder`], contain our chosen variant of the [`Border`] enum.
//!
//! Adding a rounded border makes our code look like this:
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::Border;
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!
//!     let fzf = Fzf::builder()
//!         .border(Border::Rounded)
//!         .build()
//!         .unwrap();
//!     
//!     let users_selection = run_with_output(fzf, colours);
//! }
//! ```
//!
//! And adding a label is even more simple
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::Border;
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!
//!     let fzf = Fzf::builder()
//!         .border(Border::Rounded)
//!         .border_label("Favourite Colour")
//!         .build()
//!         .unwrap();
//!     
//!     let users_selection = run_with_output(fzf, colours);
//! }
//! ```
//!
//! Running this should display an `fzf` finder with a rounded border, and a centered label
//! containing "Favourite Colour".
//!
//! ### Changing the layout of `fzf`
//!
//! Well, now that we've got a border, we may as well change up the layout. This is almost
//! identical to changing the border, as all possible layout's are mapped to an enum.
//!
//! All we need to add to our builder is the `layout()` method with our chosen [`Layout`] variant
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::{Border, Layout};
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!
//!     let fzf = Fzf::builder()
//!         .layout(Layout::Reverse)
//!         .border(Border::Rounded)
//!         .border_label("Favourite Colour")
//!         .build()
//!         .unwrap();
//!     
//!     let users_selection = run_with_output(fzf, colours);
//! }
//! ```
//!
//! ### Choosing colours
//!
//! `fzf` lets us pick from a few colour themes, but for this one we're going to keep it simple and
//! use the black and white theme. Similar to borders and the layout, this is selected using an
//! enum. Adding it to our builder results in the following code:
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::{Border, Color, Layout};
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!
//!     let fzf = Fzf::builder()
//!         .layout(Layout::Reverse)
//!         .border(Border::Rounded)
//!         .border_label("Favourite Colour")
//!         .color(Color::Bw)
//!         .build()
//!         .unwrap();
//!     
//!     let users_selection = run_with_output(fzf, colours);
//! }
//! ```
//!
//! If you run the program now, you'll notice that the ui is in black and white!
//!
//! ### Adding a header
//!
//! Our user might still be confused about what they're picking, so to add some more context, `fzf`
//! lets us set a header. To do this all we do is call the `header()` method on our [`FzfBuilder`] 
//! struct, and pass it anything with the `Into<String>` trait. We also want the header to appear
//! above our search field, so we'll call the `header_first()` method with `true`.
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::{Border, Color, Layout};
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!
//!     let fzf = Fzf::builder()
//!         .layout(Layout::Reverse)
//!         .border(Border::Rounded)
//!         .border_label("Favourite Colour")
//!         .color(Color::Bw)
//!         .header("Pick your favourite colour")
//!         .header_first(true)
//!         .build()
//!         .unwrap();
//!     
//!     let users_selection = run_with_output(fzf, colours);
//! }
//! ```
//!
//! ### Using an argument not supported by `fzf_wrapped`
//!
//! If by chance the argument you want to run with `fzf` is not a method included on the [`Fzf`]
//! struct, do not worry! The `custom_args()` command will let you pass any argument you want! For
//! example, say we wanted to make our colour picker program not take up the full screen, say only
//! 10% of it. `fzf` has the `--height=` flag, however the [`Fzf`] struct doesn't support it! To
//! add it all we'll need to do is to call the `custom_args()` command on our builder, and the
//! arguments we pass into it will be run with the `run()` method.
//!
//! Implementing it would look like:
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::{Border, Color, Layout};
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!
//!     let fzf = Fzf::builder()
//!         .layout(Layout::Reverse)
//!         .border(Border::Rounded)
//!         .border_label("Favourite Colour")
//!         .color(Color::Bw)
//!         .header("Pick your favourite colour")
//!         .header_first(true)
//!         .custom_args(vec!["--height=10".to_string()])
//!         .build()
//!         .unwrap();
//!     
//!     let users_selection = run_with_output(fzf, colours);
//!
//!     if let Some(colour) = users_selection {
//!         println!("{} is an awesome colour!", colour);
//!     }
//! }
//! ```
//!
//! And with that, our program is almost done!
//!
//! All we need to do is print some kind of nice message, and while we're at it, we may as well use
//! some proper error handling.
//!
//! ```rust
//! use fzf_wrapped::Fzf;
//! use fzf_wrapped::{Border, Color, Layout};
//! use fzf_wrapped::run_with_output;
//!
//! fn main() {
//!     let colours = vec!["red", "orange", "yellow", "green", "blue", "indigo", "violet"];
//!
//!     let fzf = Fzf::builder()
//!         .layout(Layout::Reverse)
//!         .border(Border::Rounded)
//!         .border_label("Favourite Colour")
//!         .color(Color::Bw)
//!         .header("Pick your favourite colour")
//!         .header_first(true)
//!         .custom_args(vec!["--height=10".to_string()])
//!         .build()
//!         .unwrap();
//!     
//!     let users_selection = run_with_output(fzf, colours);
//!
//!     if let Some(colour) = users_selection {
//!         println!("{} is an awesome colour!", colour);
//!     }
//! }
//! ```
//!
//! ## Adding Items at runtime of `fzf`
//!
//! With the power of this library, you can use `fzf` to select from a list of items, even if those
//! items have not been fetched yet. Using the `add_item` and `add_items` method adds items to 
//! `fzf`'s list, even while fzf is running. This means that if you're calling information from a 
//! REST api, you can display result's as they come in straight to `fzf`, or even hide the slight 
//! delay by starting up `fzf`.
//!
//! For an example of this, look at my [workflows](https://github.com/danielronalds/workflows) project


mod options;
pub use options::*;
mod fzf;
pub use fzf::*;

/// Runs the given [`Fzf`] struct and returns the user's selection as a [`String`]
///
/// # Parameters
///
/// - `items` The items to to display in `fzf`
///
/// # Returns
///
/// An option containing either the users selection as a [`String`], or `None` if the user quit `fzf`
pub fn run_with_output(fzf: Fzf, items: impl IntoIterator<Item = impl Into<String>>) -> Option<String> {
    let mut fzf = fzf;
    fzf.run().ok()?;
    fzf.add_items(items).ok()?;
    fzf.output()
}