watchexec/lib/src/lib.rs

74 lines
2.5 KiB
Rust
Raw Normal View History

2021-08-16 11:49:12 +02:00
//! Watchexec: a library for utilities and programs which respond to events;
//! file changes, human interaction, and more.
2019-10-27 10:54:44 +01:00
//!
2021-08-19 10:31:29 +02:00
//! Also see the CLI tool: <https://watchexec.github.io/>
2019-10-27 11:29:58 +01:00
//!
2021-08-19 10:31:29 +02:00
//! This library is powered by [Tokio](https://tokio.rs), minimum version 1.10. This requirement may
//! change (upwards) in the future without breaking change.
2021-08-16 11:49:12 +02:00
//!
2021-08-19 10:31:29 +02:00
//! The main way to use this crate involves constructing a [`Watchexec`] around a [`Config`] and
//! running it. The config may contain some instances of [`Handler`][handler::Handler]s, hooking
//! into watchexec at various points.
2021-08-19 10:31:29 +02:00
//!
//! ```ignore // TODO: implement and switch to no_run
//! use watchexec::{Watchexec, ConfigBuilder, Handler as _};
//!
//! #[tokio::main]
//! async fn main() {
//! let mut config = ConfigBuilder::new()
//! config.pathset(["watchexec.conf"]);
//!
//! let conf = YourConfigFormat::load_from_file("watchexec.conf").await?;
//! conf.apply(&mut config);
//!
//! let we = Watchexec::new(config.build().unwrap()).unwrap();
//! let w = we.clone();
//!
//! let c = config.clone();
//! config.on_event(|e| async move {
//! if e.path().map(|p| p.ends_with("watchexec.conf")).unwrap_or(false) {
//! let conf = YourConfigFormat::load_from_file("watchexec.conf").await?;
//!
//! conf.apply(&mut config);
//! w.reconfigure(config.build());
//! // tada! self-reconfiguring watchexec on config file change!
//! }
//! });
//!
//! w.main().await.unwrap();
//! }
//! ```
//!
2021-08-19 10:31:29 +02:00
//! Alternatively, one can use the modules exposed by the crate and the external crates such as
//! [ClearScreen][clearscreen] and [Command Group][command_group] to build something more advanced,
//! at the cost of reimplementing the glue code. See the examples folder for some basic/demo tools
//! written with the individual modules.
2021-08-16 11:49:12 +02:00
//!
//! This crate does not itself use `unsafe`. However, it depends on a number of libraries which do,
//! most because they interact with the operating system.
2019-10-27 10:54:44 +01:00
2021-07-20 10:32:38 +02:00
#![doc(html_favicon_url = "https://watchexec.github.io/logo:watchexec.svg")]
#![doc(html_logo_url = "https://watchexec.github.io/logo:watchexec.svg")]
2021-04-10 19:44:24 +02:00
#![warn(clippy::unwrap_used)]
2021-08-16 11:49:12 +02:00
#![forbid(unsafe_code)]
2019-10-27 12:06:09 +01:00
2021-08-18 15:12:50 +02:00
// the toolkit to make your own
2021-08-20 18:43:55 +02:00
pub mod action;
2021-08-19 11:28:56 +02:00
pub mod command;
pub mod error;
2021-08-16 11:49:12 +02:00
pub mod event;
2021-08-16 15:15:17 +02:00
pub mod fs;
pub mod handler;
2021-08-17 11:41:13 +02:00
pub mod signal;
2021-08-16 17:09:22 +02:00
2021-08-18 15:12:50 +02:00
// the core experience
mod config;
mod watchexec;
#[doc(inline)]
pub use crate::watchexec::Watchexec;
2021-08-19 10:30:01 +02:00
#[doc(inline)]
pub use config::{Config, ConfigBuilder};
2021-08-18 15:12:50 +02:00
2021-08-16 17:09:22 +02:00
// the *action* is debounced, not the events