diff --git a/crates/nu-protocol/src/alias.rs b/crates/nu-protocol/src/alias.rs index 8f5ea43934..701543c57b 100644 --- a/crates/nu-protocol/src/alias.rs +++ b/crates/nu-protocol/src/alias.rs @@ -4,10 +4,16 @@ use crate::{ PipelineData, ShellError, Signature, }; +/// Command wrapper of an alias. +/// +/// Our current aliases are implemented as wrapping commands +/// This has some limitations compared to text-substitution macro aliases but can reliably use more +/// of our machinery #[derive(Clone)] pub struct Alias { pub name: String, - pub command: Option>, // None if external call + /// Wrapped inner [`Command`]. `None` if alias of external call + pub command: Option>, pub wrapped_call: Expression, pub usage: String, pub extra_usage: String, diff --git a/crates/nu-protocol/src/ast/call.rs b/crates/nu-protocol/src/ast/call.rs index 6e8cc64a05..d26d0af300 100644 --- a/crates/nu-protocol/src/ast/call.rs +++ b/crates/nu-protocol/src/ast/call.rs @@ -7,12 +7,30 @@ use crate::{ ShellError, Span, Spanned, Value, }; +/// Parsed command arguments +/// +/// Primarily for internal commands #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum Argument { + /// A positional argument (that is not [`Argument::Spread`]) + /// + /// ```nushell + /// my_cmd positional + /// ``` Positional(Expression), + /// A named/flag argument that can optionally receive a [`Value`] as an [`Expression`] + /// + /// The optional second `Spanned` refers to the short-flag version if used + /// ```nushell + /// my_cmd --flag + /// my_cmd -f + /// my_cmd --flag-with-value + /// ``` Named((Spanned, Option>, Option)), - Unknown(Expression), // unknown argument used in "fall-through" signatures - Spread(Expression), // a list spread to fill in rest arguments + /// unknown argument used in "fall-through" signatures + Unknown(Expression), + /// a list spread to fill in rest arguments + Spread(Expression), } impl Argument { @@ -47,12 +65,24 @@ impl Argument { } } +/// Argument passed to an external command +/// +/// Here the parsing rules slightly differ to directly pass strings to the external process #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum ExternalArgument { + /// Expression that needs to be evaluated to turn into an external process argument Regular(Expression), + /// Occurrence of a `...` spread operator that needs to be expanded Spread(Expression), } +/// Parsed call of a `Command` +/// +/// As we also implement some internal keywords in terms of the `Command` trait, this type stores the passed arguments as [`Expression`]. +/// Some of its methods lazily evaluate those to [`Value`] while others return the underlying +/// [`Expression`]. +/// +/// For further utilities check the `nu_engine::CallExt` trait that extends [`Call`] #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct Call { /// identifier of the declaration to call diff --git a/crates/nu-protocol/src/ast/cell_path.rs b/crates/nu-protocol/src/ast/cell_path.rs index 3de37f3992..0880537557 100644 --- a/crates/nu-protocol/src/ast/cell_path.rs +++ b/crates/nu-protocol/src/ast/cell_path.rs @@ -3,16 +3,23 @@ use crate::Span; use serde::{Deserialize, Serialize}; use std::{cmp::Ordering, fmt::Display}; +/// One level of access of a [`CellPath`] #[derive(Debug, Clone, Serialize, Deserialize)] pub enum PathMember { + /// Accessing a member by string (i.e. columns of a table or [`Record`](crate::Record)) String { val: String, span: Span, + /// If marked as optional don't throw an error if not found but perform default handling + /// (e.g. return `Value::Nothing`) optional: bool, }, + /// Accessing a member by index (i.e. row of a table or item in a list) Int { val: usize, span: Span, + /// If marked as optional don't throw an error if not found but perform default handling + /// (e.g. return `Value::Nothing`) optional: bool, }, } @@ -143,6 +150,18 @@ impl PartialOrd for PathMember { } } +/// Represents the potentially nested access to fields/cells of a container type +/// +/// In our current implementation for table access the order of row/column is commutative. +/// This limits the number of possible rows to select in one [`CellPath`] to 1 as it could +/// otherwise be ambiguous +/// +/// ```nushell +/// col1.0 +/// 0.col1 +/// col2 +/// 42 +/// ``` #[derive(Debug, Clone, PartialEq, PartialOrd, Serialize, Deserialize)] pub struct CellPath { pub members: Vec, diff --git a/crates/nu-protocol/src/ast/expr.rs b/crates/nu-protocol/src/ast/expr.rs index 43548d39e4..fadbffc51f 100644 --- a/crates/nu-protocol/src/ast/expr.rs +++ b/crates/nu-protocol/src/ast/expr.rs @@ -9,6 +9,7 @@ use crate::{ ast::ImportPattern, engine::StateWorkingSet, BlockId, OutDest, Signature, Span, VarId, }; +/// An [`Expression`] AST node #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum Expr { Bool(bool), @@ -127,6 +128,7 @@ impl Expr { } } +/// Expressions permitted inside a record expression/literal #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum RecordItem { /// A key: val mapping @@ -135,6 +137,7 @@ pub enum RecordItem { Spread(Span, Expression), } +/// Expressions permitted inside a list expression/literal #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum ListItem { /// A normal expression diff --git a/crates/nu-protocol/src/ast/expression.rs b/crates/nu-protocol/src/ast/expression.rs index 906fce3fe1..dfd4187a90 100644 --- a/crates/nu-protocol/src/ast/expression.rs +++ b/crates/nu-protocol/src/ast/expression.rs @@ -6,6 +6,7 @@ use crate::{ use serde::{Deserialize, Serialize}; use std::sync::Arc; +/// Wrapper around [`Expr`] #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct Expression { pub expr: Expr, diff --git a/crates/nu-protocol/src/ast/import_pattern.rs b/crates/nu-protocol/src/ast/import_pattern.rs index 893dd9897b..ad08bfb2d1 100644 --- a/crates/nu-protocol/src/ast/import_pattern.rs +++ b/crates/nu-protocol/src/ast/import_pattern.rs @@ -3,10 +3,14 @@ use serde::{Deserialize, Serialize}; use crate::{ModuleId, Span, VarId}; use std::collections::HashSet; +/// possible patterns after the first module level in an [`ImportPattern`]. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub enum ImportPatternMember { + /// Wildcard import of items Glob { span: Span }, + /// single specific module or item Name { name: Vec, span: Span }, + /// list of items List { names: Vec<(Vec, Span)> }, } @@ -31,6 +35,7 @@ impl ImportPatternMember { } } +/// The first item of a `use` statement needs to specify an explicit module #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct ImportPatternHead { pub name: Vec, @@ -38,6 +43,7 @@ pub struct ImportPatternHead { pub span: Span, } +/// The pattern specifying modules in a `use` statement #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct ImportPattern { pub head: ImportPatternHead, diff --git a/crates/nu-protocol/src/ast/match_pattern.rs b/crates/nu-protocol/src/ast/match_pattern.rs index 1aafe84701..ca639270aa 100644 --- a/crates/nu-protocol/src/ast/match_pattern.rs +++ b/crates/nu-protocol/src/ast/match_pattern.rs @@ -2,6 +2,7 @@ use super::Expression; use crate::{Span, VarId}; use serde::{Deserialize, Serialize}; +/// AST Node for match arm with optional match guard #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct MatchPattern { pub pattern: Pattern, @@ -15,18 +16,28 @@ impl MatchPattern { } } +/// AST Node for pattern matching rules #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub enum Pattern { + /// Destructuring of records Record(Vec<(String, MatchPattern)>), + /// List destructuring List(Vec), + /// Matching against a literal // TODO: it would be nice if this didn't depend on AST // maybe const evaluation can get us to a Value instead? Value(Box), + /// binding to a variable Variable(VarId), + /// the `pattern1 \ pattern2` or-pattern Or(Vec), - Rest(VarId), // the ..$foo pattern - IgnoreRest, // the .. pattern - IgnoreValue, // the _ pattern + /// the `..$foo` pattern + Rest(VarId), + /// the `..` pattern + IgnoreRest, + /// the `_` pattern + IgnoreValue, + /// Failed parsing of a pattern Garbage, } diff --git a/crates/nu-protocol/src/ast/mod.rs b/crates/nu-protocol/src/ast/mod.rs index 7c627997fe..cb09168805 100644 --- a/crates/nu-protocol/src/ast/mod.rs +++ b/crates/nu-protocol/src/ast/mod.rs @@ -1,3 +1,4 @@ +//! Types representing parsed Nushell code (the Abstract Syntax Tree) mod block; mod call; mod cell_path; @@ -9,7 +10,7 @@ mod match_pattern; mod operator; mod pipeline; mod range; -pub mod table; +mod table; mod unit; mod value_with_unit; diff --git a/crates/nu-protocol/src/config/mod.rs b/crates/nu-protocol/src/config/mod.rs index e804e3f024..eda3d9a15e 100644 --- a/crates/nu-protocol/src/config/mod.rs +++ b/crates/nu-protocol/src/config/mod.rs @@ -1,3 +1,4 @@ +//! Module containing the internal representation of user configuration use self::completer::*; use self::helper::*; use self::hooks::*; diff --git a/crates/nu-protocol/src/debugger/mod.rs b/crates/nu-protocol/src/debugger/mod.rs index 03208fb3c7..86768a0a34 100644 --- a/crates/nu-protocol/src/debugger/mod.rs +++ b/crates/nu-protocol/src/debugger/mod.rs @@ -1,3 +1,4 @@ +//! Module containing the trait to instrument the engine for debugging and profiling pub mod debugger_trait; pub mod profiler; diff --git a/crates/nu-protocol/src/engine/mod.rs b/crates/nu-protocol/src/engine/mod.rs index 1b1762fe3c..39bb5a7ae3 100644 --- a/crates/nu-protocol/src/engine/mod.rs +++ b/crates/nu-protocol/src/engine/mod.rs @@ -1,3 +1,4 @@ +//! Representation of the engine state and many of the details that implement the scoping mod argument; mod cached_file; mod call; diff --git a/crates/nu-protocol/src/errors/cli_error.rs b/crates/nu-protocol/src/errors/cli_error.rs index 181839b948..c12c601c4d 100644 --- a/crates/nu-protocol/src/errors/cli_error.rs +++ b/crates/nu-protocol/src/errors/cli_error.rs @@ -1,3 +1,6 @@ +//! This module manages the step of turning error types into printed error messages +//! +//! Relies on the `miette` crate for pretty layout use crate::{ engine::{EngineState, StateWorkingSet}, ErrorStyle, diff --git a/crates/nu-protocol/src/eval_base.rs b/crates/nu-protocol/src/eval_base.rs index 7e1e2b0a7c..9c5878ee87 100644 --- a/crates/nu-protocol/src/eval_base.rs +++ b/crates/nu-protocol/src/eval_base.rs @@ -1,3 +1,4 @@ +//! Foundational [`Eval`] trait allowing dispatch between const-eval and regular evaluation use crate::{ ast::{ eval_operator, Assignment, Bits, Boolean, Call, Comparison, Expr, Expression, diff --git a/crates/nu-protocol/src/eval_const.rs b/crates/nu-protocol/src/eval_const.rs index 5393e35e59..da7570b43c 100644 --- a/crates/nu-protocol/src/eval_const.rs +++ b/crates/nu-protocol/src/eval_const.rs @@ -1,3 +1,7 @@ +//! Implementation of const-evaluation +//! +//! This enables you to assign `const`-constants and execute parse-time code dependent on this. +//! e.g. `source $my_const` use crate::{ ast::{Assignment, Block, Call, Expr, Expression, ExternalArgument}, debugger::{DebugContext, WithoutDebug}, diff --git a/crates/nu-protocol/src/pipeline/byte_stream.rs b/crates/nu-protocol/src/pipeline/byte_stream.rs index cd62b70801..69391b39a9 100644 --- a/crates/nu-protocol/src/pipeline/byte_stream.rs +++ b/crates/nu-protocol/src/pipeline/byte_stream.rs @@ -1,3 +1,4 @@ +//! Module managing the streaming of raw bytes between pipeline elements use crate::{ process::{ChildPipe, ChildProcess, ExitStatus}, ErrSpan, IntoSpanned, OutDest, PipelineData, ShellError, Signals, Span, Type, Value, diff --git a/crates/nu-protocol/src/pipeline/list_stream.rs b/crates/nu-protocol/src/pipeline/list_stream.rs index 104bab6bcc..55ae4bfee0 100644 --- a/crates/nu-protocol/src/pipeline/list_stream.rs +++ b/crates/nu-protocol/src/pipeline/list_stream.rs @@ -1,3 +1,7 @@ +//! Module managing the streaming of individual [`Value`]s as a [`ListStream`] between pipeline +//! elements +//! +//! For more general infos regarding our pipelining model refer to [`PipelineData`] use crate::{Config, PipelineData, ShellError, Signals, Span, Value}; use std::fmt::Debug; diff --git a/crates/nu-protocol/src/process/mod.rs b/crates/nu-protocol/src/process/mod.rs index 2fcf65f56e..6e10fdd620 100644 --- a/crates/nu-protocol/src/process/mod.rs +++ b/crates/nu-protocol/src/process/mod.rs @@ -1,3 +1,4 @@ +//! Handling of external subprocesses mod child; mod exit_status; diff --git a/crates/nu-protocol/src/signature.rs b/crates/nu-protocol/src/signature.rs index 3241b0df22..f8b83063d7 100644 --- a/crates/nu-protocol/src/signature.rs +++ b/crates/nu-protocol/src/signature.rs @@ -5,6 +5,7 @@ use crate::{ use serde::{Deserialize, Serialize}; use std::fmt::Write; +/// The signature definition of a named flag that either accepts a value or acts as a toggle flag #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct Flag { pub long: String, @@ -18,6 +19,7 @@ pub struct Flag { pub default_value: Option, } +/// The signature definition for a positional argument #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] pub struct PositionalArg { pub name: String, @@ -29,6 +31,7 @@ pub struct PositionalArg { pub default_value: Option, } +/// Command categories #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub enum Category { Bits, @@ -102,6 +105,7 @@ impl std::fmt::Display for Category { } } +/// Signature information of a [`Command`] #[derive(Clone, Debug, Serialize, Deserialize)] pub struct Signature { pub name: String, diff --git a/crates/nu-protocol/src/span.rs b/crates/nu-protocol/src/span.rs index f5bcebc543..cb6d96421c 100644 --- a/crates/nu-protocol/src/span.rs +++ b/crates/nu-protocol/src/span.rs @@ -1,3 +1,4 @@ +//! [`Span`] to point to sections of source code and the [`Spanned`] wrapper type use crate::SpanId; use miette::SourceSpan; use serde::{Deserialize, Serialize}; diff --git a/crates/nu-protocol/src/value/record.rs b/crates/nu-protocol/src/value/record.rs index 8b61e61f7f..f4e963737f 100644 --- a/crates/nu-protocol/src/value/record.rs +++ b/crates/nu-protocol/src/value/record.rs @@ -1,3 +1,4 @@ +//! Our insertion ordered map-type [`Record`] use std::{iter::FusedIterator, ops::RangeBounds}; use crate::{ShellError, Span, Value};