path: root/src/args.rs

// Copyright (c) 2021 Soni L.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT license.
// Documentation and comments licensed under CC BY-SA 4.0.

//! Argument processing.

use ::std::any::Any;
use ::std::borrow::Cow;
use ::std::fmt::Display;
use ::std::fmt::Formatter;
use ::std::future::Future;
use ::std::hash::Hash;
use ::std::io::Cursor;
use ::std::marker::PhantomData;
use ::std::num::ParseFloatError;
use ::std::num::ParseIntError;
use ::std::ops::Bound;
use ::std::ops::RangeBounds;
use ::std::pin::Pin;
use ::std::str::FromStr;

use anycast::Anycast;
//use ::ordered_float::OrderedFloat;

use crate::error::RangeError;
use crate::error::ReadError;
use crate::strcursor::StringReader;
use crate::suggestion::Suggestions;
use crate::suggestion::SuggestionsBuilder;

// FIXME delete when implemented
/// The parsing context of a command.
pub struct CommandContext<'i, S, E>(PhantomData<(&'i str, S, E)>);

/// An argument parser/validator.
///
/// Note: Iosonism requires argument types to be `Send + Sync`, but for ease
/// when implementing generic argument types, those bounds are not reflected in
/// this trait. Nevertheless, Iosonism doesn't itself use threads, so a
/// [workaround] can be used if one needs non-`Send + Sync` argument types.
///
/// Additionally, argument types must be `Display`, `Eq` and `Hash`. This *is*
/// reflected in this trait.
///
/// [workaround]: https://users.rust-lang.org/t/how-to-check-send-at-runtime-similar-to-how-refcell-checks-borrowing-at-runtime/68269
///
/// # Type params
///
/// - `S`: The source type accepted by this argument type.
/// - `E`: The error type accepted by this argument type.
///
/// # Examples
///
/// A very basic `bool` argument type:
///
/// ```
/// use ::std::fmt::Display;
/// use ::std::io::Cursor;
///
/// use ::iosonism::args::ArgumentType;
/// use ::iosonism::error::ReadError;
/// use ::iosonism::strcursor::StringReader;
///
/// struct BoolArgumentType;
///
/// impl<S, E> ArgumentType<S, E> for BoolArgumentType
/// where for<'i> E: ReadError<'i, Cursor<&'i str>>
/// {
///     type Result = bool;
///     fn parse<'i>(
///         &self,
///         reader: &mut Cursor<&'i str>,
///     ) -> Result<bool, E> where E: 'i {
///         reader.read_bool()
///     }
/// }
///
/// impl Display for BoolArgumentType {
///     fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
///         write!(f, "bool()")
///     }
/// }
/// ```
pub trait ArgumentType<S, E>: Display + Eq + ::std::hash::Hash {
    /// The parsed type of the argument.
    type Result: Sized + 'static + Any;

    /// Parses an argument of this type, returning the parsed argument.
    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<Self::Result, E> where E: 'i;

    /// Creates suggestions for this argument.
    fn list_suggestions<'i>(
        &self,
        context: &CommandContext<'i, S, E>,
        builder: SuggestionsBuilder<'i>,
    ) -> Pin<Box<dyn Future<Output=Suggestions> + Send + 'i>> {
        let _ = context;
        let _ = builder;
        Suggestions::empty()
    }

    /// Returns examples for this argument.
    fn get_examples(&self) -> Cow<'static, [&str]> {
        Cow::Borrowed(&[])
    }
}

/// Internal wrapper around `ArgumentType`, but with more `Any`.
pub(crate) trait ArgumentTypeAny<S, E>: Send + Sync + Display + Anycast {
    /// Parses an argument of this type, returning the parsed argument.
    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<Box<dyn Any>, E> where E: 'i;

    /// Creates suggestions for this argument.
    fn list_suggestions<'i>(
        &self,
        context: &CommandContext<'i, S, E>,
        builder: SuggestionsBuilder<'i>,
    ) -> Pin<Box<dyn Future<Output=Suggestions> + Send + 'i>>;

    /// Returns examples for this argument.
    fn get_examples(&self) -> Cow<'static, [&str]>;

    /// Compares this `ArgumentType` with another.
    fn dyn_eq(&self, other: &dyn ArgumentTypeAny<S, E>) -> bool;

    /// Hashes this `ArgumentType`.
    fn dyn_hash(&self, hasher: &mut dyn ::std::hash::Hasher);
}

/// Any `ArgumentType` that is also `Send`, `Sync`, `Eq` and `Hash` is an
/// `ArgumentTypeAny`.
impl<T, S, E> ArgumentTypeAny<S, E> for T
where T: ArgumentType<S, E> + Send + Sync + Eq + ::std::hash::Hash + Any {
    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<Box<dyn Any>, E> where E: 'i {
        self.parse(reader).map(|x| Box::new(x) as _)
    }

    fn list_suggestions<'i>(
        &self,
        context: &CommandContext<'i, S, E>,
        builder: SuggestionsBuilder<'i>,
    ) -> Pin<Box<dyn Future<Output=Suggestions> + Send + 'i>> {
        self.list_suggestions(context, builder)
    }

    fn get_examples(&self) -> Cow<'static, [&str]> {
        self.get_examples()
    }

    fn dyn_eq(&self, other: &dyn ArgumentTypeAny<S, E>) -> bool {
        match other.any_ref().downcast_ref() {
            Some(other) => self == other,
            None => false,
        }
    }

    fn dyn_hash(&self, mut hasher: &mut dyn ::std::hash::Hasher) {
        // rust-lang/rust#44015
        self.hash(&mut hasher)
    }
}

/// Any `dyn ArgumentTypeAny` (note the `dyn`!) is an `ArgumentType`.
impl<S, E> ArgumentType<S, E> for dyn ArgumentTypeAny<S, E> {
    type Result = Box<dyn Any>;

    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<Box<dyn Any>, E> where E: 'i {
        self.parse(reader)
    }

    fn list_suggestions<'i>(
        &self,
        context: &CommandContext<'i, S, E>,
        builder: SuggestionsBuilder<'i>,
    ) -> Pin<Box<dyn Future<Output=Suggestions> + Send + 'i>> {
        self.list_suggestions(context, builder)
    }

    fn get_examples(&self) -> Cow<'static, [&str]> {
        self.get_examples()
    }
}

impl<S, E> PartialEq for dyn ArgumentTypeAny<S, E> {
    fn eq(&self, other: &Self) -> bool {
        self.dyn_eq(other)
    }
}

impl<S, E> Eq for dyn ArgumentTypeAny<S, E> {
}

impl<S, E> ::std::hash::Hash for dyn ArgumentTypeAny<S, E> {
    fn hash<H: ::std::hash::Hasher>(&self, hasher: &mut H) {
        self.dyn_hash(hasher as &mut dyn ::std::hash::Hasher)
    }
}

/// A boolean argument.
// FIXME add examples/expand docs
#[derive(Copy, Clone, PartialEq, Eq, Debug, PartialOrd, Ord, Hash, Default)]
pub struct BoolArgumentType;

/// An `ArgumentType` for `bool`.
impl<S, E> ArgumentType<S, E> for BoolArgumentType
where for<'i> E: ReadError<'i, Cursor<&'i str>>
{
    /// A `BoolArgumentType` parses a `bool`.
    type Result = bool;

    /// Attempts to parse a `bool` from the `reader`.
    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<bool, E> where E: 'i {
        reader.read_bool()
    }

    /// Suggests completions for inputting a boolean argument.
    fn list_suggestions<'i>(
        &self,
        context: &CommandContext<'i, S, E>,
        mut builder: SuggestionsBuilder<'i>,
    ) -> Pin<Box<dyn Future<Output=Suggestions> + Send + 'i>> {
        let _ = context;
        if "true".starts_with(builder.get_remaining()) {
            builder.suggest("true".into());
        }
        if "false".starts_with(builder.get_remaining()) {
            builder.suggest("false".into());
        }
        builder.drain_build_future()
    }

    /// Returns examples
    fn get_examples(&self) -> Cow<'static, [&str]> {
        Cow::Borrowed(&["true", "false"])
    }
}

/// Formats this `BoolArgumentType`.
///
/// Always `"bool()"`.
impl Display for BoolArgumentType {
    fn fmt(&self, f: &mut Formatter) -> ::std::fmt::Result {
        write!(f, "bool()")
    }
}

/// An integer argument.
#[derive(Copy, Clone, PartialEq, Eq, Debug, PartialOrd, Ord, Hash, Default)]
pub struct IntegerArgumentType<T, R: RangeBounds<T>> {
    /// The valid range for this argument.
    pub range: R,
    /// PhantomData for the type.
    pub _ty: PhantomData<T>,
}

/// Helper to create an integer argument with values not bounded by a range.
///
/// # Examples
///
/// ```rust
/// use ::iosonism::args::integer;
///
/// let argtype = integer::<i32>();
/// ```
pub fn integer<T>() -> IntegerArgumentType<T, ::std::ops::RangeFull> {
    IntegerArgumentType {
        range: ..,
        _ty: PhantomData,
    }
}

/// Helper to create an integer argument with values bounded by a range.
///
/// # Examples
///
/// ```rust
/// use ::iosonism::args::bounded_integer;
///
/// let argtype = bounded_integer(0..100i32);
/// ```
pub fn bounded_integer<T, R: RangeBounds<T>>(
    range: R,
) -> IntegerArgumentType<T, R> {
    IntegerArgumentType {
        range: range,
        _ty: PhantomData,
    }
}

/// An `ArgumentType` for integer types.
impl<S, E, T, R> ArgumentType<S, E> for IntegerArgumentType<T, R>
where
    for<'i> E: ReadError<'i, Cursor<&'i str>>,
    for<'i> E: RangeError<'i, Cursor<&'i str>, T, R>,
    R: RangeBounds<T> + Eq + Hash,
    T: PartialOrd<T> + FromStr<Err=ParseIntError> + Any + Display + Eq + Hash,
{
    /// An `IntegerArgumentType` parses an integer type.
    type Result = T;

    /// Attempts to parse an integer from the `reader`.
    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<T, E> where E: 'i {
        let start = reader.position();
        let value = reader.read_integer()?;
        if self.range.contains(&value) {
            Ok(value)
        } else {
            reader.set_position(start);
            Err(E::value_not_in_range(reader, &value, &self.range))
        }
    }

    /// Returns examples
    fn get_examples(&self) -> Cow<'static, [&str]> {
        Cow::Borrowed(&["0", "123", "-123"])
    }
}

/// Formats this `IntegerArgumentType`.
///
/// The resulting string follows the syntax `"integer(start,end)"`, with
/// `start` and `end` being one of the below:
///
/// - `value` if the bound is inclusive.
/// - `value*` if the bound is exclusive.
/// - `-` if it's unbounded.
///
/// For example, `integer(0*,-)` is an unbounded positive integer, and
/// `integer(1,10)` is an integer between 1 and 10 inclusive.
impl<T: Display, R: RangeBounds<T>> Display for IntegerArgumentType<T, R> {
    fn fmt(&self, f: &mut Formatter) -> ::std::fmt::Result {
        let start_bound = self.range.start_bound();
        let end_bound = self.range.end_bound();
        write!(f, "integer(")?;
        match start_bound {
            Bound::Included(t) => write!(f, "{}", t)?,
            Bound::Excluded(t) => write!(f, "{}*", t)?,
            Bound::Unbounded => write!(f, "-")?,
        }
        write!(f, ",")?;
        match end_bound {
            Bound::Included(t) => write!(f, "{}", t)?,
            Bound::Excluded(t) => write!(f, "{}*", t)?,
            Bound::Unbounded => write!(f, "-")?,
        }
        write!(f,")")
    }
}

// FIXME implement Eq and Hash properly
/// A float argument.
#[derive(Copy, Clone, PartialEq, Eq, Debug, PartialOrd, Ord, Hash, Default)]
pub struct FloatArgumentType<T, R: RangeBounds<T>> {
    /// The valid range for this argument.
    pub range: R,
    /// PhantomData for the type.
    pub _ty: PhantomData<T>,
}

/// Helper to create a float argument with values not bounded by a range.
///
/// # Examples
///
/// ```rust
/// use ::iosonism::args::float;
///
/// let argtype = float::<f32>();
/// ```
pub fn float<T>() -> FloatArgumentType<T, ::std::ops::RangeFull> {
    FloatArgumentType {
        range: ..,
        _ty: PhantomData,
    }
}

/// Helper to create a float argument with values bounded by a range.
///
/// # Examples
///
/// ```rust
/// use ::iosonism::args::bounded_float;
///
/// let argtype = bounded_float(0.0..100f32);
/// ```
pub fn bounded_float<T, R: RangeBounds<T>>(
    range: R,
) -> FloatArgumentType<T, R> {
    FloatArgumentType {
        range: range,
        _ty: PhantomData,
    }
}

/// An `ArgumentType` for float types.
impl<S, E, T, R> ArgumentType<S, E> for FloatArgumentType<T, R>
where
    for<'i> E: ReadError<'i, Cursor<&'i str>>,
    for<'i> E: RangeError<'i, Cursor<&'i str>, T, R>,
    R: RangeBounds<T> + Eq + Hash,
    T: PartialOrd<T> + FromStr<Err=ParseFloatError> + Any + Display + Eq + Hash,
{
    /// A `FloatArgumentType` parses a float type.
    type Result = T;

    /// Attempts to parse a float from the `reader`.
    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<T, E> where E: 'i {
        let start = reader.position();
        let value = reader.read_float()?;
        if self.range.contains(&value) {
            Ok(value)
        } else {
            reader.set_position(start);
            Err(E::value_not_in_range(reader, &value, &self.range))
        }
    }

    /// Returns examples
    fn get_examples(&self) -> Cow<'static, [&str]> {
        Cow::Borrowed(&["0", "1.2", ".5", "-1", "-.5", "-1234.56"])
    }
}

/// Formats this `FloatArgumentType`.
///
/// The resulting string follows the syntax `"float(start,end)"`, with `start`
/// and `end` being one of the below:
///
/// - `value` if the bound is inclusive.
/// - `value*` if the bound is exclusive.
/// - `-` if it's unbounded.
///
/// For example, `float(0*,-)` is an unbounded positive float, and
/// `float(1,10)` is a float between 1.0 and 10.0 inclusive.
impl<T: Display, R: RangeBounds<T>> Display for FloatArgumentType<T, R> {
    fn fmt(&self, f: &mut Formatter) -> ::std::fmt::Result {
        let start_bound = self.range.start_bound();
        let end_bound = self.range.end_bound();
        write!(f, "float(")?;
        match start_bound {
            Bound::Included(t) => write!(f, "{}", t)?,
            Bound::Excluded(t) => write!(f, "{}*", t)?,
            Bound::Unbounded => write!(f, "-")?,
        }
        write!(f, ",")?;
        match end_bound {
            Bound::Included(t) => write!(f, "{}", t)?,
            Bound::Excluded(t) => write!(f, "{}*", t)?,
            Bound::Unbounded => write!(f, "-")?,
        }
        write!(f,")")
    }
}

/// A string argument.
#[derive(Copy, Clone, PartialEq, Eq, Debug, PartialOrd, Ord, Hash)]
pub struct StringArgumentType(StringMode);

/// Creates a string argument that accepts simple words.
///
/// # Examples
///
/// ```rust
/// use ::iosonism::args::word;
///
/// let argtype = word();
/// ```
pub fn word() -> StringArgumentType {
    StringArgumentType(StringMode::SingleWord)
}

/// Creates a string argument that accepts simple words and quoted strings.
///
/// # Examples
///
/// ```rust
/// use ::iosonism::args::string;
///
/// let argtype = string();
/// ```
pub fn string() -> StringArgumentType {
    StringArgumentType(StringMode::QuotablePhrase)
}

/// Creates a string argument that accepts simple text until the end of the
/// input.
///
/// # Examples
///
/// ```rust
/// use ::iosonism::args::greedy_string;
///
/// let argtype = greedy_string();
/// ```
pub fn greedy_string() -> StringArgumentType {
    StringArgumentType(StringMode::GreedyPhrase)
}

/// The "mode" of parsing a string.
#[derive(Copy, Clone, PartialEq, Eq, Debug, PartialOrd, Ord, Hash)]
enum StringMode {
    SingleWord,
    QuotablePhrase,
    GreedyPhrase,
}

/// An `ArgumentType` for strings.
impl<S, E> ArgumentType<S, E> for StringArgumentType
where for<'i> E: ReadError<'i, Cursor<&'i str>> {
    /// A `StringArgumentType` parses a string.
    type Result = String;

    /// Attempts to parse a string from the `reader`.
    fn parse<'i>(
        &self,
        reader: &mut Cursor<&'i str>,
    ) -> Result<String, E> where E: 'i {
        match self {
            Self(StringMode::SingleWord) => {
                Ok(reader.read_unquoted_str().into())
            },
            Self(StringMode::QuotablePhrase) => reader.read_string(),
            Self(StringMode::GreedyPhrase) => {
                let text = reader.get_remaining().into();
                reader.set_position(reader.total_len() as u64);
                Ok(text)
            },
        }
    }

    /// Returns examples
    fn get_examples(&self) -> Cow<'static, [&str]> {
        match self {
            Self(StringMode::SingleWord) => {
                Cow::Borrowed(&["word", "words_With_underscores"])
            },
            Self(StringMode::QuotablePhrase) => {
                Cow::Borrowed(&["\"quoted phrase\"", "word", "\"\""])
            },
            Self(StringMode::GreedyPhrase) => {
                Cow::Borrowed(&["word", "with spaces", "text \"and symbols\""])
            },
        }
    }
}

/// Formats this `StringArgumentType`.
///
/// The resulting string follows the syntax `"string(type)"`, with `type` being
/// one of the below:
///
/// - `word` if this argument matches a single word.
/// - `"phrase"` if this argument matches a single word or a quoted phrase.
/// - `text ...` if this argument matches any text up to the end of the input.
impl Display for StringArgumentType {
    fn fmt(&self, f: &mut Formatter) -> ::std::fmt::Result {
        match self {
            Self(StringMode::SingleWord) => {
                write!(f, "string(word)")
            },
            Self(StringMode::QuotablePhrase) => {
                write!(f, "string(\"phrase\")")
            },
            Self(StringMode::GreedyPhrase) => {
                write!(f, "string(text ...)")
            },
        }
    }
}