cliw/

lib.rs

#![warn(missing_docs)]
#![allow(clippy::needless_doctest_main)]
//! # Command line in web.
//! **Clap in web.**
//!
//! Pronounced "Clue" as in "Get a cliw."
//!
//! Command line arguments for native and the web.
//! \
//! Also provide output for the web.
//!
//! The goal is to be flexible, write your command line code once and it should be able to run anywhere!
//!
//! # Command Line Arguments
//! Provides a simple wrapper function [`args_os()`] that returns [`ArgsOs`] from [`std::env::args_os`]
//! when running on native and [`UrlArgs`] when running on wasm.  This is feature gated with the
//! "urlargs" feature.
//!
//! # Output
//! Provides writers for output to the web when compiling to wasm and running in a browser.
//! Also basic [`print(&str)`] and [`eprint(&str)`] functions that use the web or standard output
//! depending on if compiled to native or wasm.  On native, output is to standard output.  On the
//! web the output can be to the [console], a pop-up [`alert`], or standard output.
//! Web output is feature gated with the "console", "alert", and "web-std-output" features.
//!
//! # Why use cliw?
//!
//! You probably don't want to use [`cliw`] directly.  This crate was designed so [`clap`] can be
//! used in the web.  You normaly [`use cliw indirectly`] with a web enabled clap, [`we-clap`]
//! which gives your web page clap powers. (opt parsing, help, suggestions, etc)
//!
//! The README with [`recommended usage`] and screenshots is at [`crates.io`], or the [`cliw repository`].
//! Also check out the [`docs`] and [`examples`], specifically the [`we-clap_demo`] example.
//!
//! # Why not use cliw?
//! * If you are writing only for the web, you may not be wanting to use command line arguments.
//! * You might have another use of the url query string.
//! * You might be compiling to wasm but the framework you use provides [`std::env::args_os`]
//!   and/or standard output.
//!
//! # Example `cliw_demo`
//! As mentioned above, you probably want to [`use cliw indirectly`], with [`we-clap`] but here
//! is the obligitory [`cliw_demo`] example if you want to use just cliw.
//! ## Cargo.toml
//! ```toml
//!  [package]
//!  name = "cliw_demo"
//!  version = "0.1.0"
//!  edition = "2021"
//!
//!  [dependencies]
//!  cliw = { version = "0.1.0", features = [
//!      "alert",
//!      "urlargs",
//!  ]}
//! ```
//! ## main.rs
//! ```
//! fn main() {
//!     // Get the args from CLI on native
//!     // or the webpage URL on wasm in the browser
//!     let args = cliw::args_os();
//!     let args: Vec<_> = args.collect();
//!     let msg = format!("{:?}", args);
//!     // Output to standard on native
//!     // or web popup alert on wasm in the browser
//!     cliw::output::print(&msg);
//! }
//! ```
//! ## Running on native.
//! ```console
//! $ cargo r -- arg1 arg2 ar3
//!     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
//!      Running `/path/to/target/debug/cliw_demo arg1 arg2 ar3`
//! ["/path/to/target/debug/cliw_demo", "arg1", "arg2", "ar3"]
//! ```
//! ## Running on the web with "alert" and "urlargs" features.
//! ```console
//! $ cargo r --target wasm32-unknown-unknown
//!     Finished `dev` profile [unoptimized + debuginfo] target(s) in 10.44s
//!      Running `wasm-server-runner /path/to/target/wasm32-unknown-unknown/debug/cliw_demo.wasm`
//!  INFO wasm_server_runner: uncompressed wasm output is 189.62kb in size
//!  INFO wasm_server_runner: starting webserver at http://127.0.0.1:1334
//! ```
//!  Pointing your browser to
//!  ```console
//!  http://127.0.0.1:1334/?arg1&arg2&and&whatever
//!  ```
//!  you would get a popup alert with the following text.
//!  ```console
//!  ["http://127.0.0.1:1334/", "arg1", "arg2", "and", "whatever"]
//!  ```
//!
//! # Features
//!
//! The functionality of the cliw crate is gated by features.
//!
//! * "alert"            :     Enable output to browser popup alert.
//! * "console"          :     Enable output to browser console.
//! * "web-std-output"   :     Enable standard output on the web.  You can use this if your web
//!   framework provides standard output.  You always get standard output on native
//! * "urlargs"          :     Enable getting args from [`UrlArgs`] on the web.  Do not use this if
//!   your web framework provides [`std::env::args_os`].
//!
//!  For simplicity just set the "urlargs" and "console" or "alert" features in you Cargo.toml for
//!  both native and wasm.  Under native you always get standard args and output.
//!  ```toml
//!  cliw = { version = "0.1.0", features = [
//!      "alert",
//!      "urlargs",
//!  ]}
//!  ```
//!
//! [`args_os()`]: args_os
//! [`ArgsOs`]: std::env::ArgsOs
//! [console]: https://developer.mozilla.org/en-US/docs/Web/API/console
//! [`alert`]: https://developer.mozilla.org/en-US/docs/Web/API/Window/alert
//! [`print(&str)`]: output::print
//! [`eprint(&str)`]: output::eprint
//! [`cliw`]: crate
//! [`cliw_demo`]: https://github.com/stonerfish/cliw_examples/cliw_demo
//! [`docs`]: https://docs.rs/cliw
//! [`examples`]: https://github.com/stonerfish/cliw_examples
//! [`cliw repository`]: https://github.com/stonerfish/cliw/
//! [`crates.io`]: https://crates.io/crates/cliw/
//! [`clap`]: https://crates.io/crates/clap/
//! [`recommended usage`]: https://crates.io/crates/cliw/#recommended-usage
//! [`UrlArgs`]: url_args::UrlArgs
//! [`use cliw indirectly`]: https://github.com/stonerfish/cliw_examples/we-clap_demos/we-clap_demo
//! [`web enabled clap`]: https://github.com/stonerfish/clap/tree/we-clap
//! [`we-clap`]: https://github.com/stonerfish/clap/tree/we-clap
//! [`we-clap_demo`]: https://github.com/stonerfish/cliw_examples/we-clap_demos/we-clap_demo

pub mod output;
pub mod url_args;

/// Return [`ArgsOs`] from [`env::args_os`] on native or [`UrlArgs`] on wasm
///
/// This function is feature gated.  To enable getting [`UrlArgs`] on wasm
/// you must enable the "urlargs" feature.
/// ## Example
/// ```rust
///     let args_iter = cliw::args_os();
/// ```
///
/// [`ArgsOs`]: std::env::ArgsOs
/// [`env::args_os`]: std::env::args_os
/// [`UrlArgs`]: url_args::UrlArgs
pub fn args_os() -> impl Iterator<Item = std::ffi::OsString> {
    #[cfg(not(all(target_arch = "wasm32", feature = "urlargs")))]
    {
        std::env::args_os()
    }

    #[cfg(all(target_arch = "wasm32", feature = "urlargs"))]
    {
        crate::url_args::UrlArgs::new()
    }
}