multilinear_parser/

lib.rs

#![deny(missing_docs)]

//! The `multilinear-parser` library provides functionality to parse a multilinear system from a text-based format.
//! It allows you to define events, which rely on various channel specific conditions or changes using a markdown inspired syntax.
//!
//! Example Event Syntax:
//!
//! ```text
//! # Move to Livingroom
//!
//! place: bedroom > livingroom
//!
//! # Get Dressed
//!
//! place: bedroom
//! clothes: pajamas > casual
//! ```
//!
//! Supports logical combinations:
//!
//! ```text
//! (clothes: pajamas | clothes: casual) & place: bedroom
//! ```

use header_parsing::parse_header;
use logical_expressions::{LogicalExpression, ParseError};
use thiserror::Error;

use multilinear::{Channel, Condition, Event, EventInfo, InvalidChangeError, MultilinearInfo};

use std::{
    io::{BufRead, BufReader, Read},
    marker::PhantomData,
};

/// Stores index based maps.
pub struct IndexMap<I: Into<usize> + From<usize>, V> {
    entries: Vec<V>,
    index: PhantomData<I>,
}

impl<I: Into<usize> + From<usize>, V> Default for IndexMap<I, V> {
    fn default() -> Self {
        Self {
            entries: Vec::new(),
            index: PhantomData,
        }
    }
}

impl<I: Into<usize> + From<usize>, V> IndexMap<I, V> {
    fn insert(&mut self, index: I, value: V) {
        let i = index.into();
        assert_eq!(i, self.entries.len(), "Wrong insertion order");
        self.entries.push(value);
    }
}

/// An iterator over indices and values of an index map.
pub struct IntoIter<I: Into<usize> + From<usize>, V> {
    data: std::iter::Enumerate<std::vec::IntoIter<V>>,
    index: PhantomData<I>,
}

impl<I: Into<usize> + From<usize>, V> Iterator for IntoIter<I, V> {
    type Item = (I, V);

    fn next(&mut self) -> Option<(I, V)> {
        let (i, value) = self.data.next()?;
        Some((i.into(), value))
    }
}

impl<I: Into<usize> + From<usize>, V> IntoIterator for IndexMap<I, V> {
    type Item = (I, V);
    type IntoIter = IntoIter<I, V>;

    fn into_iter(self) -> IntoIter<I, V> {
        IntoIter {
            data: self.entries.into_iter().enumerate(),
            index: PhantomData,
        }
    }
}

#[derive(Copy, Clone, Debug)]
struct ValueCheckingError(char);

type Str = Box<str>;

fn check_name(name: &str) -> Result<(), ValueCheckingError> {
    if let Some(c) = name
        .chars()
        .find(|&c| !c.is_alphanumeric() && !"_- ".contains(c))
    {
        Err(ValueCheckingError(c))
    } else {
        Ok(())
    }
}

fn valid_name(name: &str) -> Result<&str, ValueCheckingError> {
    let name = name.trim();
    check_name(name)?;
    Ok(name)
}

fn value_index(value_names: &mut Vec<Str>, name: &str) -> Result<usize, ValueCheckingError> {
    let name = valid_name(name)?;

    if let Some(index) = value_names.iter().position(|x| x.as_ref() == name) {
        return Ok(index);
    }

    let index = value_names.len();
    value_names.push(name.into());
    Ok(index)
}

fn channel_info<'a>(
    channels: &'a mut IndexMap<Channel, (Str, Vec<Str>)>,
    name: &str,
    info: &mut MultilinearInfo,
) -> Result<(Channel, &'a mut Vec<Str>), ValueCheckingError> {
    let name = valid_name(name)?;

    if let Some(i) = channels
        .entries
        .iter()
        .position(|(checked_name, _)| checked_name.as_ref() == name)
    {
        return Ok((Channel(i), &mut channels.entries[i].1));
    }

    let channel = info.add_channel();
    channels.insert(channel, (name.into(), Vec::new()));

    let (_, value_names) = channels.entries.last_mut().unwrap();

    let _ = value_index(value_names, "");

    Ok((channel, value_names))
}

/// Represents errors that can occur when parsing conditions.
#[derive(Copy, Clone, Debug, Error)]
pub enum ConditionParsingError {
    /// Indicates an invalid character was encountered.
    #[error("Invalid character '{0}' for condition names")]
    InvalidCharacter(char),

    /// Indicates an invalid condition format.
    #[error("Invalid condition format")]
    InvalidCondition,
}

impl From<ValueCheckingError> for ConditionParsingError {
    fn from(ValueCheckingError(c): ValueCheckingError) -> Self {
        Self::InvalidCharacter(c)
    }
}

/// Represents the kinds of errors that can occur when parsing a line.
#[derive(Copy, Clone, Debug, Error)]
pub enum ErrorKind {
    /// Indicates an error occurred while parsing the line.
    #[error("Input error while parsing line")]
    LineParsing,

    /// Indicates an error occurred while parsing an expression.
    #[error("Parsing expression failed: {0}")]
    ExpressionParsing(ParseError<ConditionParsingError>),

    /// Indicates conflicting conditions were encountered.
    #[error("Encountered conflicting conditions: {0}")]
    ConflictingCondition(InvalidChangeError),

    /// Indicates an invalid character was encountered while parsing the event name.
    #[error("Invalid character '{0}' in event name")]
    InvalidCharacterInEventName(char),

    /// Indicates no event was specified.
    #[error("No event has been specified")]
    NoEvent,

    /// Indicates a subheader was encountered without a corresponding header.
    #[error("Subheader without matching header")]
    SubheaderWithoutHeader,
}

trait ErrorLine {
    type Output;

    fn line(self, line: usize) -> Self::Output;
}

impl ErrorLine for ErrorKind {
    type Output = Error;

    fn line(self, line: usize) -> Error {
        Error { line, kind: self }
    }
}

impl<T> ErrorLine for Result<T, ErrorKind> {
    type Output = Result<T, Error>;

    fn line(self, line: usize) -> Result<T, Error> {
        match self {
            Ok(value) => Ok(value),
            Err(err) => Err(err.line(line)),
        }
    }
}

/// Represents errors that can occur during parsing.
#[derive(Debug, Error)]
#[error("Line {line}: {kind}")]
pub struct Error {
    /// The line the error occured on.
    line: usize,
    /// The error kind.
    kind: ErrorKind,
}

/// A multilinear info containing the mapped channel and event names.
#[derive(Default)]
pub struct NamedMultilinearInfo {
    /// The parsed `MultilinearInfo` instance.
    pub info: MultilinearInfo,
    /// A map associating events with their names.
    pub events: IndexMap<Event, Vec<Str>>,
    /// A map associating channels with their names and the names of the channel.
    pub channels: IndexMap<Channel, (Str, Vec<Str>)>,
}

/// A parser for multilinear system definitions, supporting incremental parsing
/// across multiple files or input streams.
#[derive(Default)]
pub struct MultilinearParser(NamedMultilinearInfo);

impl MultilinearParser {
    /// Parses additional multilinear data from the given reader.
    ///
    /// # Arguments
    ///
    /// * `reader` - The input source to parse from
    /// * `namespace` - Initial header context/path for events (e.g., `vec!["Main Story".into()]`)
    ///
    /// # Example
    ///
    /// ```no_run
    /// use std::fs::File;
    /// use multilinear_parser::MultilinearParser;
    ///
    /// let mut parser = MultilinearParser::default();
    /// parser.parse(File::open("chapter1.mld").unwrap(), Vec::new()).unwrap();
    /// parser.parse(File::open("chapter2.mld").unwrap(), Vec::new()).unwrap();
    /// ```
    pub fn parse<R: Read>(&mut self, reader: R, mut namespace: Vec<Str>) -> Result<(), Error> {
        let NamedMultilinearInfo {
            info,
            events,
            channels,
        } = &mut self.0;

        let mut condition_groups = Vec::new();
        let mut condition_lines = Vec::new();

        let mut last_header_line = 0;

        for (line_number, line) in BufReader::new(reader).lines().enumerate() {
            let Ok(line) = line else {
                return Err(ErrorKind::LineParsing.line(line_number));
            };

            if line.trim().is_empty() {
                if !condition_lines.is_empty() {
                    condition_groups.push(LogicalExpression::and(condition_lines));
                    condition_lines = Vec::new();
                }
                continue;
            }

            if let Some(success) = parse_header(&mut namespace, &line) {
                let Ok(changes) = success else {
                    return Err(ErrorKind::SubheaderWithoutHeader.line(line_number));
                };

                if let Err(ValueCheckingError(c)) = check_name(&changes.header) {
                    return Err(ErrorKind::InvalidCharacterInEventName(c)).line(line_number);
                }

                if !condition_lines.is_empty() {
                    condition_groups.push(LogicalExpression::and(condition_lines));
                    condition_lines = Vec::new();
                }

                if !condition_groups.is_empty() {
                    let mut event = EventInfo::new();
                    for conditions in LogicalExpression::or(condition_groups).expand() {
                        if let Err(err) = event.add_change(&conditions) {
                            return Err(ErrorKind::ConflictingCondition(err).line(last_header_line));
                        }
                    }

                    let event = info.add_event(event);
                    events.insert(event, changes.path.clone());

                    condition_groups = Vec::new();
                }

                last_header_line = line_number + 1;

                changes.apply();

                continue;
            }

            if namespace.is_empty() {
                return Err(ErrorKind::NoEvent.line(line_number));
            }

            let parse_conditions = |condition: &str| {
                let Some((channel, change)) = condition.split_once(':') else {
                    return Err(ConditionParsingError::InvalidCondition);
                };

                let (channel, value_names) = channel_info(channels, channel.trim(), info)?;
                Ok(if let Some((from, to)) = change.split_once('>') {
                    let from = value_index(value_names, from)?;
                    let to = value_index(value_names, to)?;
                    Condition::change(channel, from, to)
                } else {
                    let change = value_index(value_names, change)?;
                    Condition::new(channel, change)
                })
            };

            let conditions = LogicalExpression::parse_with(&line, parse_conditions);

            let conditions = match conditions {
                Ok(conditions) => conditions,
                Err(err) => return Err(ErrorKind::ExpressionParsing(err).line(line_number)),
            };

            condition_lines.push(conditions);
        }

        if !condition_lines.is_empty() {
            condition_groups.push(LogicalExpression::and(condition_lines));
        }

        if !condition_groups.is_empty() {
            let mut event = EventInfo::new();
            for conditions in LogicalExpression::or(condition_groups).expand() {
                if let Err(err) = event.add_change(&conditions) {
                    return Err(ErrorKind::ConflictingCondition(err).line(last_header_line));
                }
            }

            let event = info.add_event(event);
            events.insert(event, namespace);
        }

        Ok(())
    }

    /// Consumes the parser and returns the fully parsed data.
    ///
    /// After calling this, the parser can no longer be used.
    pub fn into_info(self) -> NamedMultilinearInfo {
        self.0
    }
}

/// Parses a complete multilinear system from a single reader.
///
/// This is a convenience wrapper for single-file parsing. For multi-file parsing,
/// use [`MultilinearParser`] directly.
///
/// # Example
///
/// ```no_run
/// use std::fs::File;
/// use multilinear_parser::parse_multilinear;
///
/// let story = parse_multilinear(File::open("story.mld").unwrap()).unwrap();
/// ```
pub fn parse_multilinear<R: Read>(reader: R) -> Result<NamedMultilinearInfo, Error> {
    let mut result = MultilinearParser::default();
    result.parse(reader, Vec::new())?;
    Ok(result.0)
}