docs: more readme examples

Refs: #26

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "numf"
-version = "0.3.1"
+version = "0.4.1"
 edition = "2021"
 publish = true
 authors = ["Christoph J. Scherr <software@cscherr.de>"]
@@ -16,8 +16,7 @@ categories = ["command-line-utilities", "encoding"]
 [dependencies]
 anyhow = "1.0.83"
 clap = { version = "4.5.4", features = ["derive"] }
-clap-num = "1.1.1"
 fast32 = "1.0.2"
-libpt = { version = "0.5.1", features = ["bintols"]}
+libpt = { version = "0.6.0", features = ["bintols", "log", "cli"] }
 num = "0.4.3"
-
+rand = "0.8.5"

README.md

@@ -1,5 +1,18 @@
 # numf
 
+
+![Project badge](https://img.shields.io/badge/language-Rust-blue.svg)
+![Crates.io License](https://img.shields.io/crates/l/numf)
+![Gitea Release](https://img.shields.io/gitea/v/release/PlexSheep/numf?gitea_url=https%3A%2F%2Fgit.cscherr.de)
+![Gitea language count](https://img.shields.io/gitea/languages/count/PlexSheep/numf?gitea_url=https%3A%2F%2Fgit.cscherr.de)
+[![cargo checks and tests](https://github.com/PlexSheep/numf/actions/workflows/cargo.yaml/badge.svg)](https://github.com/PlexSheep/numf/actions/workflows/cargo.yaml)
+
+* [Original Repository](https://git.cscherr.de/PlexSheep/numf)
+* [GitHub Mirror](https://github.com/PlexSheep/numf)
+* [Codeberg Mirror](https://codeberg.org/PlexSheep/numf)
+* [crates.io](https://crates.io/crates/numf)
+* [docs.rs](https://docs.rs/numf/latest/numf/)
+
 `numf` is a number formatter. It formats the numbers provided to it.
 
 Current formats are:
@@ -10,9 +23,11 @@ Current formats are:
 - Decimal
 - Base32
 - Base64
+- Raw
 
-`numf` also has the option of prepending a prefix for each format, such as
-`0x` for hexadecimal.
+`numf` also has the option of prepending a prefix for the formats, such as
+`0x` for hexadecimal. Numbers may also be provided from the stdin. See `--help`
+flag for more information.
 
 ## Example
 
@@ -21,4 +36,34 @@ $ numf -xp 1337 505 0xaabb
 0x539
 0x1F9
 0xAABB
+$ numf -a 505 | hedxump -C
+00000000  01 f9                                             |..|
+00000002
+$ numf -a 505 | numf
+1F9
+$ numf -a 505 | numf -d
+505
+$ numf -a 505 | numf -b
+111111001
+$ echo -ne "\x20\xff\xb4" | numf -xpP
+0x20FFB4
+$ echo -ne "\x20\xff\xb4" | numf -d
+2162612
+$ base64='aGVsbG8gd29ybGQuCg==' ; echo "0s$base64" | numf -d
+8271117963529473544792763018762
+$ base64='aGVsbG8gd29ybGQuCg==' ; echo "0s$base64" | numf -s
+aGVsbG8gd29ybGQuCg==
+$ echo "0b100100101010" | numf -d
+2346
+$ echo "0b100100101010" | numf -bPp
+0b0000100100101010
+```
+## Installing
+
+### Cargo
+
+`numf` is on [crates.io](https://crates.io).
+
+```
+cargo install numf
 ```

scripts/release.sh

@@ -4,7 +4,7 @@ NEW_VERSION=$(cat Cargo.toml | rg '^\s*version\s*=\s*"([^"]*)"\s*$' -or '$1')
 GIT_COMMIT_SHA=$(git rev-parse HEAD)
 REPO=${PWD##*/} # name of cwd
 BODY="
-$(git log $(git describe --tags --abbrev=0)..HEAD --pretty="- %s" --oneline --decorate)
+$(git log $(git describe --tags --abbrev=0)..HEAD --pretty="- %s" --oneline --no-decorate)
 "
 USER=PlexSheep
 git tag "v$NEW_VERSION" || echo "could not tag"

src/format.rs

@@ -1,26 +1,97 @@
-#![allow(dead_code)] // this is exported to lib.rs
+//! This module implements the actual formatting in [numf](crate).
+//!
+//! You can use it in your own program to convert numbers to formats.
+//!
+//! # Example
+//!
+//! The following example shows how to use numf to format your integers.
+//!
+//! ```
+//! use numf::format::{Format, FormatOptions};
+//!
+//! let mut options = FormatOptions::default();
+//! options.set_prefix(true);
+//! options.set_padding(true);
+//!
+//! assert_eq!(Format::Hex.format_str(0x1337, &options), "0x1337");
+//! assert_eq!(Format::Base32.format_str(0x41414242, &options), "032sIFAUEQQ=");
+//! assert_eq!(Format::Base64.format_str(0x41414242, &options), "0sQUFCQg==");
+//! // sometimes you might need the raw bytes instead of a String
+//! assert_eq!(Format::Raw.format(0x1337, &options), vec![0x00, 0x13, 0x37]);
+//! assert_eq!(Format::Hex.format(0x1337, &options), vec![48, 120, 49, 51, 51, 55]);
+//!
+//! options.set_prefix(false);
+//! options.set_padding(false);
+//!
+//! assert_eq!(Format::Hex.format_str(0x1337, &options), "1337");
+//! assert_eq!(Format::Base32.format_str(0x41414242, &options), "IFAUEQQ=");
+//! assert_eq!(Format::Base64.format_str(0x41414242, &options), "QUFCQg==");
+//!
+//! assert_eq!(Format::Raw.format(0x1337, &options), vec![0x13, 0x37]);
+//! assert_eq!(Format::Hex.format(0x1337, &options), vec![49, 51, 51, 55]);
+//! ```
+
+#![allow(dead_code)]
+use std::fmt::Display;
+
+// this is exported to lib.rs
 use anyhow::anyhow;
 use clap::{ArgGroup, Parser};
 use libpt::bintols::{join, split};
+use libpt::cli::args::VerbosityLevel;
+use libpt::log::{debug, trace};
 
+/// The number type [numf](crate) uses
 pub type NumberType = u128;
 
-/// formats supported by numf
-#[derive(Copy, Clone, Debug, Hash, PartialEq, Eq)]
+/// Describes a format for numbers
+///
+/// [Format] can be used to convert unsigned integers into a textual or other representation. See
+/// [Format::format_str] for more. It is also possible to parse the various represenations to
+/// a rust integer, see [numf_parser_str] for that.
+#[derive(Copy, Clone, Debug, Hash, PartialEq, Eq, Default)]
 pub enum Format {
     Dec,
+    #[default]
     Hex,
     Bin,
     Octal,
     Base64,
     Base32,
+    /// Write raw data, not text
+    Raw,
 }
 
-/// Describes what the formatter should do
+impl Display for Format {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{self:?}")
+    }
+}
+
+/// Describes what the formatter should do exactly
 ///
 /// Use [Self::default] to get a basic variant or create a object yourself.
 ///
 /// This struct can be parsed with [clap] derive.
+///
+/// # Example
+///
+/// ```
+/// use numf::format::{Format, FormatOptions};
+/// let mut options = FormatOptions::default();
+///
+/// assert_eq!(Format::Bin.format_str(256, &options), "100000000");
+/// assert_eq!(Format::Hex.format_str(256, &options), "100");
+/// assert_eq!(Format::Base64.format_str(256, &options), "AQA=");
+///
+/// options.set_prefix(true);
+/// options.set_padding(true);
+///
+/// assert_eq!(Format::Bin.format_str(256, &options), "0b0000000100000000");
+/// assert_eq!(Format::Hex.format_str(256, &options), "0x0100");
+/// assert_eq!(Format::Base64.format_str(256, &options), "0sAQA=");
+///
+/// ```
 #[derive(Parser, Debug, Clone, PartialEq, Eq, Hash)]
 #[clap(author, version, about, long_about = None)]
 #[command(
@@ -38,7 +109,7 @@ Author: {author-with-newline}
 )]
 #[clap(group(
             ArgGroup::new("format")
-                .args(&["hex", "bin", "oct", "dec", "base64", "base32"]),
+                .args(&["hex", "bin", "oct", "dec", "base64", "base32", "raw"]),
         ))]
 pub struct FormatOptions {
     #[arg(short, long)]
@@ -50,7 +121,7 @@ pub struct FormatOptions {
     /// For example, `0b1100` will be `0b00001100` with this.
     /// This does not apply to all formats, only hexadecimal and binary.
     padding: bool,
-    #[arg(short = 'x', long, default_value_t = true)]
+    #[arg(short = 'x', long)]
     /// format to hexadecimal
     hex: bool,
     #[arg(short, long)]
@@ -65,30 +136,51 @@ pub struct FormatOptions {
     #[arg(short = 's', long)]
     /// format to base64
     base64: bool,
+    #[arg(short = 'a', long)]
+    /// format raw, no text
+    raw: bool,
+    #[arg(short = 'r', long, default_value_t = 0, value_parser=numf_parser_str::<NumberType>)]
+    /// output random numbers
+    ///
+    /// Add a user defined amount of cryptographically pseudorandom numbers to the number list.
+    rand: NumberType,
+    #[arg(long, default_value_t = NumberType::MAX, value_parser=numf_parser_str::<NumberType>)]
+    /// max for the random numbers
+    ///
+    /// Generated numbers will not be lower than this. Only has an effect with --rand set.
+    rand_max: NumberType,
     #[arg(short = 'z', long)]
     /// format to base32
     base32: bool,
-    #[clap(value_parser=numf_parser::<NumberType>, required=false)]
-    /// at least one number that should be formatted
+    #[clap(value_parser=numf_parser_str::<NumberType>, required=false)]
+    /// numbers that should be formatted
     ///
     /// Any of the [Formats](Format::format) are supported, but the prefixes are needed for formats
     /// other than decimal.
     ///
     /// Formats:
     ///
-    /// - '0x' - Hexadecimal
-    /// - '0b' - Binary
-    /// - '0o' - Octal
-    /// - '0s' - Base64
-    /// - '032s' - Base32
+    /// * '0x' - Hexadecimal
     ///
-    /// The numbers may be left empty at first, if numbers are provided with the stdin.
+    /// * '0b' - Binary
+    ///
+    /// * '0o' - Octal
+    ///
+    /// * '0s' - Base64
+    ///
+    /// * '032s' - Base32
+    ///
+    /// The numbers may be left empty at first, if numbers are provided from the stdin.
     numbers: Vec<NumberType>,
+
+    #[command(flatten)]
+    pub(crate) verbosity: VerbosityLevel,
 }
 
 impl FormatOptions {
     /// get the format that the user has configured
     pub fn format(&self) -> Format {
+        trace!("self.hex: {}", self.hex);
         if self.oct {
             Format::Octal
         } else if self.bin {
@@ -101,8 +193,12 @@ impl FormatOptions {
             Format::Base32
         } else if self.hex {
             Format::Hex
+        } else if self.raw {
+            Format::Raw
         } else {
-            unreachable!()
+            // none was explicitly selected
+            debug!("no mode was explicitly selected, going with the default");
+            Format::default()
         }
     }
 
@@ -113,9 +209,11 @@ impl FormatOptions {
         self.dec = false;
         self.hex = false;
         self.base64 = false;
+        self.raw = false;
         self.base32 = false;
         match format {
             Format::Bin => self.bin = true,
+            Format::Raw => self.raw = true,
             Format::Hex => self.hex = true,
             Format::Octal => self.oct = true,
             Format::Base64 => self.base64 = true,
@@ -158,6 +256,26 @@ impl FormatOptions {
     pub fn push_number(&mut self, value: NumberType) {
         self.numbers.push(value)
     }
+
+    /// get rand
+    pub fn rand(&self) -> NumberType {
+        self.rand
+    }
+
+    /// set amount of extra random numbers manually
+    pub fn set_rand(&mut self, rand: NumberType) {
+        self.rand = rand;
+    }
+
+    /// get highes allowed random value
+    pub fn rand_max(&self) -> NumberType {
+        self.rand_max
+    }
+
+    /// set highes allowed random value
+    pub fn set_rand_max(&mut self, rand_max: NumberType) {
+        self.rand_max = rand_max;
+    }
 }
 
 impl Default for FormatOptions {
@@ -166,74 +284,184 @@ impl Default for FormatOptions {
             padding: false,
             prefix: false,
             oct: false,
-            hex: true,
+            hex: false,
             bin: false,
+            raw: false,
             base32: false,
             base64: false,
             dec: false,
             numbers: vec![],
+            rand: 0,
+            rand_max: NumberType::MAX,
+            verbosity: VerbosityLevel::default(),
         }
     }
 }
 
 impl Format {
-    /// Get the perfix for that [Format]
-    pub fn prefix(&self) -> String {
+    /// Get the perfix for that [Format] as [Vec<u8>].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use numf::format::Format;
+    /// assert_eq!(Format::Bin.prefix_str(), "0b");
+    /// assert_eq!(Format::Dec.prefix_str(), "0d");
+    /// assert_eq!(Format::Hex.prefix_str(), "0x");
+    /// assert_eq!(Format::Octal.prefix_str(), "0o");
+    /// assert_eq!(Format::Base64.prefix_str(), "0s");
+    /// assert_eq!(Format::Base32.prefix_str(), "032s");
+    /// assert_eq!(Format::Raw.prefix_str(), "\x00");
+    /// ```
+    pub fn prefix_str(&self) -> String {
+        String::from_utf8_lossy(&self.prefix()).to_string()
+    }
+
+    /// Get the perfix for that [Format] as [Vec<u8>].
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use numf::format::Format;
+    /// assert_eq!(Format::Bin.prefix(), b"0b");
+    /// assert_eq!(Format::Dec.prefix(), b"0d");
+    /// assert_eq!(Format::Hex.prefix(), b"0x");
+    /// assert_eq!(Format::Octal.prefix(), b"0o");
+    /// assert_eq!(Format::Base64.prefix(), b"0s");
+    /// assert_eq!(Format::Base32.prefix(), b"032s");
+    /// assert_eq!(Format::Raw.prefix(), vec![0x00]);
+    /// ```
+    pub fn prefix(&self) -> Vec<u8> {
         match self {
             // apperently used nowhere, sometimes 0 is used as a prefix but I
             // think this makes it more clear that this is decimal
-            Format::Dec => "0d",
+            Format::Dec => b"0d".to_vec(),
+            Format::Raw => [0x00].to_vec(),
             // very common
-            Format::Hex => "0x",
+            Format::Hex => b"0x".to_vec(),
             // very common
-            Format::Bin => "0b",
+            Format::Bin => b"0b".to_vec(),
             // somewhat common
-            Format::Octal => "0o",
+            Format::Octal => b"0o".to_vec(),
             // perl and a few other programs seem to use this too
-            Format::Base64 => "0s",
+            Format::Base64 => b"0s".to_vec(),
             // no idea, I made this up
-            Format::Base32 => "032s",
+            Format::Base32 => b"032s".to_vec(),
         }
-        .to_string()
     }
-    /// format a number with a [Format] and [FormatOptions]
-    pub fn format(&self, num: NumberType, options: &FormatOptions) -> String {
-        let mut buf = String::new();
+    /// format a number with a [Format] and [FormatOptions] to a [String]
+    ///
+    /// If you need raw byte outputs, use [Format::format] instead.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use numf::format::{Format, FormatOptions};
+    /// let mut options = FormatOptions::default();
+    ///
+    /// assert_eq!(Format::Bin.format_str(256, &options), "100000000");
+    /// assert_eq!(Format::Hex.format_str(256, &options), "100");
+    /// assert_eq!(Format::Base64.format_str(256, &options), "AQA=");
+    ///
+    /// options.set_prefix(true);
+    /// options.set_padding(true);
+    ///
+    /// assert_eq!(Format::Bin.format_str(256, &options), "0b0000000100000000");
+    /// assert_eq!(Format::Hex.format_str(256, &options), "0x0100");
+    /// assert_eq!(Format::Base64.format_str(256, &options), "0sAQA=");
+    ///
+    /// ```
+    pub fn format_str(&self, num: NumberType, options: &FormatOptions) -> String {
+        String::from_utf8_lossy(&self.format(num, options)).to_string()
+    }
+
+    /// format a number with a [Format] and [FormatOptions] to a byte vector [Vec<u8>]
+    ///
+    /// If you need [String] outputs, use [Format::format_str] instead.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use numf::format::{Format, FormatOptions};
+    /// let mut options = FormatOptions::default();
+    ///
+    /// assert_eq!(Format::Bin.format(256, &options), b"100000000");
+    /// assert_eq!(Format::Hex.format(256, &options), b"100");
+    /// assert_eq!(Format::Hex.format(256, &options), [49, 48, 48]);
+    /// assert_eq!(Format::Base64.format(256, &options), b"AQA=");
+    /// assert_eq!(Format::Raw.format(256, &options), [1, 0]);
+    ///
+    /// options.set_prefix(true);
+    /// options.set_padding(true);
+    ///
+    /// assert_eq!(Format::Bin.format(256, &options), b"0b0000000100000000");
+    /// assert_eq!(Format::Hex.format(256, &options), b"0x0100");
+    /// assert_eq!(Format::Hex.format(256, &options), [48, 120, 48, 49, 48, 48]);
+    /// assert_eq!(Format::Base64.format(256, &options), b"0sAQA=");
+    /// assert_eq!(Format::Raw.format(256, &options), [0, 1, 0]);
+    /// assert_eq!(Format::Raw.format(255, &options), [0, 255]);
+    /// assert_eq!(Format::Raw.format(32000, &options), [0, 125, 0]);
+    ///
+    /// ```
+    pub fn format(&self, num: NumberType, options: &FormatOptions) -> Vec<u8> {
+        debug!("formatting mode: {self}");
+        let mut buf: Vec<u8> = Vec::new();
         if options.prefix() {
-            buf += &self.prefix();
+            buf.append(&mut self.prefix());
+            debug!("prefix the buffer: {buf:X?}");
         }
         match self {
             Format::Hex => {
                 if options.padding() {
                     let tmp = &format!("{num:X}");
-                    buf += &("0".repeat((2 - tmp.len() % 2) % 2) + tmp);
+                    let tmp1 = &("0".repeat((2 - tmp.len() % 2) % 2) + tmp);
+                    buf.append(&mut tmp1.as_bytes().to_owned());
                 } else {
-                    buf += &format!("{num:X}");
+                    buf.append(&mut format!("{num:X}").as_bytes().to_owned());
                 }
             }
             Format::Bin => {
                 if options.padding() {
                     let tmp = &format!("{num:b}");
-                    buf += &("0".repeat((8 - tmp.len() % 8) % 8) + tmp);
+                    let tmp1 = &("0".repeat((8 - tmp.len() % 8) % 8) + tmp);
+                    buf.append(&mut tmp1.as_bytes().to_owned());
                 } else {
-                    buf += &format!("{num:b}");
+                    buf.append(&mut format!("{num:b}").as_bytes().to_owned());
                 }
             }
-            Format::Octal => buf += &format!("{num:o}"),
-            Format::Dec => buf += &format!("{num}"),
-            Format::Base64 => buf += &fast32::base64::RFC4648.encode(&split::unsigned_to_vec(num)),
-            Format::Base32 => buf += &fast32::base32::RFC4648.encode(&split::unsigned_to_vec(num)),
+            Format::Octal => buf.append(&mut format!("{num:o}").as_bytes().to_owned()),
+            Format::Dec => buf.append(&mut format!("{num}").as_bytes().to_owned()),
+            Format::Base64 => buf.append(
+                &mut fast32::base64::RFC4648
+                    .encode(&split::unsigned_to_vec(num))
+                    .as_bytes()
+                    .to_owned(),
+            ),
+            Format::Base32 => buf.append(
+                &mut fast32::base32::RFC4648
+                    .encode(&split::unsigned_to_vec(num))
+                    .as_bytes()
+                    .to_owned(),
+            ),
+            // Format::Raw => buf.append(&mut split::unsigned_to_vec(num)),
+            Format::Raw => buf.append(&mut split::unsigned_to_vec(num)),
         }
         buf
     }
 }
 
-/// Validates an unsigned integer value that can be one of [Format](format::Format).
+/// Converts a &[str] into an unsigned integer value (like [u128]), according to one of the [Formats](Format)
 ///
 /// The number is assumed to be base-10 by default, it is parsed as a different
-/// [Format](format::Format) if the number is prefixed with the [prefix](format::FormatOptions::prefix),
-/// case sensitive. So if the user inputs `0b1100` then this is parsed as
-/// [Binary](format::Format::Bin) and so on.
+/// [Format] if the number is prefixed with the [prefix](FormatOptions::prefix),
+/// for that [Format]. So if the user inputs `0b1100` then this is parsed as
+/// [Binary](Format::Bin) and so on.
+///
+/// If you also want to parse raw inputs, use [numf_parser].
+///
+/// # Returns
+///
+/// This parser will only output unsigned integers, it cannot be used with signed integers.
 ///
 /// # Example
 ///
@@ -243,17 +471,17 @@ impl Format {
 ///
 /// ```
 /// use clap::Parser;
-/// use numf::format::numf_parser;
+/// use numf::format::numf_parser_str;
 ///
 /// #[derive(Parser)]
 /// struct Args {
-///     #[clap(short, long, value_parser=numf_parser::<u128>)]
+///     #[clap(short, long, value_parser=numf_parser_str::<u128>)]
 ///     address: u128,
 /// }
 /// let args = Args::parse_from(&["", "-a", "0x10"]);
 /// assert_eq!(args.address, 16);
 /// ```
-pub fn numf_parser<T>(s: &str) -> anyhow::Result<T>
+pub fn numf_parser_str<T>(s: &str) -> anyhow::Result<T>
 where
     T: std::str::FromStr + std::convert::TryFrom<u128>,
     <T as std::str::FromStr>::Err: std::fmt::Display,
@@ -267,10 +495,68 @@ where
     <T as std::convert::TryFrom<u128>>::Error: std::marker::Sync,
     <T as std::convert::TryFrom<u128>>::Error: 'static,
 {
-    if s.starts_with(&Format::Dec.prefix()) || s.parse::<T>().is_ok() {
-        let s = match s.strip_prefix(&Format::Dec.prefix()) {
+    numf_parser(s.as_bytes())
+}
+
+/// Converts any data (as bytes) into an unsigned integer value `T` (like [u128]), according to one of the [Formats](Format)
+///
+/// If you only want to parse text data, use [numf_parser_str] instead.
+///
+/// The parser will first try to convert the data to a [String].
+///
+/// Then, the number is assumed to be base-10 by default, it is parsed as a different
+/// [Format] if the number is prefixed with the [prefix](FormatOptions::prefix),
+/// for that [Format]. So if the user inputs `0b1100` then this is parsed as
+/// [Binary](Format::Bin) and so on.
+///
+/// If none of the text [Formats](Format) matches, the data will be assumed to be raw and converted
+/// to the ingeger type directly.
+///
+/// # Errors
+///
+/// If no text [Format] matches and the data is too long for the integer `T`.
+///
+/// # Returns
+///
+/// This parser will only output unsigned integers, it cannot be used with signed integers.
+///
+/// # Example
+///
+/// ```
+/// use numf::format::numf_parser;
+///
+/// let data = &[0x15, 0x92, 0xff];
+/// let result: u64 = 0x1592ff;
+/// assert_eq!(result, numf_parser(data).unwrap());
+///
+/// let data = b"0x1337";
+/// let result: u64 = 0x1337;
+/// assert_eq!(result, numf_parser(data).unwrap());
+///
+/// let data = b"0b110011";
+/// let result: u64 = 0b110011;
+/// assert_eq!(result, numf_parser(data).unwrap());
+/// ```
+pub fn numf_parser<T>(data: &[u8]) -> anyhow::Result<T>
+where
+    T: std::str::FromStr + std::convert::TryFrom<u128>,
+    <T as std::str::FromStr>::Err: std::fmt::Display,
+    T: num::Num,
+    <T as num::Num>::FromStrRadixErr: std::fmt::Display,
+    <T as std::str::FromStr>::Err: std::fmt::Debug,
+    u128: std::convert::From<T>,
+    <T as std::str::FromStr>::Err: std::error::Error,
+    <T as std::convert::TryFrom<u128>>::Error: std::error::Error,
+    <T as std::convert::TryFrom<u128>>::Error: std::marker::Send,
+    <T as std::convert::TryFrom<u128>>::Error: std::marker::Sync,
+    <T as std::convert::TryFrom<u128>>::Error: 'static,
+{
+    let data_as_text = String::from_utf8_lossy(data).to_string();
+
+    if data_as_text.starts_with(&Format::Dec.prefix_str()) || data_as_text.parse::<T>().is_ok() {
+        let s = match data_as_text.strip_prefix(&Format::Dec.prefix_str()) {
             Some(sr) => sr,
-            None => s,
+            None => &data_as_text,
         };
         match s.parse() {
             Ok(r) => Ok(r),
@@ -279,10 +565,10 @@ where
                 Err(anyhow!(e))
             }
         }
-    } else if s.starts_with(&Format::Hex.prefix()) {
-        let s = match s.strip_prefix(&Format::Hex.prefix()) {
+    } else if data_as_text.starts_with(&Format::Hex.prefix_str()) {
+        let s = match data_as_text.strip_prefix(&Format::Hex.prefix_str()) {
             Some(sr) => sr,
-            None => s,
+            None => &data_as_text,
         };
         match T::from_str_radix(s, 16) {
             Ok(r) => Ok(r),
@@ -291,10 +577,10 @@ where
                 Err(anyhow!(e))
             }
         }
-    } else if s.starts_with(&Format::Octal.prefix()) {
-        let s = match s.strip_prefix(&Format::Octal.prefix()) {
+    } else if data_as_text.starts_with(&Format::Octal.prefix_str()) {
+        let s = match data_as_text.strip_prefix(&Format::Octal.prefix_str()) {
             Some(sr) => sr,
-            None => s,
+            None => &data_as_text,
         };
         match T::from_str_radix(s, 8) {
             Ok(r) => Ok(r),
@@ -303,10 +589,10 @@ where
                 Err(anyhow!(e))
             }
         }
-    } else if s.starts_with(&Format::Bin.prefix()) {
-        let s = match s.strip_prefix(&Format::Bin.prefix()) {
+    } else if data_as_text.starts_with(&Format::Bin.prefix_str()) {
+        let s = match data_as_text.strip_prefix(&Format::Bin.prefix_str()) {
             Some(sr) => sr,
-            None => s,
+            None => &data_as_text,
         };
         match T::from_str_radix(s, 2) {
             Ok(r) => Ok(r),
@@ -315,10 +601,10 @@ where
                 Err(anyhow!(e))
             }
         }
-    } else if s.starts_with(&Format::Base64.prefix()) {
-        let s = match s.strip_prefix(&Format::Base64.prefix()) {
+    } else if data_as_text.starts_with(&Format::Base64.prefix_str()) {
+        let s = match data_as_text.strip_prefix(&Format::Base64.prefix_str()) {
             Some(sr) => sr,
-            None => s,
+            None => &data_as_text,
         };
         match fast32::base64::RFC4648.decode_str(s) {
             Ok(r) => Ok(join::array_to_unsigned::<T>(&r)?),
@@ -327,10 +613,10 @@ where
                 Err(anyhow!(e))
             }
         }
-    } else if s.starts_with(&Format::Base32.prefix()) {
-        let s = match s.strip_prefix(&Format::Base32.prefix()) {
+    } else if data_as_text.starts_with(&Format::Base32.prefix_str()) {
+        let s = match data_as_text.strip_prefix(&Format::Base32.prefix_str()) {
             Some(sr) => sr,
-            None => s,
+            None => &data_as_text,
         };
         match fast32::base32::RFC4648.decode_str(s) {
             Ok(r) => Ok(join::array_to_unsigned::<T>(&r)?),
@@ -340,7 +626,12 @@ where
             }
         }
     } else {
-        let e = "could not determine the format of the value".to_string();
-        Err(anyhow!(e))
+        // what could go wrong with interpreting everything else as raw number input
+        let s: Vec<u8> = if data.len() > 2 && data[0] == 0x00 {
+            data.iter().skip(1).map(ToOwned::to_owned).collect()
+        } else {
+            data.as_ref().to_vec()
+        };
+        Ok(join::array_to_unsigned(&s)?)
     }
 }

src/lib.rs

@@ -1,10 +1,17 @@
 //! Format numbers
 //!
 //! This crate contains several utility functions for formatting numbers
-//! into other systems, such as converting decimal numbers to hexadecimal.
+//! into other systems, such as converting decimal numbers to hexadecimal
+//! , and back.
 //!
 //! See [format::Format] for supported formats.
 //!
 //! Note that this crate is primarily intended to be used as a executable.
+//!
+//! Highlights:
+//! * [format::numf_parser]
+//! * [format::numf_parser_str]
+//! * [format::Format::format]
+//! * [format::Format::format_str]
 
 pub mod format;

src/main.rs

@@ -1,38 +1,54 @@
-//! # numf
-//!
-//! This binary should just take any amount of numbers and print them out formatted to some other
-//! system.
-
-use std::io::{IsTerminal, Read};
+use std::io::{IsTerminal, Read, Write};
 use std::process::exit;
 
 use clap::{CommandFactory, Parser};
+use numf::format::numf_parser_str;
 
 mod format;
+use crate::format::{numf_parser, Format};
 use format::*;
-use numf::format::numf_parser;
+use libpt::log::{debug, error};
 
-fn main() {
+fn main() -> anyhow::Result<()> {
     // try to read from stdin first, appending the numbers we read to the FormatOptions
     let mut options = FormatOptions::parse();
+    let _logger = libpt::log::Logger::builder()
+        .set_level(options.verbosity.level())
+        .display_time(false)
+        .build()
+        .map_err(|e| {
+            error!("could not initialize logger: {e}");
+        });
+    debug!("logger active");
+
     let mut stdin_nums = Vec::new();
     let stdin = std::io::stdin();
+    // only accept numbers from stdin if the stdin is not an interactive terminal
     if !stdin.is_terminal() {
         match stdin.lock().read_to_end(&mut stdin_nums) {
             Ok(_) => {
-                let whole: String = match String::from_utf8(stdin_nums) {
+                let whole: String = match String::from_utf8(stdin_nums.clone()) {
                     Ok(r) => r,
-                    Err(e) => {
-                        eprintln!("stdin for this program only accepts text: {e:#?}");
-                        exit(1);
+                    Err(_) => {
+                        let number = match numf_parser(&stdin_nums) {
+                            Ok(n) => n,
+                            Err(e) => {
+                                eprintln!("{}", FormatOptions::command().render_usage());
+                                error!("could raw inputs from stdin as numbers: {e:#?}");
+                                exit(2);
+                            }
+                        };
+                        options.push_number(number);
+                        String::new()
                     }
                 };
                 let split = whole.split_whitespace();
                 for s in split {
-                    let number = match numf_parser(s) {
+                    let number = match numf_parser_str(s) {
                         Ok(n) => n,
                         Err(e) => {
-                            eprintln!("could not parse number from stdin: {e:#?}");
+                            eprintln!("{}", FormatOptions::command().render_usage());
+                            error!("could not parse number from stdin: {e:#?}");
                             exit(2);
                         }
                     };
@@ -40,23 +56,41 @@ fn main() {
                 }
             }
             Err(e) => {
-                eprintln!("could not read from stdin: {e:#?}");
+                eprintln!("{}", FormatOptions::command().render_usage());
+                error!("could not read from stdin: {e:#?}");
                 exit(2);
             }
         };
     }
 
+    // add random numbers to the number list, according to how many are requested
+    if options.rand() > 0 {
+        use rand::prelude::*;
+        let mut rand = rand::rngs::OsRng;
+        for _i in 0..options.rand() {
+            options.push_number(rand.gen_range(0..options.rand_max()));
+        }
+    }
+
+    // exit with error if no numbers are to be formatted
     if options.numbers().is_empty() {
-        format!("{}", FormatOptions::command().render_usage());
+        eprintln!("{}", FormatOptions::command().render_usage());
+        error!("no numbers have been provided");
         exit(1);
     }
 
-    let mut out: Vec<String> = Vec::new();
+    let mut out: Vec<Vec<u8>> = Vec::new();
 
     for num in options.numbers() {
         out.push(options.format().format(*num, &options));
     }
     for o in out {
-        println!("{o}")
+        let mut stdout = std::io::stdout();
+        stdout.write_all(&o)?;
+        if options.format() != Format::Raw {
+            stdout.write_all(b"\n")?;
+        }
+        stdout.flush()?;
     }
+    Ok(())
 }

tests/format.rs

@@ -3,44 +3,47 @@ use numf::format::*;
 #[test]
 fn format() {
     let options = FormatOptions::default();
-    assert_eq!(Format::Dec.format(1337, &options), "1337");
+    assert_eq!(Format::Dec.format_str(1337, &options), "1337");
     assert_eq!(
-        Format::Dec.format(u128::MAX, &options),
+        Format::Dec.format_str(u128::MAX, &options),
         format!("{}", u128::MAX)
     );
 
-    assert_eq!(Format::Hex.format(0x1337, &options), "1337");
+    assert_eq!(Format::Hex.format_str(0x1337, &options), "1337");
     assert_eq!(
-        Format::Hex.format(u128::MAX, &options),
+        Format::Hex.format_str(u128::MAX, &options),
         format!("{:X}", u128::MAX)
     );
 
     assert_eq!(
-        Format::Bin.format(0b1010001001010010010100111, &options),
+        Format::Bin.format_str(0b1010001001010010010100111, &options),
         "1010001001010010010100111"
     );
     assert_eq!(
-        Format::Bin.format(u128::MAX, &options),
+        Format::Bin.format_str(u128::MAX, &options),
         format!("{:b}", u128::MAX)
     );
 
-    assert_eq!(Format::Octal.format(0o13377331, &options), "13377331");
+    assert_eq!(Format::Octal.format_str(0o13377331, &options), "13377331");
     assert_eq!(
-        Format::Octal.format(u128::MAX, &options),
+        Format::Octal.format_str(u128::MAX, &options),
         format!("{:o}", u128::MAX)
     );
 
-    assert_eq!(Format::Base32.format(0x41414242, &options), "IFAUEQQ=");
+    assert_eq!(Format::Base32.format_str(0x41414242, &options), "IFAUEQQ=");
     assert_eq!(
-        Format::Base32.format(0x4141414141414141, &options),
+        Format::Base32.format_str(0x4141414141414141, &options),
         "IFAUCQKBIFAUC==="
     );
 
-    assert_eq!(Format::Base64.format(0x41414242, &options), "QUFCQg==");
+    assert_eq!(Format::Base64.format_str(0x41414242, &options), "QUFCQg==");
     assert_eq!(
-        Format::Base64.format(0x4141414141414141, &options),
+        Format::Base64.format_str(0x4141414141414141, &options),
         "QUFBQUFBQUE="
     );
+
+    assert_eq!(Format::Raw.format(0x1337, &options), vec![0x13, 0x37]);
+    assert_eq!(Format::Raw.format(0x0, &options), vec![0x0]);
 }
 
 #[test]
@@ -48,49 +51,52 @@ fn format_padding() {
     let mut options = FormatOptions::default();
     options.set_padding(true);
 
-    assert_eq!(Format::Dec.format(1337, &options), "1337");
+    assert_eq!(Format::Dec.format_str(1337, &options), "1337");
     assert_eq!(
-        Format::Dec.format(u128::MAX, &options),
+        Format::Dec.format_str(u128::MAX, &options),
         format!("{}", u128::MAX)
     );
 
-    assert_eq!(Format::Hex.format(0xFFF, &options), "0FFF");
-    assert_eq!(Format::Hex.format(0xFFFF, &options), "FFFF");
+    assert_eq!(Format::Hex.format_str(0xFFF, &options), "0FFF");
+    assert_eq!(Format::Hex.format_str(0xFFFF, &options), "FFFF");
     assert_eq!(
-        Format::Hex.format(u128::MAX, &options),
+        Format::Hex.format_str(u128::MAX, &options),
         format!("{:X}", u128::MAX)
     );
 
     assert_eq!(
-        Format::Bin.format(0b11110000_00001111, &options),
+        Format::Bin.format_str(0b11110000_00001111, &options),
         "1111000000001111"
     );
     assert_eq!(
-        Format::Bin.format(0b110000_00001111, &options),
+        Format::Bin.format_str(0b110000_00001111, &options),
         "0011000000001111"
     );
     assert_eq!(
-        Format::Bin.format(u128::MAX, &options),
+        Format::Bin.format_str(u128::MAX, &options),
         format!("{:b}", u128::MAX)
     );
 
-    assert_eq!(Format::Octal.format(0o13377331, &options), "13377331");
+    assert_eq!(Format::Octal.format_str(0o13377331, &options), "13377331");
     assert_eq!(
-        Format::Octal.format(u128::MAX, &options),
+        Format::Octal.format_str(u128::MAX, &options),
         format!("{:o}", u128::MAX)
     );
 
-    assert_eq!(Format::Base32.format(0x41414242, &options), "IFAUEQQ=");
+    assert_eq!(Format::Base32.format_str(0x41414242, &options), "IFAUEQQ=");
     assert_eq!(
-        Format::Base32.format(0x4141414141414141, &options),
+        Format::Base32.format_str(0x4141414141414141, &options),
         "IFAUCQKBIFAUC==="
     );
 
-    assert_eq!(Format::Base64.format(0x41414242, &options), "QUFCQg==");
+    assert_eq!(Format::Base64.format_str(0x41414242, &options), "QUFCQg==");
     assert_eq!(
-        Format::Base64.format(0x4141414141414141, &options),
+        Format::Base64.format_str(0x4141414141414141, &options),
         "QUFBQUFBQUE="
     );
+
+    assert_eq!(Format::Raw.format(0x1337, &options), vec![0x13, 0x37]);
+    assert_eq!(Format::Raw.format(0x0, &options), vec![0x0]);
 }
 
 #[test]
@@ -98,44 +104,53 @@ fn format_prefix() {
     let mut options = FormatOptions::default();
     options.set_prefix(true);
 
-    assert_eq!(Format::Dec.format(1337, &options), "0d1337");
+    assert_eq!(Format::Dec.format_str(1337, &options), "0d1337");
     assert_eq!(
-        Format::Dec.format(u128::MAX, &options),
+        Format::Dec.format_str(u128::MAX, &options),
         format!("0d{}", u128::MAX)
     );
 
-    assert_eq!(Format::Hex.format(0x1337, &options), "0x1337");
+    assert_eq!(Format::Hex.format_str(0x1337, &options), "0x1337");
     assert_eq!(
-        Format::Hex.format(u128::MAX, &options),
+        Format::Hex.format_str(u128::MAX, &options),
         format!("0x{:X}", u128::MAX)
     );
 
     assert_eq!(
-        Format::Bin.format(0b1010001001010010010100111, &options),
+        Format::Bin.format_str(0b1010001001010010010100111, &options),
         "0b1010001001010010010100111"
     );
     assert_eq!(
-        Format::Bin.format(u128::MAX, &options),
+        Format::Bin.format_str(u128::MAX, &options),
         format!("0b{:b}", u128::MAX)
     );
 
-    assert_eq!(Format::Octal.format(0o13377331, &options), "0o13377331");
+    assert_eq!(Format::Octal.format_str(0o13377331, &options), "0o13377331");
     assert_eq!(
-        Format::Octal.format(u128::MAX, &options),
+        Format::Octal.format_str(u128::MAX, &options),
         format!("0o{:o}", u128::MAX)
     );
 
-    assert_eq!(Format::Base32.format(0x41414242, &options), "032sIFAUEQQ=");
     assert_eq!(
-        Format::Base32.format(0x4141414141414141, &options),
+        Format::Base32.format_str(0x41414242, &options),
+        "032sIFAUEQQ="
+    );
+    assert_eq!(
+        Format::Base32.format_str(0x4141414141414141, &options),
         "032sIFAUCQKBIFAUC==="
     );
 
-    assert_eq!(Format::Base64.format(0x41414242, &options), "0sQUFCQg==");
     assert_eq!(
-        Format::Base64.format(0x4141414141414141, &options),
+        Format::Base64.format_str(0x41414242, &options),
+        "0sQUFCQg=="
+    );
+    assert_eq!(
+        Format::Base64.format_str(0x4141414141414141, &options),
         "0sQUFBQUFBQUE="
     );
+
+    assert_eq!(Format::Raw.format(0x1337, &options), vec![0x0, 0x13, 0x37]);
+    assert_eq!(Format::Raw.format(0x0, &options), vec![0x0, 0x0]);
 }
 
 #[test]
@@ -144,49 +159,58 @@ fn format_padded_prefix() {
     options.set_prefix(true);
     options.set_padding(true);
 
-    assert_eq!(Format::Dec.format(1337, &options), "0d1337");
+    assert_eq!(Format::Dec.format_str(1337, &options), "0d1337");
     assert_eq!(
-        Format::Dec.format(u128::MAX, &options),
+        Format::Dec.format_str(u128::MAX, &options),
         format!("0d{}", u128::MAX)
     );
 
-    assert_eq!(Format::Hex.format(0xFFF, &options), "0x0FFF");
-    assert_eq!(Format::Hex.format(0xFFFF, &options), "0xFFFF");
+    assert_eq!(Format::Hex.format_str(0xFFF, &options), "0x0FFF");
+    assert_eq!(Format::Hex.format_str(0xFFFF, &options), "0xFFFF");
     assert_eq!(
-        Format::Hex.format(u128::MAX, &options),
+        Format::Hex.format_str(u128::MAX, &options),
         format!("0x{:X}", u128::MAX)
     );
 
     assert_eq!(
-        Format::Bin.format(0b11110000_00001111, &options),
+        Format::Bin.format_str(0b11110000_00001111, &options),
         "0b1111000000001111"
     );
     assert_eq!(
-        Format::Bin.format(0b110000_00001111, &options),
+        Format::Bin.format_str(0b110000_00001111, &options),
         "0b0011000000001111"
     );
     assert_eq!(
-        Format::Bin.format(u128::MAX, &options),
+        Format::Bin.format_str(u128::MAX, &options),
         format!("0b{:b}", u128::MAX)
     );
 
-    assert_eq!(Format::Octal.format(0o13377331, &options), "0o13377331");
+    assert_eq!(Format::Octal.format_str(0o13377331, &options), "0o13377331");
     assert_eq!(
-        Format::Octal.format(u128::MAX, &options),
+        Format::Octal.format_str(u128::MAX, &options),
         format!("0o{:o}", u128::MAX)
     );
 
-    assert_eq!(Format::Base32.format(0x41414242, &options), "032sIFAUEQQ=");
     assert_eq!(
-        Format::Base32.format(0x4141414141414141, &options),
+        Format::Base32.format_str(0x41414242, &options),
+        "032sIFAUEQQ="
+    );
+    assert_eq!(
+        Format::Base32.format_str(0x4141414141414141, &options),
         "032sIFAUCQKBIFAUC==="
     );
 
-    assert_eq!(Format::Base64.format(0x41414242, &options), "0sQUFCQg==");
     assert_eq!(
-        Format::Base64.format(0x4141414141414141, &options),
+        Format::Base64.format_str(0x41414242, &options),
+        "0sQUFCQg=="
+    );
+    assert_eq!(
+        Format::Base64.format_str(0x4141414141414141, &options),
         "0sQUFBQUFBQUE="
     );
+
+    assert_eq!(Format::Raw.format(0x1337, &options), vec![0x0, 0x13, 0x37]);
+    assert_eq!(Format::Raw.format(0x0, &options), vec![0x0, 0x0]);
 }
 
 #[test]
@@ -197,45 +221,52 @@ fn set_format_checker() {
     assert_eq!(options.format(), Format::Base32);
     options.set_format(Format::Base64);
     assert_eq!(options.format(), Format::Base64);
+    options.set_format(Format::Raw);
+    assert_eq!(options.format(), Format::Raw);
 }
 
 #[test]
 fn parser_dec() {
-    assert_eq!(numf_parser::<u32>("1337").unwrap(), 1337);
-    assert_eq!(numf_parser::<u32>("0d1337").unwrap(), 1337);
+    assert_eq!(numf_parser_str::<u32>("1337").unwrap(), 1337);
+    assert_eq!(numf_parser_str::<u32>("0d1337").unwrap(), 1337);
 }
 
 #[test]
 fn parser_bin() {
-    assert_eq!(numf_parser::<u32>("0b11001").unwrap(), 0b11001);
-    assert_eq!(numf_parser::<u32>("0b11001").unwrap(), 0b11001);
+    assert_eq!(numf_parser_str::<u32>("0b11001").unwrap(), 0b11001);
+    assert_eq!(numf_parser_str::<u32>("0b11001").unwrap(), 0b11001);
 }
 
 #[test]
 fn parser_hex() {
-    assert_eq!(numf_parser::<u32>("0xdeadbeef").unwrap(), 0xdeadbeef);
+    assert_eq!(numf_parser_str::<u32>("0xdeadbeef").unwrap(), 0xdeadbeef);
 }
 
 #[test]
 fn parser_oct() {
-    assert_eq!(numf_parser::<u32>("0o771171").unwrap(), 0o771171);
+    assert_eq!(numf_parser_str::<u32>("0o771171").unwrap(), 0o771171);
 }
 
 #[test]
 fn parser_b64() {
-    assert_eq!(numf_parser::<u32>("0sQUFCQg==").unwrap(), 0x41414242);
+    assert_eq!(numf_parser_str::<u32>("0sQUFCQg==").unwrap(), 0x41414242);
 }
 
 #[test]
 fn parser_b32() {
-    assert_eq!(numf_parser::<u32>("032sIFAUEQQ=").unwrap(), 0x41414242);
+    assert_eq!(numf_parser_str::<u32>("032sIFAUEQQ=").unwrap(), 0x41414242);
+}
+
+#[test]
+fn parser_raw() {
+    assert_eq!(numf_parser_str::<u32>("\x00\x50\x60").unwrap(), 0x5060);
 }
 
 #[test]
 fn parser_generics() {
-    assert_eq!(numf_parser::<u8>("55").unwrap(), 55);
-    assert_eq!(numf_parser::<u16>("55").unwrap(), 55);
-    assert_eq!(numf_parser::<u32>("55").unwrap(), 55);
-    assert_eq!(numf_parser::<u64>("55").unwrap(), 55);
-    assert_eq!(numf_parser::<u128>("55").unwrap(), 55);
+    assert_eq!(numf_parser_str::<u8>("55").unwrap(), 55);
+    assert_eq!(numf_parser_str::<u16>("55").unwrap(), 55);
+    assert_eq!(numf_parser_str::<u32>("55").unwrap(), 55);
+    assert_eq!(numf_parser_str::<u64>("55").unwrap(), 55);
+    assert_eq!(numf_parser_str::<u128>("55").unwrap(), 55);
 }