ic-mops 0.8.3 → 0.8.5

package/.mops/base@0.8.3/src/CertifiedData.mo

@@ -0,0 +1,53 @@
+/// Certified data.
+///
+/// The Internet Computer allows canister smart contracts to store a small amount of data during
+/// update method processing so that during query call processing, the canister can obtain
+/// a certificate about that data.
+///
+/// This module provides a _low-level_ interface to this API, aimed at advanced
+/// users and library implementors. See the Internet Computer Functional
+/// Specification and corresponding documentation for how to use this to make query
+/// calls to your canister tamperproof.
+
+import Prim "mo:⛔";
+
+module {
+
+  /// Set the certified data.
+  ///
+  /// Must be called from an update method, else traps.
+  /// Must be passed a blob of at most 32 bytes, else traps.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// import CertifiedData "mo:base/CertifiedData";
+  /// import Blob "mo:base/Blob";
+  ///
+  /// // Must be in an update call
+  ///
+  /// let array : [Nat8] = [1, 2, 3];
+  /// let blob = Blob.fromArray(array);
+  /// CertifiedData.set(blob);
+  /// ```
+  ///
+  /// See a full example on how to use certified variables here: https://github.com/dfinity/examples/tree/master/motoko/cert-var
+  ///
+  public let set : (data : Blob) -> () = Prim.setCertifiedData;
+
+  /// Gets a certificate
+  ///
+  /// Returns `null` if no certificate is available, e.g. when processing an
+  /// update call or inter-canister call. This returns a non-`null` value only
+  /// when processing a query call.
+  ///
+  /// Example:
+  /// ```motoko no-repl
+  /// import CertifiedData "mo:base/CertifiedData";
+  /// // Must be in a query call
+  ///
+  /// CertifiedData.getCertificate();
+  /// ```
+  /// See a full example on how to use certified variables here: https://github.com/dfinity/examples/tree/master/motoko/cert-var
+  ///
+  public let getCertificate : () -> ?Blob = Prim.getCertificate;
+}

package/.mops/base@0.8.3/src/Char.mo

@@ -0,0 +1,65 @@
+/// Characters
+import Prim "mo:⛔";
+module {
+
+  /// Characters represented as Unicode code points.
+  public type Char = Prim.Types.Char;
+
+  /// Convert character `c` to a word containing its Unicode scalar value.
+  public let toNat32 : (c : Char) -> Nat32 = Prim.charToNat32;
+
+  /// Convert `w` to a character.
+  /// Traps if `w` is not a valid Unicode scalar value.
+  /// Value `w` is valid if, and only if, `w < 0xD800 or (0xE000 <= w and w <= 0x10FFFF)`.
+  public let fromNat32 : (w : Nat32) -> Char = Prim.nat32ToChar;
+
+  /// Convert character `c` to single character text.
+  public let toText : (c : Char) -> Text = Prim.charToText;
+
+  // Not exposed pending multi-char implementation.
+  private let toUpper : (c : Char) -> Char = Prim.charToUpper;
+
+  // Not exposed pending multi-char implementation.
+  private let toLower : (c : Char) -> Char = Prim.charToLower;
+
+  /// Returns `true` when `c` is a decimal digit between `0` and `9`, otherwise `false`.
+  public func isDigit(c : Char) : Bool {
+    Prim.charToNat32(c) -% Prim.charToNat32('0') <= (9 : Nat32)
+  };
+
+  /// Returns the Unicode _White_Space_ property of `c`.
+  public let isWhitespace : (c : Char) -> Bool = Prim.charIsWhitespace;
+
+  /// Returns the Unicode _Lowercase_ property of `c`.
+  public let isLowercase : (c : Char) -> Bool = Prim.charIsLowercase;
+
+  /// Returns the Unicode _Uppercase_ property of `c`.
+  public let isUppercase : (c : Char) -> Bool = Prim.charIsUppercase;
+
+  /// Returns the Unicode _Alphabetic_ property of `c`.
+  public let isAlphabetic : (c : Char) -> Bool = Prim.charIsAlphabetic;
+
+  /// Returns `x == y`.
+  public func equal(x : Char, y : Char) : Bool { x == y };
+
+  /// Returns `x != y`.
+  public func notEqual(x : Char, y : Char) : Bool { x != y };
+
+  /// Returns `x < y`.
+  public func less(x : Char, y : Char) : Bool { x < y };
+
+  /// Returns `x <= y`.
+  public func lessOrEqual(x : Char, y : Char) : Bool { x <= y };
+
+  /// Returns `x > y`.
+  public func greater(x : Char, y : Char) : Bool { x > y };
+
+  /// Returns `x >= y`.
+  public func greaterOrEqual(x : Char, y : Char) : Bool { x >= y };
+
+  /// Returns the order of `x` and `y`.
+  public func compare(x : Char, y : Char) : { #less; #equal; #greater } {
+    if (x < y) { #less } else if (x == y) { #equal } else { #greater }
+  };
+
+}

package/.mops/base@0.8.3/src/Debug.mo

@@ -0,0 +1,56 @@
+/// Utility functions for debugging.
+///
+/// Import from the base library to use this module.
+/// ```motoko name=import
+/// import Debug "mo:base/Debug";
+/// ```
+
+import Prim "mo:⛔";
+module {
+  /// Prints `text` to output stream.
+  ///
+  /// NOTE: The output is placed in the replica log. When running on mainnet,
+  /// this function has no effect.
+  ///
+  /// ```motoko include=import
+  /// Debug.print "Hello New World!";
+  /// Debug.print(debug_show(4)) // Often used with `debug_show` to convert values to Text
+  /// ```
+  public func print(text : Text) {
+    Prim.debugPrint text
+  };
+
+  /// `trap(t)` traps execution with a user-provided diagnostic message.
+  ///
+  /// The caller of a future whose execution called `trap(t)` will
+  /// observe the trap as an `Error` value, thrown at `await`, with code
+  /// `#canister_error` and message `m`. Here `m` is a more descriptive `Text`
+  /// message derived from the provided `t`. See example for more details.
+  ///
+  /// NOTE: Other execution environments that cannot handle traps may only
+  /// propagate the trap and terminate execution, with or without some
+  /// descriptive message.
+  ///
+  /// ```motoko
+  /// import Debug "mo:base/Debug";
+  /// import Error "mo:base/Error";
+  ///
+  /// actor {
+  ///   func fail() : async () {
+  ///     Debug.trap("user provided error message");
+  ///   };
+  ///
+  ///   public func foo() : async () {
+  ///     try {
+  ///       await fail();
+  ///     } catch e {
+  ///       let code = Error.code(e); // evaluates to #canister_error
+  ///       let message = Error.message(e); // contains user provided error message
+  ///     }
+  ///   };
+  /// }
+  /// ```
+  public func trap(errorMessage : Text) : None {
+    Prim.trap errorMessage
+  }
+}

package/.mops/base@0.8.3/src/Deque.mo

@@ -0,0 +1,243 @@
+/// Double-ended queue (deque) of a generic element type `T`.
+///
+/// The interface to deques is purely functional, not imperative, and deques are immutable values.
+/// In particular, deque operations such as push and pop do not update their input deque but,  instead, return the
+/// value of the modified deque, alongside any other data.
+/// The input deque is left unchanged.
+///
+/// Examples of use-cases:
+/// Queue (FIFO) by using `pushBack()` and `popFront()`.
+/// Stack (LIFO) by using `pushFront()` and `popFront()`.
+///
+/// A deque is internally implemented as two lists, a head access list and a (reversed) tail access list,
+/// that are dynamically size-balanced by splitting.
+///
+/// Construction: Create a new deque with the `empty<T>()` function.
+///
+/// Note on the costs of push and pop functions:
+/// * Runtime: `O(1) amortized costs, `O(n)` worst case cost per single call.
+/// * Space: `O(1) amortized costs, `O(n)` worst case cost per single call.
+///
+/// `n` denotes the number of elements stored in the deque.
+
+import List "List";
+import P "Prelude";
+
+module {
+  type List<T> = List.List<T>;
+
+  /// Double-ended queue (deque) data type.
+  public type Deque<T> = (List<T>, List<T>);
+
+  /// Create a new empty deque.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  ///
+  /// Deque.empty<Nat>()
+  /// ```
+  ///
+  /// Runtime: `O(1)`.
+  ///
+  /// Space: `O(1)`.
+  public func empty<T>() : Deque<T> { (List.nil(), List.nil()) };
+
+  /// Determine whether a deque is empty.
+  /// Returns true if `deque` is empty, otherwise `false`.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  ///
+  /// let deque = Deque.empty<Nat>();
+  /// Deque.isEmpty(deque) // => true
+  /// ```
+  ///
+  /// Runtime: `O(1)`.
+  ///
+  /// Space: `O(1)`.
+  public func isEmpty<T>(deque : Deque<T>) : Bool {
+    switch deque {
+      case (f, r) { List.isNil(f) and List.isNil(r) }
+    }
+  };
+
+  func check<T>(q : Deque<T>) : Deque<T> {
+    switch q {
+      case (null, r) {
+        let (a, b) = List.split(List.size(r) / 2, r);
+        (List.reverse(b), a)
+      };
+      case (f, null) {
+        let (a, b) = List.split(List.size(f) / 2, f);
+        (a, List.reverse(b))
+      };
+      case q { q }
+    }
+  };
+
+  /// Insert a new element on the front end of a deque.
+  /// Returns the new deque with `element` in the front followed by the elements of `deque`.
+  ///
+  /// This may involve dynamic rebalancing of the two, internally used lists.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  ///
+  /// Deque.pushFront(Deque.pushFront(Deque.empty<Nat>(), 2), 1) // deque with elements [1, 2]
+  /// ```
+  ///
+  /// Runtime: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// Space: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// `n` denotes the number of elements stored in the deque.
+  public func pushFront<T>(deque : Deque<T>, element : T) : Deque<T> {
+    check(List.push(element, deque.0), deque.1)
+  };
+
+  /// Inspect the optional element on the front end of a deque.
+  /// Returns `null` if `deque` is empty. Otherwise, the front element of `deque`.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  ///
+  /// let deque = Deque.pushFront(Deque.pushFront(Deque.empty<Nat>(), 2), 1);
+  /// Deque.peekFront(deque) // => ?1
+  /// ```
+  ///
+  /// Runtime: `O(1)`.
+  ///
+  /// Space: `O(1)`.
+  ///
+  public func peekFront<T>(deque : Deque<T>) : ?T {
+    switch deque {
+      case (?(x, f), r) { ?x };
+      case (null, ?(x, r)) { ?x };
+      case _ { null }
+    }
+  };
+
+  /// Remove the element on the front end of a deque.
+  /// Returns `null` if `deque` is empty. Otherwise, it returns a pair of
+  /// the first element and a new deque that contains all the remaining elements of `deque`.
+  ///
+  /// This may involve dynamic rebalancing of the two, internally used lists.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  /// import Debug "mo:base/Debug";
+  /// let initial = Deque.pushFront(Deque.pushFront(Deque.empty<Nat>(), 2), 1);
+  /// // initial deque with elements [1, 2]
+  /// let reduced = Deque.popFront(initial);
+  /// switch reduced {
+  ///   case null {
+  ///     Debug.trap "Empty queue impossible"
+  ///   };
+  ///   case (?result) {
+  ///     let removedElement = result.0; // 1
+  ///     let reducedDeque = result.1; // deque with element [2].
+  ///   }
+  /// }
+  /// ```
+  ///
+  /// Runtime: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// Space: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// `n` denotes the number of elements stored in the deque.
+  public func popFront<T>(deque : Deque<T>) : ?(T, Deque<T>) {
+    switch deque {
+      case (?(x, f), r) { ?(x, check(f, r)) };
+      case (null, ?(x, r)) { ?(x, check(null, r)) };
+      case _ { null }
+    }
+  };
+
+  /// Insert a new element on the back end of a deque.
+  /// Returns the new deque with all the elements of `deque`, followed by `element` on the back.
+  ///
+  /// This may involve dynamic rebalancing of the two, internally used lists.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  ///
+  /// Deque.pushBack(Deque.pushBack(Deque.empty<Nat>(), 1), 2) // deque with elements [1, 2]
+  /// ```
+  ///
+  /// Runtime: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// Space: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// `n` denotes the number of elements stored in the deque.
+  public func pushBack<T>(deque : Deque<T>, element : T) : Deque<T> {
+    check(deque.0, List.push(element, deque.1))
+  };
+
+  /// Inspect the optional element on the back end of a deque.
+  /// Returns `null` if `deque` is empty. Otherwise, the back element of `deque`.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  ///
+  /// let deque = Deque.pushBack(Deque.pushBack(Deque.empty<Nat>(), 1), 2);
+  /// Deque.peekBack(deque) // => ?2
+  /// ```
+  ///
+  /// Runtime: `O(1)`.
+  ///
+  /// Space: `O(1)`.
+  ///
+  public func peekBack<T>(deque : Deque<T>) : ?T {
+    switch deque {
+      case (f, ?(x, r)) { ?x };
+      case (?(x, r), null) { ?x };
+      case _ { null }
+    }
+  };
+
+  /// Remove the element on the back end of a deque.
+  /// Returns `null` if `deque` is empty. Otherwise, it returns a pair of
+  /// a new deque that contains the remaining elements of `deque`
+  /// and, as the second pair item, the removed back element.
+  ///
+  /// This may involve dynamic rebalancing of the two, internally used lists.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Deque "mo:base/Deque";
+  /// import Debug "mo:base/Debug";
+  ///
+  /// let initial = Deque.pushBack(Deque.pushBack(Deque.empty<Nat>(), 1), 2);
+  /// // initial deque with elements [1, 2]
+  /// let reduced = Deque.popBack(initial);
+  /// switch reduced {
+  ///   case null {
+  ///     Debug.trap "Empty queue impossible"
+  ///   };
+  ///   case (?result) {
+  ///     let reducedDeque = result.0; // deque with element [1].
+  ///     let removedElement = result.1; // 2
+  ///   }
+  /// }
+  /// ```
+  ///
+  /// Runtime: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// Space: `O(n)` worst-case, amortized to `O(1)`.
+  ///
+  /// `n` denotes the number of elements stored in the deque.
+  public func popBack<T>(deque : Deque<T>) : ?(Deque<T>, T) {
+    switch deque {
+      case (f, ?(x, r)) { ?(check(f, r), x) };
+      case (?(x, f), null) { ?(check(f, null), x) };
+      case _ { null }
+    }
+  }
+}

package/.mops/base@0.8.3/src/Error.mo

@@ -0,0 +1,68 @@
+/// Error values and inspection.
+///
+/// The `Error` type is the argument to `throw`, parameter of `catch`.
+/// The `Error` type is opaque.
+
+import Prim "mo:⛔";
+
+module {
+
+  /// Error value resulting from  `async` computations
+  public type Error = Prim.Types.Error;
+
+  /// Error code to classify different kinds of user and system errors:
+  /// ```motoko
+  /// type ErrorCode = {
+  ///   // Fatal error.
+  ///   #system_fatal;
+  ///   // Transient error.
+  ///   #system_transient;
+  ///   // Destination invalid.
+  ///   #destination_invalid;
+  ///   // Explicit reject by canister code.
+  ///   #canister_reject;
+  ///   // Canister trapped.
+  ///   #canister_error;
+  ///   // Future error code (with unrecognized numeric code).
+  ///   #future : Nat32;
+  ///   // Error issuing inter-canister call
+  ///   // (indicating destination queue full or freezing threshold crossed).
+  ///   #call_error : { err_code :  Nat32 }
+  /// };
+  /// ```
+  public type ErrorCode = Prim.ErrorCode;
+
+  /// Create an error from the message with the code `#canister_reject`.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Error "mo:base/Error";
+  ///
+  /// Error.reject("Example error") // can be used as throw argument
+  /// ```
+  public let reject : (message : Text) -> Error = Prim.error;
+
+  /// Returns the code of an error.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Error "mo:base/Error";
+  ///
+  /// let error = Error.reject("Example error");
+  /// Error.code(error) // #canister_reject
+  /// ```
+  public let code : (error : Error) -> ErrorCode = Prim.errorCode;
+
+  /// Returns the message of an error.
+  ///
+  /// Example:
+  /// ```motoko
+  /// import Error "mo:base/Error";
+  /// import Debug "mo:base/Debug";
+  ///
+  /// let error = Error.reject("Example error");
+  /// Error.message(error) // "Example error"
+  /// ```
+  public let message : (error : Error) -> Text = Prim.errorMessage;
+
+}

package/.mops/base@0.8.3/src/ExperimentalCycles.mo

@@ -0,0 +1,151 @@
+/// Managing cycles within actors on the Internet Computer (IC).
+///
+/// The usage of the Internet Computer is measured, and paid for, in _cycles_.
+/// This library provides imperative operations for observing cycles, transferring cycles, and
+/// observing refunds of cycles.
+///
+/// **WARNING:** This low-level API is **experimental** and likely to change or even disappear.
+/// Dedicated syntactic support for manipulating cycles may be added to the language in future, obsoleting this library.
+///
+/// **NOTE:** Since cycles measure computational resources, the value of  `balance()` can change from one call to the next.
+///
+/// Example for use on IC:
+/// ```motoko no-repl
+/// import Cycles "mo:base/ExperimentalCycles";
+/// import Debug "mo:base/Debug";
+///
+/// actor {
+///   public func main() : async() {
+///     Debug.print("Main balance: " # debug_show(Cycles.balance()));
+///     Cycles.add(15_000_000);
+///     await operation(); // accepts 10_000_000 cycles
+///     Debug.print("Main refunded: " # debug_show(Cycles.refunded())); // 5_000_000
+///     Debug.print("Main balance: " # debug_show(Cycles.balance())); // decreased by around 10_000_000
+///   };
+///
+///   func operation() : async() {
+///     Debug.print("Operation balance: " # debug_show(Cycles.balance()));
+///     Debug.print("Operation available: " # debug_show(Cycles.available()));
+///     let obtained = Cycles.accept(10_000_000);
+///     Debug.print("Operation obtained: " # debug_show(obtained)); // => 10_000_000
+///     Debug.print("Operation balance: " # debug_show(Cycles.balance())); // increased by 10_000_000
+///     Debug.print("Operation available: " # debug_show(Cycles.available())); // decreased by 10_000_000
+///   }
+/// }
+/// ```
+import Prim "mo:⛔";
+module {
+
+  /// Returns the actor's current balance of cycles as `amount`.
+  ///
+  /// Example for use on the IC:
+  /// ```motoko no-repl
+  /// import Cycles "mo:base/ExperimentalCycles";
+  /// import Debug "mo:base/Debug";
+  ///
+  /// actor {
+  ///   public func main() : async() {
+  ///     let balance = Cycles.balance();
+  ///     Debug.print("Balance: " # debug_show(balance));
+  ///   }
+  /// }
+  /// ```
+  public let balance : () -> (amount : Nat) = Prim.cyclesBalance;
+
+  /// Returns the currently available `amount` of cycles.
+  /// The amount available is the amount received in the current call,
+  /// minus the cumulative amount `accept`ed by this call.
+  /// On exit from the current shared function or async expression via `return` or `throw`,
+  /// any remaining available amount is automatically refunded to the caller/context.
+  ///
+  /// Example for use on the IC:
+  /// ```motoko no-repl
+  /// import Cycles "mo:base/ExperimentalCycles";
+  /// import Debug "mo:base/Debug";
+  ///
+  /// actor {
+  ///   public func main() : async() {
+  ///     let available = Cycles.available();
+  ///     Debug.print("Available: " # debug_show(available));
+  ///   }
+  /// }
+  /// ```
+  public let available : () -> (amount : Nat) = Prim.cyclesAvailable;
+
+  /// Transfers up to `amount` from `available()` to `balance()`.
+  /// Returns the amount actually transferred, which may be less than
+  /// requested, for example, if less is available, or if canister balance limits are reached.
+  ///
+  /// Example for use on the IC (for simplicity, only transferring cycles to itself):
+  /// ```motoko no-repl
+  /// import Cycles "mo:base/ExperimentalCycles";
+  /// import Debug "mo:base/Debug";
+  ///
+  /// actor {
+  ///   public func main() : async() {
+  ///     Cycles.add(15_000_000);
+  ///     await operation(); // accepts 10_000_000 cycles
+  ///   };
+  ///
+  ///   func operation() : async() {
+  ///     let obtained = Cycles.accept(10_000_000);
+  ///     Debug.print("Obtained: " # debug_show(obtained)); // => 10_000_000
+  ///   }
+  /// }
+  /// ```
+  public let accept : (amount : Nat) -> (accepted : Nat) = Prim.cyclesAccept;
+
+  /// Indicates additional `amount` of cycles to be transferred in
+  /// the next call, that is, evaluation of a shared function call or
+  /// async expression.
+  /// Traps if the current total would exceed `2 ** 128` cycles.
+  /// Upon the call, but not before, the total amount of cycles ``add``ed since
+  /// the last call is deducted from `balance()`.
+  /// If this total exceeds `balance()`, the caller traps, aborting the call.
+  ///
+  /// **Note**: The implicit register of added amounts is reset to zero on entry to
+  /// a shared function and after each shared function call or resume from an await.
+  ///
+  /// Example for use on the IC (for simplicity, only transferring cycles to itself):
+  /// ```motoko no-repl
+  /// import Cycles "mo:base/ExperimentalCycles";
+  ///
+  /// actor {
+  ///   func operation() : async() {
+  ///     ignore Cycles.accept(10_000_000);
+  ///   };
+  ///
+  ///   public func main() : async() {
+  ///     Cycles.add(15_000_000);
+  ///     await operation();
+  ///   }
+  /// }
+  /// ```
+  public let add : (amount : Nat) -> () = Prim.cyclesAdd;
+
+  /// Reports `amount` of cycles refunded in the last `await` of the current
+  /// context, or zero if no await has occurred yet.
+  /// Calling `refunded()` is solely informational and does not affect `balance()`.
+  /// Instead, refunds are automatically added to the current balance,
+  /// whether or not `refunded` is used to observe them.
+  ///
+  /// Example for use on the IC (for simplicity, only transferring cycles to itself):
+  /// ```motoko no-repl
+  /// import Cycles "mo:base/ExperimentalCycles";
+  /// import Debug "mo:base/Debug";
+  ///
+  /// actor {
+  ///   func operation() : async() {
+  ///     ignore Cycles.accept(10_000_000);
+  ///   };
+  ///
+  ///   public func main() : async() {
+  ///     Cycles.add(15_000_000);
+  ///     await operation(); // accepts 10_000_000 cycles
+  ///     Debug.print("Refunded: " # debug_show(Cycles.refunded())); // 5_000_000
+  ///   }
+  /// }
+  /// ```
+  public let refunded : () -> (amount : Nat) = Prim.cyclesRefunded;
+
+}