Merge pull request 'implement a cli module' (#85) from feat/cli into devel
cargo devel CI / cargo CI (push) Successful in 2m20s Details

Reviewed-on: #85
This commit is contained in:
Christoph J. Scherr 2024-07-09 18:12:24 +02:00
commit 511fd69ab6
18 changed files with 891 additions and 17 deletions

View File

@ -5,12 +5,13 @@ members = [
"members/libpt-core", "members/libpt-core",
"members/libpt-log", "members/libpt-log",
"members/libpt-py", "members/libpt-py",
"members/libpt-cli",
] ]
default-members = [".", "members/libpt-core"] default-members = [".", "members/libpt-core"]
[workspace.package] [workspace.package]
publish = true publish = true
version = "0.5.1" version = "0.6.0-alpha.0"
edition = "2021" edition = "2021"
authors = ["Christoph J. Scherr <software@cscherr.de>"] authors = ["Christoph J. Scherr <software@cscherr.de>"]
license = "GPL-3.0-or-later" license = "GPL-3.0-or-later"
@ -31,6 +32,7 @@ thiserror = "1.0.56"
libpt-core = { version = "0.4.0", path = "members/libpt-core" } libpt-core = { version = "0.4.0", path = "members/libpt-core" }
libpt-bintols = { version = "0.5.1", path = "members/libpt-bintols" } libpt-bintols = { version = "0.5.1", path = "members/libpt-bintols" }
libpt-log = { version = "0.4.2", path = "members/libpt-log" } libpt-log = { version = "0.4.2", path = "members/libpt-log" }
libpt-cli = { version = "0.1.0", path = "members/libpt-cli" }
[package] [package]
name = "libpt" name = "libpt"
@ -52,6 +54,7 @@ core = []
full = ["default", "core", "log", "bintols"] full = ["default", "core", "log", "bintols"]
log = ["dep:libpt-log"] log = ["dep:libpt-log"]
bintols = ["dep:libpt-bintols", "log"] bintols = ["dep:libpt-bintols", "log"]
cli = ["dep:libpt-cli", "core", "log"]
# py = ["dep:libpt-py"] # py = ["dep:libpt-py"]
[lib] [lib]
@ -66,3 +69,4 @@ crate-type = [
libpt-core = { workspace = true } libpt-core = { workspace = true }
libpt-bintols = { workspace = true, optional = true } libpt-bintols = { workspace = true, optional = true }
libpt-log = { workspace = true, optional = true } libpt-log = { workspace = true, optional = true }
libpt-cli = { workspace = true, optional = true }

View File

@ -0,0 +1,36 @@
[package]
name = "libpt-cli"
publish.workspace = true
version = "0.1.0"
edition.workspace = true
authors.workspace = true
license.workspace = true
description.workspace = true
readme.workspace = true
homepage.workspace = true
repository.workspace = true
keywords.workspace = true
categories.workspace = true
[package.metadata.docs.rs]
cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
[features]
default = []
log = ["dep:log"]
[dependencies]
anyhow.workspace = true
clap = { version = "4.5.7", features = ["derive"] }
comfy-table = "7.1.1"
console = "0.15.8"
dialoguer = { version = "0.11.0", features = ["completion", "history"] }
embed-doc-image = "0.1.4"
exitcode = "1.1.2"
human-panic = "2.0.0"
indicatif = "0.17.8"
libpt-log = { workspace = true, optional = false }
log = { version = "0.4.21", optional = true }
shlex = "1.3.0"
strum = { version = "0.26.3", features = ["derive"] }
thiserror.workspace = true

Binary file not shown.

After

Width:  |  Height:  |  Size: 142 KiB

View File

@ -0,0 +1,41 @@
use clap::Parser;
use libpt_cli::args::VerbosityLevel;
use libpt_cli::{clap, printing};
use libpt_log::{debug, Logger};
/// This is the help
///
/// This is more help
#[derive(Parser, Debug)]
struct Cli {
// already has documentation
#[command(flatten)]
verbosity: VerbosityLevel,
/// texts to be echoed
#[arg(required = true)]
text: Vec<String>,
/// try to be more machine readable
#[arg(short, long)]
machine: bool,
}
fn main() {
let cli = Cli::parse();
let _logger = Logger::builder()
.max_level(cli.verbosity.level())
.show_time(false)
.build();
debug!("logger initialized with level: {}", cli.verbosity.level());
if !cli.machine {
let text = cli.text.join(" ");
printing::blockprint(text, console::Color::Green);
} else {
for text in cli.text {
println!("{text}")
}
}
}

View File

@ -0,0 +1,85 @@
use console::style;
use libpt_cli::repl::{DefaultRepl, Repl};
use libpt_cli::{clap, printing, strum};
use libpt_log::{debug, Level, Logger};
use clap::Subcommand;
use strum::EnumIter;
// this is where you define what data/commands/arguments the REPL accepts
#[derive(Subcommand, Debug, EnumIter, Clone)]
enum ReplCommand {
/// wait for LEN seconds
Wait {
/// wait so long
len: u64,
},
/// echo the given texts
Echo {
/// the text you want to print
text: Vec<String>,
/// print with a fancy border and colors
#[arg(short, long)]
fancy: bool,
},
/// hello world
Hello,
/// leave the repl
Exit,
}
fn main() -> anyhow::Result<()> {
// You would normally make a proper cli interface with clap before entering the repl. This is
// omitted here for brevity
let _logger = Logger::builder()
.show_time(false)
.max_level(Level::INFO)
.build()?;
// the compiler can infer that we want to use the ReplCommand enum.
let mut repl = DefaultRepl::<ReplCommand>::default();
debug!("entering the repl");
loop {
// repl.step() should be at the start of your loop
// It is here that the repl will get the user input, validate it, and so on
match repl.step() {
Ok(c) => c,
Err(e) => {
// if the user requested the help, print in blue, otherwise in red as it's just an
// error
if let libpt_cli::repl::error::Error::Parsing(e) = &e {
if e.kind() == clap::error::ErrorKind::DisplayHelp {
println!("{}", style(e).cyan());
continue;
}
}
println!("{}", style(e).red().bold());
continue;
}
};
// now we can match our defined commands
//
// only None if the repl has not stepped yet
match repl.command().to_owned().unwrap() {
ReplCommand::Exit => break,
ReplCommand::Wait { len } => {
debug!("len: {len}");
let spinner = indicatif::ProgressBar::new_spinner();
spinner.enable_steady_tick(std::time::Duration::from_millis(100));
std::thread::sleep(std::time::Duration::from_secs(len));
spinner.finish();
}
ReplCommand::Hello => println!("Hello!"),
ReplCommand::Echo { text, fancy } => {
if !fancy {
println!("{}", text.join(" "))
} else {
printing::blockprint(&text.join(" "), console::Color::Cyan)
}
}
}
}
Ok(())
}

View File

@ -0,0 +1,280 @@
//! Utilities for parsing options and arguments on the start of a CLI application
use clap::Parser;
use libpt_log::Level;
#[cfg(feature = "log")]
use log;
/// Custom help template for displaying command-line usage information
///
/// This template modifies the default template provided by Clap to include additional information
/// and customize the layout of the help message.
///
/// Differences from the default template:
/// - Includes the application version and author information at the end
///
/// Apply like this:
/// ```
/// # use libpt_cli::args::HELP_TEMPLATE;
/// use clap::Parser;
/// #[derive(Parser, Debug, Clone, PartialEq, Eq, Hash)]
/// #[command(help_template = HELP_TEMPLATE)]
/// pub struct MyArgs {
/// /// show more details
/// #[arg(short, long)]
/// pub verbose: bool,
/// }
/// ```
///
/// ## Example
///
/// Don't forget to set `authors` in your `Cargo.toml`!
///
/// ```bash
/// $ cargo run -- -h
/// about: short
///
/// Usage: aaa [OPTIONS]
///
/// Options:
/// -v, --verbose show more details
/// -h, --help Print help (see more with '--help')
/// -V, --version Print version
///
/// aaa: 0.1.0
/// Author: Christoph J. Scherr <software@cscherr.de>
///
/// ```
pub const HELP_TEMPLATE: &str = r"{about-section}
{usage-heading} {usage}
{all-args}{tab}
{name}: {version}
Author: {author-with-newline}
";
/// Transform -v and -q flags to some kind of loglevel
///
/// # Example
///
/// Include this into your [clap] derive struct like this:
///
/// ```
/// use libpt_cli::args::VerbosityLevel;
/// use clap::Parser;
///
/// #[derive(Parser, Debug)]
/// pub struct Opts {
/// #[command(flatten)]
/// pub verbose: VerbosityLevel,
/// #[arg(short, long)]
/// pub mynum: usize,
/// }
///
/// ```
///
/// Get the loglevel like this:
///
/// ```no_run
/// # use libpt_cli::args::VerbosityLevel;
/// use libpt_log::Level;
/// # use clap::Parser;
///
/// # #[derive(Parser, Debug)]
/// # pub struct Opts {
/// # #[command(flatten)]
/// # pub verbose: VerbosityLevel,
/// # }
///
/// fn main() {
/// let opts = Opts::parse();
///
/// // Level might be None if the user wants no output at all.
/// // for the 'tracing' level:
/// let level: Level = opts.verbose.level();
/// }
/// ```
#[derive(Parser, Clone, PartialEq, Eq, Hash)]
pub struct VerbosityLevel {
/// make the output more verbose
#[arg(
long,
short = 'v',
action = clap::ArgAction::Count,
global = true,
// help = L::verbose_help(),
// long_help = L::verbose_long_help(),
)]
verbose: i8,
/// make the output less verbose
///
/// ( -qqq for completely quiet)
#[arg(
long,
short = 'q',
action = clap::ArgAction::Count,
global = true,
conflicts_with = "verbose",
)]
quiet: i8,
}
impl VerbosityLevel {
/// true only if no verbose and no quiet was set (user is using defaults)
#[inline]
#[must_use]
#[allow(clippy::missing_const_for_fn)] // the values of self can change
pub fn changed(&self) -> bool {
self.verbose != 0 || self.quiet != 0
}
#[inline]
#[must_use]
fn value(&self) -> i8 {
Self::level_value(Level::INFO)
.saturating_sub((self.quiet).min(10))
.saturating_add((self.verbose).min(10))
}
/// get the [Level] for that [`VerbosityLevel`]
///
/// # Examples
///
/// ```
/// use libpt_log::Level; // reexport: tracing
/// use libpt_cli::args::VerbosityLevel;
///
/// let verbosity_level = VerbosityLevel::INFO;
/// assert_eq!(verbosity_level.level(), Level::INFO);
/// ```
#[inline]
#[must_use]
pub fn level(&self) -> Level {
let v = self.value();
match v {
0 => Level::ERROR,
1 => Level::WARN,
2 => Level::INFO,
3 => Level::DEBUG,
4 => Level::TRACE,
_ => {
if v > 4 {
Level::TRACE
} else {
/* v < 0 */
Level::ERROR
}
}
}
}
/// get the [`log::Level`] for that `VerbosityLevel`
///
/// This is the method for the [log] crate, which I use less often.
///
/// [None] means that absolutely no output is wanted (completely quiet)
#[inline]
#[must_use]
#[cfg(feature = "log")]
pub fn level_for_log_crate(&self) -> log::Level {
match self.level() {
Level::TRACE => log::Level::Trace,
Level::DEBUG => log::Level::Debug,
Level::INFO => log::Level::Info,
Level::WARN => log::Level::Warn,
Level::ERROR => log::Level::Error,
}
}
#[inline]
#[must_use]
const fn level_value(level: Level) -> i8 {
match level {
Level::TRACE => 4,
Level::DEBUG => 3,
Level::INFO => 2,
Level::WARN => 1,
Level::ERROR => 0,
}
}
/// # Examples
///
/// ```
/// use libpt_log::Level; // reexport: tracing
/// use libpt_cli::args::VerbosityLevel;
///
/// let verbosity_level = VerbosityLevel::TRACE;
/// assert_eq!(verbosity_level.level(), Level::TRACE);
/// ```
pub const TRACE: Self = Self {
verbose: 2,
quiet: 0,
};
/// # Examples
///
/// ```
/// use libpt_log::Level; // reexport: tracing
/// use libpt_cli::args::VerbosityLevel;
///
/// let verbosity_level = VerbosityLevel::DEBUG;
/// assert_eq!(verbosity_level.level(), Level::DEBUG);
/// ```
pub const DEBUG: Self = Self {
verbose: 1,
quiet: 0,
};
/// # Examples
///
/// ```
/// use libpt_log::Level; // reexport: tracing
/// use libpt_cli::args::VerbosityLevel;
///
/// let verbosity_level = VerbosityLevel::INFO;
/// assert_eq!(verbosity_level.level(), Level::INFO);
/// ```
pub const INFO: Self = Self {
verbose: 0,
quiet: 0,
};
/// # Examples
///
/// ```
/// use libpt_log::Level; // reexport: tracing
/// use libpt_cli::args::VerbosityLevel;
///
/// let verbosity_level = VerbosityLevel::WARN;
/// assert_eq!(verbosity_level.level(), Level::WARN);
/// ```
pub const WARN: Self = Self {
verbose: 0,
quiet: 1,
};
/// # Examples
///
/// ```
/// use libpt_log::Level; // reexport: tracing
/// use libpt_cli::args::VerbosityLevel;
///
/// let verbosity_level = VerbosityLevel::ERROR;
/// assert_eq!(verbosity_level.level(), Level::ERROR);
/// ```
pub const ERROR: Self = Self {
verbose: 0,
quiet: 2,
};
}
impl std::fmt::Debug for VerbosityLevel {
#[inline]
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{:?}", self.level())
}
}
impl Default for VerbosityLevel {
fn default() -> Self {
Self::INFO
}
}

View File

@ -0,0 +1,14 @@
#![warn(clippy::pedantic, clippy::style, clippy::nursery)]
pub mod args;
pub mod printing;
pub mod repl;
pub use clap;
pub use comfy_table;
pub use console;
pub use dialoguer;
pub use exitcode;
pub use human_panic;
pub use indicatif;
pub use shlex;
pub use strum;

View File

@ -0,0 +1,145 @@
//! Utilities for formatting, bordering, aligning and printing text content
//!
//! This module provides functions for formatting content with borders and colors, printing them to the console.
//! The functions in this module are designed to simplify the process of creating visually appealing
//! output for CLI applications.
//!
//! Note that most of the utilities in this module are focused on communication with humans, not
//! with machines. Consider evaluating [`std::io::IsTerminal`] before using colorful, dynamic and bordered
//! printing. If you are talking to a machine, it might be useful to not add extra space, add a
//! newline per output or even output JSON. An example that does this well is `ls`:
//!
//! ```bash
//! $ ls
//! Cargo.lock Cargo.toml data LICENSE members README.md scripts src target
//! ```
//!
//! ```bash
//! $ ls | cat
//! Cargo.lock
//! Cargo.toml
//! data
//! LICENSE
//! members
//! README.md
//! scripts
//! src
//! target
//! ```
//!
//! See the [CLI Rustbook](https://rust-cli.github.io/book/in-depth/machine-communication.html) for
//! more information on the topic.
use comfy_table::presets;
use comfy_table::{CellAlignment, ContentArrangement, Table};
use console::{style, Color};
/// Prints content with a simple border around it
///
/// This function is a convenience wrapper around [blockfmt] and [println]. It automatically
/// formats the content with a border using the specified color and then prints it to the console.
///
/// # Example
///
/// ```
/// use libpt_cli::console::Color;
/// use libpt_cli::printing::blockprint;
/// # fn main() {
/// blockprint("Hello world!", Color::Blue);
/// # }
/// ```
#[inline]
#[allow(clippy::needless_pass_by_value)] // we just take an impl, using a &impl is much less ergonomic
pub fn blockprint(content: impl ToString, color: Color) {
println!("{}", blockfmt(content, color));
}
/// Formats content with a simple border around it
///
/// This function is a convenience wrapper around [`blockfmt_advanced`] with preset values for
/// border style, content arrangement, and cell alignment. It automatically formats the content
/// with a border as large as possible and centers the content. The resulting cell is colored in
/// the specified color.
///
/// # Example
///
/// ```
/// use libpt_cli::console::Color;
/// use libpt_cli::printing::blockfmt;
/// # fn main() {
/// let formatted_content = blockfmt("Hello world!", Color::Blue);
/// println!("{}", formatted_content);
/// # }
/// ```
#[inline]
#[allow(clippy::needless_pass_by_value)] // we just take an impl, using a &impl is much less ergonomic
pub fn blockfmt(content: impl ToString, color: Color) -> String {
blockfmt_advanced(
content,
Some(color),
presets::UTF8_BORDERS_ONLY,
ContentArrangement::DynamicFullWidth,
CellAlignment::Center,
)
}
/// Formats content with a border around it
///
/// Unless you are looking for something specific, use [blockfmt] or [blockprint].
///
/// The border can be created using box-drawing characters, and the content is formatted
/// within the border. The function allows customization of the border's color, preset,
/// content arrangement, and cell alignment.
///
/// # Example
/// ```
/// use libpt_cli::comfy_table::{presets, CellAlignment, ContentArrangement};
/// use libpt_cli::console::Color;
/// use libpt_cli::printing::blockfmt_advanced;
/// # fn main() {
/// println!(
/// "{}",
/// blockfmt_advanced(
/// "Hello world!",
/// Some(Color::Blue),
/// presets::UTF8_FULL,
/// ContentArrangement::DynamicFullWidth,
/// CellAlignment::Center
/// )
/// );
/// # }
/// ```
/// ```text
/// ┌────────────────────────────────────────────────────────────────────────────────────────┐
/// │ Hello world! │
/// └────────────────────────────────────────────────────────────────────────────────────────┘
/// ```
///
/// # Parameters
///
/// - `content`: The content to be formatted within the border
/// - `color`: The color of the border and text
/// - `preset`: The preset style for the border
/// - `arrangement`: The arrangement of the the border (e.g., stretch to sides, wrap around )
/// - `alignment`: The alignment of the content within the cells (e.g., left, center, right)
#[allow(clippy::missing_panics_doc)] // we add a row then unwrap it, no panic should be possible
#[allow(clippy::needless_pass_by_value)] // we just take an impl, using a &impl is much less ergonomic
pub fn blockfmt_advanced(
content: impl ToString,
color: Option<Color>,
preset: &str,
arrangement: ContentArrangement,
alignment: CellAlignment,
) -> String {
let mut table = Table::new();
table
.load_preset(preset)
.set_content_arrangement(arrangement)
.add_row(vec![content.to_string()]);
table.column_mut(0).unwrap().set_cell_alignment(alignment);
match color {
Some(c) => format!("{}", style(table).fg(c)),
None => table.to_string(),
}
}

View File

@ -0,0 +1,217 @@
//! This module implements a default repl that fullfills the [Repl] trait
//!
//! You can implement your own [Repl] if you want.
use std::fmt::Debug;
use super::Repl;
use embed_doc_image::embed_doc_image;
/// [clap] help template with only usage and commands/options
pub const REPL_HELP_TEMPLATE: &str = r"{usage-heading} {usage}
{all-args}{tab}
";
use clap::{Parser, Subcommand};
use dialoguer::{BasicHistory, Completion};
use libpt_log::trace;
#[allow(clippy::needless_doctest_main)] // It makes the example look better
/// Default implementation for a REPL
///
/// Note that you need to define the commands by yourself with a Subcommands enum.
///
/// # Example
///
/// ```no_run
/// use libpt_cli::repl::{DefaultRepl, Repl};
/// use libpt_cli::clap::Subcommand;
/// use libpt_cli::strum::EnumIter;
///
/// #[derive(Subcommand, Debug, EnumIter, Clone)]
/// enum ReplCommand {
/// /// hello world
/// Hello,
/// /// leave the repl
/// Exit,
/// }
///
/// fn main() {
/// let mut repl = DefaultRepl::<ReplCommand>::default();
/// loop {
/// repl.step().unwrap();
/// match repl.command().to_owned().unwrap() {
/// ReplCommand::Hello => println!("Hello"),
/// ReplCommand::Exit => break,
/// _ => (),
/// }
/// }
/// }
/// ```
/// **Screenshot**
///
/// ![Screenshot of an example program with a REPL][repl_screenshot]
#[embed_doc_image("repl_screenshot", "data/media/repl.png")]
#[derive(Parser)]
#[command(multicall = true, help_template = REPL_HELP_TEMPLATE)]
#[allow(clippy::module_name_repetitions)] // we can't just name it `Default`, that's part of std
pub struct DefaultRepl<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
/// the command you want to execute, along with its arguments
#[command(subcommand)]
command: Option<C>,
// the following fields are not to be parsed from a command, but used for the internal workings
// of the repl
#[clap(skip)]
buf: String,
#[clap(skip)]
buf_preparsed: Vec<String>,
#[clap(skip)]
completion: DefaultReplCompletion<C>,
#[clap(skip)]
history: BasicHistory,
}
#[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, PartialOrd, Ord)]
struct DefaultReplCompletion<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
commands: std::marker::PhantomData<C>,
}
impl<C> Repl<C> for DefaultRepl<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
fn new() -> Self {
Self {
command: None,
buf_preparsed: Vec::new(),
buf: String::new(),
history: BasicHistory::new(),
completion: DefaultReplCompletion::new(),
}
}
fn command(&self) -> &Option<C> {
&self.command
}
fn step(&mut self) -> Result<(), super::error::Error> {
self.buf.clear();
// NOTE: display::Input requires some kind of lifetime that would be a bother to store in
// our struct. It's documentation also uses it in place, so it should be fine to do it like
// this.
//
// NOTE: It would be nice if we could use the Validator mechanism of dialoguer, but
// unfortunately we can only process our input after we've preparsed it and we need an
// actual output. If we could set a status after the Input is over that would be amazing,
// but that is currently not supported by dialoguer.
// Therefore, every prompt will show as success regardless.
self.buf = dialoguer::Input::with_theme(&dialoguer::theme::ColorfulTheme::default())
.completion_with(&self.completion)
.history_with(&mut self.history)
.interact_text()?;
self.buf_preparsed = Vec::new();
self.buf_preparsed
.extend(shlex::split(&self.buf).unwrap_or_default());
trace!("read input: {:?}", self.buf_preparsed);
trace!("repl after step: {:#?}", self);
// HACK: find a way to not allocate a new struct for this
let cmds = Self::try_parse_from(&self.buf_preparsed)?;
self.command = cmds.command;
Ok(())
}
}
impl<C> Default for DefaultRepl<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
fn default() -> Self {
Self::new()
}
}
impl<C> Debug for DefaultRepl<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("DefaultRepl")
.field("command", &self.command)
.field("buf", &self.buf)
.field("buf_preparsed", &self.buf_preparsed)
.field("completion", &self.completion)
.field("history", &"(no debug)")
.finish()
}
}
impl<C> DefaultReplCompletion<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
/// Make a new [`DefaultReplCompletion`] for the type `C`
pub const fn new() -> Self {
Self {
commands: std::marker::PhantomData::<C>,
}
}
fn commands() -> Vec<String> {
let mut buf = Vec::new();
// every crate has the help command, but it is not part of the enum
buf.push("help".to_string());
for c in C::iter() {
// HACK: this is a horrible way to do this
// I just need the names of the commands
buf.push(
format!("{c:?}")
.split_whitespace()
.map(str::to_lowercase)
.next()
.unwrap()
.to_string(),
);
}
trace!("commands: {buf:?}");
buf
}
}
impl<C> Default for DefaultReplCompletion<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
fn default() -> Self {
Self::new()
}
}
impl<C> Completion for DefaultReplCompletion<C>
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
/// Simple completion implementation based on substring
fn get(&self, input: &str) -> Option<String> {
let matches = Self::commands()
.into_iter()
.filter(|option| option.starts_with(input))
.collect::<Vec<_>>();
trace!("\nmatches: {matches:#?}");
if matches.len() == 1 {
Some(matches[0].to_string())
} else {
None
}
}
}

View File

@ -0,0 +1,13 @@
//! Errors for the Repl module
use thiserror::Error;
#[derive(Error, Debug)]
pub enum Error {
#[error(transparent)]
Parsing(#[from] clap::Error),
#[error(transparent)]
Input(#[from] dialoguer::Error),
#[error(transparent)]
Other(#[from] anyhow::Error),
}

View File

@ -0,0 +1,48 @@
//! Create easy and well defined REPLs
//!
//! A REPL is a [Read-Eval-Print-Loop](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop).
//! Well known examples for REPLs are shells (like bash).
//!
//! This module offers a convenient way to create a well-defined REPL without a lot of complicated
//! code and with a visually pleasing aesthetic. An example REPL implementation can be found in the
//! examples.
//!
//! The basic idea is that the user defines the commands with an enum and uses [claps](clap)
//! `#[derive(Subcommand)]`. A loop is then used to read from the stdin into a buffer, that buffer
//! is put to [clap] for parsing, similar to how [clap] would parse commandline arguments.
use std::fmt::Debug;
pub mod error;
use error::Error;
mod default;
pub use default::*;
use clap::{Parser, Subcommand};
/// Common Trait for repl objects
///
/// Unless you want to implement custom features (not just commands), just use [`DefaultRepl`].
pub trait Repl<C>: Parser + Debug
where
C: Debug + Subcommand + strum::IntoEnumIterator,
{
/// create a new repl
fn new() -> Self;
/// get the command that was parsed from user input
///
/// Will only be [None] if the repl has not had [step](Repl::step) executed yet.
fn command(&self) -> &Option<C>;
/// advance the repl to the next iteration of the main loop
///
/// This should be used at the start of your loop.
///
/// Note that the help menu is an Error: [`clap::error::ErrorKind::DisplayHelp`]
///
/// # Errors
///
/// * [`Error::Input`] [dialoguer] User Input had some kind of I/O Error
/// * [`Error::Parsing`] [clap] could not parse the user input, or user requested help
/// * [`Error::Other`] Any other error with [anyhow], [`DefaultRepl`] does not use this but custom implementations might
fn step(&mut self) -> Result<(), Error>;
}

View File

@ -8,5 +8,3 @@
/// macros to make things faster in your code /// macros to make things faster in your code
pub mod macros; pub mod macros;
/// some general use printing to stdout tools
pub mod printing;

View File

@ -1,11 +0,0 @@
//! # tools that make printing stuff better
/// Quickly get a one line visual divider
pub fn divider() -> String {
format!("{:=^80}", "=")
}
/// Quickly print a one line visual divider
pub fn print_divider() {
println!("{:=^80}", "=")
}

View File

@ -1,7 +1,7 @@
[package] [package]
name = "libpt-log" name = "libpt-log"
publish.workspace = true publish.workspace = true
version = "0.4.2" version = "0.4.3"
edition.workspace = true edition.workspace = true
authors.workspace = true authors.workspace = true
license.workspace = true license.workspace = true

View File

@ -23,6 +23,7 @@ use std::{
pub mod error; pub mod error;
use error::*; use error::*;
pub use tracing;
pub use tracing::{debug, error, info, trace, warn, Level}; pub use tracing::{debug, error, info, trace, warn, Level};
use tracing_appender::{self, non_blocking::NonBlocking}; use tracing_appender::{self, non_blocking::NonBlocking};
use tracing_subscriber::fmt::{format::FmtSpan, time}; use tracing_subscriber::fmt::{format::FmtSpan, time};

View File

@ -19,7 +19,7 @@ name = "libpt"
crate-type = ["cdylib", "rlib"] crate-type = ["cdylib", "rlib"]
[dependencies] [dependencies]
libpt = { version = "0.5.0", path = "../.." } libpt = { version = "0.5.0"}
pyo3 = { version = "0.19.0", features = ["full"] } pyo3 = { version = "0.19.0", features = ["full"] }
anyhow.workspace = true anyhow.workspace = true

View File

@ -1,4 +1,4 @@
//! Python bindings for [`libpt`](libpt) //! Python bindings for [`libpt`]
#[cfg(feature = "bintols")] #[cfg(feature = "bintols")]
mod bintols; mod bintols;

View File

@ -5,9 +5,12 @@
//! //!
//! `pt` is a project consisting of multiple smaller crates, all bundled together in this //! `pt` is a project consisting of multiple smaller crates, all bundled together in this
//! "main crate". Most crates will only show up if you activate their feature. //! "main crate". Most crates will only show up if you activate their feature.
#![warn(clippy::pedantic, clippy::style, clippy::nursery)]
#[cfg_attr(docsrs, doc(cfg(feature = "full")))] #[cfg_attr(docsrs, doc(cfg(feature = "full")))]
#[cfg(feature = "bintols")] #[cfg(feature = "bintols")]
pub use libpt_bintols as bintols; pub use libpt_bintols as bintols;
#[cfg(feature = "cli")]
pub use libpt_cli as cli;
#[cfg(feature = "core")] #[cfg(feature = "core")]
pub use libpt_core as core; pub use libpt_core as core;
#[cfg(feature = "log")] #[cfg(feature = "log")]