Logs the entry of a function with its arguments.

Source: flowdebugmodereporter.rs

pub fn flow_debug_mode_function_enter(  
    module_name: &str,  
    function_name: &str,  
    args: Vec<&str>  
) -> ()

Arguments:

1. module_name: &str - name of the module emitting the event.
2. function_name: &str - name of the function being entered.
3. args: Vec<&str> - vector of string slices representing the function arguments.

Behavior:

• Prints a header line: FUNCTION_ENTER - module_name -> function_name -> with args:
• Iterates over `args`, printing each with its index.

Return type:

• Void

Logs the exit of a function with its return values.

Source: flowdebugmodereporter.rs

pub fn flow_debug_mode_function_exit(  
    module_name: &str,  
    function_name: &str,  
    return_values: Vec<&str>  
) -> () 

Arguments:

1. module_name: &str - name of the module emitting the event.
2. function_name: &str - name of the function being exited.
3. return_values: Vec<&str> - vector of string slices for the return values.

Behavior:

• Prints a header line: FUNCTION_EXIT - module_name -> function_name -> with return values:
• Iterates over return_values, printing each with its index.

Return type:

• Void

Logs an informational message during function execution.

Source: flowdebugmodereporter.rs

pub fn flow_debug_mode_function_info(  
    module_name: &str,  
    function_name: &str,  
    message: &str  
) -> () 

Arguments:

1. module_name: &str - name of the module emitting the event.
2. function_name: &str - name of the function reporting info.
3. message: &str - informational message to print.

Behavior:

• Prints a single line: INFO - module_name -> function_name -> with message: "message"

Return type:

• Void

Reports an error with its location and message.

Source: flowerrorreporter.rs

pub fn flow_report_error(  
    line: u32,  
    width: u32,  
    error_location: &str,  
    message: &str  
) -> ()

Arguments:

1. line: u32 - line number where the error occurred (1-based).
2. width: u32 - character position within the line (0 indicates the entire line).
3. error_location: &str - identifier of the function or module reporting the error.
4. message: &str - error message to display.

Behavior:

• Prints to standard error in the format: [line {line}, char {width}] Error: {error_location} \u2192 {message}.

Return type:

• Void

Source: flowhistoryhandler.rs

#[derive(Debug)]  
pub struct ShellHistoryLogger {  
    hist_file_location: PathBuf,  
    runtime_shell_history: Vec<String>,  
}  

Fields:

1. hist_file_location: PathBuf - filesystem path to the history file (either from the HISTLOCATION envar or defaulting to ~/.flow_history in the users home directory).
2. runtime_shell_history: Vec<String> - in memory buffer of commands entered during the current session.

Constructs a new `ShellHistoryLogger`, determining and creating the history file if needed.

Source: flowhistoryhandler.rs

pub fn new() -> Result<Self, String>  

Arguments: None

Return type:

• Returns Result<ShellHistoryLogger, String>
  • Ok: a logger with hist_file_location set and empty runtime_shell_history.
  • Err: an error message if home directory lookup, file creation, or custom-path validation fails.

Behavior:

1. Checks HISTLOCATION envar for a custom path.
2. If unset, uses HOME or USERPROFILE to derive ~/.flow_history and creates it if nonexistent.
3. If set but the file doesnt exist, returns an error.

Appends all buffered entries to the history file.

Source: flowhistoryhandler.rs

pub fn log_all_history(&mut self) -> Result<(), String>  

Arguments:

• &mut self - mutable reference to the logger.

Return type:

• Returns Result<(), String>
  • Ok: entries successfully written.
  • Err: formatted I/O error.

Behavior:

1. Opens self.hist_file_location with append mode.
2. Iterates over runtime_shell_history, writing each entry on its own line.

Adds a new command to the inmemory history buffer.

Source: flowhistoryhandler.rs

pub fn update(&mut self, new_input: String) -> Result<(), String>  

Arguments:

1. &mut self - mutable reference to the logger.
2. new_input: String - the command string to record.

Return type:

• Returns Result<(), String> always Ok(()), since in-memory push cannot fail.

Behavior: Pushes new_input into runtime_shell_history.

Represents the kinds of lexemes recognized by the lexer.

Source: flowlexer.rs

#[derive(Debug, Clone, PartialEq, Eq)]  
pub enum TokenType {  
    LeftParen,    // (  
    RightParen,   // )  
    Identifier,  
    StringLiteral,  
    Integer,  
}  

Fields:

1. LeftParen - single-character `(`.
2. RightParen - single-character `)`.
3. Identifier - names and symbols not matching other types.
4. StringLiteral - text enclosed in double quotes.
5. Integer - sequences of ASCII digits.

Holds a lexeme with its type and source location.

Source: flowlexer.rs

#[derive(Debug, Clone, PartialEq)]  
pub struct Token {  
    pub token_type: TokenType,  
    pub lexeme: String,  
    pub line_number: u32,  
    pub token_start_number: u32,  
}  

Fields:

1. token_type: TokenType - kind of the token.
2. lexeme: String - the exact substring from the source line.
3. line_number: u32 - 1-based line index where the token was found.
4. token_start_number: u32 - 0-based character index of the tokens start.

Classifies a raw substring as `Identifier` or `Integer` and appends it to the token list.

Source: flowlexer.rs

fn push_identifier(  
    tokens: &mut Vec<Token>,  
    text: &str,  
    line_number: u32,  
    start: u32  
) -> () 

Arguments:

1. tokens: &mut Vec<Token> - buffer to receive the new token.
2. text: &str - the substring to classify.
3. line_number: u32 - source line number.
4. start: u32 - character index of `text` start.

Behavior:

• If `text` is all ASCII digits, token type is `Integer`, otherwise `Identifier`.
• Creates and pushes a `Token` with the given location and lexeme.

Splits a line of source into a vector of `Token`, handling strings, comments, and grouping.

Source: flowlexer.rs

pub fn flow_tokenize(  
    line: &str,  
    line_number: u32,  
    debug_mode: bool  
) -> Vec<Token>

Arguments:

1. line: &str - the raw source line.
2. line_number: u32 - 1-based index of the line.
3. debug_mode: bool - if `true`, emits debug-enter and debug-exit events.

Return type:

• Vec<Token> a list of tokens extracted from `line`.

Behavior:

1. Iterates over characters, maintaining state for:
   • in_string for text inside `" "`.
   • in_comment and in_single_line_comment for `;` comments.
   • current buffer accumulating identifier/number text.
   • Positions string_start and token_start.
2. On encountering delimiters, flushes current via push_identifier as needed, pushes single-char tokens, or enters/exits string/comment modes.
3. After the loop, flushes any remaining identifier/number token.
4. Returns the token vector.

Represents the inferred or annotated type of an expression.

Source: flowtypeenv.rs

#[derive(Debug, Clone, PartialEq)]  
pub enum Type {  
    Integer(i64),        // integer literal with its value  
    Boolean(bool),       // boolean literal  
    String(String),      // string literal  
    Identifier(String),  // user-defined identifier type  
    Function(Vec<Type>, Box<Type>), // function: arg types and return type  
    Alias(String),       // alias name for another type  
    Unknown,             // runtime-inferred or undetermined type  
}  

Variants:

1. Integer(i64) - literal 64 bit integer value.
2. Boolean(bool) - literal boolean value.
3. String(String) - literal string data.
4. Identifier(String) - refers to a named type or variable.
5. Function(Vec<Type>, Box<Type>) - function type signature.
6. Alias(String) - named alias for another type.
7. Unknown - placeholder for types to be inferred at runtime.

Manages a stack of scopes mapping names to `Type`.

Source: typeenv.rs

#[derive(Debug)]  
pub struct TypeEnv {  
    scopes: Vec<HashMap<String, Type>>,  
}  

Fields:

1. scopes: Vec<HashMap<String, Type>> - stack of hash maps for nested scopes.

Methods:

• new() - initializes with a single empty scope.
• enter_scope() - pushes a new, inner scope.
• exit_scope() - pops the current scope.
• insert(name: String, var_value: Type) - binds name to var_value in the current scope.
• lookup(name: &str) -> Option<&Type> - searches from innermost to outermost scope.

Validates an optional annotation against an inferred type and records the binding.

Source: typechecker.rs

pub fn handle_define_var(  
    name: String,  
    var_type: Option<Type>,  
    value: Type,  
    env: &mut TypeEnv,  
) -> Result<(), String>

Arguments:

1. name: String - variable name.
2. var_type: Option<Type> - optional user annotation.
3. value: Type - inferred type of the initializer.
4. env: &mut TypeEnv - environment to bind the variable.

Behavior:

• If var_type is Some(annot), ensures value == annot, returning an `Err` on mismatch.
• Inserts the binding into the current scope.
• Returns Ok(()) on success or Err(String).

Performs type inference and checking on an `Expression`.

Source: typechecker.rs

pub fn type_check(  
    expr: &Expression,  
    env: &mut TypeEnv  
) -> Result<Type, String> 

Arguments:

1. expr: &Expression - AST node to check.
2. env: &mut TypeEnv - current type environment.

Behavior:

• For `Integer`, `StringLiteral`, and `Bool`, returns the corresponding `Type` variant.
• For Identifier(name), looks up `name` in `env`, cloning and returning the bound `Type`, or `Err` if unbound.
• Returns `Err` for unimplemented AST variants.

Represents the different kinds of expressions the parser recognizes.

Source: flowparser.rs

#[derive(Debug, Clone, PartialEq)]  
pub enum ExpressionType {  
    // atoms  
    Integer(i64),  
    StringLiteral(String),  
    Identifier(String),  
    Bool(bool),  

    // reserved keywords  
    DefineVar {  
        name: String,  
        var_type: Option<Type>,    // optional annotation, always inferred at runtime for now  
        value: Box<Expression>  
    },  
    DefineEnvar {  
        name: String,  
        value: Box<Expression>,  
    },  

    DefineAlias {  
        name: String,  
        value: Box<Expression>,  
    },  

    // for shell purposes  
    Command {  
        name: String,  
        params: Vec<Expression>,  
        pipe: Option<Box<Expression>>,  
        redirect: Option<(RedirectionType, PathBuf)>,  
    },  

    // represents a parsed file  
    List(Vec<Expression>),  

    // for partial evaluation and error aggregation  
    Error(ErrorExp),  
    Unknown,  
}  

Variants:

1. Integer(i64) - numeric literal.
2. StringLiteral(String) - text enclosed in quotes.
3. Identifier(String) - names, variable references, and symbols.
4. Bool(bool) - boolean literal (`true` or `false`).
5. DefineVar - variable definition with optional type annotation and initializer.
6. DefineEnvar - environment variable definition with initializer.
7. DefineAlias - alias definition for commands.
8. Command - shell command invocation, with parameters, optional pipe target, and optional redirection.
9. List(Vec<Expression>) - top-level sequence of expressions
10. Error(ErrorExp) - placeholder for a parse error, captures location and message.
11. Unknown - fallback for unrecognized constructs.

Specifies kinds of I/O redirection in a command.

Source: flowparser.rs

#[derive(Debug, Clone, PartialEq)]  
pub enum RedirectionType {  
    Input,   
    Output {  
        append: bool,  
        stderr: bool,  
        stdin: bool,  
    },  
}  

Variants:

1. Input - `< file` redirect for stdin.
2. Output - `>` or `>>` or variants:
   • append: if true, use `>>`;
   • stderr: if true, redirect stderr, use `2>`;
   • stdin: if true, redirect stdin as well, use `&>`;

Categorizes the define-keyword forms.

Source: flowparser.rs

#[derive(Debug, Clone, PartialEq)]  
pub enum KeywordDefineType {  
    Var,  
    Envar,  
    Alias,  
}  

Variants:

1. Var - define `var`.
2. Envar - define `envar`.
3. Alias - define `alias`.

Enumerates redirection keywords recognized during parsing.

Source: flowparser.rs

#[derive(Debug, Clone, PartialEq)]  
pub enum KeywordRedirectType {  
    Input,  
    Output,  
    OutputAppend,  
    OutputStderr,  
    OutputCombined,  
}  

Variants correspond to `<`, `>`, `>>`, `2>`, and `&>` syntax.

Higher-level classification for parser tokens corresponding to keywords.

Source: flowparser.rs

#[derive(Debug, Clone, PartialEq)]  
pub enum KeywordType {  
    Define(KeywordDefineType),  
    Command,  
    Pipe,  
    Redirect(KeywordRedirectType),  
}  

Variants:

1. Define - wraps a `KeywordDefineType`.
2. Command - invocation keyword.
3. Pipe - `|`.
4. Redirect - wraps a `KeywordRedirectType`.

Holds a parsed expression node and its source token for location tracking.

Source: flowparser.rs

#[derive(Debug, Clone, PartialEq)]  
pub struct Expression {  
    pub exp_start_token: Option<Token>,  
    pub exp_type: ExpressionType,  
}  

Fields:

1. exp_start_token: Option<Token> - the first token of this expression (for error reporting).
2. exp_type: ExpressionType - the actual AST node kind and data.

Captures information about a parse-time error as an expression.

Source: flowparser.rs

#[derive(Debug, Clone, PartialEq)]  
pub struct ErrorExp {  
    pub token: Option<Token>,  
    pub error_location: String,  
    pub message: String,  
}  

Fields:

1. token: Option<Token> - the token where the error was detected (if available).
2. error_location: String - textual description of the error position
3. message: String - human-readable error message.

First pass turns a flat &[Token] slice into a nested Expression::List structure, detecting parentheses depth and basic atom forms.

Source: flowparser.rs

fn parse_s_expression(  
    tokens: &[Token],  
    pos: usize,  
    has_errors: &mut bool  
) -> (Expression, usize)

Arguments:

1. tokens: &[Token] - the token stream from the lexer.
2. pos: usize - current parse position in `tokens`.
3. has_errors: &mut bool - accumulates parse errors.

Behavior:

• On `LeftParen`, enters a loop to parse sub-expressions until a matching `RightParen`.
• Recursively calls itself for nested lists.
• Converts `Identifier`, `Integer`, and `StringLiteral` tokens into their respective `ExpressionType` variants
• Returns an `Expression` and the next token position.
• Reports errors for unexpected tokens, unclosed parentheses, and EOF.

Second pass: walks the raw Expression::List, recognizes keywords, and invokes specialized parsers (`parse_define`, `preproc_parse_cmd`). It also checks variable bindings and expands nested lists.

Source: flowparser.rs

fn expand_parsed_s_expression(  
    exp: Expression,  
    keyword_type_map: &HashMap<&str, KeywordType>,  
    type_env: &mut TypeEnv,  
    has_errors: &mut bool,  
) -> Expression 

Arguments:

1. exp: Expression - the raw AST from parse_s_expression.
2. keyword_type_map: &HashMap<&str, KeywordType> - maps symbols to parsing actions (define, command, pipe, redirect).
3. type_env: &mut TypeEnv - for checking that identifiers are defined.
4. has_errors: &mut bool - records any new errors.

Behavior:

• Propagates existing `Error` expressions unchanged.
• On ExpressionType::List(items):
  • If the first element is a keyword identifier, dispatches to parse_define or preproc_parse_cmd.
  • Otherwise, ensures the identifier is defined in type_env or emits an error.
  • Recursively expands each element to produce a new `List`.
• Atoms (`Integer`, `StringLiteral`, `Identifier`, `Bool`) are returned as-is.

Parses a var/envar/alias definition S-expression into a corresponding `ExpressionType`.

Source: flowparser.rs

fn parse_define(  
    items: Vec<Expression>,  
    keyword_define_type: &KeywordDefineType,  
    keyword_type_map: &HashMap<&str, KeywordType>,  
    type_env: &mut TypeEnv,  
    has_errors: &mut bool,  
) -> Expression 

Arguments:

1. items: Vec<Expression> - the three-element list: (define-keyword name expr value expr).
2. keyword_define_type: &KeywordDefineType - which define form (Var, Envar, Alias).
3. keyword_type_map: &HashMap<&str, KeywordType> - lookup for nested expansions.
4. type_env: &mut TypeEnv - environment for type inference/checking.
5. has_errors: &mut bool - flag to record parse or type errors.

Behavior:

• Extracts and validates the identifier
• Recursively expands the value expression via expand_parsed_s_expression.
• Depending on keyword_define_type, constructs one of the corresponding ExpressionType.
• Returns an Expression with exp_start_token from the keyword and the chosen ExpressionType.

Processes a flat list of expressions into a shell `Command` AST node, handling parameters, piping, and redirection.

Source: flowparser.rs

fn parse_cmd(  
    items: &Vec<Expression>,  
    index: usize,  
    keyword_type_map: &HashMap<&str, KeywordType>,  
    type_env: &mut TypeEnv,  
    has_errors: &mut bool,  
) -> Expression

Arguments:

1. items: &Vec<Expression> - sequence of expanded subexpressions.
2. index: usize - start index of the command name in `items`.
3. keyword_type_map: &HashMap<&str, KeywordType> - kind of database that matches `keyword` to its `KeywordType`.
4. type_env: &mut TypeEnv - for type checks of parameters.
5. has_errors: &mut bool - accumulates any errors encountered.

Behavior:

• Validates the command name is an `Identifier`.
• Iterates over subsequent `items`, distinguishing:
  • Pipe tokens: recursing to parse the next command into `pipe`.
  • Redirection keywords: recording a `RedirectionType` and expecting the next token as a path.
  • Other expressions, expanded via expand_parsed_s_expression, collected into `params`.
• Reports errors
• Constructs ExpressionType::Command { name, params, pipe, redirect }.

Initial wrapper that validates the S-expression for a command and invokes parse_cmd.

Source: flowparser.rs

fn preproc_parse_cmd(  
    raw_items: Vec<Expression>,  
    keyword_type_map: &HashMap<&str, KeywordType>,  
    type_env: &mut TypeEnv,  
    has_errors: &mut bool,  
) -> Expression 

Arguments:

1. raw_items: Vec<Expression> - top-level S-expression where raw_items[1] should be a `List`.
2. keyword_type_map: &HashMap<&str, KeywordType> - kind of database that matches `keyword` to its `KeywordType`.
3. type_env: &mut TypeEnv - lookup for nested expansions.
4. has_errors: &mut bool - flag to record parse or type errors.

Behavior:

• Confirms raw_items contains at least two elements and that raw_items[1] is ExpressionType::List.
• Extracts the inner Vec<Expression> and validates it is non-empty.
• Delegates to parse_cmd with that vector starting at index `0`.
• Returns an Error expression on invalid structure or command list.

Top-level entry: orchestrates token-to-AST conversion, error collection, and optional debug tracing.

Source: flowparser.rs

pub fn flow_parse(  
    tokens: &[Token],  
    type_env: &mut TypeEnv,  
    debug_mode: bool,  
) -> (Expression, bool) { \u2026 }  

Arguments:

1. tokens: &[Token] - input token stream.
2. type_env: &mut TypeEnv - initial type environment.
3. debug_mode: bool - if `true`, emits enter/exit debug events.

Behavior:

• Builds a keyword_map of reserved words.
• Calls parse_s_expression to get raw AST and updates has_errors.
• Calls expand_parsed_s_expression to produce the final AST, dispatching to specialized parsers.
• Returns the final `Expression` and has_errors flag.

Current location: ./src/interpreter/executer/builtincommands

This source file implements detection and execution of built-in shell commands for the interpreter.

Differentiates shell-loop control flow and error handling.

Source: flowexecuter.rs

// differentiate shell-loop states
pub enum FlowState {
    FreeToMove,
    ErrorsOccured,
    Return(Type),
    Error {
        message: String,
        exp: Option<Expression>,
    },
    Exit,
}

Variants:

1. FreeToMove - ready for the next command.
2. ErrorsOccured - one or more errors have occurred, skip to error handler.
3. Return(Type) - a return from a function or script, carrying its Type
4. Error { message, exp } - runtime error with a message and optional Expression reference.
5. Exit - terminate the shell loop and exit.

Recursively reports all parse-time errors in an AST.

Source: flowexecuter.rs

fn report_all_parse_errors(
    parsed_exp: Expression,
) -> ()

Arguments:

1. parsed_exp: Expression - AST to inspect.

Behavior:

• On ExpressionType::Error(err), extracts line, column, location, and message then calls flow_report_error.
• On ExpressionType::List(items), recurses into each sub-expression.
• Ignores other.

Performs filesystem globbing on command arguments.

Source: flowexecuter.rs

fn expand_globs(
    args: Vec<String>
) -> Result<Vec<String>, String>

Arguments:

1. args: Vec<String> - raw argument strings.

Behavior:

• For each argument containing `*`, `?`, or `[`, uses glob(&arg).
• On matches, adds each paths string form.
• Returns Ok(expanded_args) on success.

Forks and executes an external command with redirection and optional piping.

Source: flowexecuter.rs

fn execute_command(
    name: &str,
    params: Vec<String>,
    redirect_stderr: Option<PathBuf>,
    redirect_stdout: Option<PathBuf>,
    redirect_stdin: Option<PathBuf>,
    mut prev_pipe_output: Option<Stdio>,
    pipe_stdout: bool,
) -> Result<io::Result<Child>, String>

Arguments:

1. name: &str - program to run.
2. params: Vec<String> - command-line arguments.
3. redirect_stderr: Option<PathBuf> - file for stderr.
4. redirect_stdout: Option<PathBuf> - file for stdout.
5. redirect_stdin: Option<PathBuf> - file for stdin.
6. prev_pipe_output: Option<Stdio> - upstream pipe as stdin.
7. pipe_stdout: bool - whether to pipe this processs stdout.

Behavior:

• Constructs Command::new(name).
• Sets up `stdin`, `stdout`, `stderr` based on redirection or piping.
• Appends arguments and spawns the child process.
• Returns nested `Result` to distinguish io errors and spawn errors.

Evaluates and executes a shell command AST node, handling built-ins, glob expansion, redirection, and pipelines.

Source: flowexecuter.rs

fn handle_command_execution(
    name: String,
    raw_params: Vec<String>,
    raw_redirect: Option<(RedirectionType, PathBuf)>,
    mut prev_pipe_output: Option<Stdio>,
    next_pipe: Option<Box<Expression>>,
    type_env: &mut TypeEnv,
) -> FlowState 

Arguments:

1. name: String - command identifier.
2. raw_params: Vec<String> - unexpanded argument patterns.
3. raw_redirect: Option<(RedirectionType, PathBuf)> - optional redirection.
4. prev_pipe_output: Option<Stdio> - pipe input from previous command.
5. next_pipe: Option<Box<Expression>> - AST for next piped command.
6. type_env: &mut TypeEnv - environment for var/envar lookup.

Behavior:

• Calls expand_globs.
• Detects built-in commands via is_built_in_command, dispatches to execute_built_in_command.
• Parses raw_redirect into separate stdin/stdout/stderr paths, errors on conflicts.
• Invokes execute_command, checks spawn and I/O errors
• If next_pipe exists, capture stdout, evaluate its parameters, and recurses into handle_command_execution.
• On success of command, returns FlowState::FreeToMove.

Recursively evaluates any `Expression`, returning a `FlowState`.

Source: flowexecuter.rs

fn eval_expression(
    parsed_exp: Expression,
    type_env: &mut TypeEnv,
) -> FlowState

Arguments:

1. parsed_exp: Expression - AST node to evaluate.
2. type_env: &mut TypeEnv - for variable and type lookups.

Behavior:

• Evaluates based on ExpressionType.
• Propagates errors as FlowState::Error.

Top-level entry: tokenizes, parses, reports errors, and evaluates a single input line.

Source: flowexecuter.rs

pub fn flow_interpret(
    line: &str,
    line_number: u32,
    type_env: &mut TypeEnv,
    debug_mode: bool
) -> FlowState 

Arguments:

1. line: &str - raw input text.
2. line_number: u32 - for error reporting.
3. type_env: &mut TypeEnv - current type environment.
4. debug_mode: bool - toggles debug tracing.

Behavior:

• Ignores lines starting with `;` (commends).
• Wraps non-parenthesized lines into (exec ({line})) form.
• Tokenizes via flow_tokenize, parses with flow_parse.
• On parse errors, calls report_all_parse_errors and returns ErrorsOccured.
• Otherwise, calls eval_expression, reports runtime errors.
• Returns the resulting `FlowState`.