watchexec/crates/lib/src/lib.rs

90 lines
2.8 KiB
Rust
Raw Normal View History

//! Watchexec: a library for utilities and programs which respond to (file, signal, etc) events
//! primarily by launching or managing other programs.
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-12-23 14:28:21 +01:00
//! This library is powered by [Tokio](https://tokio.rs).
2021-08-16 11:49:12 +02:00
//!
//! The main way to use this crate involves constructing a [`Watchexec`] around a [`Config`], then
//! running it. [`Handler`][handler::Handler]s are used to hook into Watchexec at various points.
//! The config can be changed at any time with the [`Watchexec::reconfigure()`] method.
2021-08-19 10:31:29 +02:00
//!
2021-10-16 08:08:35 +02:00
//! It's recommended to use the [miette] erroring library in applications, but all errors implement
//! [`std::error::Error`] so your favourite error handling library can of course be used.
//!
2021-08-22 12:06:50 +02:00
//! ```no_run
2021-10-16 08:08:35 +02:00
//! use miette::{IntoDiagnostic, Result};
//! use watchexec_signals::Signal;
//! use watchexec::Watchexec;
//!
//! #[tokio::main]
2021-10-16 08:08:35 +02:00
//! async fn main() -> Result<()> {
//! let wx = Watchexec::new(|mut action| {
//! // print any events
//! for event in action.events.iter() {
//! eprintln!("EVENT: {event:?}");
//! }
2021-08-22 12:06:50 +02:00
//!
//! // if Ctrl-C is received, quit
//! if action.signals().any(|sig| sig == Signal::Interrupt) {
//! action.quit();
//! }
2021-08-22 12:06:50 +02:00
//!
//! action
//! })?;
2021-08-22 12:06:50 +02:00
//!
//! // watch the current directory
//! wx.config.pathset(["."]);
//!
//! wx.main().await.into_diagnostic()?;
2021-08-22 12:06:50 +02:00
//! Ok(())
//! }
//! ```
//!
//! Alternatively, you can use the modules exposed by the crate and the external crates such as
2021-08-19 10:31:29 +02:00
//! [ClearScreen][clearscreen] and [Command Group][command_group] to build something more advanced,
//! at the cost of reimplementing the glue code.
2021-08-16 11:49:12 +02:00
//!
//! Note that the library generates a _lot_ of debug messaging with [tracing]. **You should not
//! enable printing even `error`-level log messages for this crate unless it's for debugging.**
//! Instead, make use of the [`Config::on_error()`] method to define a handler for errors
//! occurring at runtime that are _meant_ for you to handle (by printing out or otherwise).
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-10-16 06:13:32 +02:00
#![warn(clippy::unwrap_used, missing_docs)]
2022-04-13 12:59:43 +02:00
#![deny(rust_2018_idioms)]
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;
pub mod error;
2021-09-13 09:51:07 +02:00
pub mod filter;
2021-10-16 02:55:20 +02:00
pub mod paths;
pub mod sources;
2021-08-16 17:09:22 +02:00
2021-08-18 15:12:50 +02:00
// the core experience
pub mod changeable;
pub mod config;
2021-08-18 15:12:50 +02:00
mod id;
mod late_join_set;
mod watchexec;
2023-03-18 09:32:24 +01:00
2021-08-18 15:12:50 +02:00
#[doc(inline)]
pub use crate::{
id::Id,
watchexec::{ErrorHook, Watchexec},
};
#[doc(no_inline)]
pub use crate::config::Config;
#[doc(no_inline)]
pub use watchexec_supervisor::{command, job};
2022-06-17 01:18:31 +02:00
#[cfg(debug_assertions)]
2022-06-17 01:18:31 +02:00
#[doc(hidden)]
pub mod readme_doc_check {
#[doc = include_str!("../README.md")]
pub struct Readme;
}