cliw 0.1.1

Command Line In Web
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159

#![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()
    }
}