parser/runtime: Destructuring assignment syntax

Author: shesek

src/error.rs

@@ -6,7 +6,7 @@ use miniscript::policy::compiler::CompilerError;
 use miniscript::{descriptor, TranslateErr};
 
 use crate::parser::ast::{Ident, InfixOp};
-use crate::{stdlib, PrettyDisplay, Value};
+use crate::{ast, stdlib, PrettyDisplay, Value};
 
 #[derive(thiserror::Error, Debug)]
 pub enum Error {
@@ -34,6 +34,12 @@ pub enum RuntimeError {
     #[error("Undefined variable: {0}")]
     VarNotFound(Ident),
 
+    #[error("Expected an array to unpack into {}, not {}", &.0, ValErrFmt(.1))]
+    UnpackArrayExpected(Box<ast::AssignTarget>, Box<Value>),
+
+    #[error("Expected an array of length {1} to unpack into {2}, received an array of {0}")]
+    UnpackInvalidArrayLen(usize, usize, Box<ast::AssignTarget>),
+
     #[error("Expected a function, not {}", ValErrFmt(.0))]
     NotFn(Box<Value>),
 
@@ -96,7 +102,7 @@ pub enum RuntimeError {
     #[error("Expected a Script (or script bytes), not {}. Perhaps you meant to use explicitScript()/scriptPubKey()", ValErrFmt(.0))]
     NotScriptLike(Box<Value>),
 
-    #[error("Expected a transaction, raw bytes or tagged list, not {}", ValErrFmt(.0))]
+    #[error("Expected a Transaction (also accepted as raw bytes, tagged list or PSBT), not {}", ValErrFmt(.0))]
     NotTxLike(Box<Value>),
 
     #[error("Expected txid bytes or tx, not {}", ValErrFmt(.0))]
@@ -452,6 +458,9 @@ impl<'a> fmt::Display for ValErrFmt<'a> {
 
 #[derive(thiserror::Error, Debug)]
 pub enum ParseError {
+    #[error("Invalid assignemnt target")]
+    InvalidAssignTarget,
+
     #[error("ParseFloatError: {0}")]
     ParseFloatError(#[from] std::num::ParseFloatError),
 

src/parser/ast.rs

@@ -3,6 +3,8 @@ use miniscript::{bitcoin, descriptor};
 use bitcoin::address::{self, Address};
 use descriptor::{DescriptorPublicKey, DescriptorSecretKey};
 
+use crate::util::fmt_list;
+
 /// Expressions have no side-effects and produce a value
 #[derive(Debug, Clone)]
 pub enum Expr {
@@ -149,7 +151,7 @@ impl_from_variant!(ScriptFrag, Expr);
 /// An anonymous function expression
 #[derive(Debug, Clone)]
 pub struct FnExpr {
-    pub params: Vec<Ident>,
+    pub params: Vec<AssignTarget>,
     pub body: Box<Expr>,
     pub dynamic_scoping: bool,
 }
@@ -241,7 +243,7 @@ impl_from_variant!(BtcAmount, Expr);
 #[derive(Debug, Clone)]
 pub struct FnDef {
     pub ident: Ident,
-    pub params: Vec<Ident>,
+    pub params: Vec<AssignTarget>,
     pub body: Expr,
     pub dynamic_scoping: bool,
 }
@@ -254,10 +256,17 @@ impl_from_variant!(Assign, Stmt);
 
 #[derive(Debug, Clone)]
 pub struct Assignment {
-    pub lhs: Ident,
+    pub lhs: AssignTarget,
     pub rhs: Expr,
 }
 
+// Used for assignment and function parameters
+#[derive(Debug, Clone)]
+pub enum AssignTarget {
+    Ident(Ident),
+    List(Vec<AssignTarget>),
+}
+
 /// A call statement whose return value is discarded
 #[derive(Debug, Clone)]
 pub struct ExprStmt(pub Expr);
@@ -284,3 +293,19 @@ impl Expr {
         }
     }
 }
+
+impl From<&str> for AssignTarget {
+    fn from(s: &str) -> Self {
+        Self::Ident(s.into())
+    }
+}
+impl std::fmt::Display for AssignTarget {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AssignTarget::Ident(ident) => write!(f, "{}", ident),
+            AssignTarget::List(items) => {
+                fmt_list(f, items.iter(), None, |f, item, _| write!(f, "{}", item))
+            }
+        }
+    }
+}

src/parser/grammar.lalrpop

@@ -1,6 +1,8 @@
+use std::convert::TryFrom;
 use std::str::FromStr;
 use crate::time;
 use crate::parser::{ast, Expr, Stmt, ParseError, concat, prepend, call, self};
+use ast::AssignTarget;
 
 grammar;
 
@@ -277,13 +279,13 @@ FnExpr = { FnExpr1, FnExpr2 };
 FnExpr1: Expr = <dyn_scoping:"dyn"?> <params:FnExpr1Params> <body:Either2<Expr, FnBlockNoReturn>> =>
     ast::FnExpr { params, body: body.into(), dynamic_scoping: dyn_scoping.is_some() }.into();
 FnExpr1Params = {
-  "|" <List0<IdentTerm, ",">> "|",
+  "|" <List0<AssignTarget, ",">> "|",
   // Zero arguments should be captures by the List0, but it isn't because `||` is pre-tokenized as OR
   "||" => vec![],
 };
 
 // FnDef-like syntax, more suitable for chaining with FnDef: fn adder($a) = fn ($b) = $a+$b; adder(2)(3)
-FnExpr2: Expr = <dyn_scoping:"dyn"?> "fn" <params:Paren<List0<IdentTerm, ",">>> <body:Either3<("=" <Expr>), BlockExpr, FnBlockNoReturn>> =>
+FnExpr2: Expr = <dyn_scoping:"dyn"?> "fn" <params:Paren<List0<AssignTarget, ",">>> <body:Either3<("=" <Expr>), BlockExpr, FnBlockNoReturn>> =>
     ast::FnExpr { params, body: body.into(), dynamic_scoping: dyn_scoping.is_some() }.into();
 
 // XXX Should probably settle on one syntax to rule them all. Maybe `($a, $b) => $a+$b`?
@@ -393,10 +395,10 @@ BtcAmount: Expr = <num:SExpr> <denom:BTC_DENOMINATION> =>
 Assign: Stmt = "let"? <assigns:List1<Assignment, ",">> ";" =>
     ast::Assign(assigns).into();
 
-Assignment: ast::Assignment = <lhs:IdentTerm> "=" <rhs:Expr> =>
+Assignment: ast::Assignment = <lhs:AssignTarget> "=" <rhs:Expr> =>
     ast::Assignment { lhs, rhs };
 
-FnDef: Stmt = <dyn_scoping:"dyn"?> "fn" <ident:IdentTerm> <params:Paren<List0<IdentTerm, ",">>> <body:FnDefBody> =>
+FnDef: Stmt = <dyn_scoping:"dyn"?> "fn" <ident:IdentTerm> <params:Paren<List0<AssignTarget, ",">>> <body:FnDefBody> =>
   ast::FnDef { ident, params, body, dynamic_scoping: dyn_scoping.is_some() }.into();
 
 FnDefBody = { "=" <Expr> ";", <BlockExpr> ";"?, <FnBlockNoReturn> ";"? };
@@ -409,15 +411,23 @@ IfStmtElse: Vec<Stmt> = {
   "else" <IfStmt> => vec![<>],
 };
 
-// An expression used in a statement position. The evaluated return value is
-// discarded, but this can be useful for expressions that produce side effects
-// like logging and exceptions.
+// An expression used in a statement position. The evaluated return value is discarded,
+// but this can be useful for expressions that produce logging/exceptions side effects.
 ExprStmt: Stmt = <Expr> ";" => ast::ExprStmt(<>).into();
 
+// Used as the target for Assignment and function parameters
+AssignTarget: AssignTarget = {
+  IdentTerm => AssignTarget::Ident(<>),
+  // Reuses the existing Expr Array type as an AssignTarget to play nicely with LR(1) grammar.
+  // ASsignTarget::try_from() will reject Arrays that are not valid as a target.
+  // https://github.com/lalrpop/lalrpop/issues/552#issuecomment-778923903
+  Array =>? Ok(AssignTarget::try_from(<>)?),
+};
+
 // Helpers
 
 Either2<A, B>: Expr = { A, B };
-Either3<A, B, C>: Expr = { A, B };
+Either3<A, B, C>: Expr = { A, B, C };
 
 // A `S`-separated list of zero or more `T` values
 List0<T, S>: Vec<T> = <l:(<T> S)*> <t:T?> => concat(l, t);

src/parser/mod.rs

@@ -4,7 +4,7 @@ use std::str::FromStr;
 pub use crate::error::ParseError;
 
 pub mod ast;
-pub use ast::{Expr, Ident, Library, Stmt};
+pub use ast::{AssignTarget, Expr, Ident, Library, Stmt};
 
 lalrpop_mod!(
     #[allow(clippy::all)]
@@ -30,6 +30,33 @@ impl FromStr for Library {
 }
 impl_tryfrom_fromstr!(Library);
 
+// The grammar reuses the Expr Array/Ident types as an AssignTarget to play nicely with LR(1) grammar.
+// This converts them into an AssignTarget, or reject ones that are invalid.
+// See https://github.com/lalrpop/lalrpop/issues/552#issuecomment-778923903
+impl TryFrom<Expr> for AssignTarget {
+    type Error = ParseError;
+    fn try_from(expr: Expr) -> Result<Self, ParseError> {
+        use ast::{Infix, InfixOp::Colon};
+        Ok(match expr {
+            Expr::Ident(ident) => Self::Ident(ident),
+            Expr::Array(ast::Array(mut items)) => {
+                // Colon tuple syntax is supported within Array brackets, as e.g. `[$txid:$vout]` (it cannot be
+                // supported without it due to grammar conflicts). Must peek to check prior to taking ownership.
+                if items.len() == 1 && matches!(items[0], Expr::Infix(Infix { op: Colon, .. })) {
+                    let Expr::Infix(ast::Infix { lhs, rhs, .. }) = items.remove(0) else {
+                        unreachable!()
+                    };
+                    Self::List(vec![Self::try_from(*lhs)?, Self::try_from(*rhs)?])
+                } else {
+                    let targets = items.into_iter().map(Self::try_from);
+                    Self::List(targets.collect::<Result<_, _>>()?)
+                }
+            }
+            _ => bail!(ParseError::InvalidAssignTarget),
+        })
+    }
+}
+
 // Utility functions used by the grammar
 
 pub fn concat<T>(mut list: Vec<T>, val: Option<T>) -> Vec<T> {

src/runtime/function.rs

@@ -1,6 +1,6 @@
 use std::fmt;
 
-use crate::parser::{ast, Expr, Ident};
+use crate::parser::{ast, AssignTarget, Expr, Ident};
 use crate::runtime::{Array, Error, Evaluate, Result, ScopeRef, Value};
 
 #[derive(Debug, Clone)]
@@ -13,7 +13,7 @@ pub enum Function {
 #[derive(Clone)]
 pub struct UserFunction {
     pub ident: Option<Ident>,
-    pub params: Vec<Ident>,
+    pub params: Vec<AssignTarget>,
     pub body: Expr,
     pub scope: Option<ScopeRef>,
 }
@@ -55,9 +55,8 @@ impl Call for UserFunction {
             // For lexically-scoped functions, create a child scope of the scope where the function was defined.
             // For dynamically-scoped function, create a child of the caller scope.
             let mut scope = self.scope.as_ref().unwrap_or(caller_scope).child();
-            for (index, value) in args.into_iter().enumerate() {
-                let ident = self.params.get(index).unwrap();
-                scope.set(ident.clone(), value)?;
+            for (param_target, arg_value) in self.params.iter().zip(args) {
+                param_target.unpack(arg_value, &mut scope)?;
             }
             self.body.eval(&scope.into_ref())
         };

src/runtime/mod.rs

@@ -3,6 +3,7 @@ use std::convert::TryInto;
 
 use crate::parser::{ast, Expr, Stmt};
 use crate::stdlib;
+pub use ast::AssignTarget;
 
 pub use crate::error::{ResultExt, RuntimeError as Error};
 pub type Result<T> = std::result::Result<T, Error>;
@@ -36,7 +37,7 @@ impl Execute for ast::Assign {
         let readonly = scope.as_readonly();
         for assignment in &self.0 {
             let value = assignment.rhs.eval(&readonly)?;
-            scope.borrow_mut().set(assignment.lhs.clone(), value)?;
+            assignment.lhs.unpack(value, &mut scope.borrow_mut())?;
         }
         Ok(())
     }
@@ -409,6 +410,31 @@ impl Evaluate for ast::Block {
     }
 }
 
+impl ast::AssignTarget {
+    pub fn unpack(&self, value: Value, scope: &mut Scope) -> Result<()> {
+        match self {
+            AssignTarget::Ident(ident) if ident.0 == "_" => Ok(()),
+            AssignTarget::Ident(ident) => scope.set(ident.clone(), value),
+            AssignTarget::List(targets) => {
+                let Value::Array(array) = value else {
+                    bail!(Error::UnpackArrayExpected(
+                        self.clone().into(),
+                        value.into()
+                    ));
+                };
+                ensure!(
+                    targets.len() == array.len(),
+                    Error::UnpackInvalidArrayLen(array.len(), targets.len(), self.clone().into())
+                );
+                for (target, array_el) in targets.iter().zip(array) {
+                    target.unpack(array_el, scope)?;
+                }
+                Ok(())
+            }
+        }
+    }
+}
+
 impl Evaluate for Expr {
     fn eval(&self, scope: &ScopeRef) -> Result<Value> {
         Ok(match self {