Add environment variable support for modules (#331)

* Add 'expor env' dummy command

* (WIP) Abstract away module exportables as Overlay

* Switch to Overlays for use/hide

Works for decls only right now.

* Fix passing import patterns of hide to eval

* Simplify use/hide of decls

* Add ImportPattern as Expr; Add use env eval

Still no parsing of "export env" so I can't test it yet.

* Refactor export parsing; Add InternalError

* Add env var export and activation; Misc changes

Now it is possible to `use` env var that was exported from a module.

This commit also adds some new errors and other small changes.

* Add env var hiding

* Fix eval not recognizing hidden decls

Without this change, calling `hide foo`, the evaluator does not know
whether a custom command named "foo" was hidden during parsing,
therefore, it is not possible to reliably throw an error about the "foo"
name not found.

* Add use/hide/export env var tests; Cleanup; Notes

* Ignore hide env related tests for now

* Fix main branch merge mess

* Fixed multi-word export def

* Fix hiding tests on Windows

* Remove env var hiding for now

crates/nu-command/src/core_commands/export.rs

@@ -0,0 +1,41 @@
+use nu_engine::get_full_help;
+use nu_protocol::{
+    ast::Call,
+    engine::{Command, EngineState, Stack},
+    IntoPipelineData, PipelineData, Signature, Value,
+};
+
+#[derive(Clone)]
+pub struct ExportCommand;
+
+impl Command for ExportCommand {
+    fn name(&self) -> &str {
+        "export"
+    }
+
+    fn signature(&self) -> Signature {
+        Signature::build("export")
+    }
+
+    fn usage(&self) -> &str {
+        "Export custom commands or environment variables from a module."
+    }
+
+    fn run(
+        &self,
+        engine_state: &EngineState,
+        _stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<nu_protocol::PipelineData, nu_protocol::ShellError> {
+        Ok(Value::String {
+            val: get_full_help(
+                &ExportCommand.signature(),
+                &ExportCommand.examples(),
+                engine_state,
+            ),
+            span: call.head,
+        }
+        .into_pipeline_data())
+    }
+}

crates/nu-command/src/core_commands/export_def.rs

@@ -16,7 +16,7 @@ impl Command for ExportDef {
 
     fn signature(&self) -> nu_protocol::Signature {
         Signature::build("export def")
-            .required("target", SyntaxShape::String, "definition name")
+            .required("name", SyntaxShape::String, "definition name")
             .required("params", SyntaxShape::Signature, "parameters")
             .required(
                 "block",

crates/nu-command/src/core_commands/export_env.rs

@@ -0,0 +1,41 @@
+use nu_protocol::ast::Call;
+use nu_protocol::engine::{Command, EngineState, Stack};
+use nu_protocol::{PipelineData, Signature, SyntaxShape};
+
+#[derive(Clone)]
+pub struct ExportEnv;
+
+impl Command for ExportEnv {
+    fn name(&self) -> &str {
+        "export env"
+    }
+
+    fn usage(&self) -> &str {
+        "Export a block from a module that will be evaluated as an environment variable when imported."
+    }
+
+    fn signature(&self) -> nu_protocol::Signature {
+        Signature::build("export env")
+            .required(
+                "name",
+                SyntaxShape::String,
+                "name of the environment variable",
+            )
+            .required(
+                "block",
+                SyntaxShape::Block(Some(vec![])),
+                "body of the environment variable definition",
+            )
+    }
+
+    fn run(
+        &self,
+        _engine_state: &EngineState,
+        _stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<nu_protocol::PipelineData, nu_protocol::ShellError> {
+        //TODO: Add the env to stack
+        Ok(PipelineData::new(call.head))
+    }
+}

crates/nu-command/src/core_commands/mod.rs

@@ -2,7 +2,9 @@ mod alias;
 mod def;
 mod do_;
 mod echo;
+mod export;
 mod export_def;
+mod export_env;
 mod for_;
 mod help;
 mod hide;
@@ -16,7 +18,9 @@ pub use alias::Alias;
 pub use def::Def;
 pub use do_::Do;
 pub use echo::Echo;
+pub use export::ExportCommand;
 pub use export_def::ExportDef;
+pub use export_env::ExportEnv;
 pub use for_::For;
 pub use help::Help;
 pub use hide::Hide;

crates/nu-command/src/core_commands/use_.rs

@@ -1,6 +1,7 @@
-use nu_protocol::ast::Call;
+use nu_engine::eval_block;
+use nu_protocol::ast::{Call, Expr, Expression, ImportPatternMember};
 use nu_protocol::engine::{Command, EngineState, Stack};
-use nu_protocol::{PipelineData, Signature, SyntaxShape};
+use nu_protocol::{PipelineData, ShellError, Signature, Span, SyntaxShape};
 
 #[derive(Clone)]
 pub struct Use;
@@ -20,11 +21,85 @@ impl Command for Use {
 
     fn run(
         &self,
-        _engine_state: &EngineState,
+        engine_state: &EngineState,
-        _stack: &mut Stack,
+        stack: &mut Stack,
         call: &Call,
         _input: PipelineData,
-    ) -> Result<nu_protocol::PipelineData, nu_protocol::ShellError> {
+    ) -> Result<PipelineData, ShellError> {
+        let import_pattern = if let Some(Expression {
+            expr: Expr::ImportPattern(pat),
+            ..
+        }) = call.positional.get(0)
+        {
+            pat
+        } else {
+            return Err(ShellError::InternalError(
+                "Got something else than import pattern".into(),
+            ));
+        };
+
+        if let Some(block_id) = engine_state.find_module(&import_pattern.head.name) {
+            let overlay = &engine_state.get_block(block_id).overlay;
+
+            let env_vars_to_use = if import_pattern.members.is_empty() {
+                overlay.env_vars_with_head(&import_pattern.head.name)
+            } else {
+                match &import_pattern.members[0] {
+                    ImportPatternMember::Glob { .. } => overlay.env_vars(),
+                    ImportPatternMember::Name { name, span } => {
+                        let mut output = vec![];
+
+                        if let Some(id) = overlay.get_env_var_id(name) {
+                            output.push((name.clone(), id));
+                        } else if !overlay.has_decl(name) {
+                            return Err(ShellError::EnvVarNotFoundAtRuntime(*span));
+                        }
+
+                        output
+                    }
+                    ImportPatternMember::List { names } => {
+                        let mut output = vec![];
+
+                        for (name, span) in names {
+                            if let Some(id) = overlay.get_env_var_id(name) {
+                                output.push((name.clone(), id));
+                            } else if !overlay.has_decl(name) {
+                                return Err(ShellError::EnvVarNotFoundAtRuntime(*span));
+                            }
+                        }
+
+                        output
+                    }
+                }
+            };
+
+            for (name, block_id) in env_vars_to_use {
+                let name = if let Ok(s) = String::from_utf8(name.clone()) {
+                    s
+                } else {
+                    return Err(ShellError::NonUtf8(import_pattern.head.span));
+                };
+
+                let block = engine_state.get_block(block_id);
+
+                // TODO: Add string conversions (e.g. int to string)
+                // TODO: Later expand env to take all Values
+                let val = if let Ok(s) =
+                    eval_block(engine_state, stack, block, PipelineData::new(call.head))?
+                        .into_value(Span::unknown())
+                        .as_string()
+                {
+                    s
+                } else {
+                    return Err(ShellError::EnvVarNotAString(import_pattern.span()));
+                };
+
+                stack.add_env_var(name, val);
+            }
+        } else {
+            return Err(ShellError::EnvVarNotFoundAtRuntime(call.positional[0].span));
+        }
+
         Ok(PipelineData::new(call.head))
     }
 }

crates/nu-command/src/default_context.rs

@@ -39,7 +39,9 @@ pub fn create_default_context() -> EngineState {
             Do,
             Each,
             Echo,
+            ExportCommand,
             ExportDef,
+            ExportEnv,
             External,
             First,
             For,

crates/nu-engine/src/eval.rs

@@ -225,6 +225,9 @@ pub fn eval_expression(
 
             value.follow_cell_path(&cell_path.tail)
         }
+        Expr::ImportPattern(_) => Ok(Value::Nothing {
+            span: Span::unknown(),
+        }),
         Expr::RowCondition(_, expr) => eval_expression(engine_state, stack, expr),
         Expr::Call(call) => {
             // FIXME: protect this collect with ctrl-c

crates/nu-parser/src/errors.rs

@@ -81,6 +81,10 @@ pub enum ParseError {
     #[diagnostic(code(nu::parser::module_not_found), url(docsrs))]
     ModuleNotFound(#[label = "module not found"] Span),
 
+    #[error("Not found.")]
+    #[diagnostic(code(nu::parser::not_found), url(docsrs))]
+    NotFound(#[label = "did not find anything under this name"] Span),
+
     #[error("Duplicate command definition within a block.")]
     #[diagnostic(code(nu::parser::duplicate_command_def), url(docsrs))]
     DuplicateCommandDef(#[label = "defined more than once"] Span),
@@ -141,6 +145,10 @@ pub enum ParseError {
     #[diagnostic(code(nu::parser::unknown_state), url(docsrs))]
     UnknownState(String, #[label("{0}")] Span),
 
+    #[error("Internal error.")]
+    #[diagnostic(code(nu::parser::unknown_state), url(docsrs))]
+    InternalError(String, #[label("{0}")] Span),
+
     #[error("Parser incomplete.")]
     #[diagnostic(code(nu::parser::parser_incomplete), url(docsrs))]
     IncompleteParser(#[label = "parser support missing for this expression"] Span),
@@ -175,7 +183,7 @@ pub enum ParseError {
     #[diagnostic(code(nu::parser::missing_import_pattern), url(docsrs))]
     WrongImportPattern(#[label = "invalid import pattern structure"] Span),
 
-    #[error("Module export not found.")]
+    #[error("Export not found.")]
     #[diagnostic(code(nu::parser::export_not_found), url(docsrs))]
     ExportNotFound(#[label = "could not find imports"] Span),
 

crates/nu-parser/src/flatten.rs

@@ -1,4 +1,6 @@
-use nu_protocol::ast::{Block, Expr, Expression, PathMember, Pipeline, Statement};
+use nu_protocol::ast::{
+    Block, Expr, Expression, ImportPatternMember, PathMember, Pipeline, Statement,
+};
 use nu_protocol::{engine::StateWorkingSet, Span};
 
 #[derive(Debug, Eq, PartialEq, Ord, PartialOrd)]
@@ -133,6 +135,25 @@ pub fn flatten_expression(
             }
             output
         }
+        Expr::ImportPattern(import_pattern) => {
+            let mut output = vec![(import_pattern.head.span, FlatShape::String)];
+
+            for member in &import_pattern.members {
+                match member {
+                    ImportPatternMember::Glob { span } => output.push((*span, FlatShape::String)),
+                    ImportPatternMember::Name { span, .. } => {
+                        output.push((*span, FlatShape::String))
+                    }
+                    ImportPatternMember::List { names } => {
+                        for (_, span) in names {
+                            output.push((*span, FlatShape::String));
+                        }
+                    }
+                }
+            }
+
+            output
+        }
         Expr::Range(from, next, to, op) => {
             let mut output = vec![];
             if let Some(f) = from {

crates/nu-parser/src/parse_keywords.rs

@@ -1,8 +1,12 @@
 use nu_protocol::{
-    ast::{Block, Call, Expr, Expression, ImportPattern, ImportPatternMember, Pipeline, Statement},
+    ast::{
+        Block, Call, Expr, Expression, ImportPattern, ImportPatternHead, ImportPatternMember,
+        Pipeline, Statement,
+    },
     engine::StateWorkingSet,
-    span, DeclId, Span, SyntaxShape, Type, CONFIG_VARIABLE_ID,
+    span, Exportable, Overlay, Span, SyntaxShape, Type, CONFIG_VARIABLE_ID,
 };
+use std::collections::HashMap;
 use std::path::Path;
 
 #[cfg(feature = "plugin")]
@@ -63,6 +67,7 @@ pub fn parse_def(
     let name = working_set.get_span_contents(spans[0]);
 
     if name == b"def" {
+        // TODO: Convert all 'expect("internal error: ...")' to ParseError::InternalError
         let def_decl_id = working_set
             .find_decl(b"def")
             .expect("internal error: missing def command");
@@ -113,10 +118,8 @@ pub fn parse_def(
                             *declaration = signature.into_block_command(block_id);
                         } else {
                             error = error.or_else(|| {
-                                // FIXME: add a variant to ParseError that represents internal errors
+                                Some(ParseError::InternalError(
-                                Some(ParseError::UnknownState(
+                                    "Predeclaration failed to add declaration".into(),
-                                    "Internal error: Predeclaration failed to add declaration"
-                                        .into(),
                                     spans[1],
                                 ))
                             });
@@ -238,8 +241,8 @@ pub fn parse_alias(
 
     (
         garbage_statement(spans),
-        Some(ParseError::UnknownState(
+        Some(ParseError::InternalError(
-            "internal error: alias statement unparseable".into(),
+            "Alias statement unparseable".into(),
             span(spans),
         )),
     )
@@ -248,66 +251,231 @@ pub fn parse_alias(
 pub fn parse_export(
     working_set: &mut StateWorkingSet,
     spans: &[Span],
-) -> (Statement, Option<ParseError>) {
+) -> (Statement, Option<Exportable>, Option<ParseError>) {
-    let bytes = working_set.get_span_contents(spans[0]);
+    let mut error = None;
 
-    if bytes == b"export" && spans.len() >= 3 {
+    let export_span = if let Some(sp) = spans.get(0) {
-        let export_name = working_set.get_span_contents(spans[1]);
+        if working_set.get_span_contents(*sp) != b"export" {
-
+            return (
-        match export_name {
-            b"def" => {
-                let (stmt, err) = parse_def(working_set, &spans[1..]);
-
-                let export_def_decl_id = working_set
-                    .find_decl(b"export def")
-                    .expect("internal error: missing 'export def' command");
-
-                // Trying to warp the 'def' call into the 'export def' in a very clumsy way
-                let stmt = if let Statement::Pipeline(ref pipe) = stmt {
-                    if !pipe.expressions.is_empty() {
-                        if let Expr::Call(ref call) = pipe.expressions[0].expr {
-                            let mut call = call.clone();
-
-                            call.head = span(&spans[0..=1]);
-                            call.decl_id = export_def_decl_id;
-
-                            Statement::Pipeline(Pipeline::from_vec(vec![Expression {
-                                expr: Expr::Call(call),
-                                span: span(spans),
-                                ty: Type::Unknown,
-                                custom_completion: None,
-                            }]))
-                        } else {
-                            stmt
-                        }
-                    } else {
-                        stmt
-                    }
-                } else {
-                    stmt
-                };
-
-                (stmt, err)
-            }
-            _ => (
                 garbage_statement(spans),
-                Some(ParseError::Expected(
+                None,
-                    // TODO: Fill in more as they come
+                Some(ParseError::UnknownState(
-                    "def keyword".into(),
+                    "expected export statement".into(),
-                    spans[1],
+                    span(spans),
                 )),
-            ),
+            );
         }
+
+        *sp
     } else {
-        (
+        return (
             garbage_statement(spans),
+            None,
             Some(ParseError::UnknownState(
-                // TODO: fill in more export types as they come
+                "got empty input for parsing export statement".into(),
-                "Expected structure: export def [] {}".into(),
                 span(spans),
             )),
-        )
+        );
-    }
+    };
+
+    let export_decl_id = if let Some(id) = working_set.find_decl(b"export") {
+        id
+    } else {
+        return (
+            garbage_statement(spans),
+            None,
+            Some(ParseError::InternalError(
+                "missing export command".into(),
+                export_span,
+            )),
+        );
+    };
+
+    let mut call = Box::new(Call {
+        head: spans[0],
+        decl_id: export_decl_id,
+        positional: vec![],
+        named: vec![],
+    });
+
+    let exportable = if let Some(kw_span) = spans.get(1) {
+        let kw_name = working_set.get_span_contents(*kw_span);
+        match kw_name {
+            b"def" => {
+                let (stmt, err) = parse_def(working_set, &spans[1..]);
+                error = error.or(err);
+
+                let export_def_decl_id = if let Some(id) = working_set.find_decl(b"export def") {
+                    id
+                } else {
+                    return (
+                        garbage_statement(spans),
+                        None,
+                        Some(ParseError::InternalError(
+                            "missing 'export def' command".into(),
+                            export_span,
+                        )),
+                    );
+                };
+
+                // Trying to warp the 'def' call into the 'export def' in a very clumsy way
+                if let Statement::Pipeline(ref pipe) = stmt {
+                    if let Some(Expression {
+                        expr: Expr::Call(ref def_call),
+                        ..
+                    }) = pipe.expressions.get(0)
+                    {
+                        call = def_call.clone();
+
+                        call.head = span(&spans[0..=1]);
+                        call.decl_id = export_def_decl_id;
+                    } else {
+                        error = error.or_else(|| {
+                            Some(ParseError::InternalError(
+                                "unexpected output from parsing a definition".into(),
+                                span(&spans[1..]),
+                            ))
+                        });
+                    }
+                } else {
+                    error = error.or_else(|| {
+                        Some(ParseError::InternalError(
+                            "unexpected output from parsing a definition".into(),
+                            span(&spans[1..]),
+                        ))
+                    });
+                };
+
+                if error.is_none() {
+                    let decl_name = working_set.get_span_contents(spans[2]);
+                    let decl_name = trim_quotes(decl_name);
+                    if let Some(decl_id) = working_set.find_decl(decl_name) {
+                        Some(Exportable::Decl(decl_id))
+                    } else {
+                        error = error.or_else(|| {
+                            Some(ParseError::InternalError(
+                                "failed to find added declaration".into(),
+                                span(&spans[1..]),
+                            ))
+                        });
+                        None
+                    }
+                } else {
+                    None
+                }
+            }
+            b"env" => {
+                if let Some(id) = working_set.find_decl(b"export env") {
+                    call.decl_id = id;
+                } else {
+                    return (
+                        garbage_statement(spans),
+                        None,
+                        Some(ParseError::InternalError(
+                            "missing 'export env' command".into(),
+                            export_span,
+                        )),
+                    );
+                }
+
+                call.head = span(&spans[0..=1]);
+
+                if let Some(name_span) = spans.get(2) {
+                    let (name_expr, err) = parse_string(working_set, *name_span);
+                    error = error.or(err);
+                    call.positional.push(name_expr);
+
+                    if let Some(block_span) = spans.get(3) {
+                        let (block_expr, err) = parse_block_expression(
+                            working_set,
+                            &SyntaxShape::Block(None),
+                            *block_span,
+                        );
+                        error = error.or(err);
+
+                        let exportable = if let Expression {
+                            expr: Expr::Block(block_id),
+                            ..
+                        } = block_expr
+                        {
+                            Some(Exportable::EnvVar(block_id))
+                        } else {
+                            error = error.or_else(|| {
+                                Some(ParseError::InternalError(
+                                    "block was not parsed as a block".into(),
+                                    *block_span,
+                                ))
+                            });
+                            None
+                        };
+
+                        call.positional.push(block_expr);
+
+                        exportable
+                    } else {
+                        let err_span = Span {
+                            start: name_span.end,
+                            end: name_span.end,
+                        };
+
+                        error = error.or_else(|| {
+                            Some(ParseError::MissingPositional("block".into(), err_span))
+                        });
+
+                        None
+                    }
+                } else {
+                    let err_span = Span {
+                        start: kw_span.end,
+                        end: kw_span.end,
+                    };
+
+                    error = error.or_else(|| {
+                        Some(ParseError::MissingPositional(
+                            "environment variable name".into(),
+                            err_span,
+                        ))
+                    });
+
+                    None
+                }
+            }
+            _ => {
+                error = error.or_else(|| {
+                    Some(ParseError::Expected(
+                        // TODO: Fill in more keywords as they come
+                        "def or env keyword".into(),
+                        spans[1],
+                    ))
+                });
+
+                None
+            }
+        }
+    } else {
+        error = error.or_else(|| {
+            Some(ParseError::MissingPositional(
+                "def or env keyword".into(), // TODO: keep filling more keywords as they come
+                Span {
+                    start: export_span.end,
+                    end: export_span.end,
+                },
+            ))
+        });
+
+        None
+    };
+
+    (
+        Statement::Pipeline(Pipeline::from_vec(vec![Expression {
+            expr: Expr::Call(call),
+            span: span(spans),
+            ty: Type::Unknown,
+            custom_completion: None,
+        }])),
+        exportable,
+        error,
+    )
 }
 
 pub fn parse_module_block(
@@ -327,12 +495,13 @@ pub fn parse_module_block(
     error = error.or(err);
 
     for pipeline in &output.block {
+        // TODO: Should we add export env predecls as well?
         if pipeline.commands.len() == 1 {
             parse_def_predecl(working_set, &pipeline.commands[0].parts);
         }
     }
 
-    let mut exports: Vec<(Vec<u8>, DeclId)> = vec![];
+    let mut overlay = Overlay::new();
 
     let block: Block = output
         .block
@@ -349,29 +518,40 @@ pub fn parse_module_block(
 
                         (stmt, err)
                     }
+                    // TODO: Currently, it is not possible to define a private env var.
+                    // TODO: Exported env vars are usable iside the module only if correctly
+                    // exported by the user. For example:
+                    //
+                    //   > module foo { export env a { "2" }; export def b [] { $nu.env.a } }
+                    //
+                    // will work only if you call `use foo *; b` but not with `use foo; foo b`
+                    // since in the second case, the name of the env var would be $nu.env."foo a".
                     b"export" => {
-                        let (stmt, err) = parse_export(working_set, &pipeline.commands[0].parts);
+                        let (stmt, exportable, err) =
+                            parse_export(working_set, &pipeline.commands[0].parts);
 
                         if err.is_none() {
-                            let decl_name =
+                            let name_span = pipeline.commands[0].parts[2];
-                                // parts[2] is safe since it's checked in parse_export already
+                            let name = working_set.get_span_contents(name_span);
-                                working_set.get_span_contents(pipeline.commands[0].parts[2]);
+                            let name = trim_quotes(name);
 
-                            let decl_name = trim_quotes(decl_name);
+                            match exportable {
-
+                                Some(Exportable::Decl(decl_id)) => {
-                            let decl_id = working_set
+                                    overlay.add_decl(name, decl_id);
-                                .find_decl(decl_name)
+                                }
-                                .expect("internal error: failed to find added declaration");
+                                Some(Exportable::EnvVar(block_id)) => {
-
+                                    overlay.add_env_var(name, block_id);
-                            exports.push((decl_name.into(), decl_id));
+                                }
+                                None => {} // None should always come with error from parse_export()
+                            }
                         }
 
                         (stmt, err)
                     }
                     _ => (
                         garbage_statement(&pipeline.commands[0].parts),
-                        Some(ParseError::Expected(
+                        Some(ParseError::UnexpectedKeyword(
-                            "def or export keyword".into(),
+                            "expected def or export keyword".into(),
                             pipeline.commands[0].parts[0],
                         )),
                     ),
@@ -391,7 +571,7 @@ pub fn parse_module_block(
 
     working_set.exit_scope();
 
-    (block.with_exports(exports), error)
+    (block.with_overlay(overlay), error)
 }
 
 pub fn parse_module(
@@ -488,10 +668,8 @@ pub fn parse_use(
     let bytes = working_set.get_span_contents(spans[0]);
 
     if bytes == b"use" && spans.len() >= 2 {
-        let mut import_pattern_exprs: Vec<Expression> = vec![];
         for span in spans[1..].iter() {
-            let (expr, err) = parse_string(working_set, *span);
+            let (_, err) = parse_string(working_set, *span);
-            import_pattern_exprs.push(expr);
             error = error.or(err);
         }
 
@@ -500,16 +678,16 @@ pub fn parse_use(
         let (import_pattern, err) = parse_import_pattern(working_set, &spans[1..]);
         error = error.or(err);
 
-        let (import_pattern, exports) =
+        let (import_pattern, overlay) =
-            if let Some(block_id) = working_set.find_module(&import_pattern.head) {
+            if let Some(block_id) = working_set.find_module(&import_pattern.head.name) {
                 (
                     import_pattern,
-                    working_set.get_block(block_id).exports.clone(),
+                    working_set.get_block(block_id).overlay.clone(),
                 )
             } else {
                 // TODO: Do not close over when loading module from file
                 // It could be a file
-                if let Ok(module_filename) = String::from_utf8(import_pattern.head) {
+                if let Ok(module_filename) = String::from_utf8(import_pattern.head.name) {
                     let module_path = Path::new(&module_filename);
                     let module_name = if let Some(stem) = module_path.file_stem() {
                         stem.to_string_lossy().to_string()
@@ -533,10 +711,13 @@ pub fn parse_use(
 
                         (
                             ImportPattern {
-                                head: module_name.into(),
+                                head: ImportPatternHead {
+                                    name: module_name.into(),
+                                    span: spans[1],
+                                },
                                 members: import_pattern.members,
                             },
-                            working_set.get_block(block_id).exports.clone(),
+                            working_set.get_block(block_id).overlay.clone(),
                         )
                     } else {
                         return (
@@ -552,42 +733,31 @@ pub fn parse_use(
                 }
             };
 
-        let exports = if import_pattern.members.is_empty() {
+        let decls_to_use = if import_pattern.members.is_empty() {
-            exports
+            overlay.decls_with_head(&import_pattern.head.name)
-                .into_iter()
-                .map(|(name, id)| {
-                    let mut new_name = import_pattern.head.to_vec();
-                    new_name.push(b' ');
-                    new_name.extend(&name);
-                    (new_name, id)
-                })
-                .collect()
         } else {
             match &import_pattern.members[0] {
-                ImportPatternMember::Glob { .. } => exports,
+                ImportPatternMember::Glob { .. } => overlay.decls(),
                 ImportPatternMember::Name { name, span } => {
-                    let new_exports: Vec<(Vec<u8>, usize)> =
+                    let mut output = vec![];
-                        exports.into_iter().filter(|x| &x.0 == name).collect();
 
-                    if new_exports.is_empty() {
+                    if let Some(id) = overlay.get_decl_id(name) {
+                        output.push((name.clone(), id));
+                    } else if !overlay.has_env_var(name) {
                         error = error.or(Some(ParseError::ExportNotFound(*span)))
                     }
 
-                    new_exports
+                    output
                 }
                 ImportPatternMember::List { names } => {
                     let mut output = vec![];
 
                     for (name, span) in names {
-                        let mut new_exports: Vec<(Vec<u8>, usize)> = exports
+                        if let Some(id) = overlay.get_decl_id(name) {
-                            .iter()
+                            output.push((name.clone(), id));
-                            .filter_map(|x| if &x.0 == name { Some(x.clone()) } else { None })
+                        } else if !overlay.has_env_var(name) {
-                            .collect();
+                            error = error.or(Some(ParseError::ExportNotFound(*span)));
-
+                            break;
-                        if new_exports.is_empty() {
-                            error = error.or(Some(ParseError::ExportNotFound(*span)))
-                        } else {
-                            output.append(&mut new_exports)
                         }
                     }
 
@@ -596,18 +766,25 @@ pub fn parse_use(
             }
         };
 
-        // Extend the current scope with the module's exports
+        // Extend the current scope with the module's overlay
-        working_set.activate_overlay(exports);
+        working_set.add_decls(decls_to_use);
 
         // Create the Use command call
         let use_decl_id = working_set
             .find_decl(b"use")
             .expect("internal error: missing use command");
 
+        let import_pattern_expr = Expression {
+            expr: Expr::ImportPattern(import_pattern),
+            span: span(&spans[1..]),
+            ty: Type::List(Box::new(Type::String)),
+            custom_completion: None,
+        };
+
         let call = Box::new(Call {
             head: spans[0],
             decl_id: use_decl_id,
-            positional: import_pattern_exprs,
+            positional: vec![import_pattern_expr],
             named: vec![],
         });
 
@@ -639,26 +816,37 @@ pub fn parse_hide(
     let bytes = working_set.get_span_contents(spans[0]);
 
     if bytes == b"hide" && spans.len() >= 2 {
-        let (name_expr, err) = parse_string(working_set, spans[1]);
+        for span in spans[1..].iter() {
-        error = error.or(err);
+            let (_, err) = parse_string(working_set, *span);
+            error = error.or(err);
+        }
 
         let (import_pattern, err) = parse_import_pattern(working_set, &spans[1..]);
         error = error.or(err);
 
-        let (is_module, exported_names): (bool, Vec<Vec<u8>>) =
+        let (is_module, overlay) =
-            if let Some(block_id) = working_set.find_module(&import_pattern.head) {
+            if let Some(block_id) = working_set.find_module(&import_pattern.head.name) {
-                (
+                (true, working_set.get_block(block_id).overlay.clone())
-                    true,
-                    working_set
-                        .get_block(block_id)
-                        .exports
-                        .iter()
-                        .map(|(name, _)| name.clone())
-                        .collect(),
-                )
             } else if import_pattern.members.is_empty() {
                 // The pattern head can be e.g. a function name, not just a module
-                (false, vec![import_pattern.head.clone()])
+                if let Some(id) = working_set.find_decl(&import_pattern.head.name) {
+                    let mut decls = HashMap::new();
+                    decls.insert(import_pattern.head.name.clone(), id);
+
+                    (
+                        false,
+                        Overlay {
+                            decls,
+                            env_vars: HashMap::new(),
+                        },
+                    )
+                } else {
+                    // TODO: Or it could be an env var
+                    return (
+                        garbage_statement(spans),
+                        Some(ParseError::ModuleNotFound(spans[1])),
+                    );
+                }
             } else {
                 return (
                     garbage_statement(spans),
@@ -667,68 +855,38 @@ pub fn parse_hide(
             };
 
         // This kind of inverts the import pattern matching found in parse_use()
-        let names_to_hide = if import_pattern.members.is_empty() {
+        let decls_to_hide = if import_pattern.members.is_empty() {
             if is_module {
-                exported_names
+                overlay.decls_with_head(&import_pattern.head.name)
-                    .into_iter()
-                    .map(|name| {
-                        let mut new_name = import_pattern.head.to_vec();
-                        new_name.push(b' ');
-                        new_name.extend(&name);
-                        new_name
-                    })
-                    .collect()
             } else {
-                exported_names
+                overlay.decls()
             }
         } else {
             match &import_pattern.members[0] {
-                ImportPatternMember::Glob { .. } => exported_names
+                ImportPatternMember::Glob { .. } => {
-                    .into_iter()
+                    overlay.decls_with_head(&import_pattern.head.name)
-                    .map(|name| {
+                }
-                        let mut new_name = import_pattern.head.to_vec();
-                        new_name.push(b' ');
-                        new_name.extend(&name);
-                        new_name
-                    })
-                    .collect(),
                 ImportPatternMember::Name { name, span } => {
-                    let new_exports: Vec<Vec<u8>> = exported_names
+                    let mut output = vec![];
-                        .into_iter()
-                        .filter(|n| n == name)
-                        .map(|n| {
-                            let mut new_name = import_pattern.head.to_vec();
-                            new_name.push(b' ');
-                            new_name.extend(&n);
-                            new_name
-                        })
-                        .collect();
 
-                    if new_exports.is_empty() {
+                    if let Some(item) = overlay.decl_with_head(name, &import_pattern.head.name) {
-                        error = error.or(Some(ParseError::ExportNotFound(*span)))
+                        output.push(item);
+                    } else if !overlay.has_env_var(name) {
+                        error = error.or(Some(ParseError::ExportNotFound(*span)));
                     }
 
-                    new_exports
+                    output
                 }
                 ImportPatternMember::List { names } => {
                     let mut output = vec![];
 
                     for (name, span) in names {
-                        let mut new_exports: Vec<Vec<u8>> = exported_names
+                        if let Some(item) = overlay.decl_with_head(name, &import_pattern.head.name)
-                            .iter()
+                        {
-                            .filter_map(|n| if n == name { Some(n.clone()) } else { None })
+                            output.push(item);
-                            .map(|n| {
+                        } else if !overlay.has_env_var(name) {
-                                let mut new_name = import_pattern.head.to_vec();
+                            error = error.or(Some(ParseError::ExportNotFound(*span)));
-                                new_name.push(b' ');
+                            break;
-                                new_name.extend(n);
-                                new_name
-                            })
-                            .collect();
-
-                        if new_exports.is_empty() {
-                            error = error.or(Some(ParseError::ExportNotFound(*span)))
-                        } else {
-                            output.append(&mut new_exports)
                         }
                     }
 
@@ -737,23 +895,26 @@ pub fn parse_hide(
             }
         };
 
-        for name in names_to_hide {
+        // TODO: `use spam; use spam foo; hide foo` will hide both `foo` and `spam foo` since
-            // TODO: `use spam; use spam foo; hide foo` will hide both `foo` and `spam foo` since
+        // they point to the same DeclId. Do we want to keep it that way?
-            // they point to the same DeclId. Do we want to keep it that way?
+        working_set.hide_decls(&decls_to_hide);
-            if working_set.hide_decl(&name).is_none() {
-                error = error.or_else(|| Some(ParseError::UnknownCommand(spans[1])));
-            }
-        }
 
         // Create the Hide command call
         let hide_decl_id = working_set
             .find_decl(b"hide")
             .expect("internal error: missing hide command");
 
+        let import_pattern_expr = Expression {
+            expr: Expr::ImportPattern(import_pattern),
+            span: span(&spans[1..]),
+            ty: Type::List(Box::new(Type::String)),
+            custom_completion: None,
+        };
+
         let call = Box::new(Call {
             head: spans[0],
             decl_id: hide_decl_id,
-            positional: vec![name_expr],
+            positional: vec![import_pattern_expr],
             named: vec![],
         });
 

crates/nu-parser/src/parser.rs

@@ -7,8 +7,9 @@ use crate::{
 
 use nu_protocol::{
     ast::{
-        Block, Call, CellPath, Expr, Expression, FullCellPath, ImportPattern, ImportPatternMember,
+        Block, Call, CellPath, Expr, Expression, FullCellPath, ImportPattern, ImportPatternHead,
-        Operator, PathMember, Pipeline, RangeInclusion, RangeOperator, Statement,
+        ImportPatternMember, Operator, PathMember, Pipeline, RangeInclusion, RangeOperator,
+        Statement,
     },
     engine::StateWorkingSet,
     span, Flag, PositionalArg, Signature, Span, Spanned, SyntaxShape, Type, Unit, VarId,
@@ -1788,12 +1789,18 @@ pub fn parse_import_pattern(
 ) -> (ImportPattern, Option<ParseError>) {
     let mut error = None;
 
-    let head = if let Some(head_span) = spans.get(0) {
+    let (head, head_span) = if let Some(head_span) = spans.get(0) {
-        working_set.get_span_contents(*head_span).to_vec()
+        (
+            working_set.get_span_contents(*head_span).to_vec(),
+            head_span,
+        )
     } else {
         return (
             ImportPattern {
-                head: vec![],
+                head: ImportPatternHead {
+                    name: vec![],
+                    span: Span::unknown(),
+                },
                 members: vec![],
             },
             Some(ParseError::WrongImportPattern(span(spans))),
@@ -1806,7 +1813,10 @@ pub fn parse_import_pattern(
         if tail == b"*" {
             (
                 ImportPattern {
-                    head,
+                    head: ImportPatternHead {
+                        name: head,
+                        span: *head_span,
+                    },
                     members: vec![ImportPatternMember::Glob { span: *tail_span }],
                 },
                 error,
@@ -1830,7 +1840,10 @@ pub fn parse_import_pattern(
 
                     (
                         ImportPattern {
-                            head,
+                            head: ImportPatternHead {
+                                name: head,
+                                span: *head_span,
+                            },
                             members: vec![ImportPatternMember::List { names: output }],
                         },
                         error,
@@ -1838,7 +1851,10 @@ pub fn parse_import_pattern(
                 }
                 _ => (
                     ImportPattern {
-                        head,
+                        head: ImportPatternHead {
+                            name: head,
+                            span: *head_span,
+                        },
                         members: vec![],
                     },
                     Some(ParseError::ExportNotFound(result.span)),
@@ -1848,7 +1864,10 @@ pub fn parse_import_pattern(
             let tail = trim_quotes(tail);
             (
                 ImportPattern {
-                    head,
+                    head: ImportPatternHead {
+                        name: head,
+                        span: *head_span,
+                    },
                     members: vec![ImportPatternMember::Name {
                         name: tail.to_vec(),
                         span: *tail_span,
@@ -1860,7 +1879,10 @@ pub fn parse_import_pattern(
     } else {
         (
             ImportPattern {
-                head,
+                head: ImportPatternHead {
+                    name: head,
+                    span: *head_span,
+                },
                 members: vec![],
             },
             None,
@@ -3419,6 +3441,7 @@ pub fn find_captures_in_expr(
             let result = find_captures_in_expr(working_set, &cell_path.head, seen);
             output.extend(&result);
         }
+        Expr::ImportPattern(_) => {}
         Expr::Garbage => {}
         Expr::GlobPattern(_) => {}
         Expr::Int(_) => {}

crates/nu-protocol/src/ast/block.rs

@@ -1,6 +1,6 @@
 use std::ops::{Index, IndexMut};
 
-use crate::{DeclId, Signature, VarId};
+use crate::{Overlay, Signature, VarId};
 
 use super::Statement;
 
@@ -8,7 +8,7 @@ use super::Statement;
 pub struct Block {
     pub signature: Box<Signature>,
     pub stmts: Vec<Statement>,
-    pub exports: Vec<(Vec<u8>, DeclId)>, // Assuming just defs for now
+    pub overlay: Overlay,
     pub captures: Vec<VarId>,
 }
 
@@ -47,16 +47,16 @@ impl Block {
         Self {
             signature: Box::new(Signature::new("")),
             stmts: vec![],
-            exports: vec![],
+            overlay: Overlay::new(),
             captures: vec![],
         }
     }
 
-    pub fn with_exports(self, exports: Vec<(Vec<u8>, DeclId)>) -> Self {
+    pub fn with_overlay(self, overlay: Overlay) -> Self {
         Self {
             signature: self.signature,
             stmts: self.stmts,
-            exports,
+            overlay,
             captures: self.captures,
         }
     }
@@ -70,7 +70,7 @@ where
         Self {
             signature: Box::new(Signature::new("")),
             stmts: stmts.collect(),
-            exports: vec![],
+            overlay: Overlay::new(),
             captures: vec![],
         }
     }

crates/nu-protocol/src/ast/expr.rs

@@ -1,5 +1,5 @@
 use super::{Call, CellPath, Expression, FullCellPath, Operator, RangeOperator};
-use crate::{BlockId, Signature, Span, Spanned, Unit, VarId};
+use crate::{ast::ImportPattern, BlockId, Signature, Span, Spanned, Unit, VarId};
 
 #[derive(Debug, Clone)]
 pub enum Expr {
@@ -31,6 +31,7 @@ pub enum Expr {
     String(String),
     CellPath(CellPath),
     FullCellPath(Box<FullCellPath>),
+    ImportPattern(ImportPattern),
     Signature(Box<Signature>),
     Garbage,
 }

crates/nu-protocol/src/ast/expression.rs

@@ -131,6 +131,7 @@ impl Expression {
                 }
                 false
             }
+            Expr::ImportPattern(_) => false,
             Expr::Filepath(_) => false,
             Expr::Float(_) => false,
             Expr::FullCellPath(full_cell_path) => {
@@ -282,6 +283,7 @@ impl Expression {
                     .head
                     .replace_in_variable(working_set, new_var_id);
             }
+            Expr::ImportPattern(_) => {}
             Expr::Garbage => {}
             Expr::GlobPattern(_) => {}
             Expr::Int(_) => {}

crates/nu-protocol/src/ast/import_pattern.rs

@@ -1,4 +1,4 @@
-use crate::Span;
+use crate::{span, Span};
 
 #[derive(Debug, Clone)]
 pub enum ImportPatternMember {
@@ -7,8 +7,34 @@ pub enum ImportPatternMember {
     List { names: Vec<(Vec<u8>, Span)> },
 }
 
+#[derive(Debug, Clone)]
+pub struct ImportPatternHead {
+    pub name: Vec<u8>,
+    pub span: Span,
+}
+
 #[derive(Debug, Clone)]
 pub struct ImportPattern {
-    pub head: Vec<u8>,
+    pub head: ImportPatternHead,
     pub members: Vec<ImportPatternMember>,
 }
+
+impl ImportPattern {
+    pub fn span(&self) -> Span {
+        let mut spans = vec![self.head.span];
+
+        for member in &self.members {
+            match member {
+                ImportPatternMember::Glob { span } => spans.push(*span),
+                ImportPatternMember::Name { name: _, span } => spans.push(*span),
+                ImportPatternMember::List { names } => {
+                    for (_, span) in names {
+                        spans.push(*span);
+                    }
+                }
+            }
+        }
+
+        span(&spans)
+    }
+}

crates/nu-protocol/src/engine/engine_state.rs

@@ -7,41 +7,41 @@ use std::{
 };
 
 // Tells whether a decl etc. is visible or not
-// TODO: When adding new exportables (env vars, aliases, etc.), parametrize the ID type with generics
 #[derive(Debug, Clone)]
 struct Visibility {
-    ids: HashMap<DeclId, bool>,
+    decl_ids: HashMap<DeclId, bool>,
 }
 
 impl Visibility {
     fn new() -> Self {
         Visibility {
-            ids: HashMap::new(),
+            decl_ids: HashMap::new(),
         }
     }
 
-    fn is_id_visible(&self, id: &DeclId) -> bool {
+    fn is_decl_id_visible(&self, decl_id: &DeclId) -> bool {
-        *self.ids.get(id).unwrap_or(&true) // by default it's visible
+        *self.decl_ids.get(decl_id).unwrap_or(&true) // by default it's visible
     }
 
-    fn hide_id(&mut self, id: &DeclId) {
+    fn hide_decl_id(&mut self, decl_id: &DeclId) {
-        self.ids.insert(*id, false);
+        self.decl_ids.insert(*decl_id, false);
     }
 
-    fn use_id(&mut self, id: &DeclId) {
+    fn use_decl_id(&mut self, decl_id: &DeclId) {
-        self.ids.insert(*id, true);
+        self.decl_ids.insert(*decl_id, true);
     }
 
     fn merge_with(&mut self, other: Visibility) {
         // overwrite own values with the other
-        self.ids.extend(other.ids);
+        self.decl_ids.extend(other.decl_ids);
+        // self.env_var_ids.extend(other.env_var_ids);
     }
 
     fn append(&mut self, other: &Visibility) {
         // take new values from other but keep own values
-        for (id, visible) in other.ids.iter() {
+        for (decl_id, visible) in other.decl_ids.iter() {
-            if !self.ids.contains_key(id) {
+            if !self.decl_ids.contains_key(decl_id) {
-                self.ids.insert(*id, *visible);
+                self.decl_ids.insert(*decl_id, *visible);
             }
         }
     }
@@ -53,6 +53,7 @@ pub struct ScopeFrame {
     predecls: HashMap<Vec<u8>, DeclId>, // temporary storage for predeclarations
     pub decls: HashMap<Vec<u8>, DeclId>,
     pub aliases: HashMap<Vec<u8>, Vec<Span>>,
+    pub env_vars: HashMap<Vec<u8>, BlockId>,
     pub modules: HashMap<Vec<u8>, BlockId>,
     visibility: Visibility,
 }
@@ -64,6 +65,7 @@ impl ScopeFrame {
             predecls: HashMap::new(),
             decls: HashMap::new(),
             aliases: HashMap::new(),
+            env_vars: HashMap::new(),
             modules: HashMap::new(),
             visibility: Visibility::new(),
         }
@@ -232,7 +234,7 @@ impl EngineState {
             visibility.append(&scope.visibility);
 
             if let Some(decl_id) = scope.decls.get(name) {
-                if visibility.is_id_visible(decl_id) {
+                if visibility.is_decl_id_visible(decl_id) {
                     return Some(*decl_id);
                 }
             }
@@ -241,6 +243,16 @@ impl EngineState {
         None
     }
 
+    pub fn find_module(&self, name: &[u8]) -> Option<BlockId> {
+        for scope in self.scope.iter().rev() {
+            if let Some(block_id) = scope.modules.get(name) {
+                return Some(*block_id);
+            }
+        }
+
+        None
+    }
+
     pub fn find_commands_by_prefix(&self, name: &[u8]) -> Vec<Vec<u8>> {
         let mut output = vec![];
 
@@ -457,11 +469,24 @@ impl<'a> StateWorkingSet<'a> {
             .expect("internal error: missing required scope frame");
 
         scope_frame.decls.insert(name, decl_id);
-        scope_frame.visibility.use_id(&decl_id);
+        scope_frame.visibility.use_decl_id(&decl_id);
 
         decl_id
     }
 
+    pub fn add_decls(&mut self, decls: Vec<(Vec<u8>, DeclId)>) {
+        let scope_frame = self
+            .delta
+            .scope
+            .last_mut()
+            .expect("internal error: missing required scope frame");
+
+        for (name, decl_id) in decls {
+            scope_frame.decls.insert(name, decl_id);
+            scope_frame.visibility.use_decl_id(&decl_id);
+        }
+    }
+
     pub fn add_predecl(&mut self, decl: Box<dyn Command>) -> Option<DeclId> {
         let name = decl.name().as_bytes().to_vec();
 
@@ -486,7 +511,7 @@ impl<'a> StateWorkingSet<'a> {
 
         if let Some(decl_id) = scope_frame.predecls.remove(name) {
             scope_frame.decls.insert(name.into(), decl_id);
-            scope_frame.visibility.use_id(&decl_id);
+            scope_frame.visibility.use_decl_id(&decl_id);
 
             return Some(decl_id);
         }
@@ -517,9 +542,9 @@ impl<'a> StateWorkingSet<'a> {
             visibility.append(&scope.visibility);
 
             if let Some(decl_id) = scope.decls.get(name) {
-                if visibility.is_id_visible(decl_id) {
+                if visibility.is_decl_id_visible(decl_id) {
                     // Hide decl only if it's not already hidden
-                    last_scope_frame.visibility.hide_id(decl_id);
+                    last_scope_frame.visibility.hide_decl_id(decl_id);
                     return Some(*decl_id);
                 }
             }
@@ -528,12 +553,34 @@ impl<'a> StateWorkingSet<'a> {
         None
     }
 
+    pub fn hide_decls(&mut self, decls: &[(Vec<u8>, DeclId)]) {
+        for decl in decls.iter() {
+            self.hide_decl(&decl.0); // let's assume no errors
+        }
+    }
+
     pub fn add_block(&mut self, block: Block) -> BlockId {
         self.delta.blocks.push(block);
 
         self.num_blocks() - 1
     }
 
+    pub fn add_env_var(&mut self, name_span: Span, block: Block) -> BlockId {
+        self.delta.blocks.push(block);
+        let block_id = self.num_blocks() - 1;
+        let name = self.get_span_contents(name_span).to_vec();
+
+        let scope_frame = self
+            .delta
+            .scope
+            .last_mut()
+            .expect("internal error: missing required scope frame");
+
+        scope_frame.env_vars.insert(name, block_id);
+
+        block_id
+    }
+
     pub fn add_module(&mut self, name: &str, block: Block) -> BlockId {
         let name = name.as_bytes().to_vec();
 
@@ -551,19 +598,6 @@ impl<'a> StateWorkingSet<'a> {
         block_id
     }
 
-    pub fn activate_overlay(&mut self, overlay: Vec<(Vec<u8>, DeclId)>) {
-        let scope_frame = self
-            .delta
-            .scope
-            .last_mut()
-            .expect("internal error: missing required scope frame");
-
-        for (name, decl_id) in overlay {
-            scope_frame.decls.insert(name, decl_id);
-            scope_frame.visibility.use_id(&decl_id);
-        }
-    }
-
     pub fn next_span_start(&self) -> usize {
         let permanent_span_start = self.permanent_state.next_span_start();
 
@@ -665,7 +699,7 @@ impl<'a> StateWorkingSet<'a> {
             visibility.append(&scope.visibility);
 
             if let Some(decl_id) = scope.decls.get(name) {
-                if visibility.is_id_visible(decl_id) {
+                if visibility.is_decl_id_visible(decl_id) {
                     return Some(*decl_id);
                 }
             }

crates/nu-protocol/src/engine/stack.rs

@@ -38,6 +38,7 @@ impl Stack {
             env_vars: HashMap::new(),
         }
     }
+
     pub fn get_var(&self, var_id: VarId) -> Result<Value, ShellError> {
         if let Some(v) = self.vars.get(&var_id) {
             return Ok(v.clone());
@@ -87,6 +88,10 @@ impl Stack {
         None
     }
 
+    pub fn remove_env_var(&mut self, name: &str) -> Option<String> {
+        self.env_vars.remove(name)
+    }
+
     pub fn get_config(&self) -> Result<Config, ShellError> {
         let config = self.get_var(CONFIG_VARIABLE_ID);
 

crates/nu-protocol/src/exportable.rs

@@ -0,0 +1,6 @@
+use crate::{BlockId, DeclId};
+
+pub enum Exportable {
+    Decl(DeclId),
+    EnvVar(BlockId),
+}

crates/nu-protocol/src/lib.rs

@@ -2,7 +2,9 @@ pub mod ast;
 mod config;
 pub mod engine;
 mod example;
+mod exportable;
 mod id;
+mod overlay;
 mod pipeline_data;
 mod shell_error;
 mod signature;
@@ -15,7 +17,9 @@ pub use value::Value;
 pub use config::*;
 pub use engine::{CONFIG_VARIABLE_ID, IN_VARIABLE_ID, NU_VARIABLE_ID, SCOPE_VARIABLE_ID};
 pub use example::*;
+pub use exportable::*;
 pub use id::*;
+pub use overlay::*;
 pub use pipeline_data::*;
 pub use shell_error::*;
 pub use signature::*;

crates/nu-protocol/src/overlay.rs

@@ -0,0 +1,121 @@
+use crate::{BlockId, DeclId};
+
+use std::collections::HashMap;
+
+// TODO: Move the import pattern matching logic here from use/hide commands and
+// parse_use/parse_hide
+
+/// Collection of definitions that can be exported from a module
+#[derive(Debug, Clone)]
+pub struct Overlay {
+    pub decls: HashMap<Vec<u8>, DeclId>,
+    pub env_vars: HashMap<Vec<u8>, BlockId>,
+}
+
+impl Overlay {
+    pub fn new() -> Self {
+        Overlay {
+            decls: HashMap::new(),
+            env_vars: HashMap::new(),
+        }
+    }
+
+    pub fn add_decl(&mut self, name: &[u8], decl_id: DeclId) -> Option<DeclId> {
+        self.decls.insert(name.to_vec(), decl_id)
+    }
+
+    pub fn add_env_var(&mut self, name: &[u8], block_id: BlockId) -> Option<BlockId> {
+        self.env_vars.insert(name.to_vec(), block_id)
+    }
+
+    pub fn extend(&mut self, other: &Overlay) {
+        self.decls.extend(other.decls.clone());
+        self.env_vars.extend(other.env_vars.clone());
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.decls.is_empty() && self.env_vars.is_empty()
+    }
+
+    pub fn get_decl_id(&self, name: &[u8]) -> Option<DeclId> {
+        self.decls.get(name).copied()
+    }
+
+    pub fn has_decl(&self, name: &[u8]) -> bool {
+        self.decls.contains_key(name)
+    }
+
+    pub fn decl_with_head(&self, name: &[u8], head: &[u8]) -> Option<(Vec<u8>, DeclId)> {
+        if let Some(id) = self.get_decl_id(name) {
+            let mut new_name = head.to_vec();
+            new_name.push(b' ');
+            new_name.extend(name);
+            Some((new_name, id))
+        } else {
+            None
+        }
+    }
+
+    pub fn decls_with_head(&self, head: &[u8]) -> Vec<(Vec<u8>, DeclId)> {
+        self.decls
+            .iter()
+            .map(|(name, id)| {
+                let mut new_name = head.to_vec();
+                new_name.push(b' ');
+                new_name.extend(name);
+                (new_name, *id)
+            })
+            .collect()
+    }
+
+    pub fn decls(&self) -> Vec<(Vec<u8>, DeclId)> {
+        self.decls
+            .iter()
+            .map(|(name, id)| (name.clone(), *id))
+            .collect()
+    }
+
+    pub fn get_env_var_id(&self, name: &[u8]) -> Option<BlockId> {
+        self.env_vars.get(name).copied()
+    }
+
+    pub fn has_env_var(&self, name: &[u8]) -> bool {
+        self.env_vars.contains_key(name)
+    }
+
+    pub fn env_var_with_head(&self, name: &[u8], head: &[u8]) -> Option<(Vec<u8>, BlockId)> {
+        if let Some(id) = self.get_env_var_id(name) {
+            let mut new_name = head.to_vec();
+            new_name.push(b' ');
+            new_name.extend(name);
+            Some((new_name, id))
+        } else {
+            None
+        }
+    }
+
+    pub fn env_vars_with_head(&self, head: &[u8]) -> Vec<(Vec<u8>, BlockId)> {
+        self.env_vars
+            .iter()
+            .map(|(name, id)| {
+                let mut new_name = head.to_vec();
+                new_name.push(b' ');
+                new_name.extend(name);
+                (new_name, *id)
+            })
+            .collect()
+    }
+
+    pub fn env_vars(&self) -> Vec<(Vec<u8>, BlockId)> {
+        self.env_vars
+            .iter()
+            .map(|(name, id)| (name.clone(), *id))
+            .collect()
+    }
+}
+
+impl Default for Overlay {
+    fn default() -> Self {
+        Self::new()
+    }
+}

crates/nu-protocol/src/shell_error.rs

@@ -84,6 +84,18 @@ pub enum ShellError {
     #[diagnostic(code(nu::shell::variable_not_found), url(docsrs))]
     VariableNotFoundAtRuntime(#[label = "variable not found"] Span),
 
+    #[error("Environment variable not found")]
+    #[diagnostic(code(nu::shell::variable_not_found), url(docsrs))]
+    EnvVarNotFoundAtRuntime(#[label = "environment variable not found"] Span),
+
+    #[error("Environment variable is not a string")]
+    #[diagnostic(code(nu::shell::variable_not_found), url(docsrs))]
+    EnvVarNotAString(#[label = "does not evaluate to a string"] Span),
+
+    #[error("Not found.")]
+    #[diagnostic(code(nu::parser::not_found), url(docsrs))]
+    NotFound(#[label = "did not find anything under this name"] Span),
+
     #[error("Can't convert to {0}.")]
     #[diagnostic(code(nu::shell::cant_convert), url(docsrs))]
     CantConvert(String, String, #[label("can't convert {1} to {0}")] Span),
@@ -190,6 +202,10 @@ pub enum ShellError {
     #[error("Name not found")]
     #[diagnostic(code(nu::shell::name_not_found), url(docsrs))]
     DidYouMean(String, #[label("did you mean '{0}'?")] Span),
+
+    #[error("Non-UTF8 string.")]
+    #[diagnostic(code(nu::parser::non_utf8), url(docsrs))]
+    NonUtf8(#[label = "non-UTF8 string"] Span),
 }
 
 impl From<std::io::Error> for ShellError {

src/tests.rs

@@ -395,7 +395,7 @@ fn better_block_types() -> TestResult {
 }
 
 #[test]
-fn module_imports_1() -> TestResult {
+fn module_def_imports_1() -> TestResult {
     run_test(
         r#"module foo { export def a [] { 1 }; def b [] { 2 } }; use foo; foo a"#,
         "1",
@@ -403,7 +403,7 @@ fn module_imports_1() -> TestResult {
 }
 
 #[test]
-fn module_imports_2() -> TestResult {
+fn module_def_imports_2() -> TestResult {
     run_test(
         r#"module foo { export def a [] { 1 }; def b [] { 2 } }; use foo a; a"#,
         "1",
@@ -411,7 +411,7 @@ fn module_imports_2() -> TestResult {
 }
 
 #[test]
-fn module_imports_3() -> TestResult {
+fn module_def_imports_3() -> TestResult {
     run_test(
         r#"module foo { export def a [] { 1 }; export def b [] { 2 } }; use foo *; b"#,
         "2",
@@ -419,7 +419,7 @@ fn module_imports_3() -> TestResult {
 }
 
 #[test]
-fn module_imports_4() -> TestResult {
+fn module_def_imports_4() -> TestResult {
     fail_test(
         r#"module foo { export def a [] { 1 }; export def b [] { 2 } }; use foo c"#,
         "not find import",
@@ -427,35 +427,101 @@ fn module_imports_4() -> TestResult {
 }
 
 #[test]
-fn module_imports_5() -> TestResult {
+fn module_def_imports_5() -> TestResult {
     run_test(
-        r#"module foo { export def a [] { 1 }; def b [] { 2 }; export def c [] { 3 } }; use foo [a, c]; c"#,
+        r#"module foo { export def a [] { 1 }; def b [] { '2' }; export def c [] { '3' } }; use foo [a, c]; c"#,
         "3",
     )
 }
 
 #[test]
-fn module_import_uses_internal_command() -> TestResult {
+fn module_env_imports_1() -> TestResult {
+    run_test(
+        r#"module foo { export env a { '1' } }; use foo; $nu.env.'foo a'"#,
+        "1",
+    )
+}
+
+#[test]
+fn module_env_imports_2() -> TestResult {
+    run_test(
+        r#"module foo { export env a { '1' } }; use foo a; $nu.env.a"#,
+        "1",
+    )
+}
+
+#[test]
+fn module_env_imports_3() -> TestResult {
+    run_test(
+        r#"module foo { export env a { '1' }; export env b { '2' } }; use foo *; $nu.env.b"#,
+        "2",
+    )
+}
+
+#[test]
+fn module_env_imports_4() -> TestResult {
+    fail_test(
+        r#"module foo { export env a { '1' }; export env b { '2' } }; use foo c"#,
+        "not find import",
+    )
+}
+
+#[test]
+fn module_env_imports_5() -> TestResult {
+    run_test(
+        r#"module foo { export env a { '1' }; export env b { '2' }; export env c { '3' } }; use foo [a, c]; $nu.env.c"#,
+        "3",
+    )
+}
+
+#[test]
+fn module_def_import_uses_internal_command() -> TestResult {
     run_test(
         r#"module foo { def b [] { 2 }; export def a [] { b }  }; use foo; foo a"#,
         "2",
     )
 }
 
+#[test]
+fn module_env_import_uses_internal_command() -> TestResult {
+    run_test(
+        r#"module foo { def b [] { "2" }; export env a { b }  }; use foo; $nu.env.'foo a'"#,
+        "2",
+    )
+}
+
 // TODO: Test the use/hide tests also as separate lines in REPL (i.e., with  merging the delta in between)
 #[test]
 fn hides_def() -> TestResult {
     fail_test(r#"def foo [] { "foo" }; hide foo; foo"#, not_found_msg())
 }
 
+#[ignore]
+fn hides_env() -> TestResult {
+    fail_test(
+        r#"let-env foo = "foo"; hide foo; $nu.env.foo"#,
+        "did you mean",
+    )
+}
+
 #[test]
 fn hides_def_then_redefines() -> TestResult {
+    // this one should fail because of predecl -- cannot have more defs with the same name in a
+    // block
     fail_test(
         r#"def foo [] { "foo" }; hide foo; def foo [] { "bar" }; foo"#,
         "defined more than once",
     )
 }
 
+#[ignore]
+fn hides_env_then_redefines() -> TestResult {
+    run_test(
+        r#"let-env foo = "foo"; hide foo; let-env foo = "bar"; $nu.env.foo"#,
+        "bar",
+    )
+}
+
 #[test]
 fn hides_def_in_scope_1() -> TestResult {
     fail_test(
@@ -488,40 +554,96 @@ fn hides_def_in_scope_4() -> TestResult {
     )
 }
 
-#[test]
+#[ignore]
-fn hide_twice_not_allowed() -> TestResult {
+fn hides_env_in_scope_1() -> TestResult {
     fail_test(
-        r#"def foo [] { "foo" }; hide foo; hide foo"#,
+        r#"let-env foo = "foo"; do { hide foo; $nu.env.foo }"#,
-        "unknown command",
+        "did you mean",
+    )
+}
+
+#[ignore]
+fn hides_env_in_scope_2() -> TestResult {
+    // TODO: Revisit this -- 'hide foo' should restore the env, not hide it completely
+    run_test(
+        r#"let-env foo = "foo"; do { let-env foo = "bar"; hide foo; $nu.env.foo }"#,
+        "foo",
+    )
+}
+
+#[ignore]
+fn hides_env_in_scope_3() -> TestResult {
+    fail_test(
+        r#"let-env foo = "foo"; do { hide foo; let-env foo = "bar"; hide foo; $nu.env.foo }"#,
+        "did you mean",
+    )
+}
+
+#[ignore]
+fn hides_env_in_scope_4() -> TestResult {
+    // TODO: Revisit this -- 'hide foo' should restore the env, not hide it completely
+    fail_test(
+        r#"let-env foo = "foo"; do { let-env foo = "bar"; hide foo; hide foo; $nu.env.foo }"#,
+        "did you mean",
     )
 }
 
 #[test]
-fn hides_import_1() -> TestResult {
+fn hide_def_twice_not_allowed() -> TestResult {
+    fail_test(r#"def foo [] { "foo" }; hide foo; hide foo"#, "not found")
+}
+
+#[ignore]
+fn hide_env_twice_not_allowed() -> TestResult {
+    fail_test(r#"let-env foo = "foo"; hide foo; hide foo"#, "did not find")
+}
+
+#[ignore]
+fn hides_def_runs_env() -> TestResult {
+    // TODO: We need some precedence system to handle this. Currently, 'hide foo' hides both the
+    // def and env var.
+    run_test(
+        r#"let-env foo = "bar"; def foo [] { "foo" }; hide foo; $nu.env.foo"#,
+        "bar",
+    )
+}
+
+#[ignore]
+fn hides_def_and_env() -> TestResult {
+    // TODO: We need some precedence system to handle this. Currently, 'hide foo' hides both the
+    // def and env var.
     fail_test(
-        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam foo; foo"#,
+        r#"let-env foo = "bar"; def foo [] { "foo" }; hide foo; hide foo; $nu.env.foo"#,
         not_found_msg(),
     )
 }
 
 #[test]
-fn hides_import_2() -> TestResult {
+fn hides_def_import_1() -> TestResult {
     fail_test(
-        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam *; foo"#,
+        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam foo; spam foo"#,
         not_found_msg(),
     )
 }
 
 #[test]
-fn hides_import_3() -> TestResult {
+fn hides_def_import_2() -> TestResult {
     fail_test(
-        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam [foo]; foo"#,
+        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam *; spam foo"#,
         not_found_msg(),
     )
 }
 
 #[test]
-fn hides_import_4() -> TestResult {
+fn hides_def_import_3() -> TestResult {
+    fail_test(
+        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam [foo]; spam foo"#,
+        not_found_msg(),
+    )
+}
+
+#[test]
+fn hides_def_import_4() -> TestResult {
     fail_test(
         r#"module spam { export def foo [] { "foo" } }; use spam foo; hide foo; foo"#,
         not_found_msg(),
@@ -529,7 +651,7 @@ fn hides_import_4() -> TestResult {
 }
 
 #[test]
-fn hides_import_5() -> TestResult {
+fn hides_def_import_5() -> TestResult {
     fail_test(
         r#"module spam { export def foo [] { "foo" } }; use spam *; hide foo; foo"#,
         not_found_msg(),
@@ -537,13 +659,61 @@ fn hides_import_5() -> TestResult {
 }
 
 #[test]
-fn hides_import_6() -> TestResult {
+fn hides_def_import_6() -> TestResult {
     fail_test(
-        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam; foo"#,
+        r#"module spam { export def foo [] { "foo" } }; use spam; hide spam; spam foo"#,
         not_found_msg(),
     )
 }
 
+#[ignore]
+fn hides_env_import_1() -> TestResult {
+    fail_test(
+        r#"module spam { export env foo { "foo" } }; use spam; hide spam foo; $nu.env.'spam foo'"#,
+        "did you mean",
+    )
+}
+
+#[ignore]
+fn hides_env_import_2() -> TestResult {
+    fail_test(
+        r#"module spam { export env foo { "foo" } }; use spam; hide spam *; $nu.env.'spam foo'"#,
+        "did you mean",
+    )
+}
+
+#[ignore]
+fn hides_env_import_3() -> TestResult {
+    fail_test(
+        r#"module spam { export env foo { "foo" }; } use spam; hide spam [foo]; $nu.env.'spam foo'"#,
+        "did you mean",
+    )
+}
+
+#[ignore]
+fn hides_env_import_4() -> TestResult {
+    fail_test(
+        r#"module spam { export env foo { "foo" } }; use spam foo; hide foo; $nu.env.foo"#,
+        "did you mean",
+    )
+}
+
+#[ignore]
+fn hides_env_import_5() -> TestResult {
+    fail_test(
+        r#"module spam { export env foo { "foo" } }; use spam *; hide foo; $nu.env.foo"#,
+        "did you mean",
+    )
+}
+
+#[ignore]
+fn hides_env_import_6() -> TestResult {
+    fail_test(
+        r#"module spam { export env foo { "foo" } }; use spam; hide spam; $nu.env.'spam foo'"#,
+        "did you mean",
+    )
+}
+
 #[test]
 fn def_twice_should_fail() -> TestResult {
     fail_test(
@@ -553,13 +723,21 @@ fn def_twice_should_fail() -> TestResult {
 }
 
 #[test]
-fn use_import_after_hide() -> TestResult {
+fn use_def_import_after_hide() -> TestResult {
     run_test(
         r#"module spam { export def foo [] { "foo" } }; use spam foo; hide foo; use spam foo; foo"#,
         "foo",
     )
 }
 
+#[ignore]
+fn use_env_import_after_hide() -> TestResult {
+    run_test(
+        r#"module spam { export env foo { "foo" } }; use spam foo; hide foo; use spam foo; $nu.env.foo"#,
+        "foo",
+    )
+}
+
 #[test]
 fn hide_shadowed_decl() -> TestResult {
     run_test(
@@ -568,6 +746,15 @@ fn hide_shadowed_decl() -> TestResult {
     )
 }
 
+#[ignore]
+fn hide_shadowed_env() -> TestResult {
+    // TODO: waiting for a fix
+    run_test(
+        r#"module spam { export env foo { "bar" } }; let-env foo = "foo"; do { use spam foo; hide foo; $nu.env.foo }"#,
+        "foo",
+    )
+}
+
 #[test]
 fn hides_all_decls_within_scope() -> TestResult {
     fail_test(
@@ -576,6 +763,14 @@ fn hides_all_decls_within_scope() -> TestResult {
     )
 }
 
+#[ignore]
+fn hides_all_envs_within_scope() -> TestResult {
+    fail_test(
+        r#"module spam { export env foo { "bar" } }; let-env foo = "foo"; use spam foo; hide foo; $nu.env.foo"#,
+        "did you mean",
+    )
+}
+
 #[test]
 fn from_json_1() -> TestResult {
     run_test(r#"('{"name": "Fred"}' | from json).name"#, "Fred")