duat_core/cmd/

mod.rs

//! Creation and execution of commands.
//!
//! Commands on Duat are bits of code that can be executed on the
//! [`PromptLine`] widget. They can also be invoked from other parts
//! of the code, but their use is mostly intended for user calls.
//!
//! # Running commands
//!
//! There are two environments where you'd run commands. When you have
//! a [`Pass`] available, and when you don't.
//!
//! ## When you have a [`Pass`]
//!
//! If you have a `Pass` available, it means you are in the main
//! thread of execution, and can safely execute commands. The
//! advantage of using a `Pass` is that you can retrieve the value
//! returned by the command:
//!
//! ```rust
//! # duat_core::doc_duat!(duat);
//! setup_duat!(setup);
//! use duat::prelude::*;
//! fn main_thread_function(pa: &mut Pass) {
//!     let result = cmd::call(pa, "colorscheme solarized");
//!     if result.is_ok() {
//!         context::info!("[a]Awesome!");
//!     }
//! }
//! ```
//!
//! The code above runs the `colorscheme` command. In this case, if
//! the command succeds or fails, no notification will be shown, if
//! you want notifications, you should use [`cmd::call_notify`], and
//! the return value would still be acquired.
//!
//! ## When you don't have a [`Pass`]
//!
//! you may not have a `Pass` if, for example, you are not on the
//! main thread of execution. In this case, there is [`cmd::queue`],
//! which queues up a call to be executed later.
//! This means that you can't retrieve the return value, since it will
//! be executed asynchronously:
//!
//! ```rust
//! # duat_core::doc_duat!(duat);
//! setup_duat!(setup);
//! use duat::prelude::*;
//! fn on_a_thread_far_far_away() {
//!     cmd::queue("set-form --flag -abc punctuation.delimiter rgb 255 0 0 hsl 1");
//! }
//! ```
//!
//! The `set-form` command above will fail, since the hsl [`Color`]
//! [`Parameter`] was not completely matched, missing the saturation
//! and lightness arguments. It also shows two flag arguments, word
//! flags (`"--flag"`) and blob flags (`"-abc"`). Even failing, no
//! notification will be sent, because I called [`queue`], if you want
//! notifications, call [`queue_notify`].
//!
//! If you want to "react" to the result of a queued call, you can use
//! the [`cmd::queue_and`] function, which lets you also send a
//! function that takes [`CmdResult`] as parameter:
//!
//! ```rust
//! # mod duat { pub mod prelude { pub use duat_core::cmd; } }
//! # use std::sync::atomic::{AtomicUsize, Ordering};
//! use duat::prelude::*;
//!
//! static FAILURE_COUNT: AtomicUsize = AtomicUsize::new(0);
//!
//! fn on_a_thread_far_far_away() {
//!     cmd::queue_and(
//!         "set-form --flag -abc punctuation.delimiter rgb 255 0 0 hsl 1",
//!         |res| {
//!             if res.is_err() {
//!                 FAILURE_COUNT.fetch_add(1, Ordering::Relaxed);
//!             }
//!         },
//!     );
//! }
//! ```
//!
//! Note that, because this function might be sent to another thread,
//! it must be [`Send + 'static`].
//!
//! # Adding commands
//!
//! Commands are added through the [`add!`] macro. This macro takes in
//! two arguments. The first argument is a list of callers, for
//! example `["quit", "q"]`, or just a caller, like `"reload"`.
//!
//! The second argument is a _rust-like_ "closure" that receives a
//! variable number of [`Parameter`]s as arguments, alongside a
//! [`Pass`]. Inside of this "closure", you will have access to the
//! ful breatdh of duat's shareable state (just like any other time
//! you have a `Pass`).
//!
//! Most Rust [`std`] types (that would make sense) are implemented as
//! [`Parameter`]s, so you can place [`String`]s, [`f32`]s, [`bool`]s,
//! and all sorts of other types as `Parameter`s for your command.
//!
//! Types like [`Vec`] and [`Option`] are also implemented as
//! [`Parameter`]s, so you can have a list of `Parameter`s or an
//! optional `Parameter`.
//!
//! ```rust
//! # mod duat { pub mod prelude { pub use duat_core::{
//! #     cmd, data::Pass, form::{self, Form}, text::txt
//! # };}}
//! use duat::prelude::*;
//!
//! let callers = ["unset-form", "uf"];
//! // A `Vec<T>` parameter will try to collect all
//! // remaining arguments as `T` in a list.
//! let result = cmd::add!(callers, |pa: &mut Pass, forms: Vec<cmd::FormName>| {
//!     for form in forms.iter() {
//!         form::set("form", Form::new());
//!     }
//!     // You can return a success message, but must
//!     // return an error message if there is a problem.
//!     // For those, you should use the `txt!` macro.
//!     Ok(Some(txt!("Unset [a]{}[] forms", forms.len())))
//! });
//! ```
//!
//! In the command above, you'll notice that [`Ok`] values return
//! [`Option<Text>`]. This is because you may not care about
//! announcing that the command succedeed. For the [`Err`] variant,
//! however, the return value is just [`Text`], because you should say
//! what went wrong in the command. Most of the time, this happens
//! because of something out of your control, like a buffer not
//! existing. In these cases, the `?` is enough to return an
//! appropriate `Text`.
//!
//! There are other builtin types of [`Parameter`]s in `cmd` that
//! can be used on a variety of things. For example, the [`Remainder`]
//! `Parameter` is one that just takes the remaining arguments and
//! collects them into a single [`String`].
//!
//! ```rust
//! # duat_core::doc_duat!(duat);
//! setup_duat!(setup);
//! use duat::prelude::*;
//!
//! cmd::add!("pip", |_pa, args: cmd::Remainder| {
//!     let child = std::process::Command::new("pip").spawn()?;
//!     let res = child.wait_with_output()?;
//!
//!     Ok(Some(txt!("{res:?}")))
//! });
//! ```
//!
//! [`PromptLine`]: https://docs.rs/duat/latest/duat/widgets/struct.PromptLine.html
//! [`cmd::call_notify`]: call_notify
//! [`cmd::queue`]: queue
//! [`cmd::queue_and`]: queue_and
//! [`Send + 'static`]: Send
//! [`Color`]: crate::form::Color
//! [`txt!`]: crate::text::txt
//! [`Ok(Some({Text}))`]: Ok
//! [`Form`]: crate::form::Form
//! [`Handle`]: crate::context::Handle
use std::{
    collections::HashMap,
    fmt::Display,
    ops::Range,
    sync::{Arc, LazyLock},
};

use crossterm::style::Color;

pub use self::{global::*, parameters::*};
use crate::{
    buffer::{Buffer, PathKind},
    context::{self, Handle, sender},
    data::{Pass, RwData},
    form::FormId,
    mode,
    session::DuatEvent,
    text::{Text, txt},
    ui::{Node, Widget},
};

mod parameters;

/// Adds all the usual session commands
pub(crate) fn add_session_commands() {
    add!("alias", |pa, alias: &str, command: Remainder| {
        crate::cmd::alias(pa, alias, command)
    });

    add!(["quit", "q"], |pa, handle: Option<Buffer>| {
        let handle = match handle {
            Some(handle) => handle,
            None => context::current_buffer(pa).clone(),
        };

        let buffer = handle.read(pa);
        if buffer.text().has_unsaved_changes() && buffer.exists() {
            return Err(txt!("{} has unsaved changes", buffer.name()));
        }

        context::windows().close(pa, &handle)?;

        Ok(Some(txt!("Closed [buffer]{}", handle.read(pa).name())))
    });

    add!(["quit!", "q!"], |pa, handle: Option<Buffer>| {
        let handle = match handle {
            Some(handle) => handle,
            None => context::current_buffer(pa).clone(),
        };

        context::windows().close(pa, &handle)?;

        Ok(Some(txt!("Forcefully closed {}", handle.read(pa).name())))
    });

    add!(["quit-all", "qa"], |pa| {
        let windows = context::windows();
        let unwritten = windows
            .buffers(pa)
            .filter(|handle| {
                let buffer = handle.read(pa);
                buffer.text().has_unsaved_changes() && buffer.exists()
            })
            .count();

        if unwritten == 0 {
            sender().send(DuatEvent::Quit).unwrap();
            Ok(None)
        } else if unwritten == 1 {
            Err(txt!("There is [a]1[] unsaved buffer"))
        } else {
            Err(txt!("There are [a]{unwritten}[] unsaved buffers"))
        }
    });

    add!(["quit-all!", "qa!"], |_pa| {
        sender().send(DuatEvent::Quit).unwrap();
        Ok(None)
    });

    add!(["write", "w"], |pa, path: Option<ValidBuffer>| {
        let handle = context::current_buffer(pa).clone();
        let buffer = handle.write(pa);

        let (bytes, name) = if let Some(path) = path {
            (buffer.save_to(&path)?, path)
        } else if let Some(name) = buffer.name_set() {
            (buffer.save()?, std::path::PathBuf::from(name))
        } else {
            return Err(txt!("Buffer has no name path to write to"));
        };

        match bytes {
            Some(bytes) => Ok(Some(txt!("Wrote [a]{bytes}[] bytes to [buffer]{name}"))),
            None => Ok(Some(txt!("Nothing to be written"))),
        }
    });

    add!(["write-quit", "wq"], |pa, path: Option<ValidBuffer>| {
        let handle = context::current_buffer(pa).clone();

        let (bytes, name) = {
            let buffer = handle.write(pa);
            let bytes = if let Some(path) = path {
                buffer.save_quit_to(path, true)?
            } else {
                buffer.save_quit(true)?
            };
            (bytes, buffer.name())
        };

        context::windows().close(pa, &handle)?;

        match bytes {
            Some(bytes) => Ok(Some(txt!(
                "Closed [buffer]{name}[], writing [a]{bytes}[] bytes"
            ))),
            None => Ok(Some(txt!("Closed [buffer]{name}[]"))),
        }
    });

    add!(["write-all", "wa"], |pa| {
        let windows = context::windows();

        let mut written = 0;
        let handles: Vec<_> = windows
            .buffers(pa)
            .filter(|handle| handle.read(pa).path_set().is_some())
            .collect();

        for handle in &handles {
            written += handle.write(pa).save().is_ok() as usize;
        }

        if written == handles.len() {
            Ok(Some(txt!("Wrote to [a]{written}[] buffers")))
        } else {
            let unwritten = handles.len() - written;
            let plural = if unwritten == 1 { "" } else { "s" };
            Err(txt!("Failed to write to [a]{unwritten}[] buffer{plural}"))
        }
    });

    add!(["write-all-quit", "waq"], |pa| {
        let windows = context::windows();

        let mut written = 0;
        let handles: Vec<_> = windows
            .buffers(pa)
            .filter(|handle| handle.read(pa).path_set().is_some())
            .collect();
        for handle in &handles {
            written += handle.write(pa).save_quit(true).is_ok() as usize;
        }

        if written == handles.len() {
            sender().send(DuatEvent::Quit).unwrap();
            Ok(None)
        } else {
            let unwritten = handles.len() - written;
            let plural = if unwritten == 1 { "" } else { "s" };
            Err(txt!("Failed to write to [a]{unwritten}[] buffer{plural}"))
        }
    });

    add!(["write-all-quit!", "waq!"], |pa| {
        let handles: Vec<_> = context::windows().buffers(pa).collect();

        for handle in handles {
            let _ = handle.write(pa).save_quit(true);
        }

        sender().send(DuatEvent::Quit).unwrap();
        Ok(None)
    });

    add!(["reload"], |_pa, flags: Flags, profile: Option<String>| {
        sender()
            .send(DuatEvent::RequestReload(crate::session::ReloadEvent {
                clean: flags.word("clean"),
                update: flags.word("update"),
                profile: profile.unwrap_or(crate::utils::profile().to_string()),
            }))
            .unwrap();

        // This has to be done on Windows, since you can't remove
        // loaded dlls. Thus, we need to quit the curent
        // configuration first, and then we can start compiling the
        // new version of the config crate.
        #[cfg(target_os = "windows")]
        sender().send(DuatEvent::ReloadSucceeded).unwrap();

        Ok(None)
    });

    add!(["edit", "e"], |pa, arg: PathOrBufferOrCfg| {
        let windows = context::windows();

        let pk = match arg {
            PathOrBufferOrCfg::Cfg => {
                PathKind::from(crate::utils::crate_dir()?.join("src").join("lib.rs"))
            }
            PathOrBufferOrCfg::CfgManifest => {
                PathKind::from(crate::utils::crate_dir()?.join("Cargo.toml"))
            }
            PathOrBufferOrCfg::Path(path) => PathKind::from(path),
            PathOrBufferOrCfg::Buffer(handle) => {
                mode::reset_to(handle.to_dyn());
                return Ok(Some(txt!("Switched to {}", handle.read(pa).name())));
            }
        };

        let buffer = Buffer::new(pk.as_path(), *crate::session::FILE_CFG.get().unwrap());
        let handle = windows.new_buffer(pa, buffer);
        context::set_current_node(pa, handle);

        return Ok(Some(txt!("Opened {pk}")));
    });

    add!(["open", "o"], |pa, arg: PathOrBufferOrCfg| {
        let windows = context::windows();

        let (pk, msg) = match arg {
            PathOrBufferOrCfg::Cfg => (
                PathKind::from(crate::utils::crate_dir()?.join("src").join("lib.rs")),
                None,
            ),
            PathOrBufferOrCfg::CfgManifest => (
                PathKind::from(crate::utils::crate_dir()?.join("Cargo.toml")),
                None,
            ),
            PathOrBufferOrCfg::Path(path) => (PathKind::from(path), None),
            PathOrBufferOrCfg::Buffer(handle) => {
                let pk = handle.read(pa).path_kind();
                let (win, ..) = windows.buffer_entry(pa, pk.clone()).unwrap();
                if windows.get(pa, win).unwrap().buffers(pa).len() == 1 {
                    (pk.clone(), Some(txt!("Switched to {pk}")))
                } else {
                    (pk.clone(), Some(txt!("Moved {pk} to a new window")))
                }
            }
        };

        let file_cfg = *crate::session::FILE_CFG.get().unwrap();
        let node = windows.open_or_move_to_new_window(pa, pk.clone(), file_cfg);

        return Ok(msg.or_else(|| Some(txt!("Opened {pk} on new window"))));
    });

    add!(["buffer", "b"], |pa, handle: OtherBuffer| {
        mode::reset_to(handle.to_dyn());
        Ok(Some(txt!("Switched to [buffer]{}", handle.read(pa).name())))
    });

    add!("next-buffer", |pa, flags: Flags| {
        let windows = context::windows();
        let handle = context::current_buffer(pa);
        let win = context::current_win_index(pa);

        let wid = windows
            .get(pa, win)
            .unwrap()
            .nodes(pa)
            .position(|node| handle.ptr_eq(node.widget()))
            .unwrap_or_else(|| panic!("{}, {win}", handle.read(pa).name()));

        let handle = if flags.word("global") {
            windows
                .iter_around(pa, win, wid)
                .find_map(as_buffer_handle)
                .ok_or_else(|| txt!("There are no other open buffers"))?
        } else {
            windows
                .iter_around(pa, win, wid)
                .filter(|(lhs, ..)| *lhs == win)
                .find_map(as_buffer_handle)
                .ok_or_else(|| txt!("There are no other buffers open in this window"))?
        };

        mode::reset_to(handle.to_dyn());
        Ok(Some(txt!("Switched to [buffer]{}", handle.read(pa).name())))
    });

    add!("prev-buffer", |pa, flags: Flags| {
        let windows = context::windows();
        let handle = context::current_buffer(pa);
        let win = context::current_win_index(pa);

        let wid = windows
            .get(pa, win)
            .unwrap()
            .nodes(pa)
            .position(|node| handle.ptr_eq(node.widget()))
            .unwrap();

        let handle = if flags.word("global") {
            windows
                .iter_around_rev(pa, win, wid)
                .find_map(as_buffer_handle)
                .ok_or_else(|| txt!("There are no other open buffers"))?
        } else {
            windows
                .iter_around(pa, win, wid)
                .filter(|(lhs, ..)| *lhs == win)
                .find_map(as_buffer_handle)
                .ok_or_else(|| txt!("There are no other buffers open in this window"))?
        };

        mode::reset_to(handle.to_dyn());
        Ok(Some(txt!("Switched to [buffer]{}", handle.read(pa).name())))
    });

    add!("last-buffer", |pa| {
        let handle = context::windows().last_buffer(pa)?;
        Ok(Some(txt!("Switched to [buffer]{}", handle.read(pa).name())))
    });

    add!("swap", |pa, lhs: Buffer, rhs: Option<Buffer>| {
        let rhs = rhs.unwrap_or_else(|| context::current_buffer(pa).clone());

        context::windows().swap(pa, &lhs.to_dyn(), &rhs.to_dyn())?;

        Ok(Some(txt!(
            "Swapped {} and {}",
            lhs.read(pa).name(),
            rhs.read(pa).name()
        )))
    });

    add!("colorscheme", |_pa, scheme: ColorSchemeArg| {
        crate::form::set_colorscheme(scheme);
        Ok(Some(txt!("Set colorscheme to [a]{scheme}[]")))
    });

    add!(
        "set-form",
        |_pa, name: FormName, colors: Between<0, 3, Color>| {
            let mut form = crate::form::Form::new();
            form.style.foreground_color = colors.first().cloned();
            form.style.background_color = colors.get(1).cloned();
            form.style.underline_color = colors.get(2).cloned();
            crate::form::set(name, form);

            Ok(Some(txt!("Set [a]{name}[] to a new Form")))
        }
    );
}

mod global {
    use std::ops::Range;

    use super::{CheckerFn, CmdFn, CmdResult, Commands};
    use crate::{
        context, data::Pass, form::FormId, main_thread_only::MainThreadOnly, session::DuatEvent,
        text::Text,
    };

    static COMMANDS: MainThreadOnly<Commands> = MainThreadOnly::new(Commands::new());

    /// Adds a command to Duat
    ///
    /// Anyone will be able to execute this command, and it can take
    /// any number of [`Parameter`] arguments. These arguments will be
    /// automatically matched and checked before the command starts
    /// execution, providing feedback to the user as he is typing the
    /// commands.
    ///
    /// # Examples
    ///
    /// In the config crate:
    ///
    /// ```rust
    /// # duat_core::doc_duat!(duat);
    /// setup_duat!(setup);
    /// use duat::prelude::*;
    ///
    /// fn setup() {
    ///     let var = data::RwData::new(35);
    ///
    ///     let var_clone = var.clone();
    ///     cmd::add!("set-var", |pa: &mut Pass, value: usize| {
    ///         *var_clone.write(pa) = value;
    ///         Ok(None)
    ///     });
    ///
    ///     hook::add::<WindowCreated>(move |mut pa, window| {
    ///         // status! macro is from duat.
    ///         status!("The value is currently {var}")
    ///             .above()
    ///             .push_on(pa, window);
    ///         Ok(())
    ///     });
    /// }
    /// ```
    ///
    /// Since `var` is an [`RwData`], it will be updated
    /// automatically in the [`StatusLine`]
    ///
    /// [`StatusLine`]: https://docs.rs/duat/latest/duat/widgets/struct.StatusLine.html
    /// [`RwData`]: crate::data::RwData
    /// [`Parameter`]: super::Parameter
    pub macro add($callers:expr, |$pa:ident $(: &mut Pass)? $(, $arg:tt: $t:ty)* $(,)?| $f:block) {{
        use std::{sync::Arc, cell::UnsafeCell};
        #[allow(unused_imports)]
        use $crate::{
            data::{Pass, RwData},
            cmd::{Args, Caller, CmdFn, CmdResult, Parameter, Remainder, add_inner}
        };

        #[allow(unused_variables, unused_mut)]
        let cmd = move |pa: &mut Pass, mut args: Args| -> CmdResult {
            $(
                let ($arg, form): (<$t as Parameter>::Returns, _) =
                    <$t as Parameter>::new(pa, &mut args)?;
            )*

            if let Ok(arg) = args.next() {
                return Err($crate::text::txt!("Too many arguments"));
            }

            let mut $pa = pa;

            $f
        };

        #[allow(unused_variables, unused_mut)]
        let check_args = |pa: &Pass, mut args: Args| {
            let mut ok_ranges = Vec::new();

            $(
                let start = args.next_start();
                let result = <$t as Parameter>::new(pa, &mut args);
                match result {
                    Ok((_, form)) => if let Some(start) = start
                        .filter(|s| args.param_range().end > *s)
                    {
                        ok_ranges.push((start..args.param_range().end, form));
                    }
                    Err(err) => return (ok_ranges, Some((args.param_range(), err)))
                }
            )*

            let start = args.next_start();
            if let (Ok(_), Some(start)) = (args.next_as::<Remainder>(pa), start) {
                let err = $crate::text::txt!("Too many arguments");
                return (ok_ranges, Some((start..args.param_range().end, err)))
            }

            (ok_ranges, None)
        };

        let callers: Vec<String> = $callers.into_callers().map(str::to_string).collect();
        // SAFETY: This type will never actually be queried
        let cmd: CmdFn = unsafe { RwData::new_unsized::<()>(Arc::new(UnsafeCell::new(cmd))) };

        add_inner(callers, cmd, check_args)
    }}

    /// Canonical way to quit Duat.
    ///
    /// By calling the quit command, all threads will finish their
    /// tasks, and then Duat will execute a program closing
    /// function, as defined by the [Ui].
    ///
    /// [Ui]: crate::ui::traits::RawUi
    pub fn quit() {
        queue("quit");
    }

    /// Switches to/opens a [`Buffer`] with the given name.
    ///
    /// If you wish to specifically switch to buffers that are already
    /// open, use [`buffer`].
    ///
    /// If there are more arguments, they will be ignored.
    ///
    /// [`Buffer`]: crate::buffer::Buffer
    pub fn edit(pa: &mut Pass, buffer: impl std::fmt::Display) -> CmdResult {
        call(pa, format!("edit {buffer}"))
    }

    /// Switches to a [`Buffer`] with the given name.
    ///
    /// If there is no buffer open with that name, does nothing. Use
    /// [`edit`] if you wish to open buffers.
    ///
    /// If there are more arguments, they will be ignored.
    ///
    /// [`Buffer`]: crate::buffer::Buffer
    pub fn buffer(pa: &mut Pass, buffer: impl std::fmt::Display) -> CmdResult {
        call(pa, format!("buffer {buffer}"))
    }

    /// Switches to the next [`Buffer`].
    ///
    /// This function will only look at buffers that are opened in the
    /// current window. If you want to include other windows in the
    /// search, use [`next_global_buffer`].
    ///
    /// [`Buffer`]: crate::buffer::Buffer
    pub fn next_buffer(pa: &mut Pass) -> CmdResult {
        call(pa, "next-buffer")
    }

    /// Switches to the previous [`Buffer`].
    ///
    /// This function will only look at buffers that are opened in the
    /// current window. If you want to include other windows in the
    /// search, use [`prev_global_buffer`].
    ///
    /// [`Buffer`]: crate::buffer::Buffer
    pub fn prev_buffer(pa: &mut Pass) -> CmdResult {
        call(pa, "prev-buffer")
    }

    /// Switches to the next [`Buffer`].
    ///
    /// This function will look for buffers in all windows. If you
    /// want to limit the search to just the current window, use
    /// [`next_buffer`].
    ///
    /// [`Buffer`]: crate::buffer::Buffer
    pub fn next_global_buffer(pa: &mut Pass) -> CmdResult {
        call(pa, "next-buffer --global")
    }

    /// Switches to the previous [`Buffer`].
    ///
    /// This function will look for buffers in all windows. If you
    /// want to limit the search to just the current window, use
    /// [`prev_buffer`].
    ///
    /// [`Buffer`]: crate::buffer::Buffer
    pub fn prev_global_buffer(pa: &mut Pass) -> CmdResult {
        call(pa, "prev-buffer --global")
    }

    /// Tries to alias a `caller` to an existing `command`.
    ///
    /// Returns an [`Err`] if the `caller` is already a caller for
    /// another command, or if `command` is not a real caller to an
    /// existing command.
    pub fn alias(pa: &mut Pass, alias: impl ToString, command: impl ToString) -> CmdResult {
        // SAFETY: Function has a Pass argument.
        unsafe { COMMANDS.get() }.alias(pa, alias, command)
    }

    /// Runs a full command synchronously, with a [`Pass`].
    ///
    /// If you call commands through this function, you will be able
    /// to retrieve their return values,  but because of the [`Pass`],
    /// this function can only be used on the main thread of
    /// execution. If you want to call commands from other threads,
    /// see [`cmd::queue`].
    ///
    /// When running the command, the ordering of [`Flags`] does not
    /// matter, as long as they are placed before the arguments to the
    /// command.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # duat_core::doc_duat!(duat);
    /// setup_duat!(setup);
    /// use duat::prelude::*;
    ///
    /// fn main_thread_function(pa: &mut Pass) {
    ///     cmd::call(pa, "set-prompt new-prompt");
    /// }
    /// ```
    ///
    /// In this case we're running a command that will affect the most
    /// relevant [`PromptLine`], and no notifications are sent. That's
    /// because I used [`call`]. If you want notifications, see
    /// [`cmd::call_notify`].
    ///
    /// [`cmd::queue`]: queue
    /// [`cmd::call_notify`]: call_notify
    /// [`PromptLine`]: https://docs.rs/duat/latest/duat/widgets/struct.PromptLine.html
    /// [`Flags`]: super::Flags
    pub fn call(pa: &mut Pass, call: impl std::fmt::Display) -> CmdResult {
        // SAFETY: Function has a Pass argument.
        unsafe { COMMANDS.get() }.run(pa, call)
    }

    /// Like [`call`], but notifies the result
    #[allow(unused_must_use)]
    pub fn call_notify(pa: &mut Pass, call: impl std::fmt::Display) -> CmdResult {
        // SAFETY: Function has a Pass argument.
        let result = unsafe { COMMANDS.get() }.run(pa, call.to_string());
        context::logs().push_cmd_result(result.clone());

        result
    }

    /// Queues a command call
    ///
    /// You should only use this if you're not in the main thread of
    /// execution, or if you don't have a [`Pass`] for some other
    /// reason, like you are in the middle of accessing an [`RwData`]
    /// or something like that.
    ///
    /// Since this function will run outside of the current scope, its
    /// [`Result`] will not be returned.
    ///
    /// [`RwData`]: crate::data::RwData
    pub fn queue(call: impl std::fmt::Display) {
        let call = call.to_string();
        crate::context::sender()
            .send(DuatEvent::QueuedFunction(Box::new(move |pa| {
                // SAFETY: Closure has Pass argument.
                let _ = unsafe { COMMANDS.get() }.run(pa, call);
            })))
            .unwrap();
    }

    /// Like [`queue`], but notifies the result
    pub fn queue_notify(call: impl std::fmt::Display) {
        let call = call.to_string();
        crate::context::sender()
            .send(DuatEvent::QueuedFunction(Box::new(move |pa| {
                context::logs()
                    .push_cmd_result(unsafe { COMMANDS.get() }.run(pa, call.clone()).clone());
            })))
            .unwrap()
    }

    /// Like [`queue`], but acts on the [`Result`]
    pub fn queue_and(call: impl std::fmt::Display, map: impl FnOnce(CmdResult) + Send + 'static) {
        let call = call.to_string();
        crate::context::sender()
            .send(DuatEvent::QueuedFunction(Box::new(move |pa| {
                // SAFETY: Function has a Pass argument.
                map(unsafe { COMMANDS.get() }.run(pa, call));
            })))
            .unwrap()
    }

    /// Like [`queue_and`], but also notifies the [`Result`]
    pub fn queue_notify_and(
        call: impl std::fmt::Display,
        map: impl FnOnce(CmdResult) + Send + 'static,
    ) {
        let call = call.to_string();
        crate::context::sender()
            .send(DuatEvent::QueuedFunction(Box::new(move |pa| {
                // SAFETY: Function has a Pass argument.
                let result = unsafe { COMMANDS.get() }.run(pa, call.clone());
                context::logs().push_cmd_result(result.clone());

                map(result)
            })))
            .unwrap()
    }

    /// Don't call this function, use [`cmd::add`] instead
    ///
    /// [`cmd::add`]: add
    #[doc(hidden)]
    pub fn add_inner(callers: Vec<String>, cmd: CmdFn, check_args: CheckerFn) {
        // SAFETY: There is no way to obtain an external RwData of Commands,
        // so you can modify it from anywhere in the main thread.
        let mut pa = unsafe { Pass::new() };
        unsafe { COMMANDS.get() }.add(&mut pa, callers, cmd, check_args)
    }

    /// Check if the arguments for a given `caller` are correct
    pub fn check_args(
        pa: &Pass,
        caller: &str,
    ) -> Option<(
        Vec<(Range<usize>, Option<FormId>)>,
        Option<(Range<usize>, Text)>,
    )> {
        // SAFETY: There is a Pass argument
        unsafe { COMMANDS.get() }.check_args(pa, caller)
    }
}

/// A list of commands.
///
/// This list contains all of the commands that have been
/// added to Duat, as well as info on the current [`Buffer`],
/// [widget] and all of the [windows].
///
/// [`Buffer`]: crate::buffer::Buffer
/// [widget]: crate::ui::Widget
/// [windows]: crate::ui::Window
struct Commands(LazyLock<RwData<InnerCommands>>);

impl Commands {
    /// Returns a new instance of [`Commands`].
    const fn new() -> Self {
        Self(LazyLock::new(|| {
            RwData::new(InnerCommands {
                list: Vec::new(),
                aliases: HashMap::new(),
            })
        }))
    }

    /// Aliases a command to a specific word
    fn alias(&self, pa: &mut Pass, alias: impl ToString, command: impl ToString) -> CmdResult {
        self.0
            .write(pa)
            .try_alias(alias.to_string(), command.to_string())
    }

    /// Runs a command from a call
    fn run(&self, pa: &mut Pass, call: impl Display) -> CmdResult {
        let call = call.to_string();
        let mut args = call.split_whitespace();
        let caller = args.next().ok_or(txt!("The command is empty"))?.to_string();

        let inner = self.0.read(pa);

        let (command, call) = {
            if let Some(command) = inner.aliases.get(&caller) {
                let (command, call) = command;
                let mut call = call.clone() + " ";
                call.extend(args);

                (command.clone(), call)
            } else {
                let command = inner
                    .list
                    .iter()
                    .find(|cmd| cmd.callers().contains(&caller))
                    .ok_or(txt!("[a]{caller}[]: No such command"))?;

                (command.clone(), call.clone())
            }
        };

        let args = get_args(&call);

        if let (_, Some((_, err))) = (command.check_args)(pa, args.clone()) {
            return Err(err);
        }

        let silent = call.len() > call.trim_start().len();
        command.cmd.write(&mut unsafe { Pass::new() })(pa, args).map(|ok| ok.filter(|_| !silent))
    }

    /// Adds a command to the list of commands
    fn add(&self, pa: &mut Pass, callers: Vec<String>, cmd: CmdFn, check_args: CheckerFn) {
        let cmd = Command::new(callers, cmd, check_args);
        self.0.write(pa).add(cmd)
    }

    /// Gets the parameter checker for a command, if it exists
    fn check_args(
        &self,
        pa: &Pass,
        call: &str,
    ) -> Option<(
        Vec<(Range<usize>, Option<FormId>)>,
        Option<(Range<usize>, Text)>,
    )> {
        let mut args = call.split_whitespace();
        let caller = args.next()?.to_string();

        let inner = self.0.read(pa);
        if let Some((command, _)) = inner.aliases.get(&caller) {
            Some((command.check_args)(pa, get_args(call)))
        } else {
            let command = inner
                .list
                .iter()
                .find(|cmd| cmd.callers().contains(&caller))?;

            Some((command.check_args)(pa, get_args(call)))
        }
    }
}

/// The standard error that should be returned when [`call`]ing
/// commands.
///
/// This error _must_ include an error message in case of failure. It
/// may also include a success message, but that is not required.
///
/// [`call`]: global::call
pub type CmdResult = Result<Option<Text>, Text>;

/// A function that can be called by name.
#[derive(Clone)]
struct Command {
    callers: Arc<[String]>,
    cmd: CmdFn,
    check_args: CheckerFn,
}

impl Command {
    /// Returns a new instance of command.
    fn new(callers: Vec<String>, cmd: CmdFn, check_args: CheckerFn) -> Self {
        if let Some(caller) = callers
            .iter()
            .find(|caller| caller.split_whitespace().count() != 1)
        {
            panic!("Command caller \"{caller}\" contains more than one word");
        }
        Self { cmd, check_args, callers: callers.into() }
    }

    /// The list of callers that will trigger this command.
    fn callers(&self) -> &[String] {
        &self.callers
    }
}

struct InnerCommands {
    list: Vec<Command>,
    aliases: HashMap<String, (Command, String)>,
}

impl InnerCommands {
    /// Adds a command to the list
    ///
    /// Overrides previous commands with the same name.
    fn add(&mut self, command: Command) {
        let mut new_callers = command.callers().iter();

        self.list
            .retain(|cmd| new_callers.all(|caller| !cmd.callers.contains(caller)));

        self.list.push(command);
    }

    /// Tries to alias a full command (caller, flags, and
    /// arguments) to an alias.
    fn try_alias(&mut self, alias: String, call: String) -> Result<Option<Text>, Text> {
        if alias.split_whitespace().count() != 1 {
            return Err(txt!("Alias [a]{alias}[] is not a single word"));
        }

        let caller = call
            .split_whitespace()
            .next()
            .ok_or(txt!("The command is empty"))?
            .to_string();

        let mut cmds = self.list.iter();

        if let Some(command) = cmds.find(|cmd| cmd.callers().contains(&caller)) {
            let entry = (command.clone(), call.clone());
            Ok(Some(match self.aliases.insert(alias.clone(), entry) {
                Some((_, prev_call)) => {
                    txt!("Aliased [a]{alias}[] from [a]{prev_call}[] to [a]{call}")
                }
                None => txt!("Aliased [a]{alias}[] to [a]{call}"),
            }))
        } else {
            Err(txt!("The caller [a]{caller}[] was not found"))
        }
    }
}

/// A list of names to call a command with
pub trait Caller<'a>: Sized {
    /// An [`Iterator`] over said callers
    fn into_callers(self) -> impl Iterator<Item = &'a str>;
}

impl<'a> Caller<'a> for &'a str {
    fn into_callers(self) -> impl Iterator<Item = &'a str> {
        [self].into_iter()
    }
}

impl<'a> Caller<'a> for &'a [&'a str] {
    fn into_callers(self) -> impl Iterator<Item = &'a str> {
        self.iter().cloned()
    }
}

impl<'a, const N: usize> Caller<'a> for [&'a str; N] {
    fn into_callers(self) -> impl Iterator<Item = &'a str> {
        self.into_iter()
    }
}

/// Inner function for Commands
#[doc(hidden)]
pub type CmdFn = RwData<dyn FnMut(&mut Pass, Args) -> CmdResult + Send + 'static>;

/// Inner checking function
#[doc(hidden)]
pub type CheckerFn = fn(
    &Pass,
    Args,
) -> (
    Vec<(Range<usize>, Option<FormId>)>,
    Option<(Range<usize>, Text)>,
);

pub(crate) fn as_buffer_handle((.., node): (usize, &Node)) -> Option<Handle> {
    node.try_downcast()
}