yash-env 0.13.2

Yash shell execution environment interface
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

// This file is part of yash, an extended POSIX shell.
// Copyright (C) 2025 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/>.

//! Shell language parser configuration and utilities
//!
//! This module contains several items related to the shell language parser.
//!
//! - [`Config`] is a struct that holds configuration options for the parser.
//! - [`IsKeyword`] is a wrapper for a function that checks if a string is a
//!   reserved word.
//! - [`IsName`] is a wrapper for a function that checks if a string is a valid
//!   variable name.
//!
//! Parser implementations are not provided in this crate (`yash-env`). The
//! standard parser implementation is provided in the `yash-syntax` crate.

use crate::Env;
use crate::input::InputObject;
use crate::source::Source;
use derive_more::Debug;
use std::num::NonZeroU64;
use std::rc::Rc;

/// Configuration for the parser
///
/// This struct holds various configuration options for the parser, including
/// the input function to read source code and source information.
///
/// Parser implementations are not provided in this crate (`yash-env`). The
/// standard parser implementation is provided in the `yash-syntax` crate.
/// `Config` is provided here so that other crates can use [`RunReadEvalLoop`]
/// without depending on `yash-syntax`.
///
/// Since this struct is marked as `#[non_exhaustive]`, you cannot construct it
/// directly. Instead, use the [`with_input`](Self::with_input) function to
/// create a `Config` instance, and then modify its fields as necessary.
///
/// [`RunReadEvalLoop`]: crate::semantics::RunReadEvalLoop
#[derive(Debug)]
#[non_exhaustive]
pub struct Config<'a> {
    /// Input function to read source code
    #[debug(skip)]
    pub input: Box<dyn InputObject + 'a>,

    /// Line number for the first line of the input
    ///
    /// The lexer counts lines starting from this number. This affects the
    /// `start_line_number` field of the [`Code`] instance attached to the
    /// parsed AST.
    ///
    /// The default value is `1`.
    ///
    /// [`Code`]: crate::source::Code
    pub start_line_number: NonZeroU64,

    /// Source information for the input
    ///
    /// If provided, this source information is saved in the `source` field of
    /// the [`Code`] instance attached to the parsed AST.
    ///
    /// The default value is `None`, in which case `Source::Unknown` is used.
    ///
    /// [`Code`]: crate::source::Code
    pub source: Option<Rc<Source>>,
}

impl<'a> Config<'a> {
    /// Creates a `Config` with the given input function.
    #[must_use]
    pub fn with_input(input: Box<dyn InputObject + 'a>) -> Self {
        Self {
            input,
            start_line_number: NonZeroU64::new(1).unwrap(),
            source: None,
        }
    }
}

/// Wrapper for a function that checks if a string is a keyword
///
/// This struct wraps a function that takes an environment and a string, and
/// returns `true` if the string is a shell reserved word (keyword) in the given
/// environment. An implementation of the function should be provided and stored
/// in the environment's [`any`](Env::any) storage. This allows modules that
/// need to check for keywords to do so without directly depending on the parser
/// crate (`yash-syntax`).
#[derive(Debug)]
pub struct IsKeyword<S>(pub fn(&Env<S>, &str) -> bool);

// Not derived automatically because S may not implement Clone or Copy.
impl<S> Clone for IsKeyword<S> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<S> Copy for IsKeyword<S> {}

/// Wrapper for a function that checks if a string is a valid variable name
///
/// This struct wraps a function that takes an environment and a string, and
/// returns `true` if the string is a valid shell variable name in the given
/// environment. An implementation of the function should be provided and stored
/// in the environment's [`any`](Env::any) storage. This allows modules that
/// need to check for variable names to do so without directly depending on the
/// parser crate (`yash-syntax`).
#[derive(Debug)]
pub struct IsName<S>(pub fn(&Env<S>, &str) -> bool);

// Not derived automatically because S may not implement Clone or Copy.
impl<S> Clone for IsName<S> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<S> Copy for IsName<S> {}