watchexec/lib/src/event.rs

226 lines
5.4 KiB
Rust
Raw Normal View History

//! Synthetic event type, derived from inputs, triggers actions.
//!
2021-08-16 11:49:12 +02:00
//! Fundamentally, events in watchexec have three purposes:
//!
//! 1. To trigger the launch, restart, or other interruption of a process;
//! 2. To be filtered upon according to whatever set of criteria is desired;
//! 3. To carry information about what caused the event, which may be provided to the process.
2021-08-22 12:06:12 +02:00
use std::{
collections::HashMap,
2021-09-02 21:57:59 +02:00
fmt,
2021-08-22 12:06:12 +02:00
path::{Path, PathBuf},
process::ExitStatus,
2021-08-22 12:06:12 +02:00
};
2021-08-16 11:49:12 +02:00
2021-09-02 22:14:04 +02:00
use notify::EventKind;
use crate::signal::source::MainSignal;
2021-08-17 11:41:13 +02:00
2021-08-16 11:49:12 +02:00
/// An event, as far as watchexec cares about.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
2021-08-16 11:49:12 +02:00
pub struct Event {
2021-10-16 12:47:00 +02:00
/// Structured, classified information which can be used to filter or classify the event.
2021-09-13 09:34:40 +02:00
pub tags: Vec<Tag>,
2021-10-16 12:47:00 +02:00
/// Arbitrary other information, cannot be used for filtering.
2021-08-16 11:49:12 +02:00
pub metadata: HashMap<String, Vec<String>>,
}
/// Something which can be used to filter or qualify an event.
2021-08-16 11:49:12 +02:00
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
2021-09-13 09:34:40 +02:00
pub enum Tag {
2021-10-16 12:47:00 +02:00
/// The event is about a path or file in the filesystem.
2021-10-12 17:06:39 +02:00
Path {
2021-10-16 12:47:00 +02:00
/// Path to the file or directory.
2021-10-12 17:06:39 +02:00
path: PathBuf,
2021-10-16 12:47:00 +02:00
/// Optional file type, if known.
2021-10-12 17:06:39 +02:00
file_type: Option<FileType>,
},
2021-10-16 12:47:00 +02:00
/// Kind of a filesystem event (create, remove, modify, etc).
2021-09-02 22:14:04 +02:00
FileEventKind(EventKind),
2021-10-16 12:47:00 +02:00
/// The general source of the event.
2021-08-16 11:49:12 +02:00
Source(Source),
2021-10-16 12:47:00 +02:00
/// The event was caused by a particular process.
2021-08-16 11:49:12 +02:00
Process(u32),
2021-10-16 12:47:00 +02:00
/// The event is about a signal being delivered to the main process.
Signal(MainSignal),
2021-10-16 12:47:00 +02:00
/// The event is about the subprocess exiting.
// TODO: replace ExitStatus with something we can de/serialize.
ProcessCompletion(Option<ExitStatus>),
2021-08-16 11:49:12 +02:00
}
impl Tag {
2021-10-16 12:47:00 +02:00
/// The name of the variant.
pub const fn discriminant_name(&self) -> &'static str {
match self {
2021-10-12 17:06:39 +02:00
Tag::Path { .. } => "Path",
Tag::FileEventKind(_) => "FileEventKind",
Tag::Source(_) => "Source",
Tag::Process(_) => "Process",
Tag::Signal(_) => "Signal",
Tag::ProcessCompletion(_) => "ProcessCompletion",
}
}
}
/// The type of a file.
///
/// This is a simplification of the [`std::fs::FileType`] type, which is not constructable and may
/// differ on different platforms.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum FileType {
/// A regular file.
File,
/// A directory.
Dir,
/// A symbolic link.
Symlink,
/// Something else.
Other,
}
impl From<std::fs::FileType> for FileType {
fn from(ft: std::fs::FileType) -> Self {
if ft.is_file() {
Self::File
} else if ft.is_dir() {
Self::Dir
} else if ft.is_symlink() {
Self::Symlink
} else {
Self::Other
}
}
}
impl fmt::Display for FileType {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::File => write!(f, "file"),
Self::Dir => write!(f, "dir"),
Self::Symlink => write!(f, "symlink"),
Self::Other => write!(f, "other"),
}
}
}
2021-08-16 11:49:12 +02:00
/// The general origin of the event.
2021-10-16 12:47:00 +02:00
///
/// This is set by the event source. Note that not all of these are currently used.
2021-08-16 11:49:12 +02:00
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum Source {
2021-10-16 12:47:00 +02:00
/// Event comes from a file change.
2021-08-16 11:49:12 +02:00
Filesystem,
2021-10-16 12:47:00 +02:00
/// Event comes from a keyboard input.
2021-08-16 11:49:12 +02:00
Keyboard,
2021-10-16 12:47:00 +02:00
/// Event comes from a mouse click.
2021-08-16 11:49:12 +02:00
Mouse,
2021-10-16 12:47:00 +02:00
/// Event comes from the OS.
2021-08-17 11:41:13 +02:00
Os,
2021-10-16 12:47:00 +02:00
/// Event is time based.
2021-08-16 11:49:12 +02:00
Time,
2021-10-16 12:47:00 +02:00
/// Event is internal to Watchexec.
2021-09-02 21:57:45 +02:00
Internal,
2021-08-16 11:49:12 +02:00
}
2021-08-22 12:06:12 +02:00
impl fmt::Display for Source {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2021-09-28 11:22:33 +02:00
write!(
f,
"{}",
match self {
Self::Filesystem => "filesystem",
Self::Keyboard => "keyboard",
Self::Mouse => "mouse",
Self::Os => "os",
Self::Time => "time",
Self::Internal => "internal",
}
)
}
}
2021-08-22 12:06:12 +02:00
impl Event {
2021-09-28 11:22:33 +02:00
/// Returns true if the event has an Internal source tag.
pub fn is_internal(&self) -> bool {
self.tags
.iter()
.any(|tag| matches!(tag, Tag::Source(Source::Internal)))
}
/// Returns true if the event has no tags.
pub fn is_empty(&self) -> bool {
self.tags.is_empty()
}
2021-09-13 09:34:40 +02:00
/// Return all paths in the event's tags.
2021-10-16 05:26:29 +02:00
pub fn paths(&self) -> impl Iterator<Item = (&Path, Option<&FileType>)> {
2021-09-13 09:34:40 +02:00
self.tags.iter().filter_map(|p| match p {
2021-10-16 05:26:29 +02:00
Tag::Path { path, file_type } => Some((path.as_path(), file_type.as_ref())),
2021-08-22 12:06:12 +02:00
_ => None,
})
}
2021-09-02 23:25:06 +02:00
2021-09-13 09:34:40 +02:00
/// Return all signals in the event's tags.
pub fn signals(&self) -> impl Iterator<Item = MainSignal> + '_ {
2021-09-13 09:34:40 +02:00
self.tags.iter().filter_map(|p| match p {
Tag::Signal(s) => Some(*s),
_ => None,
})
}
2021-09-02 23:25:06 +02:00
2021-09-13 09:34:40 +02:00
/// Return all process completions in the event's tags.
2021-09-02 23:25:06 +02:00
pub fn completions(&self) -> impl Iterator<Item = Option<ExitStatus>> + '_ {
2021-09-13 09:34:40 +02:00
self.tags.iter().filter_map(|p| match p {
Tag::ProcessCompletion(s) => Some(*s),
2021-09-02 23:25:06 +02:00
_ => None,
})
}
2021-08-22 12:06:12 +02:00
}
2021-09-02 21:57:59 +02:00
impl fmt::Display for Event {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "Event")?;
2021-09-13 09:34:40 +02:00
for p in &self.tags {
2021-09-02 21:57:59 +02:00
match p {
2021-10-12 17:06:39 +02:00
Tag::Path { path, file_type } => {
write!(f, " path={}", path.display())?;
if let Some(ft) = file_type {
write!(f, " filetype={}", ft)?;
2021-10-12 17:06:39 +02:00
}
}
2021-09-13 09:34:40 +02:00
Tag::FileEventKind(kind) => write!(f, " kind={:?}", kind)?,
Tag::Source(s) => write!(f, " source={:?}", s)?,
Tag::Process(p) => write!(f, " process={}", p)?,
Tag::Signal(s) => write!(f, " signal={:?}", s)?,
Tag::ProcessCompletion(None) => write!(f, " command-completed")?,
Tag::ProcessCompletion(Some(c)) => write!(f, " command-completed({})", c)?,
2021-09-02 21:57:59 +02:00
}
}
if !self.metadata.is_empty() {
write!(f, " meta: {:?}", self.metadata)?;
}
Ok(())
}
}