Add support for builtin functions (#2508)

This PR adds the necessary infrastructure to support builtin functions
in the lowerer and prepares the groundwork for providing language
service support for const evaluated expressions. These changes are
related because builtin function calls are a kind of const evaluated
expression.

The PR can be understood in two areas:
1. The part that prepares the groundwork for providing language service
support for const evaluated expressions, which includes two changes:
const expressions are now eagerly evaluated in the lowerer; and the
`Expr` type is augmented with the result of const evaluating the
expression, instead of just storing the final value in the AST, this
will provide the language service with the necessary span and type
information for its hover, jump to definition, and type hint features.
2. The part that adds the necessary infrastructure to support builtin
functions in the lowerer: this changes include adding a polymorphic
dispatch mechanism for QASM bultins and wiring this mechanism to the
`Lowerer::lower_function_call_expr` method.

Author: orpuente-MS

compiler/qsc_qasm/src/compiler.rs

@@ -816,17 +816,19 @@ impl QasmCompiler {
                         build_path_ident_expr("ApplyOperationPowerA", modifier.span, stmt.span);
                 }
                 semast::GateModifierKind::Ctrl(num_ctrls) => {
+                    let num_ctrls = num_ctrls.get_const_u32()?;
+
                     // remove the last n qubits from the qubit list
-                    if qubits.len() < *num_ctrls as usize {
+                    if qubits.len() < num_ctrls as usize {
                         let kind = CompilerErrorKind::InvalidNumberOfQubitArgs(
-                            *num_ctrls as usize,
+                            num_ctrls as usize,
                             qubits.len(),
                             modifier.span,
                         );
                         self.push_compiler_error(kind);
                         return None;
                     }
-                    let ctrl = qubits.split_off(qubits.len().saturating_sub(*num_ctrls as usize));
+                    let ctrl = qubits.split_off(qubits.len().saturating_sub(num_ctrls as usize));
                     let ctrls = build_expr_array_expr(ctrl, modifier.span);
                     args = build_tuple_expr(vec![ctrls, args]);
                     callee = build_unary_op_expr(
@@ -836,17 +838,19 @@ impl QasmCompiler {
                     );
                 }
                 semast::GateModifierKind::NegCtrl(num_ctrls) => {
+                    let num_ctrls = num_ctrls.get_const_u32()?;
+
                     // remove the last n qubits from the qubit list
-                    if qubits.len() < *num_ctrls as usize {
+                    if qubits.len() < num_ctrls as usize {
                         let kind = CompilerErrorKind::InvalidNumberOfQubitArgs(
-                            *num_ctrls as usize,
+                            num_ctrls as usize,
                             qubits.len(),
                             modifier.span,
                         );
                         self.push_compiler_error(kind);
                         return None;
                     }
-                    let ctrl = qubits.split_off(qubits.len().saturating_sub(*num_ctrls as usize));
+                    let ctrl = qubits.split_off(qubits.len().saturating_sub(num_ctrls as usize));
                     let ctrls = build_expr_array_expr(ctrl, modifier.span);
                     let lit_0 = build_lit_int_expr(0, Span::default());
                     args = build_tuple_expr(vec![lit_0, callee, ctrls, args]);
@@ -1024,11 +1028,12 @@ impl QasmCompiler {
 
         let stmt = match self.config.qubit_semantics {
             QubitSemantics::QSharp => {
-                managed_qubit_alloc_array(name, stmt.size, stmt.span, name_span, stmt.size_span)
+                let size = stmt.size.get_const_u32()?;
+                managed_qubit_alloc_array(name, size, stmt.span, name_span, stmt.size_span)
             }
             QubitSemantics::Qiskit => build_unmanaged_qubit_alloc_array(
                 name,
-                stmt.size,
+                stmt.size.get_const_u32()?,
                 stmt.span,
                 name_span,
                 stmt.size_span,
@@ -1143,6 +1148,12 @@ impl QasmCompiler {
     }
 
     fn compile_expr(&mut self, expr: &semast::Expr) -> qsast::Expr {
+        if expr.ty.is_const() {
+            if let Some(value) = expr.get_const_value() {
+                return self.compile_literal_expr(&value, expr.span);
+            }
+        }
+
         match expr.kind.as_ref() {
             semast::ExprKind::Err => qsast::Expr {
                 span: expr.span,
@@ -1162,6 +1173,13 @@ impl QasmCompiler {
             semast::ExprKind::FunctionCall(function_call) => {
                 self.compile_function_call_expr(function_call)
             }
+            semast::ExprKind::BuiltinFunctionCall(_) => {
+                let Some(value) = expr.get_const_value() else {
+                    unreachable!("builtin function call exprs are only lowered if they succeed");
+                };
+
+                self.compile_literal_expr(&value, expr.span)
+            }
             semast::ExprKind::Cast(cast) => self.compile_cast_expr(cast),
             semast::ExprKind::IndexExpr(index_expr) => self.compile_index_expr(index_expr),
             semast::ExprKind::Paren(pexpr) => self.compile_paren_expr(pexpr, expr.span),

compiler/qsc_qasm/src/semantic.rs

@@ -5,7 +5,7 @@ use crate::io::InMemorySourceResolver;
 use crate::io::SourceResolver;
 use crate::parser::QasmSource;
 
-use lowerer::Lowerer;
+pub(crate) use lowerer::Lowerer;
 use qsc_frontend::compile::SourceMap;
 use qsc_frontend::error::WithSource;
 

compiler/qsc_qasm/src/semantic/ast.rs

@@ -479,17 +479,90 @@ impl Display for ExprStmt {
 pub struct Expr {
     pub span: Span,
     pub kind: Box<ExprKind>,
+    pub const_value: Option<LiteralKind>,
     pub ty: super::types::Type,
 }
 
 impl Display for Expr {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         writeln_header(f, "Expr", self.span)?;
         writeln_field(f, "ty", &self.ty)?;
+        if self.const_value.is_some() {
+            writeln_opt_field(f, "const_value", self.const_value.as_ref())?;
+        }
         write_field(f, "kind", &self.kind)
     }
 }
 
+impl Expr {
+    pub fn new(span: Span, kind: ExprKind, ty: super::types::Type) -> Self {
+        Self {
+            span,
+            kind: kind.into(),
+            ty,
+            const_value: None,
+        }
+    }
+
+    pub fn int(val: i64, span: Span) -> Self {
+        let val = LiteralKind::Int(val);
+        Expr {
+            span,
+            kind: Box::new(ExprKind::Lit(val.clone())),
+            ty: super::types::Type::Int(None, true),
+            const_value: Some(val),
+        }
+    }
+
+    pub fn uint(val: i64, span: Span) -> Self {
+        let val = LiteralKind::Int(val);
+        Expr {
+            span,
+            kind: Box::new(ExprKind::Lit(val.clone())),
+            ty: super::types::Type::UInt(None, true),
+            const_value: Some(val),
+        }
+    }
+
+    pub fn float(val: f64, span: Span) -> Self {
+        let val = LiteralKind::Float(val);
+        Expr {
+            span,
+            kind: Box::new(ExprKind::Lit(val.clone())),
+            ty: super::types::Type::Float(None, true),
+            const_value: Some(val),
+        }
+    }
+
+    pub fn builtin_funcall(
+        name: &str,
+        span: Span,
+        fn_name_span: Span,
+        function_ty: crate::semantic::types::Type,
+        args: &[Expr],
+        output: LiteralKind,
+    ) -> Self {
+        let crate::semantic::types::Type::Function(_, ty) = &function_ty else {
+            unreachable!("if we hit this there is a bug in the builtin functions implementation");
+        };
+
+        let ty = ty.as_ref().clone();
+
+        Self {
+            span,
+            kind: Box::new(ExprKind::BuiltinFunctionCall(BuiltinFunctionCall {
+                span,
+                fn_name_span,
+                name: name.into(),
+                args: args.into(),
+                function_ty,
+            })),
+            ty,
+            const_value: Some(output),
+        }
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct Set {
     pub span: Span,
@@ -539,8 +612,12 @@ impl Display for QuantumGateModifier {
 pub enum GateModifierKind {
     Inv,
     Pow(Expr),
-    Ctrl(u32),
-    NegCtrl(u32),
+    /// This `Expr` is const, but we don't substitute by the `LiteralKind` yet
+    /// to be able to provide Span and Type information to the Language Service.
+    Ctrl(Expr),
+    /// This `Expr` is const, but we don't substitute by the `LiteralKind` yet
+    /// to be able to provide Span and Type information to the Language Service.
+    NegCtrl(Expr),
 }
 
 impl Display for GateModifierKind {
@@ -692,7 +769,9 @@ impl Display for QubitDeclaration {
 pub struct QubitArrayDeclaration {
     pub span: Span,
     pub symbol_id: SymbolId,
-    pub size: u32,
+    /// This `Expr` is const, but we don't substitute by the `LiteralKind` yet
+    /// to be able to provide Span and Type information to the Language Service.
+    pub size: Expr,
     pub size_span: Span,
 }
 
@@ -991,6 +1070,7 @@ pub enum ExprKind {
     BinaryOp(BinaryOpExpr),
     Lit(LiteralKind),
     FunctionCall(FunctionCall),
+    BuiltinFunctionCall(BuiltinFunctionCall),
     Cast(Cast),
     IndexExpr(IndexExpr),
     Paren(Expr),
@@ -1007,6 +1087,7 @@ impl Display for ExprKind {
             ExprKind::BinaryOp(expr) => write!(f, "{expr}"),
             ExprKind::Lit(lit) => write!(f, "Lit: {lit}"),
             ExprKind::FunctionCall(call) => write!(f, "{call}"),
+            ExprKind::BuiltinFunctionCall(call) => write!(f, "{call}"),
             ExprKind::Cast(expr) => write!(f, "{expr}"),
             ExprKind::IndexExpr(expr) => write!(f, "{expr}"),
             ExprKind::Paren(expr) => write!(f, "Paren {expr}"),
@@ -1104,6 +1185,29 @@ impl Display for FunctionCall {
     }
 }
 
+/// The information in this struct is aimed to be consumed
+/// by the language service. The result of the computation
+/// is already stored in the [`Expr::const_value`] field by
+/// the time the `Expr` is created.
+#[derive(Clone, Debug)]
+pub struct BuiltinFunctionCall {
+    pub span: Span,
+    pub fn_name_span: Span,
+    pub name: Rc<str>,
+    pub function_ty: crate::semantic::types::Type,
+    pub args: Rc<[Expr]>,
+}
+
+impl Display for BuiltinFunctionCall {
+    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+        writeln_header(f, "BuiltinFunctionCall", self.span)?;
+        writeln_field(f, "fn_name_span", &self.fn_name_span)?;
+        writeln_field(f, "name", &self.name)?;
+        writeln_field(f, "function_ty", &self.function_ty)?;
+        write_list_field(f, "args", self.args.iter())
+    }
+}
+
 #[derive(Clone, Debug)]
 pub struct Cast {
     pub span: Span,
@@ -1216,11 +1320,11 @@ impl Array {
                 data,
                 dims: (&dims[1..]).into(),
             };
-            let expr = Expr {
-                span: Default::default(),
-                kind: Box::new(ExprKind::Lit(LiteralKind::Array(array))),
-                ty: super::types::Type::make_array_ty(&dims[1..], base_ty),
-            };
+            let expr = Expr::new(
+                Default::default(),
+                ExprKind::Lit(LiteralKind::Array(array)),
+                super::types::Type::make_array_ty(&dims[1..], base_ty),
+            );
             let dim_size = dims[0] as usize;
             vec![expr; dim_size]
         }

compiler/qsc_qasm/src/semantic/const_eval.rs

@@ -23,7 +23,7 @@ use thiserror::Error;
 
 #[derive(Clone, Debug, Diagnostic, Eq, Error, PartialEq)]
 pub enum ConstEvalError {
-    #[error("division by error during const evaluation")]
+    #[error("division by zero error during const evaluation")]
     #[diagnostic(code("Qasm.Lowerer.DivisionByZero"))]
     DivisionByZero(#[label] Span),
     #[error("expression must be const")]
@@ -38,6 +38,9 @@ pub enum ConstEvalError {
     #[error("uint expression must evaluate to a non-negative value, but it evaluated to {0}")]
     #[diagnostic(code("Qasm.Lowerer.NegativeUIntValue"))]
     NegativeUIntValue(i64, #[label] Span),
+    #[error("{0}")]
+    #[diagnostic(code("Qasm.Lowerer.NoValidOverloadForBuiltinFunction"))]
+    NoValidOverloadForBuiltinFunction(String, #[label] Span),
     #[error("too many indices provided")]
     #[diagnostic(code("Qasm.Lowerer.TooManyIndices"))]
     TooManyIndices(#[label] Span),
@@ -50,10 +53,33 @@ pub enum ConstEvalError {
 }
 
 impl Expr {
+    /// A builder pattern that initializes the [`Expr::const_value`] field
+    /// to the result of const evaluating the expression.
+    pub(crate) fn with_const_value(mut self, ctx: &mut Lowerer) -> Self {
+        self.const_value = self.const_eval(ctx);
+        self
+    }
+
+    pub(crate) fn get_const_value(&self) -> Option<LiteralKind> {
+        self.const_value.clone()
+    }
+
+    pub(crate) fn get_const_u32(&self) -> Option<u32> {
+        if let Some(LiteralKind::Int(val)) = self.get_const_value() {
+            u32::try_from(val).ok()
+        } else {
+            None
+        }
+    }
+
     /// Tries to evaluate the expression. It takes the current `Lowerer` as
     /// the evaluation context to resolve symbols and push errors in case
     /// of failure.
-    pub(crate) fn const_eval(&self, ctx: &mut Lowerer) -> Option<LiteralKind> {
+    fn const_eval(&self, ctx: &mut Lowerer) -> Option<LiteralKind> {
+        if self.const_value.is_some() {
+            return self.const_value.clone();
+        }
+
         let ty = &self.ty;
 
         if ty.is_err() {
@@ -72,6 +98,7 @@ impl Expr {
             ExprKind::BinaryOp(binary_op_expr) => binary_op_expr.const_eval(ctx),
             ExprKind::Lit(literal_kind) => Some(literal_kind.clone()),
             ExprKind::FunctionCall(function_call) => function_call.const_eval(ctx, ty),
+            ExprKind::BuiltinFunctionCall(_) => self.get_const_value(),
             ExprKind::Cast(cast) => cast.const_eval(ctx),
             ExprKind::IndexExpr(index_expr) => index_expr.const_eval(ctx, ty),
             ExprKind::Paren(expr) => expr.const_eval(ctx),
@@ -83,7 +110,10 @@ impl Expr {
 
 impl SymbolId {
     fn const_eval(self, ctx: &mut Lowerer) -> Option<LiteralKind> {
-        ctx.symbols[self].get_const_expr()?.const_eval(ctx)
+        // Expressions associated to const symbols are evaluated
+        // when they are pushed in the symbol table. So, we just
+        // need to get the already computed value here.
+        ctx.symbols[self].get_const_value()
     }
 }
 

compiler/qsc_qasm/src/semantic/error.rs

@@ -30,9 +30,6 @@ pub enum SemanticErrorKind {
     #[error("array literals are only allowed in classical declarations")]
     #[diagnostic(code("Qasm.Lowerer.ArrayLiteralInNonClassicalDecl"))]
     ArrayLiteralInNonClassicalDecl(#[label] Span),
-    #[error("array size must be a non-negative integer const expression")]
-    #[diagnostic(code("Qasm.Lowerer.ArraySizeMustBeNonNegativeConstExpr"))]
-    ArraySizeMustBeNonNegativeConstExpr(#[label] Span),
     #[error("first quantum register is of type {0} but found an argument of type {1}")]
     #[diagnostic(code("Qasm.Lowerer.BroadcastCallQuantumArgsDisagreeInSize"))]
     BroadcastCallQuantumArgsDisagreeInSize(String, String, #[label] Span),
@@ -88,6 +85,15 @@ pub enum SemanticErrorKind {
     #[error("{0} must be a const expression")]
     #[diagnostic(code("Qasm.Lowerer.ExprMustBeConst"))]
     ExprMustBeConst(String, #[label] Span),
+    #[error("{0} must be an integer")]
+    #[diagnostic(code("Qasm.Lowerer.ExprMustBeInt"))]
+    ExprMustBeInt(String, #[label] Span),
+    #[error("{0} must be a non-negative integer")]
+    #[diagnostic(code("Qasm.Lowerer.ExprMustBeNonNegativeInt"))]
+    ExprMustBeNonNegativeInt(String, #[label] Span),
+    #[error("{0} must be a positive integer")]
+    #[diagnostic(code("Qasm.Lowerer.ExprMustBePositiveInt"))]
+    ExprMustBePositiveInt(String, #[label] Span),
     #[error("{0} must fit in a u32")]
     #[diagnostic(code("Qasm.Lowerer.ExprMustFitInU32"))]
     ExprMustFitInU32(String, #[label] Span),
@@ -187,6 +193,10 @@ pub enum SemanticErrorKind {
     #[error("range expressions must have a stop when used in for loops")]
     #[diagnostic(code("Qasm.Lowerer.RangeExpressionsMustHaveStop"))]
     RangeExpressionsMustHaveStop(#[label] Span),
+    #[error("redefined builtin function: {0}")]
+    #[help("builtin functions cannot be redefined, try choosing another name")]
+    #[diagnostic(code("Qasm.Lowerer.RedefinedBuiltinFunction"))]
+    RedefinedBuiltinFunction(String, #[label] Span),
     #[error("redefined symbol: {0}")]
     #[diagnostic(code("Qasm.Lowerer.RedefinedSymbol"))]
     RedefinedSymbol(String, #[label] Span),
@@ -223,9 +233,6 @@ pub enum SemanticErrorKind {
     #[error("types differ by dimensions and are incompatible")]
     #[diagnostic(code("Qasm.Lowerer.TypeRankError"))]
     TypeRankError(#[label] Span),
-    #[error("type width must be a positive integer const expression")]
-    #[diagnostic(code("Qasm.Lowerer.TypeWidthMustBePositiveIntConstExpr"))]
-    TypeWidthMustBePositiveIntConstExpr(#[label] Span),
     #[error("undefined symbol: {0}")]
     #[diagnostic(code("Qasm.Lowerer.UndefinedSymbol"))]
     UndefinedSymbol(String, #[label] Span),