Implement the Needs rule forms and $ContextAliases

`Needs["ctx`" -> "alias`"]` records the alias in `$ContextAliases` and
`Needs["ctx`" -> None]` records nothing; both leave `$ContextPath` exactly
as they found it, undoing what the read file did to it. An alias stands for
its context wherever the context's own name could appear: in a symbol, and
in a `Names` or `Contexts` pattern. The alias is registered as soon as the
rule has been read — so a call that goes on to fail on its second argument
keeps it — and taken back out, restoring any previous target, when the load
produces no context. `$ContextAliases::cxinuse` and `::cxconflict` are
re-checked on every write to the mapping, as wolframscript does.

Fixes found on the way there:

- `$Path` was ignored: `Needs`, `Get` and `FindFile` searched a hardcoded
  list, so `AppendTo[$Path, dir]` had no effect.
- `$ContextPath` was dual-sourced — assignments landed in the variable
  store while resolution read a separate stack, so which one answered
  depended on who asked.
- A part assignment to a system variable that only had a built-in default
  defined a down-value instead of extending the value.
- A list literal of `$…` variables (`{$Version}`) was echoed verbatim by
  `interpret`'s fast path instead of being evaluated.
- `clear_symbol_table` was never called, so the context symbol table
  survived `clear_state`.
- `ComputerArithmetic`` — the reference page's own example — was missing
  from the standard-distribution contexts.

Author: ad-si

functions.csv

@@ -249,7 +249,7 @@ Sort,Sorts a list in ascending order or by an ordering function which leaves a p
 Series,Computes a power series expansion about a point or at Infinity,✅,pure,1.0,195
 Return,Returns a value from a definition body Do or Scan — anywhere else it stands as Return[value] and is collected like any other,✅,pure,1.0,196
 Appearance,Option symbol for specifying visual appearance,✅,pure,6.0,197
-Needs,Loads the file providing a context from a loaded paclet directory or from $Path,✅,effectful,1.0,198
+Needs,Loads the file providing a context from a loaded paclet directory or from $Path; a rule right-hand side aliases the context in $ContextAliases or (None) records nothing,✅,effectful,1.0,198
 Center,Symbol for centering alignment,✅,pure,1.0,199
 UndirectedEdge,Undirected graph edge,✅,pure,8.0,201
 Filling,Option for filling areas under curves in plots,✅,pure,6.0,202

src/evaluator/assignment.rs

@@ -1052,6 +1052,61 @@ fn normalize_symbol_lhs(lhs: &Expr) -> Expr {
   lhs.clone()
 }
 
+/// The symbol an assignment ultimately writes to: `a`, `a[[1]]`, `a[k]` and
+/// `a[[1, 2]]` all target `a`.
+fn assignment_target_symbol(lhs: &Expr) -> Option<&str> {
+  match lhs {
+    Expr::Identifier(name) | Expr::Constant(name) => Some(name),
+    Expr::Part { expr, .. } => assignment_target_symbol(expr),
+    Expr::FunctionCall { name, .. } => Some(name),
+    _ => None,
+  }
+}
+
+/// Re-checks `$ContextAliases` once the assignment that touched it is done.
+struct AliasCheck(bool);
+
+impl Drop for AliasCheck {
+  fn drop(&mut self) {
+    if self.0 {
+      crate::evaluator::contexts::validate_aliases();
+    }
+  }
+}
+
+/// Give a `$…` system variable that only has a built-in default an entry in
+/// the variable store, so that a *part* assignment has something to modify.
+///
+/// The Wolfram Language keeps these values as own-values, so
+/// `$ContextAliases["c`"] = "Long`"` extends the association the variable
+/// already holds. Woxi computes the defaults on demand instead, and without
+/// this the assignment would fall through to defining a down-value. Only
+/// container defaults are seeded — a scalar one (`$Assumptions` is `True`)
+/// has no part to assign to, and wolframscript reports that as an error on
+/// the value rather than on the variable.
+fn seed_system_variable(name: &str) {
+  if !name.starts_with('$')
+    || crate::ENV.with(|e| e.borrow().contains_key(name))
+  {
+    return;
+  }
+  let Some(value) = crate::evaluator::listable::get_system_variable(name)
+  else {
+    return;
+  };
+  let stored = match &value {
+    Expr::Association(items) => StoredValue::Association(
+      items
+        .iter()
+        .map(|(k, v)| (crate::syntax::expr_to_string(k), v.clone()))
+        .collect(),
+    ),
+    Expr::List(_) => StoredValue::ExprVal(value.clone()),
+    _ => return,
+  };
+  crate::ENV.with(|e| e.borrow_mut().insert(name.to_string(), stored));
+}
+
 /// Heads whose `head[sym, …] = value` assignment is redirected into a
 /// per-symbol storage slot (NValues, Messages, Format rules, Options, …).
 /// wolframscript permits these even though the head itself is Protected,
@@ -1115,6 +1170,13 @@ pub fn set_ast(lhs: &Expr, rhs: &Expr) -> Result<Expr, InterpreterError> {
     (lhs, None)
   };
 
+  // Assigning `$ContextAliases`, whole or by key, re-checks the mapping the
+  // way the Wolfram Language does — the warnings belong after the assignment
+  // has landed, so they ride on the way out of every return path here.
+  let _alias_check = AliasCheck(
+    assignment_target_symbol(lhs).is_some_and(|s| s == "$ContextAliases"),
+  );
+
   // Handle Entity property mutation: Entity["type", "name"]["property"] = value
   if let Expr::CurriedCall { func, args } = lhs
     && let Expr::FunctionCall {
@@ -1142,6 +1204,7 @@ pub fn set_ast(lhs: &Expr, rhs: &Expr) -> Result<Expr, InterpreterError> {
   } = lhs
     && head_args.len() == 1
   {
+    seed_system_variable(head_name);
     let is_assoc = crate::ENV.with(|e| {
       let env = e.borrow();
       matches!(env.get(head_name), Some(StoredValue::Association(_)))
@@ -1210,6 +1273,8 @@ pub fn set_ast(lhs: &Expr, rhs: &Expr) -> Result<Expr, InterpreterError> {
       return Ok(rhs_value);
     }
 
+    seed_system_variable(&var_name);
+
     // Evaluate indices
     let mut eval_indices = Vec::new();
     for idx in &indices {

src/evaluator/contexts.rs

@@ -60,6 +60,33 @@ pub fn contexts_active() -> bool {
   crate::current_context() != "Global`"
     || crate::current_context_path()
       != vec!["System`".to_string(), "Global`".to_string()]
+    || crate::has_context_aliases()
+}
+
+/// Expand a `$ContextAliases` prefix: with `mp`` aliased to `MyPkg``, the
+/// name `mp`Foo` is read as `MyPkg`Foo`. Only the first segment is an alias,
+/// and the rest of the name rides along — `mp`Sub`Foo` becomes
+/// `MyPkg`Sub`Foo`. A name that no alias claims comes back unchanged.
+pub fn expand_alias(name: &str) -> String {
+  if !crate::has_context_aliases() {
+    return name.to_string();
+  }
+  let Some(first) = name.find('`') else {
+    return name.to_string();
+  };
+  // A name that starts with a backtick is relative to `$Context`; there is no
+  // leading segment for an alias to match.
+  if first == 0 {
+    return name.to_string();
+  }
+  let prefix = &name[..=first];
+  crate::context_aliases()
+    .into_iter()
+    .find(|(alias, _)| alias == prefix)
+    .map_or_else(
+      || name.to_string(),
+      |(_, target)| format!("{target}{}", &name[first + 1..]),
+    )
 }
 
 thread_local! {
@@ -100,6 +127,40 @@ impl Drop for ReadContext {
   }
 }
 
+/// Report every `$ContextAliases` entry that cannot do its job.
+///
+/// An alias claims a context name for itself, so a context that already holds
+/// symbols of its own becomes unreachable once its name is an alias, and one
+/// that is on `$ContextPath` would be searched under a name that no longer
+/// means it. The Wolfram Language warns about both, and re-checks the whole
+/// mapping every time it changes — so a warning repeats until the entry that
+/// caused it is taken back out.
+pub fn validate_aliases() {
+  let path = crate::current_context_path();
+  let symbols = known_symbols();
+  for (alias, target) in crate::context_aliases() {
+    if path.contains(&alias) {
+      crate::emit_message_to_stdout(&format!(
+        "$ContextAliases::cxconflict: Warning: the alias {alias} -> {target} \
+         conflicts with the value of $ContextPath."
+      ));
+    }
+    if symbols.iter().any(|(context, _)| *context == alias) {
+      crate::emit_message_to_stdout(&format!(
+        "$ContextAliases::cxinuse: Warning: Symbols already exist in the \
+         context {alias}. These symbols will not be able to be accessed \
+         while {alias} is in $ContextAliases."
+      ));
+    }
+  }
+}
+
+/// Record `alias` as standing for `target` in `$ContextAliases`.
+pub fn set_alias(alias: &str, target: &str) {
+  crate::set_context_alias(alias, Some(target));
+  validate_aliases();
+}
+
 /// The store key for `name` in `context`. `Global`` symbols are keyed by
 /// their short name, the way Woxi has always stored them.
 fn key_for(context: &str, name: &str) -> String {
@@ -231,8 +292,9 @@ pub fn resolve(name: &str) -> String {
     return full;
   }
   if name.contains('`') {
-    create_symbol(name);
-    return name.to_string();
+    let full = expand_alias(name);
+    create_symbol(&full);
+    return full;
   }
   let (current, path) = read_context();
   for context in path {
@@ -250,9 +312,12 @@ pub fn resolve(name: &str) -> String {
 /// print a symbol under its visible short name, so anything that looks state
 /// up from a rendered name has to map it back first.
 pub fn resolve_existing(name: &str) -> String {
-  if !contexts_active() || name.contains('`') || !is_user_symbol(name) {
+  if !contexts_active() || !is_user_symbol(name) {
     return name.to_string();
   }
+  if name.contains('`') {
+    return expand_alias(name);
+  }
   crate::current_context_path()
     .into_iter()
     .map(|context| key_for(&context, name))

src/evaluator/dispatch/evaluate_functions.rs

@@ -1819,24 +1819,64 @@ fn evaluate_function_call_ast_inner(
   }
 
   // Needs["pkg`"] loads the file providing the context — from a paclet in a
-  // directory registered with `PacletDirectoryLoad`, or from `$Path`.
-  // `Needs["pkg`", "file"]` reads the named file instead. A package that
-  // ships with the Wolfram Language loads as a no-op, because Woxi keeps
-  // every built-in in one namespace.
+  // directory registered with `PacletDirectoryLoad`, or from `$Path` — and
+  // leaves the context on `$ContextPath`, so its symbols can be named
+  // unqualified. `Needs["pkg`", "file"]` reads the named file instead.
+  //
+  // The rule forms load the same way but keep `$ContextPath` as they found
+  // it: `Needs["pkg`" -> "p`"]` records `p`` as an alias for the context in
+  // `$ContextAliases`, so its symbols are reachable as `p`sym`, and
+  // `Needs["pkg`" -> None]` records nothing, leaving only the full name.
+  //
+  // A package that ships with the Wolfram Language loads as a no-op, because
+  // Woxi keeps every built-in in one namespace.
   if name == "Needs" && (args.len() == 1 || args.len() == 2) {
     let call = || {
       crate::syntax::format_expr(
         &unevaluated("Needs", args),
         crate::syntax::ExprForm::Output,
       )
     };
-    let Expr::String(ctx) = &args[0] else {
+    let cxru = || {
       crate::emit_message_to_stdout(&format!(
         "Needs::cxru: Context or appropriately structured rule expected at \
          position 1 in {}.",
         call()
       ));
-      return Ok(unevaluated("Needs", args));
+    };
+    // An alias is a context of a single segment: `p``, never `p`q``.
+    let is_alias = |name: &str| {
+      crate::utils::context_segments(name).is_some_and(|s| s.len() == 1)
+    };
+    // `None` means "no rule given"; `Some(None)` is `-> None`, which asks for
+    // neither a context-path entry nor an alias.
+    let (ctx, alias) = match &args[0] {
+      Expr::String(ctx) => (ctx, None),
+      Expr::Rule {
+        pattern,
+        replacement,
+      } => match (pattern.as_ref(), replacement.as_ref()) {
+        (Expr::String(ctx), Expr::String(alias))
+          if crate::utils::context_segments(ctx).is_some()
+            && is_alias(alias) =>
+        {
+          (ctx, Some(Some(alias)))
+        }
+        (Expr::String(ctx), Expr::Identifier(none))
+          if none == "None"
+            && crate::utils::context_segments(ctx).is_some() =>
+        {
+          (ctx, Some(None))
+        }
+        _ => {
+          cxru();
+          return Ok(unevaluated("Needs", args));
+        }
+      },
+      _ => {
+        cxru();
+        return Ok(unevaluated("Needs", args));
+      }
     };
     if crate::utils::context_segments(ctx).is_none() {
       crate::emit_message_to_stdout(&format!(
@@ -1846,6 +1886,23 @@ fn evaluate_function_call_ast_inner(
       ));
       return Ok(unevaluated("Needs", args));
     }
+    // The alias is recorded as soon as the rule has been read, so that even a
+    // call that goes on to fail on its second argument leaves it behind; only
+    // a *load* that does not produce the context takes it back out again,
+    // restoring whatever the alias stood for before.
+    let previous_alias = match alias {
+      Some(Some(alias)) => {
+        let previous = crate::context_alias_target(alias);
+        crate::evaluator::contexts::set_alias(alias, ctx);
+        Some((alias, previous))
+      }
+      _ => None,
+    };
+    let forget_alias = || {
+      if let Some((alias, previous)) = &previous_alias {
+        crate::set_context_alias(alias, previous.as_deref());
+      }
+    };
     if let Some(file) = args.get(1)
       && !matches!(file, Expr::String(_))
     {
@@ -1871,23 +1928,36 @@ fn evaluate_function_call_ast_inner(
         Some(Expr::String(file)) => file,
         _ => ctx,
       };
+      // A rule form reaches the package by alias or by full name, so whatever
+      // the file did to `$ContextPath` — its own `EndPackage[]` above all —
+      // is undone once it has been read.
+      let saved_path = alias.is_some().then(crate::save_context_path);
+      let restore_path = || {
+        if let Some(saved) = saved_path.clone() {
+          crate::restore_context_path(saved);
+        }
+      };
       let loaded = resolve_get_target(requested)
         .as_deref()
         .and_then(evaluate_file);
       let nocont = format!(
         "Needs::nocont: Context {ctx} was not created when Needs was evaluated."
       );
       let Some(result) = loaded else {
+        restore_path();
+        forget_alias();
         crate::emit_message_to_stdout(&format!(
           "Get::noopen: Cannot open {requested}."
         ));
         crate::emit_message_to_stdout(&nocont);
         return Ok(Expr::Identifier("$Failed".to_string()));
       };
+      restore_path();
       result?;
       // The file loaded but never opened the context it was supposed to
       // provide — wolframscript reports that and still returns Null.
       if !crate::packages_list().iter().any(|pkg| pkg == ctx) {
+        forget_alias();
         crate::emit_message_to_stdout(&nocont);
       }
       return Ok(Expr::Identifier("Null".to_string()));

src/evaluator/dispatch/evaluation_control.rs

@@ -759,7 +759,9 @@ pub fn dispatch_evaluation_control(
         // pattern without a backtick looks in the contexts on
         // `$ContextPath`, which is why `Names["List*"]` finds the built-ins
         // (they are `System`` symbols) and `Names["S`*"]` does not reach
-        // into `S`Private``.
+        // into `S`Private``. A leading `$ContextAliases` alias names the
+        // context it stands for, here as anywhere else.
+        let pattern = &crate::evaluator::contexts::expand_alias(pattern);
         let (context_pattern, name_pattern) = match pattern.rfind('`') {
           Some(last) => (
             Some(pattern[..=last].to_string()),

src/evaluator/dispatch/predicate_functions.rs

@@ -1362,7 +1362,9 @@ pub fn dispatch_predicate_functions(
     }
     "Contexts" if args.len() == 1 => {
       let pattern = match &args[0] {
-        Expr::String(s) => s.clone(),
+        // A pattern may name a context by its `$ContextAliases` alias, which
+        // stands in for the context's real name here as everywhere else.
+        Expr::String(s) => crate::evaluator::contexts::expand_alias(s),
         _ => {
           return Some(Ok(unevaluated("Contexts", args)));
         }

src/evaluator/listable.rs

@@ -847,7 +847,7 @@ pub fn get_system_variable(name: &str) -> Option<Expr> {
     // Wolfram layout.
     #[cfg(not(target_arch = "wasm32"))]
     "$Path" => Some(Expr::List(
-      crate::utils::search_path()
+      crate::utils::default_search_path()
         .into_iter()
         .map(Expr::String)
         .collect(),
@@ -893,6 +893,11 @@ pub fn get_system_variable(name: &str) -> Option<Expr> {
         .map(Expr::String)
         .collect(),
     )),
+    // `$ContextAliases` maps a short context onto the long one it stands
+    // for. It starts out empty; `Needs["ctx`" -> "alias`"]` and plain
+    // assignment both fill it in, and the value then lives in the variable
+    // store (which takes precedence over this default).
+    "$ContextAliases" => Some(Expr::Association(Vec::new())),
     // Woxi only tracks the System`/Global` baseline plus any contexts
     // registered by `BeginPackage[]`; wolframscript lists many kernel
     // packages here, but `MemberQ[$Packages, "System`"]` and