actions_rs/
lib.rs

1//! # actions-rs
2//!
3//! A **zero-dependency** toolkit for writing GitHub Actions in Rust — an independent, unofficial
4//! Rust port of `@actions/core` (faithful API and semantics, with deliberate safety-first departures;
5//! not affiliated with or endorsed by GitHub or the `@actions/toolkit` project).
6//!
7//! It speaks the GitHub Actions *workflow-command* and *environment-file* protocols so your action can:
8//!
9//! - emit `notice` / `warning` / `error` annotations with file + line/column ranges ([`Annotation`], [`log`]),
10//! - group and mask log output, and pause command interpretation ([`log::group`], [`log::mask`], [`log::stop_commands`]),
11//! - read typed, validated inputs ([`input`]),
12//! - set step outputs, saved state, env vars and `PATH` ([`output`]) — using modern env files,
13//!   with deprecated-command fallback only for output/state,
14//! - build a rich job summary ([`Summary`]),
15//! - detect and inspect the runtime ([`env`](mod@env)).
16//!
17//! Pure stdout commands are infallible;
18//! operations that touch the filesystem or parse input return [`Result`].
19//!
20//! ## Quick start
21//!
22//! ```
23//! use actions_rs::{Annotation, log};
24//!
25//! if actions_rs::env::is_github_actions() {
26//!     log::info("running inside GitHub Actions");
27//! }
28//!
29//! // A located warning, rendered as a workflow command on stdout.
30//! Annotation::new()
31//!     .file("src/lib.rs")
32//!     .line(1)
33//!     .title("example")
34//!     .warning("this is just a demo");
35//!
36//! // `format!`-style macros are exported at the crate root.
37//! actions_rs::warning!("disk {}% full", 92);
38//!
39//! // A group that closes even if the closure panics.
40//! let answer = actions_rs::group!("compute", { 6 * 7 });
41//! assert_eq!(answer, 42);
42//! ```
43
44#![forbid(unsafe_code)]
45
46pub mod annotation;
47pub mod command;
48pub mod env;
49pub mod error;
50mod escape;
51mod file_command;
52pub mod input;
53pub mod log;
54mod macros;
55pub mod output;
56pub mod summary;
57
58pub use annotation::{Annotation, AnnotationKind, AnnotationSpan};
59pub use command::WorkflowCommand;
60pub use env::{Context, RunnerArch, RunnerOs};
61pub use error::{Error, Result};
62pub use input::InputOptions;
63pub use summary::{Cell, Summary, SummaryText};
64
65/// Common imports for action authors: `use actions_rs::prelude::*;`.
66pub mod prelude {
67    pub use crate::error::{Error, Result};
68    pub use crate::input::InputOptions;
69    pub use crate::summary::{Cell, Summary, SummaryText};
70    pub use crate::{
71        Annotation, AnnotationKind, AnnotationSpan, Context, RunnerArch, RunnerOs, WorkflowCommand,
72    };
73    pub use crate::{debug, error, group, info, notice, warning};
74    pub use crate::{env, input, log, output};
75}
76
77/// Compiles (and runs) every fenced example in `README.md` as a doctest.
78/// `#[cfg(doctest)]` so it exists only during `cargo test --doc` — zero
79/// effect on the published API.
80#[cfg(doctest)]
81#[doc = include_str!("../README.md")]
82struct ReadmeDoctests;
actions_rs/lib.rs

actions_rs/
lib.rs
