// 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::future::Future;
use ::std::io::Cursor;
use ::std::marker::PhantomData;
use ::std::num::ParseFloatError;
use ::std::num::ParseIntError;
use ::std::ops::RangeBounds;
use ::std::pin::Pin;
use ::std::str::FromStr;
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>(::std::marker::PhantomData<(&'i str, S, E)>);
/// An argument parser/validator.
///
/// Note: Iosonism requires arguments 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.
///
/// [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::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()
/// }
/// }
/// ```
pub trait ArgumentType<S, E> {
/// 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(&[])
}
}
/// Wrapper around `ArgumentType`, but with `Any`.
pub(crate) trait ArgumentTypeAny<S, E>: Send + Sync {
/// 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]>;
}
impl<T: ArgumentType<S, E> + Send + Sync, S, E> ArgumentTypeAny<S, E> for T {
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()
}
}
/// A boolean argument.
// FIXME add examples/expand docs
// FIXME add tests
#[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"])
}
}
/// 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>,
T: PartialOrd<T> + FromStr<Err=ParseIntError> + Any,
{
/// 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"])
}
}
/// A float argument.
#[derive(Copy, Clone, PartialEq, Debug, PartialOrd, 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>,
T: PartialOrd<T> + FromStr<Err=ParseFloatError> + Any,
{
/// 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"])
}
}