yash-env 0.15.2

// This file is part of yash, an extended POSIX shell.
// Copyright (C) 2021 WATANABE Yuki
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

//! Methods about passing [source](crate::source) code to the
//! [parser](crate::parser).
//!
//! # Input sources
//!
//! The [`Input`] trait is the core abstraction for reading source code lines.
//! These types are leaf inputs that produce lines from a concrete source:
//!
//! - [`Memory`]: In-memory input from a pre-loaded string
//! - [`FdReader2`]: Reads from a file descriptor asynchronously
//!
//! # Input decorators
//!
//! Several decorators wrap an inner [`Input`] to add behavior:
//!
//! - [`Echo`]: Echoes each line read to stderr (for the `verbose` option)
//! - [`IgnoreEof`]: Retries on EOF when the `ignore-eof` option is on (simple
//!   interactive use)
//! - [`Reporter`]: Reports job status changes before each prompt
//! - [`EofGuard`]: Combines suspended-jobs protection with `ignore-eof` retry;
//!   prefer over [`IgnoreEof`] for the interactive read loop
//!
//! ## Configuration stored in `env.any`
//!
//! [`EofGuard`] reads its behavior configuration from
//! [`SuspendedJobsGuardConfig`] and [`IgnoreEofConfig`] stored in
//! [`Env::any`](crate::Env::any):
//!
//! - [`SuspendedJobsGuardConfig`]: enables the suspended-jobs protection in
//!   [`EofGuard`] (and any other component that opts in). If absent, the
//!   protection is disabled.
//! - [`IgnoreEofConfig`]: enables the `ignore-eof` retry behavior in
//!   [`EofGuard`]. If absent, EOF is not retried even when the `ignore-eof`
//!   option is on.

use std::ops::DerefMut;
use std::pin::Pin;

/// Parameter passed to the input function
///
/// The context is passed to the [input function](Input::next_line) so that it
/// can read the input in a context-dependent way.
#[derive(Debug)]
#[non_exhaustive]
pub struct Context {
    is_first_line: bool,
}

impl Default for Context {
    fn default() -> Self {
        Self {
            is_first_line: true,
        }
    }
}

impl Context {
    /// Whether the current line is the first line of the input
    #[inline]
    #[must_use]
    pub fn is_first_line(&self) -> bool {
        self.is_first_line
    }

    /// Sets whether the current line is the first line of the input
    ///
    /// This method is used by the lexer to set the flag. It can also be used in
    /// tests to simulate a non-first line. The default value is `true`.
    #[inline]
    pub fn set_is_first_line(&mut self, is_first_line: bool) {
        self.is_first_line = is_first_line;
    }
}

/// Error returned by the [Input] function
pub type Error = std::io::Error;

/// Result of the [Input] function
pub type Result = std::result::Result<String, Error>;

/// Line-oriented source code reader
///
/// An `Input` implementor provides the parser with source code by reading from underlying source.
///
/// [`InputObject`] is an object-safe version of this trait.
#[must_use = "Input instances should be used by a parser"]
pub trait Input {
    /// Reads a next line of the source code.
    ///
    /// The input function is line-oriented; that is, this function returns a string that is
    /// terminated by a newline unless the end of input (EOF) is reached, in which case the
    /// remaining characters up to the EOF must be returned without a trailing newline. If there
    /// are no more characters at all, the returned line is empty.
    ///
    /// Errors returned from this function are considered unrecoverable. Once an error is returned,
    /// this function should not be called any more.
    fn next_line(&mut self, context: &Context) -> impl Future<Output = Result>;
}

impl<T> Input for T
where
    T: DerefMut,
    T::Target: Input,
{
    fn next_line(&mut self, context: &Context) -> impl Future<Output = Result> {
        self.deref_mut().next_line(context)
    }
}

/// Object-safe adapter for the [`Input`] trait
///
/// `InputObject` is an object-safe version of the [`Input`] trait. It allows
/// the trait to be used as a trait object, which is necessary for dynamic
/// dispatch.
///
/// The umbrella implementation is provided for all types that implement the
/// [`Input`] trait.
pub trait InputObject {
    fn next_line<'a>(
        &'a mut self,
        context: &'a Context,
    ) -> Pin<Box<dyn Future<Output = Result> + 'a>>;
}

impl<T: Input> InputObject for T {
    fn next_line<'a>(
        &'a mut self,
        context: &'a Context,
    ) -> Pin<Box<dyn Future<Output = Result> + 'a>> {
        Box::pin(Input::next_line(self, context))
    }
}

mod memory;
pub use memory::Memory;

mod fd_reader_2;
pub use fd_reader_2::FdReader2;

mod echo;
pub use echo::Echo;

mod ignore_eof;
pub use ignore_eof::IgnoreEof;

mod reporter;
pub use reporter::Reporter;

mod eof_guard;
pub use eof_guard::{EofGuard, IgnoreEofConfig, SuspendedJobsGuardConfig};