path: root/src/strcursor.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.

//! String Cursor (sorta).

use ::std::io::Cursor;
use ::std::str::FromStr;

/// Built-in `StringReader` errors.
pub trait ReadError<'a, C: StringReader<'a>>: Sized + std::error::Error {
    /// Creates an error that indicates an invalid integer was found.
    fn invalid_integer(context: &C, from: &str) -> Self;
    /// Creates an error that indicates an integer was expected.
    fn expected_integer(context: &C) -> Self;
    /// Creates an error that indicates an invalid float was found.
    fn invalid_float(context: &C, from: &str) -> Self;
    /// Creates an error that indicates a float was expected.
    fn expected_float(context: &C) -> Self;
    /// Creates an error that indicates an invalid bool was found.
    fn invalid_bool(context: &C, from: &str) -> Self;
    /// Creates an error that indicates a bool was expected.
    fn expected_bool(context: &C) -> Self;
    /// Creates an error that indicates the start of a quote was expected.
    fn expected_start_of_quote(context: &C) -> Self;
    /// Creates an error that indicates the end of a quote was expected.
    fn expected_end_of_quote(context: &C) -> Self;
    /// Creates an error that indicates an invalid escape was found.
    fn invalid_escape(context: &C, from: &str) -> Self;
    /// Creates an error that indicates a symbol was expected.
    fn expected_symbol(context: &C, from: &str) -> Self;
}

/// Extension trait on [`Cursor`]s to help with command parsing.
///
/// All `read_*` methods reset the cursor on error.
///
/// Note that, compared to Brigadier, this lacks methods such as
/// `getRemainingLength` (use `get_remaining().len()` or
/// `remaining_slice().len()`) and `getTotalLength` (use `get_ref().len()`).
pub trait StringReader<'a>: Sized {
    /// Returns the part of the string that has been read so far.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    //#[inline]
    fn get_read(&self) -> &'a str;
    /// Returns the part of the string that has yet to be read.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    //#[inline]
    fn get_remaining(&self) -> &'a str;
    /// Returns whether there's anything left to read.
    #[inline]
    fn can_read(&self) -> bool {
        self.can_read_n(1)
    }
    /// Returns whether there's enough left to read, based on the passed length.
    //#[inline]
    fn can_read_n(&self, len: usize) -> bool;
    /// Returns the next char.
    ///
    /// # Panics
    ///
    /// Panics if there's nothing left to read, or if this cursor is not on an
    /// UTF-8 character boundary.
    #[inline]
    fn peek(&self) -> char {
        self.peek_n(0)
    }
    /// Returns the next nth **byte** (and, if needed, subsequent bytes) as a
    /// char.
    ///
    /// # Panics
    ///
    /// Panics if the offset is beyond the boundaries of the buffer, or if the
    /// offset is not on an UTF-8 character boundary.
    //#[inline]
    fn peek_n(&self, offset: usize) -> char;

    /// Advances to the next char.
    ///
    /// # Panics
    ///
    /// Panics if there's nothing left to read, or if this cursor is not on an
    /// UTF-8 character boundary.
    //#[inline]
    fn skip(&mut self);
    /// Attempts to read the next char.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    //#[inline]
    fn read_char(&mut self) -> Option<char>;
    /// Checks the next char.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    fn expect<E: ReadError<'a, Self>>(&mut self, c: char) -> Result<(), E> {
        if !self.can_read() || self.peek() != c {
            // because we want the error constructors to take &str.
            let mut buf = [0u8; 4];
            Err(E::expected_symbol(self, c.encode_utf8(&mut buf)))
        } else {
            Ok(self.skip())
        }
    }
    /// Skips whitespace.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    fn skip_whitespace(&mut self) {
        // FIXME figure out if we wanna use the same whitespace rules as
        // brigadier, because rust uses unicode whereas java uses java rules.
        while self.can_read() && self.peek().is_whitespace() {
            self.skip();
        }
    }

    /// Reads an integer.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    fn read_integer<T, E: ReadError<'a, Self>>(&mut self) -> Result<T, E>
    where T: FromStr<Err=std::num::ParseIntError>;
    /// Reads a float.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    fn read_float<T, E: ReadError<'a, Self>>(&mut self) -> Result<T, E>
    where T: FromStr<Err=std::num::ParseFloatError>;
    /// Reads a bool.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    fn read_bool<E: ReadError<'a, Self>>(&mut self) -> Result<bool, E>;
    /// Reads an unquoted string.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    // this is a bit of a weird one in that it can't error.
    fn read_unquoted_str(&mut self) -> &'a str;
    /// Reads a quoted string.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    fn read_quoted_string<E: ReadError<'a, Self>>(
        &mut self,
    ) -> Result<String, E>;
    /// Reads a quoted or an unquoted string.
    ///
    /// # Panics
    ///
    /// Panics if this cursor is not on an UTF-8 character boundary.
    fn read_string<E: ReadError<'a, Self>>(&mut self) -> Result<String, E>;
}

impl<'a> StringReader<'a> for Cursor<&'a str> {
    #[inline]
    fn get_read(&self) -> &'a str {
        &self.get_ref()[..(self.position() as usize)]
    }
    #[inline]
    fn get_remaining(&self) -> &'a str {
        &self.get_ref()[(self.position() as usize)..]
    }
    #[inline]
    fn can_read_n(&self, len: usize) -> bool {
        // NOTE: NOT overflow-aware!
        self.position() as usize + len <= self.get_ref().len()
    }
    #[inline]
    fn peek_n(&self, offset: usize) -> char {
        // NOTE: NOT overflow-aware!
        self.get_ref()[(self.position() as usize + offset)..]
            .chars().next().unwrap()
    }

    #[inline]
    fn skip(&mut self) {
        self.set_position(self.position() + self.peek().len_utf8() as u64);
    }
    #[inline]
    fn read_char(&mut self) -> Option<char> {
        let res = self.get_ref()[(self.position() as usize)..].chars().next();
        if let Some(c) = res {
            self.set_position(self.position() + c.len_utf8() as u64);
        }
        res
    }

    fn read_integer<T, E: ReadError<'a, Self>>(&mut self) -> Result<T, E>
    where T: FromStr<Err=std::num::ParseIntError> {
        // see read_unquoted_str for rationale
        let start = self.position() as usize;
        let total = self.get_ref().len();
        let end = total - {
            self.get_remaining().trim_start_matches(number_chars).len()
        };
        self.set_position(end as u64);

        let number = &self.get_ref()[start..end];
        if number.is_empty() {
            // don't need to set_position here, we haven't moved
            Err(E::expected_integer(self))
        } else {
            number.parse().map_err(|_| {
                self.set_position(start as u64);
                E::invalid_integer(self, number)
            })
        }
    }
    fn read_float<T, E: ReadError<'a, Self>>(&mut self) -> Result<T, E>
    where T: FromStr<Err=std::num::ParseFloatError> {
        // see read_unquoted_str for rationale
        let start = self.position() as usize;
        let total = self.get_ref().len();
        let end = total - {
            self.get_remaining().trim_start_matches(number_chars).len()
        };
        self.set_position(end as u64);

        let number = &self.get_ref()[start..end];
        if number.is_empty() {
            // don't need to set_position here, we haven't moved
            Err(E::expected_float(self))
        } else {
            number.parse().map_err(|_| {
                self.set_position(start as u64);
                E::invalid_float(self, number)
            })
        }
    }
    fn read_bool<E: ReadError<'a, Self>>(&mut self) -> Result<bool, E> {
        let pos = self.position();
        // NOTE: brigadier also allows quoted strings for bools.
        // we consider that a bug, so we don't.
        let res = match self.read_unquoted_str() {
            "true" => Ok(true),
            "false" => Ok(false),
            "" => Err(E::expected_bool(self)),
            value => {
                self.set_position(pos);
                Err(E::invalid_bool(self, value))
            },
        };
        res
    }
    fn read_unquoted_str(&mut self) -> &'a str {
        // there's no easy way to grab start matches, so we have to do something
        // a bit more involved.
        let start = self.position() as usize;
        let total = self.get_ref().len();
        let end = total - {
            self.get_remaining().trim_start_matches(unquoted_chars).len()
        };
        self.set_position(end as u64);
        &self.get_ref()[start..end]
    }
    fn read_quoted_string<E: ReadError<'a, Self>>(
        &mut self,
    ) -> Result<String, E> {
        if !self.can_read() {
            Ok("".into())
        } else if quote_chars(self.peek()) {
            let start = self.position() as usize;
            let terminator = self.read_char().unwrap();
            let res = read_string_until(self, terminator);
            if res.is_err() {
                self.set_position(start as u64);
            }
            res
        } else {
            Err(E::expected_start_of_quote(self))
        }
    }
    fn read_string<E: ReadError<'a, Self>>(&mut self) -> Result<String, E> {
        if !self.can_read() {
            Ok("".into())
        } else if quote_chars(self.peek()) {
            let start = self.position() as usize;
            let terminator = self.read_char().unwrap();
            let res = read_string_until(self, terminator);
            if res.is_err() {
                self.set_position(start as u64);
            }
            res
        } else {
            Ok(self.read_unquoted_str().into())
        }
    }
}

fn read_string_until<'a, E: ReadError<'a, Cursor<&'a str>>>(
    this: &mut Cursor<&'a str>,
    terminator: char,
) -> Result<String, E> {
    let mut result = String::new();
    let mut escaped = false;

    while let Some(c) = this.read_char() {
        if escaped {
            if c == terminator || escape_char(c) {
                result.push(c);
                escaped = false;
            } else {
                let mut buf = [0u8; 4];
                // NOTE: brigadier unskips the escape. we don't bother.
                return Err(E::invalid_escape(this, c.encode_utf8(&mut buf)));
            }
        } else if escape_char(c) {
            escaped = true;
        } else if c == terminator {
            return Ok(result);
        } else {
            result.push(c);
        }
    }

    Err(E::expected_end_of_quote(this))
}

/// Symbols allowed in unquoted strings.
#[inline]
fn unquoted_chars(c: char) -> bool {
    matches!(
        c,
        '0' ..= '9' | 'A' ..= 'Z' | 'a' ..= 'z' | '_' | '-' | '.' | '+',
    )
}

/// Symbols allowed in numbers.
#[inline]
fn number_chars(c: char) -> bool {
    matches!(
        c,
        '0' ..= '9' | '-' | '.',
    )
}

/// Symbols allowed to start/end a quoted string.
#[inline]
fn quote_chars(c: char) -> bool {
    matches!(
        c,
        '"' | '\'',
    )
}

/// Symbol allowed to escape other symbols.
#[inline]
fn escape_char(c: char) -> bool {
    matches!(
        c,
        '\\',
    )
}