From 2f2a151fb0e941b358f4b6e98746ed1b27f7127d Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Tue, 4 Feb 2025 20:25:55 -0500 Subject: [PATCH 01/94] docs: rewrite and restructure meet-motoko.md --- doc/md/meet-motoko.md | 105 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 102 insertions(+), 3 deletions(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index aa943c78585..e6a290d3c0b 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -2,7 +2,106 @@ sidebar_position: 1 --- -# Meet Motoko: The language shaping the future of Web3 +# Meet Motoko: The language of the Internet Computer -Hello, world example -Brief description of what Motoko is / key design aspects +import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; + +import Tabs from "@theme/Tabs"; + +import TabItem from "@theme/TabItem"; + + + +Logo + +## Introduction + +Motoko is the native programming language of the Internet Computer. It’s a modern, **actor-based** language designed for safety, efficiency, and scalability. With native support for asynchronous messaging, WebAssembly (Wasm) interoperability, robust type safety, and data persistence, Motoko makes it easy to build secure and performant decentralized web applications. + +## Install Motoko + +Follow these steps to set up your Motoko development environment: + +1. **Install the IC SDK (DFX)** + + ```bash + sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)" + ``` + + Verify the installation with: + + ```bash + dfx --version + ``` + +2. **Install Visual Studio Code** + - Download VSCode from [https://code.visualstudio.com](https://code.visualstudio.com) + - Follow the installation instructions for your operating system + +3. **Install Motoko Extension** + - Open VSCode + - Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X) + - Search for "Motoko" + - Install the official Motoko extension + +## Explore Motoko use cases + + + + + +Motoko makes it easy to build scalable backend services for web applications. + +1. [Deploy your first Motoko canister.](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-1/1.1-live-demo) + +2. [Expand your application by calling external APIs from a Motoko canister.](https://internetcomputer.org/docs/current/developer-docs/backend/https-outcalls) + +3. [Connect your Motoko backend with a frontend canister.](https://internetcomputer.org/docs/current/references/samples/svelte/svelte-motoko-starter/) + + + + + +Build decentralized finance (DeFi) applications using Motoko. + +1. [Set up an ICRC-1 canister.](https://internetcomputer.org/docs/current/tutorials/hackathon-prep-course/integrating-with-tokens/#deploying-an-icrc-1-ledger-locally) + +2. [Create a decentralized exchange (DEX)](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-5/5.3-token-swap-tutorial/) + + + + + +Develop cross-chain applications and integrate with other blockchains. + +1. [Explore Bitcoin integration (ckBTC).](https://internetcomputer.org/docs/current/developer-docs/multi-chain/bitcoin/overview) + +2. [Explore Ethereum integration (ckETH).](https://internetcomputer.org/ethereum-integration/) + +3. [Explore Chain-Key ERC-20 (ckERC-20) integrations.](https://internetcomputer.org/docs/current/developer-docs/multi-chain/chain-key-tokens/ckerc20/overview/) + + + + + +Manage digital assets on the Internet Computer. + +1. [Learn how to deploy NFTs on ICP](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-5/5.4-NFT-tutorial) + + + + + +## Quick References + +For developers looking for quick access to key resources, here are direct links to the base library and useful examples: + +- **[Motoko base library](https://internetcomputer.org/docs/current/motoko/main/base/)** – Browse core modules and functions. + +- **[Examples:](https://internetcomputer.org/docs/current/motoko/main/getting-started/examples)** + +### Share your feedback + +Was this page helpful? [Yes] [No] + +If you have any questions or suggestions, join the [DFINITY Developer Forum](https://forum.dfinity.org/) to share your feedback. Connect with the community, collaborate with other developers, and stay up to date with the latest Motoko updates. From 35f44428b6cc0f15eda740955006191cd23d536d Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Thu, 6 Feb 2025 00:51:52 -0500 Subject: [PATCH 02/94] fix: address feedback --- doc/md/meet-motoko.md | 80 ++++++++++++++++++++----------------------- 1 file changed, 38 insertions(+), 42 deletions(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index e6a290d3c0b..8a3ab26b2d5 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# Meet Motoko: The language of the Internet Computer +# Meet Motoko: The language shaping the future of Web3 import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; @@ -14,49 +14,53 @@ import TabItem from "@theme/TabItem"; Logo -## Introduction - -Motoko is the native programming language of the Internet Computer. It’s a modern, **actor-based** language designed for safety, efficiency, and scalability. With native support for asynchronous messaging, WebAssembly (Wasm) interoperability, robust type safety, and data persistence, Motoko makes it easy to build secure and performant decentralized web applications. +Motoko is a modern, **actor-based** language designed for safety, efficiency, and scalability. Motoko natively supports asynchronous messaging, Candid interoperability, robust type safety, automatic memory management, and the unique features of the Internet Computer. ## Install Motoko Follow these steps to set up your Motoko development environment: -1. **Install the IC SDK (DFX)** +### 1. **Install the IC SDK** + +To develop Motoko applications, you need a development environment that includes the Motoko compiler and base library. The Internet Computer Software Development Kit (IC SDK) provides these essential tools, along with utilities for managing and deploying canisters. + +```bash +sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)" +``` + +Verify the installation with: + +```bash +dfx --version +``` - ```bash - sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)" - ``` +### 2. **Choose an IDE** - Verify the installation with: +While you can use any IDE for Motoko development, **Visual Studio Code (VS Code)** is recommended due to its convenient extension support. If you prefer to use VS Code, you can download it from: +[https://code.visualstudio.com](https://code.visualstudio.com) - ```bash - dfx --version - ``` +### 3. **Install the Motoko Extension(Optional, Recommended for VS Code Users)** -2. **Install Visual Studio Code** - - Download VSCode from [https://code.visualstudio.com](https://code.visualstudio.com) - - Follow the installation instructions for your operating system +If you are using VS Code, you can enhance your development experience by installing the official Motoko extension: -3. **Install Motoko Extension** - - Open VSCode - - Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X) - - Search for "Motoko" - - Install the official Motoko extension +- Open VS Code +- Go to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`) +- Search for **"Motoko"** +- Install the official Motoko extension ## Explore Motoko use cases - + Motoko makes it easy to build scalable backend services for web applications. -1. [Deploy your first Motoko canister.](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-1/1.1-live-demo) +1. [Deploy your first Motoko canister.](https://github.com/dfinity/examples/tree/master/motoko/counter) -2. [Expand your application by calling external APIs from a Motoko canister.](https://internetcomputer.org/docs/current/developer-docs/backend/https-outcalls) +2. [Expand your application by calling external APIs from a Motoko canister.](https://github.com/dfinity/examples/tree/master/motoko/send_http_get) -3. [Connect your Motoko backend with a frontend canister.](https://internetcomputer.org/docs/current/references/samples/svelte/svelte-motoko-starter/) +3. [Explore a Reversi game built in motoko.](https://github.com/ninegua/reversi) @@ -64,9 +68,11 @@ Motoko makes it easy to build scalable backend services for web applications. Build decentralized finance (DeFi) applications using Motoko. -1. [Set up an ICRC-1 canister.](https://internetcomputer.org/docs/current/tutorials/hackathon-prep-course/integrating-with-tokens/#deploying-an-icrc-1-ledger-locally) +1. [Set up an ICRC-1 canister.](https://github.com/sonicdex/icrc-1-public/) -2. [Create a decentralized exchange (DEX)](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-5/5.3-token-swap-tutorial/) +2. [Create a decentralized exchange (DEX)](https://github.com/dfinity/examples/tree/master/motoko/icrc2-swap) + +3. [Learn how to deploy NFTs on ICP](https://github.com/noku-team/icrc7_motoko) @@ -74,34 +80,24 @@ Build decentralized finance (DeFi) applications using Motoko. Develop cross-chain applications and integrate with other blockchains. -1. [Explore Bitcoin integration (ckBTC).](https://internetcomputer.org/docs/current/developer-docs/multi-chain/bitcoin/overview) - -2. [Explore Ethereum integration (ckETH).](https://internetcomputer.org/ethereum-integration/) - -3. [Explore Chain-Key ERC-20 (ckERC-20) integrations.](https://internetcomputer.org/docs/current/developer-docs/multi-chain/chain-key-tokens/ckerc20/overview/) - - - - - -Manage digital assets on the Internet Computer. +1. [Explore Ethereum integration](https://github.com/dfinity/icp-eth-starter) -1. [Learn how to deploy NFTs on ICP](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-5/5.4-NFT-tutorial) +2. [Build a Bitcoin POS application.](https://github.com/dfinity/examples/tree/master/motoko/ic-pos) -## Quick References +## Quick references For developers looking for quick access to key resources, here are direct links to the base library and useful examples: -- **[Motoko base library](https://internetcomputer.org/docs/current/motoko/main/base/)** – Browse core modules and functions. +- **[Motoko base library](https://internetcomputer.org/docs/current/motoko/main/base/)** -- **[Examples:](https://internetcomputer.org/docs/current/motoko/main/getting-started/examples)** +- **[Motoko example projects](https://github.com/dfinity/examples/tree/master/motoko)** ### Share your feedback Was this page helpful? [Yes] [No] -If you have any questions or suggestions, join the [DFINITY Developer Forum](https://forum.dfinity.org/) to share your feedback. Connect with the community, collaborate with other developers, and stay up to date with the latest Motoko updates. +If you have any questions or suggestions, join the [DFINITY developer forum](https://forum.dfinity.org/) to share your feedback. Connect with the community, collaborate with other developers, and stay up to date with the latest Motoko updates. From ea1216ff724d4e38c372b3c4feadbfe2dcf10761 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Thu, 6 Feb 2025 13:55:46 -0500 Subject: [PATCH 03/94] Update doc/md/meet-motoko.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/meet-motoko.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index 8a3ab26b2d5..8b012e6d237 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -80,7 +80,7 @@ Build decentralized finance (DeFi) applications using Motoko. Develop cross-chain applications and integrate with other blockchains. -1. [Explore Ethereum integration](https://github.com/dfinity/icp-eth-starter) +1. [Explore the Ethereum integration.](https://github.com/dfinity/icp-eth-starter) 2. [Build a Bitcoin POS application.](https://github.com/dfinity/examples/tree/master/motoko/ic-pos) From 01e2d002d3d3dd82566b351f6facd87f8c50c337 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Thu, 6 Feb 2025 13:56:08 -0500 Subject: [PATCH 04/94] Update doc/md/meet-motoko.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/meet-motoko.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index 8b012e6d237..a4a9cbe6436 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -72,7 +72,7 @@ Build decentralized finance (DeFi) applications using Motoko. 2. [Create a decentralized exchange (DEX)](https://github.com/dfinity/examples/tree/master/motoko/icrc2-swap) -3. [Learn how to deploy NFTs on ICP](https://github.com/noku-team/icrc7_motoko) +3. [Learn how to deploy NFTs on ICP.](https://github.com/noku-team/icrc7_motoko) From fb322185ed21b3c89d4af8c03f93cb89e9114d25 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Thu, 6 Feb 2025 13:56:22 -0500 Subject: [PATCH 05/94] Update doc/md/meet-motoko.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/meet-motoko.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index a4a9cbe6436..1cfc963b8a4 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -70,7 +70,7 @@ Build decentralized finance (DeFi) applications using Motoko. 1. [Set up an ICRC-1 canister.](https://github.com/sonicdex/icrc-1-public/) -2. [Create a decentralized exchange (DEX)](https://github.com/dfinity/examples/tree/master/motoko/icrc2-swap) +2. [Create a decentralized exchange (DEX).](https://github.com/dfinity/examples/tree/master/motoko/icrc2-swap) 3. [Learn how to deploy NFTs on ICP.](https://github.com/noku-team/icrc7_motoko) From f219cb940ebc66eda43b5bb87c82c1f8abcd6de6 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Thu, 6 Feb 2025 13:56:34 -0500 Subject: [PATCH 06/94] Update doc/md/meet-motoko.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/meet-motoko.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index 1cfc963b8a4..e56e80f0af5 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -60,7 +60,7 @@ Motoko makes it easy to build scalable backend services for web applications. 2. [Expand your application by calling external APIs from a Motoko canister.](https://github.com/dfinity/examples/tree/master/motoko/send_http_get) -3. [Explore a Reversi game built in motoko.](https://github.com/ninegua/reversi) +3. [Explore a Reversi game built in Motoko.](https://github.com/ninegua/reversi) From a1d15699901664711c41e207c5d3755f5ce36f18 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Thu, 6 Feb 2025 13:56:43 -0500 Subject: [PATCH 07/94] Update doc/md/meet-motoko.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/meet-motoko.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index e56e80f0af5..c93f850569b 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -43,10 +43,10 @@ While you can use any IDE for Motoko development, **Visual Studio Code (VS Code) If you are using VS Code, you can enhance your development experience by installing the official Motoko extension: -- Open VS Code -- Go to Extensions (`Ctrl+Shift+X` / `Cmd+Shift+X`) -- Search for **"Motoko"** -- Install the official Motoko extension +1. Open VS Code. +2. Go to "Extensions" (`Ctrl+Shift+X` / `Cmd+Shift+X`). +3. Search for **"Motoko"** +4. Install the official Motoko extension. ## Explore Motoko use cases From 736d5f10bc439fb21b719f33fbca594355f22432 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Thu, 6 Feb 2025 13:56:55 -0500 Subject: [PATCH 08/94] Update doc/md/meet-motoko.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/meet-motoko.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index c93f850569b..d93d7de431a 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -39,7 +39,7 @@ dfx --version While you can use any IDE for Motoko development, **Visual Studio Code (VS Code)** is recommended due to its convenient extension support. If you prefer to use VS Code, you can download it from: [https://code.visualstudio.com](https://code.visualstudio.com) -### 3. **Install the Motoko Extension(Optional, Recommended for VS Code Users)** +### 3. **Install the Motoko VS Code extension (optional, recommended for VS Code Users)** If you are using VS Code, you can enhance your development experience by installing the official Motoko extension: From 722c6b4c514ed0435d73dbef75494f8457d2bd2e Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Fri, 7 Feb 2025 01:40:07 -0500 Subject: [PATCH 09/94] fundamental to pipes draft. --- doc/md/getting-started.md | 350 +++++++++++++++++++++++++++++++++++++- 1 file changed, 346 insertions(+), 4 deletions(-) diff --git a/doc/md/getting-started.md b/doc/md/getting-started.md index 78049a98f66..d0d8bc7da5c 100644 --- a/doc/md/getting-started.md +++ b/doc/md/getting-started.md @@ -2,8 +2,350 @@ sidebar_position: 2 --- -# Getting started +# Fundamentals -Installing Motoko w/ dfx, building from base/moc, etc. -Tools: VS code extension, mo-dev server, etc -Example project links \ No newline at end of file +This section introduces the core concepts of Motoko, covering essential syntax, data types, and expressions. Before you begin writing canisters in Motoko, you should be familiar with a few of the basic concepts and terms specific to Motoko. + +To learn through practical examples, visit the **[Motoko tutorial](https://internetcomputer.org/docs/current/motoko/tutorial/)**. + +## Basic syntax + +### Defining an actor + +In Motoko, an actor is a unit of computation that encapsulates state and behavior. Unlike traditional functions or objects in other programming languages, actors operate independently and interact with each other through asynchronous messaging. + +A Motoko program typically starts by defining an actor. The example below declares an actor named `Main` with a `hello` function that returns a `"Hello, world!"` message: + +```motoko +actor Main { + public query func hello() : async Text { + "Hello, world!" + }; +}; + +await Main.hello(); +``` + +A Motoko actor always presents its interface as a suite of named functions with defined argument types and return types. The Motoko compiler and IC SDK generates this interface in **Candid**, a language-neutral format that enables communication between different systems. + +Since actors in Motoko communicate asynchronously, `await` ensures the result is retrieved once the function completes. + +### Imports + +Package imports should be at the top of the source file. You can import from: + +Standard modules provided by the base library. + + ```motoko + import Text "mo:base/Text"; + ``` + +Third-party packages installed via the Mops package manager. + + ```motoko + import Package "mo:packagename"; + ``` + +Files within your own project. + + ```motoko + import Utils "utils"; + ``` + +You can also import specific functions from a module: + +```motoko +import { compare } "mo:base/Nat"; +``` + +### Printing values + +Motoko uses `Debug.print` to output text to the terminal. It takes a `Text` value and returns `()`, meaning it has no meaningful return value. + +```motoko +import Debug "mo:base/Debug"; +Debug.print("Hello, world!"); +``` + +For debugging, `debug_show` converts most Motoko values into `Text`: + +```motoko +import Debug "mo:base/Debug"; +Debug.print(debug_show(42)); // "42" +``` + +Since printing modifies output, it is considered an **impure function**, unlike pure functions that return values without side effects. + +### Integers + +Int: Represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). By default, `Int` is unbounded, meaning it can grow as large as needed without overflow. + +For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (8, 16, 32, 64). These types can overflow if their limits are exceeded, resulting in a runtime error. + +```motoko +let a: Int = -42; +let c: Int32 = 2147483647; // max bounded 32-bit integer +``` + +### Floats + +Floating-point numbers in Motoko are represented using the `Float` type, which corresponds to a 64-bit double-precision floating-point number. + +```motoko +let pi: Float = 3.14159; +let exp: Float = 2.71828; +``` + +### Characters + +The `Char` type in Motoko represents a single unicode character (`'`) delimited. + +```motoko +let letter: Char = 'A'; +let symbol: Char = '☃'; +``` + +### Text + +Sequences of characters are handled using the `Text` type, which represents immutable strings of unicode characters (`"`) delimited. + +```motoko +let greeting: Text = "Hello, world!"; +``` + +### Literals + +Literals are fixed values written directly in the code. + +- Integer literals: `42`, `0x2A` (hexadecimal) +- Float literals: `3.14`, `2.5e3` +- Character literals: `'A'`, `'☃'` +- Text literals: `"Hello"` + +### Whitespace + +Whitespace characters (spaces, tabs, newlines) are generally ignored in Motoko but are essential for separating tokens like keywords and identifiers. Proper use of whitespace enhances code readability. + +### Comments + +Motoko supports single-line, multi-line, and nested comments: + +Use `//` for comments that extend to the end of a line. + + ```motoko + // This is a single-line comment + ``` + +Use `/* ... */` for block comments spanning multiple lines. + + ```motoko + /* This is a + multi-line comment */ + ``` + +Multi-line comments can be nested within each other. + + ```motoko + /* Outer comment + /* Nested comment */ + End of outer comment */ + ``` + +Use `///` for function or module documentation. + + ```motoko + /// Returns the sum of two integers. + func add(a: Int, b: Int): Int { + a + b + } + ``` + +### Identifiers + +Identifiers are names used for variables, functions, and other entities. They must start with a letter and can contain letters, digits, and underscores. + +```motoko +let number = 10; +``` + +### Keywords + +Motoko reserves certain words for its syntax and they cannot be used as identifiers. These include: + +```motoko +actor and assert async async* await await* +break case catch class composite continue debug +debug_show do else false flexible finally for +from_candid func if ignore import in module +not null persistent object or label let +loop private public query return shared stable +switch system throw to_candid true transient try +type var while with +``` + +### Traps + +A trap is a runtime error that causes execution to abort immediately. Common causes include division by zero, out-of-bounds array access and pattern match failure + +If a trap occurs inside an actor message, only that message fails—other messages continue execution. + +To trigger a trap manually, use `Debug.trap`: + +```motoko +import Debug "mo:base/Debug"; + +Debug.trap("oops!"); +``` + +### Assertions + +An assertion checks a condition at runtime and traps if it fails. + +```motoko +let n = 10; +assert n % 2 == 1; // Traps +``` + +```motoko +let n = 10; +assert n % 2 == 0; // Succeeds +``` + +Assertions help catch logic errors early but should not be used for regular error handling. + +## Expressions + +TBC + +## Operators + +Motoko provides various operators for working with numbers, text, and boolean values. They can be categorized as follows: + +| **Category** | **Description** | **Examples** | +|---------------|----------------------------------|----------------------| +| Arithmetic | Math operations on numbers | `+`, `-`, `*`, `/`, `%`, `**` | +| Bitwise | Operations on individual bits | `&`, `^`, `<<`, `>>`, `<<>`, `<>>` | +| Text | Text concatenation | `#` | +| Logical | Logical/Boolean operations | `!`, `&`, | +| Ordered | Compare values | `==`, `!=`, `<`, `>` | + +### Unary operators + +| Operator | Description | +|----------|------------| +| `-` | Numeric negation | +| `+` | Numeric identity | +| `^` | Bitwise negation | + +### Relational operators + +Relational operators compare two values and return `true` or `false`: + +| Operator | Description | Examples| +|----------|------------|-----------| +| `==` | Equals | `a == b` | +| `!=` | Not equals | `a != b`| +| `<` | Less than | `a < b` | +| `>` | Greater than | `a > b` | +| `<=` | Less than or equal | `a <= b` | +| `>=` | Greater than or equal | `a >= b`| + +### Numeric binary operators + +Binary operators combine two numbers to produce a result. + +| Operator | Description | Examples| +|----------|------------|------------| +| `+` | Addition | `a + b` | +| `-` | Subtraction | `a - b` | +| `*` | Multiplication | `a * b` | +| `/` | Division (integer division) | `a / b` | +| `%` | Modulus (remainder) | `a % b` | +| `**` | Exponentiation | `a ** b` | + +⚠ **Note:** Division (`/`) on integers **truncates** decimals. For floating-point division, use `Float.fromInt()`. + +```motoko +let result = Float.fromInt(10 / 3); +``` + +### Bitwise operators + +Bitwise operators manipulate numbers **at the binary level**. + +| Operator | Description |Examples | +|----------|------------|----------| +| `&` | Bitwise AND |`a & b` | +| `|` | Bitwise OR | `a | b` | +| `^` | Bitwise XOR | `a ^ b` | +| `<<` | Shift left | `a << b` | +| `>>` | Shift right (must be proceeded by whitespace) |`a >> b` | +| `<<>` | Rotate left (circular shift) | `a <<> b` | +| `<>` | Rotate right (circular shift)| `a <> b` | + +### Wrapping operators + +Bounded integers **trap** on overflow, but **wrapping versions** allow overflow behavior: + +| Operator | Description | Examples | +|----------|------------|------------| +| `+%` | Addition with wrap-around | `a +% b` | +| `-%` | Subtraction with wrap-around | `a -% b` | +| `*%` | Multiplication with wrap-around | `a *% b` | +| `**%` | Exponentiation with wrap-around | `a **% b` | + +### Text operators + +| Operator | Description | Example | +|----------|------------|------------| +| `#` | Concatenates two `Text` values | `a # b` | + +### Assignment operators + +Assignment operators modify variables in place. Only mutable variables `var` can be reassigned. + +| Operator | Description |Examples| +|----------|------------|---------| +| `:=` | Assign a value | `a := b` | +| `+=` | Add and assign | `a += b` | +| `-=` | Subtract and assign | `a -= b` | +| `*=` | Multiply and assign | `a *= b` | +| `/=` | Divide and assign | `a /= b` | +| `#=` | Concatenate and assign (for `Text`) | `a #= b` | + +### Operator precedence + +Operators follow precedence rules, meaning some operators are evaluated before others. + +1. Unary operators (`-`, `!`, `^`) +2. Exponentiation (`**`, `**%`) +3. Multiplication & Division (`*`, `/`, `%`, `*%`) +4. Addition & Subtraction (`+`, `-`, `+%`, `-%`) +5. Bitwise operators (`&`, `|`, `^`) +6. Comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`) +7. Assignment operators (`:=`, `+=`, `-=`, etc.) + +For example: + +```motoko +let result = 10 + 5 * 2; // result = 20 +``` + +Use parentheses to enforce a different order: + +```motoko +let result = (10 + 5) * 2; // result = 30 +``` + +### Pipes + +Pipes (`|>`) chain function calls in a readable way. Instead of nesting function calls, pipes pass the result of one expression as an argument to the next function. + +```motoko +func double(n: Int): Int { n * 2 }; +func increment(n: Int): Int { n + 1 }; + +let result = 5 |> double(_) |> increment(_); // (5 * 2) + 1 = 11 +``` + +Logo From ad4cc67803b9ffd33a0f23468c447f4bc3680e4f Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Fri, 7 Feb 2025 15:40:41 -0500 Subject: [PATCH 10/94] updated fundamentals draft. --- doc/md/fundamentals/basic-syntax/assertion.md | 18 + .../fundamentals/basic-syntax/characters.md | 11 +- doc/md/fundamentals/basic-syntax/comments.md | 36 +- .../basic-syntax/defining_an_actor.md | 22 ++ doc/md/fundamentals/basic-syntax/floats.md | 11 +- .../fundamentals/basic-syntax/identifiers.md | 10 +- doc/md/fundamentals/basic-syntax/imports.md | 31 ++ doc/md/fundamentals/basic-syntax/integers.md | 13 +- doc/md/fundamentals/basic-syntax/keywords.md | 17 +- doc/md/fundamentals/basic-syntax/literals.md | 12 +- .../basic-syntax/printing_values.md | 20 ++ doc/md/fundamentals/basic-syntax/text.md | 10 +- doc/md/fundamentals/basic-syntax/traps.md | 3 + .../fundamentals/basic-syntax/whitespace.md | 6 +- .../expressions/integers-numbers.md | 77 +++- doc/md/fundamentals/expressions/operators.md | 136 +++++++- doc/md/getting-started.md | 328 +----------------- 17 files changed, 407 insertions(+), 354 deletions(-) create mode 100644 doc/md/fundamentals/basic-syntax/assertion.md create mode 100644 doc/md/fundamentals/basic-syntax/defining_an_actor.md create mode 100644 doc/md/fundamentals/basic-syntax/imports.md create mode 100644 doc/md/fundamentals/basic-syntax/printing_values.md create mode 100644 doc/md/fundamentals/basic-syntax/traps.md diff --git a/doc/md/fundamentals/basic-syntax/assertion.md b/doc/md/fundamentals/basic-syntax/assertion.md new file mode 100644 index 00000000000..de64f2c57ed --- /dev/null +++ b/doc/md/fundamentals/basic-syntax/assertion.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 14 +--- +# Assertions + +An assertion checks a condition at runtime and traps if it fails. + +```motoko +let n = 10; +assert n % 2 == 1; // Traps +``` + +```motoko +let n = 10; +assert n % 2 == 0; // Succeeds +``` + +Assertions help catch logic errors early but should not be used for regular error handling. diff --git a/doc/md/fundamentals/basic-syntax/characters.md b/doc/md/fundamentals/basic-syntax/characters.md index 45711e5c0b6..9b9f2f93cae 100644 --- a/doc/md/fundamentals/basic-syntax/characters.md +++ b/doc/md/fundamentals/basic-syntax/characters.md @@ -1,5 +1,12 @@ --- -sidebar_position: 3 +sidebar_position: 6 --- -# Characters \ No newline at end of file +# Characters + +The `Char` type in Motoko represents a single unicode character (`'`) delimited. + +```motoko +let letter: Char = 'A'; +let symbol: Char = '☃'; +``` diff --git a/doc/md/fundamentals/basic-syntax/comments.md b/doc/md/fundamentals/basic-syntax/comments.md index c462d8690e5..0042881cb76 100644 --- a/doc/md/fundamentals/basic-syntax/comments.md +++ b/doc/md/fundamentals/basic-syntax/comments.md @@ -1,5 +1,37 @@ --- -sidebar_position: 7 +sidebar_position: 10 --- -# Comments \ No newline at end of file +# Comments + +Motoko supports single-line, multi-line, and nested comments: + +Use `//` for comments that extend to the end of a line. + + ```motoko + // This is a single-line comment + ``` + +Use `/* ... */` for block comments spanning multiple lines. + + ```motoko + /* This is a + multi-line comment */ + ``` + +Multi-line comments can be nested within each other. + + ```motoko + /* Outer comment + /* Nested comment */ + End of outer comment */ + ``` + +Use `///` for function or module documentation. + + ```motoko + /// Returns the sum of two integers. + func add(a: Int, b: Int): Int { + a + b + } + ``` diff --git a/doc/md/fundamentals/basic-syntax/defining_an_actor.md b/doc/md/fundamentals/basic-syntax/defining_an_actor.md new file mode 100644 index 00000000000..6e2313f0728 --- /dev/null +++ b/doc/md/fundamentals/basic-syntax/defining_an_actor.md @@ -0,0 +1,22 @@ +--- +sidebar_position: 1 +--- +# Defining an actor + +In Motoko, an actor is a unit of computation that encapsulates state and behavior. Unlike traditional functions or objects in other programming languages, actors operate independently and interact with each other through asynchronous messaging. + +A Motoko program typically starts by defining an actor. The example below declares an actor named `Main` with a `hello` function that returns a `"Hello, world!"` message: + +```motoko +actor Main { + public query func hello() : async Text { + "Hello, world!" + }; +}; + +await Main.hello(); +``` + +A Motoko actor always presents its interface as a suite of named functions with defined argument types and return types. The Motoko compiler and IC SDK generates this interface in **Candid**, a language-neutral format that enables communication between different systems. + +Since actors in Motoko communicate asynchronously, `await` ensures the result is retrieved once the function completes. diff --git a/doc/md/fundamentals/basic-syntax/floats.md b/doc/md/fundamentals/basic-syntax/floats.md index 0d28941dc1d..58107fc7c71 100644 --- a/doc/md/fundamentals/basic-syntax/floats.md +++ b/doc/md/fundamentals/basic-syntax/floats.md @@ -1,5 +1,12 @@ --- -sidebar_position: 2 +sidebar_position: 5 --- -# Floats \ No newline at end of file +# Floats + +Floating-point numbers in Motoko are represented using the `Float` type, which corresponds to a 64-bit double-precision floating-point number. + +```motoko +let pi: Float = 3.14159; +let exp: Float = 2.71828; +``` diff --git a/doc/md/fundamentals/basic-syntax/identifiers.md b/doc/md/fundamentals/basic-syntax/identifiers.md index 4751d4c4e93..70e0249f18f 100644 --- a/doc/md/fundamentals/basic-syntax/identifiers.md +++ b/doc/md/fundamentals/basic-syntax/identifiers.md @@ -1,5 +1,11 @@ --- -sidebar_position: 9 +sidebar_position: 11 --- -# Identifiers \ No newline at end of file +# Identifiers + +Identifiers are names used for variables, functions, and other entities. They must start with a letter and can contain letters, digits, and underscores. + +```motoko +let number = 10; +``` diff --git a/doc/md/fundamentals/basic-syntax/imports.md b/doc/md/fundamentals/basic-syntax/imports.md new file mode 100644 index 00000000000..d9730aaf2f8 --- /dev/null +++ b/doc/md/fundamentals/basic-syntax/imports.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 2 +--- + +# Imports + +Package imports should be at the top of the source file. You can import from: + +Standard modules provided by the base library. + + ```motoko + import Text "mo:base/Text"; + ``` + +Third-party packages installed via the Mops package manager. + + ```motoko + import Package "mo:packagename"; + ``` + +Files within your own project. + + ```motoko + import Utils "utils"; + ``` + +You can also import specific functions from a module: + +```motoko +import { compare } "mo:base/Nat"; +``` diff --git a/doc/md/fundamentals/basic-syntax/integers.md b/doc/md/fundamentals/basic-syntax/integers.md index bbcf619bfa8..2ba0fcaae44 100644 --- a/doc/md/fundamentals/basic-syntax/integers.md +++ b/doc/md/fundamentals/basic-syntax/integers.md @@ -1,5 +1,14 @@ --- -sidebar_position: 1 +sidebar_position: 4 --- -# Integers \ No newline at end of file +# Integers + +Int: Represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). By default, `Int` is unbounded, meaning it can grow as large as needed without overflow. + +For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (8, 16, 32, 64). These types can overflow if their limits are exceeded, resulting in a runtime error. + +```motoko +let a: Int = -42; +let c: Int32 = 2147483647; // max bounded 32-bit integer +``` diff --git a/doc/md/fundamentals/basic-syntax/keywords.md b/doc/md/fundamentals/basic-syntax/keywords.md index 2ce5094decd..99b8c39f6d8 100644 --- a/doc/md/fundamentals/basic-syntax/keywords.md +++ b/doc/md/fundamentals/basic-syntax/keywords.md @@ -1,5 +1,18 @@ --- -sidebar_position: 8 +sidebar_position: 12 --- -# Keywords \ No newline at end of file +# Keywords + +Motoko reserves certain words for its syntax and they cannot be used as identifiers. These include: + +```motoko +actor and assert async async* await await* +break case catch class composite continue debug +debug_show do else false flexible finally for +from_candid func if ignore import in module +not null persistent object or label let +loop private public query return shared stable +switch system throw to_candid true transient try +type var while with +``` diff --git a/doc/md/fundamentals/basic-syntax/literals.md b/doc/md/fundamentals/basic-syntax/literals.md index fccd23e9a04..6e2892a3d5e 100644 --- a/doc/md/fundamentals/basic-syntax/literals.md +++ b/doc/md/fundamentals/basic-syntax/literals.md @@ -1,5 +1,13 @@ --- -sidebar_position: 5 +sidebar_position: 8 --- -# Literals \ No newline at end of file +# Literals + +Literals are fixed values written directly in the code. + +- Integer literals: `42`, `0x2A` (hexadecimal) +- Float literals: `3.14`, `2.5e3` +- Character literals: `'A'`, `'☃'` +- Text literals: `"Hello"` + \ No newline at end of file diff --git a/doc/md/fundamentals/basic-syntax/printing_values.md b/doc/md/fundamentals/basic-syntax/printing_values.md new file mode 100644 index 00000000000..bb683e281ce --- /dev/null +++ b/doc/md/fundamentals/basic-syntax/printing_values.md @@ -0,0 +1,20 @@ +--- +sidebar_position: 3 +--- +# Printing values + +Motoko uses `Debug.print` to output text to the terminal. It takes a `Text` value and returns `()`, meaning it has no meaningful return value. + +```motoko +import Debug "mo:base/Debug"; +Debug.print("Hello, world!"); +``` + +For debugging, `debug_show` converts most Motoko values into `Text`: + +```motoko +import Debug "mo:base/Debug"; +Debug.print(debug_show(42)); // "42" +``` + +Since printing modifies output, it is considered an **impure function**, unlike pure functions that return values without side effects. diff --git a/doc/md/fundamentals/basic-syntax/text.md b/doc/md/fundamentals/basic-syntax/text.md index af55a790f17..74ac6d54008 100644 --- a/doc/md/fundamentals/basic-syntax/text.md +++ b/doc/md/fundamentals/basic-syntax/text.md @@ -1,5 +1,11 @@ --- -sidebar_position: 4 +sidebar_position: 7 --- -# Text \ No newline at end of file +# Text + +Sequences of characters are handled using the `Text` type, which represents immutable strings of unicode characters (`"`) delimited. + +```motoko +let greeting: Text = "Hello, world!"; +``` diff --git a/doc/md/fundamentals/basic-syntax/traps.md b/doc/md/fundamentals/basic-syntax/traps.md new file mode 100644 index 00000000000..8576af0e001 --- /dev/null +++ b/doc/md/fundamentals/basic-syntax/traps.md @@ -0,0 +1,3 @@ +--- +sidebar_position: 13 +--- \ No newline at end of file diff --git a/doc/md/fundamentals/basic-syntax/whitespace.md b/doc/md/fundamentals/basic-syntax/whitespace.md index 72b930836da..3cef3ac36ba 100644 --- a/doc/md/fundamentals/basic-syntax/whitespace.md +++ b/doc/md/fundamentals/basic-syntax/whitespace.md @@ -1,5 +1,7 @@ --- -sidebar_position: 6 +sidebar_position: 9 --- -# Whitespace \ No newline at end of file +# Whitespace + +Whitespace characters (spaces, tabs, newlines) are generally ignored in Motoko but are essential for separating tokens like keywords and identifiers. Proper use of whitespace enhances code readability. diff --git a/doc/md/fundamentals/expressions/integers-numbers.md b/doc/md/fundamentals/expressions/integers-numbers.md index d153b0fa2ee..79350407fa3 100644 --- a/doc/md/fundamentals/expressions/integers-numbers.md +++ b/doc/md/fundamentals/expressions/integers-numbers.md @@ -2,4 +2,79 @@ sidebar_position: 1 --- -# Integers and numbers \ No newline at end of file +# Integers and numbers + +This section focuses on integers `Int` and introduces **natural numbers `Nat`. + +The `Int` type represents all integers, both positive and negative. + +```motoko +let a: Int = -42; +let b: Int = 0; +let c: Int = 12345; +``` + +## Unbounded integers + +By default, `Int` is unbounded, meaning it can grow as large (or as small) as needed without causing overflow: + +```motoko +let bigNumber: Int = 999_999_999_999_999; +``` + +## Bounded integers + +For scenarios requiring fixed-size integers, Motoko offers bounded integer types with specific bit-widths: + +- `Int8` (8-bit signed integer) +- `Int16` (16-bit signed integer) +- `Int32` (32-bit signed integer) +- `Int64` (64-bit signed integer) + +Bounded integers can overflow if their limits are exceeded, resulting in a runtime error: + +```motoko +// let overflowInt: Int8 = 128; // Error: literal out of range Int8 +``` + +## Natural numbers + +The `Nat` type represents natural numbers, which are all non-negative integers (i.e., `0` and positive numbers): + +```motoko +let n: Nat = 42; +let zero: Nat = 0; +// let negative: Nat = -1; // Error: Cannot assign a negative value to Nat (underflow) +``` + +## Unbounded natural numbers + +Like `Int`, the `Nat` type is unbounded by default, allowing extremely large values without overflow: + +```motoko +let hugeNat: Nat = 1_000_000_000_000_000; +``` + +## Bounded natural numbers + +Motoko also provides bounded natural number types: + +- `Nat8` (8-bit unsigned integer, range: 0 to 255) +- `Nat16` (16-bit unsigned integer, range: 0 to 65,535) +- `Nat32` (32-bit unsigned integer, range: 0 to 4,294,967,295) +- `Nat64` (64-bit unsigned integer, range: 0 to 18,446,744,073,709,551,615) + +Bounded `Nat` types are ideal when working with binary protocols, embedded systems, or hardware where size constraints matter: + +```motoko +let overflowNat8: Nat8 = 256; // Error: literal out of range Nat8 +``` + +## Key differences between Int and Nat + +| Feature | `Int` | `Nat` | +|-----------------------|----------------------------|--------------------------| +| Values supported | Positive & Negative | Only Non-negative | +| Default behavior | Unbounded | Unbounded | +| Bounded variants | `Int8`, `Int16`, `Int32`...| `Nat8`, `Nat16`, `Nat32`...| +| Overflow possibility | Yes (for bounded types) | Yes (for bounded types) | diff --git a/doc/md/fundamentals/expressions/operators.md b/doc/md/fundamentals/expressions/operators.md index 6410010b316..60d676d548c 100644 --- a/doc/md/fundamentals/expressions/operators.md +++ b/doc/md/fundamentals/expressions/operators.md @@ -4,11 +4,131 @@ sidebar_position: 2 # Operators -Unary operators -Relational operators -Numeric binary operators -Bitwise and wrapping binary operators -Text operators -Assignment operators -Operator and keyword precedence -Pipes +Motoko provides various operators for working with numbers, text, and boolean values. They can be categorized as follows: + +| **Category** | **Description** | **Examples** | +|---------------|----------------------------------|----------------------| +| Arithmetic | Math operations on numbers | `+`, `-`, `*`, `/`, `%`, `**` | +| Bitwise | Operations on individual bits | `&`, `^`, `<<`, `>>`, `<<>`, `<>>` | +| Text | Text concatenation | `#` | +| Logical | Logical/Boolean operations | `!`, `&`, | +| Ordered | Compare values | `==`, `!=`, `<`, `>` | + +## Unary operators + +| Operator | Description | +|----------|------------| +| `-` | Numeric negation | +| `+` | Numeric identity | +| `^` | Bitwise negation | + +## Relational operators + +Relational operators compare two values and return `true` or `false`: + +| Operator | Description | Examples| +|----------|------------|-----------| +| `==` | Equals | `a == b` | +| `!=` | Not equals | `a != b`| +| `<` | Less than | `a < b` | +| `>` | Greater than | `a > b` | +| `<=` | Less than or equal | `a <= b` | +| `>=` | Greater than or equal | `a >= b`| + +## Numeric binary operators + +Binary operators combine two numbers to produce a result. + +| Operator | Description | Examples| +|----------|------------|------------| +| `+` | Addition | `a + b` | +| `-` | Subtraction | `a - b` | +| `*` | Multiplication | `a * b` | +| `/` | Division (integer division) | `a / b` | +| `%` | Modulus (remainder) | `a % b` | +| `**` | Exponentiation | `a ** b` | + +⚠ **Note:** Division (`/`) on integers **truncates** decimals. For floating-point division, use `Float.fromInt()`. + +```motoko +let result = Float.fromInt(10) / Float.fromInt(3); +``` + +## Bitwise operators + +Bitwise operators manipulate numbers **at the binary level**. + +| Operator | Description |Examples | +|----------|------------|----------| +| `&` | Bitwise AND |`a & b` | +| `|` | Bitwise OR | `a | b` | +| `^` | Bitwise XOR | `a ^ b` | +| `<<` | Shift left | `a << b` | +| `>>` | Shift right (must be proceeded by whitespace) |`a >> b` | +| `<<>` | Rotate left (circular shift) | `a <<> b` | +| `<>` | Rotate right (circular shift)| `a <> b` | + +## Wrapping operators + +Bounded integers **trap** on overflow, but **wrapping versions** allow overflow behavior: + +| Operator | Description | Examples | +|----------|------------|------------| +| `+%` | Addition with wrap-around | `a +% b` | +| `-%` | Subtraction with wrap-around | `a -% b` | +| `*%` | Multiplication with wrap-around | `a *% b` | +| `**%` | Exponentiation with wrap-around | `a **% b` | + +## Text operators + +| Operator | Description | Example | +|----------|------------|------------| +| `#` | Concatenates two `Text` values | `a # b` | + +## Assignment operators + +Assignment operators modify variables in place. Only mutable variables `var` can be reassigned. + +| Operator | Description |Examples| +|----------|------------|---------| +| `:=` | Assign a value | `a := b` | +| `+=` | Add and assign | `a += b` | +| `-=` | Subtract and assign | `a -= b` | +| `*=` | Multiply and assign | `a *= b` | +| `/=` | Divide and assign | `a /= b` | +| `#=` | Concatenate and assign (for `Text`) | `a #= b` | + +## Operator precedence + +Operators follow precedence rules, meaning some operators are evaluated before others. + +1. Unary operators (`-`, `!`, `^`) +2. Exponentiation (`**`, `**%`) +3. Multiplication & Division (`*`, `/`, `%`, `*%`) +4. Addition & Subtraction (`+`, `-`, `+%`, `-%`) +5. Bitwise operators (`&`, `|`, `^`) +6. Comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`) +7. Assignment operators (`:=`, `+=`, `-=`, etc.) + +For example: + +```motoko +let result = 10 + 5 * 2; // result = 20 +``` + +Use parentheses to enforce a different order: + +```motoko +let result = (10 + 5) * 2; // result = 30 +``` + +## Pipes + +Pipes (`|>`) chain function calls in a readable way. Instead of nesting function calls, pipes pass the result of one expression as an argument to the next function. + +```motoko +func double(n: Int): Int { n * 2 }; +func increment(n: Int): Int { n + 1 }; + +let result = 5 |> double(_) |> increment(_); // (5 * 2) + 1 = 11 +``` diff --git a/doc/md/getting-started.md b/doc/md/getting-started.md index d0d8bc7da5c..1e7da654167 100644 --- a/doc/md/getting-started.md +++ b/doc/md/getting-started.md @@ -2,187 +2,12 @@ sidebar_position: 2 --- -# Fundamentals +# Getting Started This section introduces the core concepts of Motoko, covering essential syntax, data types, and expressions. Before you begin writing canisters in Motoko, you should be familiar with a few of the basic concepts and terms specific to Motoko. To learn through practical examples, visit the **[Motoko tutorial](https://internetcomputer.org/docs/current/motoko/tutorial/)**. -## Basic syntax - -### Defining an actor - -In Motoko, an actor is a unit of computation that encapsulates state and behavior. Unlike traditional functions or objects in other programming languages, actors operate independently and interact with each other through asynchronous messaging. - -A Motoko program typically starts by defining an actor. The example below declares an actor named `Main` with a `hello` function that returns a `"Hello, world!"` message: - -```motoko -actor Main { - public query func hello() : async Text { - "Hello, world!" - }; -}; - -await Main.hello(); -``` - -A Motoko actor always presents its interface as a suite of named functions with defined argument types and return types. The Motoko compiler and IC SDK generates this interface in **Candid**, a language-neutral format that enables communication between different systems. - -Since actors in Motoko communicate asynchronously, `await` ensures the result is retrieved once the function completes. - -### Imports - -Package imports should be at the top of the source file. You can import from: - -Standard modules provided by the base library. - - ```motoko - import Text "mo:base/Text"; - ``` - -Third-party packages installed via the Mops package manager. - - ```motoko - import Package "mo:packagename"; - ``` - -Files within your own project. - - ```motoko - import Utils "utils"; - ``` - -You can also import specific functions from a module: - -```motoko -import { compare } "mo:base/Nat"; -``` - -### Printing values - -Motoko uses `Debug.print` to output text to the terminal. It takes a `Text` value and returns `()`, meaning it has no meaningful return value. - -```motoko -import Debug "mo:base/Debug"; -Debug.print("Hello, world!"); -``` - -For debugging, `debug_show` converts most Motoko values into `Text`: - -```motoko -import Debug "mo:base/Debug"; -Debug.print(debug_show(42)); // "42" -``` - -Since printing modifies output, it is considered an **impure function**, unlike pure functions that return values without side effects. - -### Integers - -Int: Represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). By default, `Int` is unbounded, meaning it can grow as large as needed without overflow. - -For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (8, 16, 32, 64). These types can overflow if their limits are exceeded, resulting in a runtime error. - -```motoko -let a: Int = -42; -let c: Int32 = 2147483647; // max bounded 32-bit integer -``` - -### Floats - -Floating-point numbers in Motoko are represented using the `Float` type, which corresponds to a 64-bit double-precision floating-point number. - -```motoko -let pi: Float = 3.14159; -let exp: Float = 2.71828; -``` - -### Characters - -The `Char` type in Motoko represents a single unicode character (`'`) delimited. - -```motoko -let letter: Char = 'A'; -let symbol: Char = '☃'; -``` - -### Text - -Sequences of characters are handled using the `Text` type, which represents immutable strings of unicode characters (`"`) delimited. - -```motoko -let greeting: Text = "Hello, world!"; -``` - -### Literals - -Literals are fixed values written directly in the code. - -- Integer literals: `42`, `0x2A` (hexadecimal) -- Float literals: `3.14`, `2.5e3` -- Character literals: `'A'`, `'☃'` -- Text literals: `"Hello"` - -### Whitespace - -Whitespace characters (spaces, tabs, newlines) are generally ignored in Motoko but are essential for separating tokens like keywords and identifiers. Proper use of whitespace enhances code readability. - -### Comments - -Motoko supports single-line, multi-line, and nested comments: - -Use `//` for comments that extend to the end of a line. - - ```motoko - // This is a single-line comment - ``` - -Use `/* ... */` for block comments spanning multiple lines. - - ```motoko - /* This is a - multi-line comment */ - ``` - -Multi-line comments can be nested within each other. - - ```motoko - /* Outer comment - /* Nested comment */ - End of outer comment */ - ``` - -Use `///` for function or module documentation. - - ```motoko - /// Returns the sum of two integers. - func add(a: Int, b: Int): Int { - a + b - } - ``` - -### Identifiers - -Identifiers are names used for variables, functions, and other entities. They must start with a letter and can contain letters, digits, and underscores. - -```motoko -let number = 10; -``` - -### Keywords - -Motoko reserves certain words for its syntax and they cannot be used as identifiers. These include: - -```motoko -actor and assert async async* await await* -break case catch class composite continue debug -debug_show do else false flexible finally for -from_candid func if ignore import in module -not null persistent object or label let -loop private public query return shared stable -switch system throw to_candid true transient try -type var while with -``` - ### Traps A trap is a runtime error that causes execution to abort immediately. Common causes include division by zero, out-of-bounds array access and pattern match failure @@ -197,155 +22,4 @@ import Debug "mo:base/Debug"; Debug.trap("oops!"); ``` -### Assertions - -An assertion checks a condition at runtime and traps if it fails. - -```motoko -let n = 10; -assert n % 2 == 1; // Traps -``` - -```motoko -let n = 10; -assert n % 2 == 0; // Succeeds -``` - -Assertions help catch logic errors early but should not be used for regular error handling. - -## Expressions - -TBC - -## Operators - -Motoko provides various operators for working with numbers, text, and boolean values. They can be categorized as follows: - -| **Category** | **Description** | **Examples** | -|---------------|----------------------------------|----------------------| -| Arithmetic | Math operations on numbers | `+`, `-`, `*`, `/`, `%`, `**` | -| Bitwise | Operations on individual bits | `&`, `^`, `<<`, `>>`, `<<>`, `<>>` | -| Text | Text concatenation | `#` | -| Logical | Logical/Boolean operations | `!`, `&`, | -| Ordered | Compare values | `==`, `!=`, `<`, `>` | - -### Unary operators - -| Operator | Description | -|----------|------------| -| `-` | Numeric negation | -| `+` | Numeric identity | -| `^` | Bitwise negation | - -### Relational operators - -Relational operators compare two values and return `true` or `false`: - -| Operator | Description | Examples| -|----------|------------|-----------| -| `==` | Equals | `a == b` | -| `!=` | Not equals | `a != b`| -| `<` | Less than | `a < b` | -| `>` | Greater than | `a > b` | -| `<=` | Less than or equal | `a <= b` | -| `>=` | Greater than or equal | `a >= b`| - -### Numeric binary operators - -Binary operators combine two numbers to produce a result. - -| Operator | Description | Examples| -|----------|------------|------------| -| `+` | Addition | `a + b` | -| `-` | Subtraction | `a - b` | -| `*` | Multiplication | `a * b` | -| `/` | Division (integer division) | `a / b` | -| `%` | Modulus (remainder) | `a % b` | -| `**` | Exponentiation | `a ** b` | - -⚠ **Note:** Division (`/`) on integers **truncates** decimals. For floating-point division, use `Float.fromInt()`. - -```motoko -let result = Float.fromInt(10 / 3); -``` - -### Bitwise operators - -Bitwise operators manipulate numbers **at the binary level**. - -| Operator | Description |Examples | -|----------|------------|----------| -| `&` | Bitwise AND |`a & b` | -| `|` | Bitwise OR | `a | b` | -| `^` | Bitwise XOR | `a ^ b` | -| `<<` | Shift left | `a << b` | -| `>>` | Shift right (must be proceeded by whitespace) |`a >> b` | -| `<<>` | Rotate left (circular shift) | `a <<> b` | -| `<>` | Rotate right (circular shift)| `a <> b` | - -### Wrapping operators - -Bounded integers **trap** on overflow, but **wrapping versions** allow overflow behavior: - -| Operator | Description | Examples | -|----------|------------|------------| -| `+%` | Addition with wrap-around | `a +% b` | -| `-%` | Subtraction with wrap-around | `a -% b` | -| `*%` | Multiplication with wrap-around | `a *% b` | -| `**%` | Exponentiation with wrap-around | `a **% b` | - -### Text operators - -| Operator | Description | Example | -|----------|------------|------------| -| `#` | Concatenates two `Text` values | `a # b` | - -### Assignment operators - -Assignment operators modify variables in place. Only mutable variables `var` can be reassigned. - -| Operator | Description |Examples| -|----------|------------|---------| -| `:=` | Assign a value | `a := b` | -| `+=` | Add and assign | `a += b` | -| `-=` | Subtract and assign | `a -= b` | -| `*=` | Multiply and assign | `a *= b` | -| `/=` | Divide and assign | `a /= b` | -| `#=` | Concatenate and assign (for `Text`) | `a #= b` | - -### Operator precedence - -Operators follow precedence rules, meaning some operators are evaluated before others. - -1. Unary operators (`-`, `!`, `^`) -2. Exponentiation (`**`, `**%`) -3. Multiplication & Division (`*`, `/`, `%`, `*%`) -4. Addition & Subtraction (`+`, `-`, `+%`, `-%`) -5. Bitwise operators (`&`, `|`, `^`) -6. Comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`) -7. Assignment operators (`:=`, `+=`, `-=`, etc.) - -For example: - -```motoko -let result = 10 + 5 * 2; // result = 20 -``` - -Use parentheses to enforce a different order: - -```motoko -let result = (10 + 5) * 2; // result = 30 -``` - -### Pipes - -Pipes (`|>`) chain function calls in a readable way. Instead of nesting function calls, pipes pass the result of one expression as an argument to the next function. - -```motoko -func double(n: Int): Int { n * 2 }; -func increment(n: Int): Int { n + 1 }; - -let result = 5 |> double(_) |> increment(_); // (5 * 2) + 1 = 11 -``` - Logo From 506e10aed5e46064fafa60126f9722b44bb29e44 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:31:34 -0500 Subject: [PATCH 11/94] Update doc/md/meet-motoko.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/meet-motoko.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index d93d7de431a..d13c546f1e1 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -96,8 +96,5 @@ For developers looking for quick access to key resources, here are direct links - **[Motoko example projects](https://github.com/dfinity/examples/tree/master/motoko)** -### Share your feedback -Was this page helpful? [Yes] [No] -If you have any questions or suggestions, join the [DFINITY developer forum](https://forum.dfinity.org/) to share your feedback. Connect with the community, collaborate with other developers, and stay up to date with the latest Motoko updates. From c9db19c2d67157575a1de1a3f3ad98937b9bf911 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:32:07 -0500 Subject: [PATCH 12/94] Update doc/md/fundamentals/expressions/operators.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/expressions/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/expressions/operators.md b/doc/md/fundamentals/expressions/operators.md index 60d676d548c..491e2b60f3a 100644 --- a/doc/md/fundamentals/expressions/operators.md +++ b/doc/md/fundamentals/expressions/operators.md @@ -105,7 +105,7 @@ Operators follow precedence rules, meaning some operators are evaluated before o 1. Unary operators (`-`, `!`, `^`) 2. Exponentiation (`**`, `**%`) 3. Multiplication & Division (`*`, `/`, `%`, `*%`) -4. Addition & Subtraction (`+`, `-`, `+%`, `-%`) +4. Addition & subtraction (`+`, `-`, `+%`, `-%`) 5. Bitwise operators (`&`, `|`, `^`) 6. Comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`) 7. Assignment operators (`:=`, `+=`, `-=`, etc.) From 868df9d35eddf8f1a5e9dcbb72f87f0f51f09578 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:32:23 -0500 Subject: [PATCH 13/94] Update doc/md/fundamentals/basic-syntax/imports.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/basic-syntax/imports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/basic-syntax/imports.md b/doc/md/fundamentals/basic-syntax/imports.md index d9730aaf2f8..825b7418254 100644 --- a/doc/md/fundamentals/basic-syntax/imports.md +++ b/doc/md/fundamentals/basic-syntax/imports.md @@ -6,7 +6,7 @@ sidebar_position: 2 Package imports should be at the top of the source file. You can import from: -Standard modules provided by the base library. +1. Standard modules provided by the base library: ```motoko import Text "mo:base/Text"; From ab6cf78e9b2cb6241b05f028d4a8f85e20cbef03 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:33:15 -0500 Subject: [PATCH 14/94] Update doc/md/getting-started.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/getting-started.md b/doc/md/getting-started.md index 1e7da654167..40f02e65c57 100644 --- a/doc/md/getting-started.md +++ b/doc/md/getting-started.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -# Getting Started +# Getting started This section introduces the core concepts of Motoko, covering essential syntax, data types, and expressions. Before you begin writing canisters in Motoko, you should be familiar with a few of the basic concepts and terms specific to Motoko. From 59f786fc305521f790ae16772baba09dc73faa20 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:34:38 -0500 Subject: [PATCH 15/94] Update doc/md/fundamentals/basic-syntax/imports.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/basic-syntax/imports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/basic-syntax/imports.md b/doc/md/fundamentals/basic-syntax/imports.md index 825b7418254..861c2ca3ed4 100644 --- a/doc/md/fundamentals/basic-syntax/imports.md +++ b/doc/md/fundamentals/basic-syntax/imports.md @@ -12,7 +12,7 @@ Package imports should be at the top of the source file. You can import from: import Text "mo:base/Text"; ``` -Third-party packages installed via the Mops package manager. +2. Third-party packages installed via the Mops package manager: ```motoko import Package "mo:packagename"; From 4616b0893923b1b1ff6cba6476f8d2ebbe18f91f Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:35:34 -0500 Subject: [PATCH 16/94] Update doc/md/fundamentals/basic-syntax/integers.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/basic-syntax/integers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/basic-syntax/integers.md b/doc/md/fundamentals/basic-syntax/integers.md index 2ba0fcaae44..c89fc171056 100644 --- a/doc/md/fundamentals/basic-syntax/integers.md +++ b/doc/md/fundamentals/basic-syntax/integers.md @@ -4,7 +4,7 @@ sidebar_position: 4 # Integers -Int: Represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). By default, `Int` is unbounded, meaning it can grow as large as needed without overflow. +`Int` represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). By default, `Int` is unbounded, meaning it can grow as large as needed without overflow. For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (8, 16, 32, 64). These types can overflow if their limits are exceeded, resulting in a runtime error. From dea36577f4585df7b1bd056de7e651b2f5c273a1 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:40:46 -0500 Subject: [PATCH 17/94] Update doc/md/fundamentals/basic-syntax/imports.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/basic-syntax/imports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/basic-syntax/imports.md b/doc/md/fundamentals/basic-syntax/imports.md index 861c2ca3ed4..922f1f86983 100644 --- a/doc/md/fundamentals/basic-syntax/imports.md +++ b/doc/md/fundamentals/basic-syntax/imports.md @@ -18,7 +18,7 @@ Package imports should be at the top of the source file. You can import from: import Package "mo:packagename"; ``` -Files within your own project. +3. Files within your own project: ```motoko import Utils "utils"; From c268553118098809cb59773b694d68262a74ed4e Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:41:27 -0500 Subject: [PATCH 18/94] Update doc/md/fundamentals/basic-syntax/integers.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/basic-syntax/integers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/basic-syntax/integers.md b/doc/md/fundamentals/basic-syntax/integers.md index c89fc171056..ffd972b32e4 100644 --- a/doc/md/fundamentals/basic-syntax/integers.md +++ b/doc/md/fundamentals/basic-syntax/integers.md @@ -6,7 +6,7 @@ sidebar_position: 4 `Int` represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). By default, `Int` is unbounded, meaning it can grow as large as needed without overflow. -For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (8, 16, 32, 64). These types can overflow if their limits are exceeded, resulting in a runtime error. +For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (Int8, Int16, Int32, Int64). These types can overflow if their limits are exceeded, resulting in a runtime error. ```motoko let a: Int = -42; From 1dfcaad67b50c63fa9f9661a8deead3b8be0f756 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:42:28 -0500 Subject: [PATCH 19/94] Update doc/md/fundamentals/expressions/integers-numbers.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/expressions/integers-numbers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/expressions/integers-numbers.md b/doc/md/fundamentals/expressions/integers-numbers.md index 79350407fa3..a583d9f5a8e 100644 --- a/doc/md/fundamentals/expressions/integers-numbers.md +++ b/doc/md/fundamentals/expressions/integers-numbers.md @@ -4,7 +4,7 @@ sidebar_position: 1 # Integers and numbers -This section focuses on integers `Int` and introduces **natural numbers `Nat`. +This section focuses on integers `Int` and introduces natural numbers `Nat`. The `Int` type represents all integers, both positive and negative. From a7a058f3e58bd8e566d0dac706e138952f951f80 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:43:39 -0500 Subject: [PATCH 20/94] Update doc/md/fundamentals/expressions/operators.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/expressions/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/expressions/operators.md b/doc/md/fundamentals/expressions/operators.md index 491e2b60f3a..c5992921784 100644 --- a/doc/md/fundamentals/expressions/operators.md +++ b/doc/md/fundamentals/expressions/operators.md @@ -104,7 +104,7 @@ Operators follow precedence rules, meaning some operators are evaluated before o 1. Unary operators (`-`, `!`, `^`) 2. Exponentiation (`**`, `**%`) -3. Multiplication & Division (`*`, `/`, `%`, `*%`) +3. Multiplication & division (`*`, `/`, `%`, `*%`) 4. Addition & subtraction (`+`, `-`, `+%`, `-%`) 5. Bitwise operators (`&`, `|`, `^`) 6. Comparison operators (`==`, `!=`, `<`, `>`, `<=`, `>=`) From b0b64f92b527f60db8b56ab574d9f8f002f33b35 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:58:05 -0500 Subject: [PATCH 21/94] Update doc/md/fundamentals/expressions/operators.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/expressions/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/expressions/operators.md b/doc/md/fundamentals/expressions/operators.md index c5992921784..0bdb9318d85 100644 --- a/doc/md/fundamentals/expressions/operators.md +++ b/doc/md/fundamentals/expressions/operators.md @@ -72,7 +72,7 @@ Bitwise operators manipulate numbers **at the binary level**. Bounded integers **trap** on overflow, but **wrapping versions** allow overflow behavior: -| Operator | Description | Examples | +| Operator | Description | Example | |----------|------------|------------| | `+%` | Addition with wrap-around | `a +% b` | | `-%` | Subtraction with wrap-around | `a -% b` | From 4a533a589e624de00e9aac875aef1e35a7aefd84 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 09:58:17 -0500 Subject: [PATCH 22/94] Update doc/md/fundamentals/basic-syntax/assertion.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/basic-syntax/assertion.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/md/fundamentals/basic-syntax/assertion.md b/doc/md/fundamentals/basic-syntax/assertion.md index de64f2c57ed..b23de919c7b 100644 --- a/doc/md/fundamentals/basic-syntax/assertion.md +++ b/doc/md/fundamentals/basic-syntax/assertion.md @@ -15,4 +15,11 @@ let n = 10; assert n % 2 == 0; // Succeeds ``` -Assertions help catch logic errors early but should not be used for regular error handling. +Assertions help catch logic errors early, but should not be used for regular error handling. + + From 423d07e1f0fbc9cbbcf88893f2bdf4200d9704d8 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 10:12:16 -0500 Subject: [PATCH 23/94] Update doc/md/fundamentals/expressions/operators.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/expressions/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/expressions/operators.md b/doc/md/fundamentals/expressions/operators.md index 0bdb9318d85..2b479ba9b9b 100644 --- a/doc/md/fundamentals/expressions/operators.md +++ b/doc/md/fundamentals/expressions/operators.md @@ -26,7 +26,7 @@ Motoko provides various operators for working with numbers, text, and boolean va Relational operators compare two values and return `true` or `false`: -| Operator | Description | Examples| +| Operator | Description | Example| |----------|------------|-----------| | `==` | Equals | `a == b` | | `!=` | Not equals | `a != b`| From 31cec710df6d0c9b75d648095f7af7db95a77cc6 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 10:13:02 -0500 Subject: [PATCH 24/94] Update doc/md/fundamentals/expressions/operators.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/expressions/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/expressions/operators.md b/doc/md/fundamentals/expressions/operators.md index 2b479ba9b9b..ec913b4c81f 100644 --- a/doc/md/fundamentals/expressions/operators.md +++ b/doc/md/fundamentals/expressions/operators.md @@ -39,7 +39,7 @@ Relational operators compare two values and return `true` or `false`: Binary operators combine two numbers to produce a result. -| Operator | Description | Examples| +| Operator | Description | Example| |----------|------------|------------| | `+` | Addition | `a + b` | | `-` | Subtraction | `a - b` | From fca412c622f6cdb1c20690d4459a98810b97961f Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 10:14:01 -0500 Subject: [PATCH 25/94] Update doc/md/fundamentals/expressions/operators.md Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/expressions/operators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/md/fundamentals/expressions/operators.md b/doc/md/fundamentals/expressions/operators.md index ec913b4c81f..243e0492a14 100644 --- a/doc/md/fundamentals/expressions/operators.md +++ b/doc/md/fundamentals/expressions/operators.md @@ -58,7 +58,7 @@ let result = Float.fromInt(10) / Float.fromInt(3); Bitwise operators manipulate numbers **at the binary level**. -| Operator | Description |Examples | +| Operator | Description |Example | |----------|------------|----------| | `&` | Bitwise AND |`a & b` | | `|` | Bitwise OR | `a | b` | From 7765d0b03b8cf3212effe26bcea253c10dc8439b Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 11:27:01 -0500 Subject: [PATCH 26/94] updates to draft --- .../fundamentals/basic-syntax/defining_an_actor.md | 6 +++++- doc/md/getting-started.md | 14 -------------- doc/md/meet-motoko.md | 3 --- 3 files changed, 5 insertions(+), 18 deletions(-) diff --git a/doc/md/fundamentals/basic-syntax/defining_an_actor.md b/doc/md/fundamentals/basic-syntax/defining_an_actor.md index 6e2313f0728..ec80b443972 100644 --- a/doc/md/fundamentals/basic-syntax/defining_an_actor.md +++ b/doc/md/fundamentals/basic-syntax/defining_an_actor.md @@ -17,6 +17,10 @@ actor Main { await Main.hello(); ``` -A Motoko actor always presents its interface as a suite of named functions with defined argument types and return types. The Motoko compiler and IC SDK generates this interface in **Candid**, a language-neutral format that enables communication between different systems. +A Motoko actor always presents its interface as a suite of named functions with defined argument types and return types. When Motoko code is compiled, this interface is automatically generated in **[Candid](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/candid/candid-concepts)**, an interface description language. Since actors in Motoko communicate asynchronously, `await` ensures the result is retrieved once the function completes. + +## Quick references + +- [Actors](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/actors-async) diff --git a/doc/md/getting-started.md b/doc/md/getting-started.md index 40f02e65c57..f9e9e4727ae 100644 --- a/doc/md/getting-started.md +++ b/doc/md/getting-started.md @@ -8,18 +8,4 @@ This section introduces the core concepts of Motoko, covering essential syntax, To learn through practical examples, visit the **[Motoko tutorial](https://internetcomputer.org/docs/current/motoko/tutorial/)**. -### Traps - -A trap is a runtime error that causes execution to abort immediately. Common causes include division by zero, out-of-bounds array access and pattern match failure - -If a trap occurs inside an actor message, only that message fails—other messages continue execution. - -To trigger a trap manually, use `Debug.trap`: - -```motoko -import Debug "mo:base/Debug"; - -Debug.trap("oops!"); -``` - Logo diff --git a/doc/md/meet-motoko.md b/doc/md/meet-motoko.md index d13c546f1e1..f01c6919a21 100644 --- a/doc/md/meet-motoko.md +++ b/doc/md/meet-motoko.md @@ -95,6 +95,3 @@ For developers looking for quick access to key resources, here are direct links - **[Motoko base library](https://internetcomputer.org/docs/current/motoko/main/base/)** - **[Motoko example projects](https://github.com/dfinity/examples/tree/master/motoko)** - - - From 733458efe8ba3927b9e802be5c5a412663324e88 Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 11:46:55 -0500 Subject: [PATCH 27/94] updates to imports.md --- doc/md/fundamentals/basic-syntax/imports.md | 26 ++++++++++++--------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/doc/md/fundamentals/basic-syntax/imports.md b/doc/md/fundamentals/basic-syntax/imports.md index 922f1f86983..4d3251af887 100644 --- a/doc/md/fundamentals/basic-syntax/imports.md +++ b/doc/md/fundamentals/basic-syntax/imports.md @@ -4,28 +4,32 @@ sidebar_position: 2 # Imports -Package imports should be at the top of the source file. You can import from: +Package imports should be at the top of the source file. Imports allow you to reuse code from external libraries or modules, making your code easier to maintain and manage. You can import from: 1. Standard modules provided by the base library: - ```motoko - import Text "mo:base/Text"; - ``` +```motoko +import Text "mo:base/Text"; +``` 2. Third-party packages installed via the Mops package manager: - ```motoko - import Package "mo:packagename"; - ``` +```motoko +import Package "mo:packagename"; +``` 3. Files within your own project: - ```motoko - import Utils "utils"; - ``` +```motoko +import Utils "utils"; +``` -You can also import specific functions from a module: +You can also import specific functions from a module: ```motoko import { compare } "mo:base/Nat"; ``` + +## Quick references + +- **[Modules and imports](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/modules-and-imports/)** From 59c6ba26c9ccf26e674abf03b03064e46ed89311 Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 12:10:54 -0500 Subject: [PATCH 28/94] updates to printing values --- doc/md/fundamentals/basic-syntax/imports.md | 2 +- doc/md/fundamentals/basic-syntax/printing_values.md | 10 +++++++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/md/fundamentals/basic-syntax/imports.md b/doc/md/fundamentals/basic-syntax/imports.md index 4d3251af887..50740cdc26f 100644 --- a/doc/md/fundamentals/basic-syntax/imports.md +++ b/doc/md/fundamentals/basic-syntax/imports.md @@ -32,4 +32,4 @@ import { compare } "mo:base/Nat"; ## Quick references -- **[Modules and imports](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/modules-and-imports/)** +- [Modules and imports](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/modules-and-imports/) diff --git a/doc/md/fundamentals/basic-syntax/printing_values.md b/doc/md/fundamentals/basic-syntax/printing_values.md index bb683e281ce..5a461c818ef 100644 --- a/doc/md/fundamentals/basic-syntax/printing_values.md +++ b/doc/md/fundamentals/basic-syntax/printing_values.md @@ -10,7 +10,7 @@ import Debug "mo:base/Debug"; Debug.print("Hello, world!"); ``` -For debugging, `debug_show` converts most Motoko values into `Text`: +For debugging, `debug_show` converts most Motoko values into `Text`. The function handles primitive types and simple collections well but may not work with nested, recursive, or complex custom types, which may require **transformation or unwrapping** before use. ```motoko import Debug "mo:base/Debug"; @@ -18,3 +18,11 @@ Debug.print(debug_show(42)); // "42" ``` Since printing modifies output, it is considered an **impure function**, unlike pure functions that return values without side effects. + +`debug_show(42)` is pure because it always returns `"42"` without affecting anything outside the function. + +`Debug.print`("Hello, World!") is impure because it causes a side effect by printing to the console. + +## Quick references + +- [Base library Debug](https://internetcomputer.org/docs/current/motoko/main/base/Debug) From ea8be8dfddc4d2f73eb8fc4568b37f942091bfa9 Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 14:13:59 -0500 Subject: [PATCH 29/94] updates integer --- doc/md/fundamentals/basic-syntax/integers.md | 38 ++++++++++++++++++-- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/doc/md/fundamentals/basic-syntax/integers.md b/doc/md/fundamentals/basic-syntax/integers.md index ffd972b32e4..933c78eeb8e 100644 --- a/doc/md/fundamentals/basic-syntax/integers.md +++ b/doc/md/fundamentals/basic-syntax/integers.md @@ -4,11 +4,43 @@ sidebar_position: 4 # Integers -`Int` represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). By default, `Int` is unbounded, meaning it can grow as large as needed without overflow. +`Int` represents all integers, both positive and negative (e.g., -2, -1, 0, 1, 2). -For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (Int8, Int16, Int32, Int64). These types can overflow if their limits are exceeded, resulting in a runtime error. +For scenarios requiring fixed-size integers, Motoko offers bounded variants with specific bit-widths (`Int8`, `Int16`, `Int32`, `Int64`). These types can overflow if their limits are exceeded, resulting in a runtime error. ```motoko let a: Int = -42; -let c: Int32 = 2147483647; // max bounded 32-bit integer +let b: Int = 0; +let c: Int = 12345; ``` + +## Unbounded integers + +By default, `Int` is unbounded, meaning it can grow as large (or as small) as needed without causing overflow: + +```motoko +let bigNumber: Int = 999_999_999_999_999; +``` + +## Bounded integers + +For scenarios requiring fixed-size integers, Motoko offers bounded integer types with specific bit-widths: + +- `Int8` (8-bit signed integer) +- `Int16` (16-bit signed integer) +- `Int32` (32-bit signed integer) +- `Int64` (64-bit signed integer) + +Bounded integers can overflow if their limits are exceeded, resulting in a runtime error: + +```motoko +// let overflowInt: Int8 = 128; // Error: literal out of range Int8 +``` + +## Quick references + +- [Base library Int](https://internetcomputer.org/docs/current/motoko/main/base/Int) +- [Base library Int8](https://internetcomputer.org/docs/current/motoko/main/base/Int8) +- [Base library Int16](https://internetcomputer.org/docs/current/motoko/main/base/Int16) +- [Base library Int32](https://internetcomputer.org/docs/current/motoko/main/base/Int32) +- [Base library Int64](https://internetcomputer.org/docs/current/motoko/main/base/Int64) From 2aecba0797d036684c135a06c8456a77722c1935 Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 14:17:47 -0500 Subject: [PATCH 30/94] update to Float --- doc/md/fundamentals/basic-syntax/floats.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/md/fundamentals/basic-syntax/floats.md b/doc/md/fundamentals/basic-syntax/floats.md index 58107fc7c71..bdd16a7eedd 100644 --- a/doc/md/fundamentals/basic-syntax/floats.md +++ b/doc/md/fundamentals/basic-syntax/floats.md @@ -10,3 +10,7 @@ Floating-point numbers in Motoko are represented using the `Float` type, which c let pi: Float = 3.14159; let exp: Float = 2.71828; ``` + +## Quick references + +- [Base library Float](https://internetcomputer.org/docs/current/motoko/main/base/Float) From 93cdf13a8793bb785618ca462b1706518c901108 Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 14:40:25 -0500 Subject: [PATCH 31/94] update to Characters --- doc/md/fundamentals/basic-syntax/characters.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/md/fundamentals/basic-syntax/characters.md b/doc/md/fundamentals/basic-syntax/characters.md index 9b9f2f93cae..91cf7830921 100644 --- a/doc/md/fundamentals/basic-syntax/characters.md +++ b/doc/md/fundamentals/basic-syntax/characters.md @@ -10,3 +10,13 @@ The `Char` type in Motoko represents a single unicode character (`'`) delimited. let letter: Char = 'A'; let symbol: Char = '☃'; ``` + +Comparing characters + +```motoko +'I' == 'i' //false +``` + +## Quick references + +- [Base library Char](https://internetcomputer.org/docs/current/motoko/main/base/Char) From 480a0a10e5ebf66ed893d488f6ceea1d524dc91a Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 14:53:09 -0500 Subject: [PATCH 32/94] update to Text --- doc/md/fundamentals/basic-syntax/text.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/md/fundamentals/basic-syntax/text.md b/doc/md/fundamentals/basic-syntax/text.md index 74ac6d54008..ee26ade330e 100644 --- a/doc/md/fundamentals/basic-syntax/text.md +++ b/doc/md/fundamentals/basic-syntax/text.md @@ -9,3 +9,13 @@ Sequences of characters are handled using the `Text` type, which represents immu ```motoko let greeting: Text = "Hello, world!"; ``` + +Concatenating text + +```motoko +"ICP" # "x" # "Motoko" //ICP x Motoko +``` + +## Quick references + +- [Base library Text](https://internetcomputer.org/docs/current/motoko/main/base/Text) From 04ee43a78a4d6578234604e5d762f1fd18dc164b Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 15:08:26 -0500 Subject: [PATCH 33/94] update to literals --- doc/md/fundamentals/basic-syntax/literals.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/doc/md/fundamentals/basic-syntax/literals.md b/doc/md/fundamentals/basic-syntax/literals.md index 6e2892a3d5e..ab014266098 100644 --- a/doc/md/fundamentals/basic-syntax/literals.md +++ b/doc/md/fundamentals/basic-syntax/literals.md @@ -10,4 +10,15 @@ Literals are fixed values written directly in the code. - Float literals: `3.14`, `2.5e3` - Character literals: `'A'`, `'☃'` - Text literals: `"Hello"` - \ No newline at end of file + +You can use literals directly in expressions: + +Numeric literal in expression + +```motoko +100 + 50 +``` + +## Quick references + +- [Literals](https://internetcomputer.org/docs/current/motoko/main/reference/language-manual/#literals) From 2587cdf8a8910c775bb014f7f8425d5a141b825e Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 16:05:17 -0500 Subject: [PATCH 34/94] update to whitespace --- doc/md/fundamentals/basic-syntax/whitespace.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/md/fundamentals/basic-syntax/whitespace.md b/doc/md/fundamentals/basic-syntax/whitespace.md index 3cef3ac36ba..b67eb2d4262 100644 --- a/doc/md/fundamentals/basic-syntax/whitespace.md +++ b/doc/md/fundamentals/basic-syntax/whitespace.md @@ -5,3 +5,21 @@ sidebar_position: 9 # Whitespace Whitespace characters (spaces, tabs, newlines) are generally ignored in Motoko but are essential for separating tokens like keywords and identifiers. Proper use of whitespace enhances code readability. + +Without Proper Whitespace + +```motoko +actor Incrementer{public func inc(x:Int): async Int{return x+=1}} await Incrementer.inc(1); +``` + +With Proper Whitespace + +```motoko +actor Incrementer { + public func inc(x: Int) : async Int { + return x+=1; + }; +}; + +await Incrementer.inc(1); //2 +``` From 179e634a5d40dc427f854319afe9503833a1a499 Mon Sep 17 00:00:00 2001 From: Demali-876 <90882773+Demali-876@users.noreply.github.com> Date: Sat, 8 Feb 2025 17:21:11 -0500 Subject: [PATCH 35/94] updates --- doc/md/fundamentals/basic-syntax/assertion.md | 2 +- doc/md/fundamentals/basic-syntax/comments.md | 6 ++++ doc/md/fundamentals/basic-syntax/traps.md | 19 +++++++++++- .../expressions/integers-numbers.md | 31 +------------------ 4 files changed, 26 insertions(+), 32 deletions(-) diff --git a/doc/md/fundamentals/basic-syntax/assertion.md b/doc/md/fundamentals/basic-syntax/assertion.md index b23de919c7b..3c0c7377811 100644 --- a/doc/md/fundamentals/basic-syntax/assertion.md +++ b/doc/md/fundamentals/basic-syntax/assertion.md @@ -18,7 +18,7 @@ assert n % 2 == 0; // Succeeds Assertions help catch logic errors early, but should not be used for regular error handling. ```motoko actor and assert async async* await await* break case catch class composite continue debug From f45a68c2a18cc26570c5e9b9365d1dc4e76e1d6b Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Fri, 21 Feb 2025 15:16:34 -0500 Subject: [PATCH 93/94] Apply suggestions from code review Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/declarations/function_declarations.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/md/fundamentals/declarations/function_declarations.md b/doc/md/fundamentals/declarations/function_declarations.md index 16a5a5f310d..f0297090eb0 100644 --- a/doc/md/fundamentals/declarations/function_declarations.md +++ b/doc/md/fundamentals/declarations/function_declarations.md @@ -1,4 +1,8 @@ -# Functions +--- +sidebar_position: 2 +--- + +# Functions declarations A function in Motoko is a reusable block of code that takes inputs, processes them, and returns a result. Functions can be named or anonymous and can optionally specify parameter types and return types. From 99ae1fae392c3299950e39412d5d45aabb758204 Mon Sep 17 00:00:00 2001 From: "Demali.icp" <90882773+Demali-876@users.noreply.github.com> Date: Fri, 21 Feb 2025 15:20:46 -0500 Subject: [PATCH 94/94] Apply suggestions from code review Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com> --- doc/md/fundamentals/basic-syntax/text.md | 5 ++++- doc/md/fundamentals/declarations/class_declarations.md | 6 +++++- doc/md/fundamentals/declarations/expression_declarations.md | 4 ++++ doc/md/fundamentals/declarations/function_declarations.md | 4 +++- doc/md/fundamentals/declarations/object_declaration.md | 2 ++ doc/md/fundamentals/declarations/type_declarations.md | 3 +++ doc/md/fundamentals/declarations/variable_declarations.md | 4 ++++ doc/md/fundamentals/expressions/control-flow/block.md | 3 +++ doc/md/fundamentals/expressions/control-flow/option.md | 4 ++++ doc/md/fundamentals/expressions/control-flow/record.md | 5 +++++ doc/md/fundamentals/expressions/control-flow/switch.md | 4 ++++ doc/md/fundamentals/expressions/control-flow/tuple.md | 4 ++++ doc/md/fundamentals/expressions/control-flow/while_loop.md | 4 ++++ 13 files changed, 49 insertions(+), 3 deletions(-) diff --git a/doc/md/fundamentals/basic-syntax/text.md b/doc/md/fundamentals/basic-syntax/text.md index 8a3ddf51f4e..b6ccb3ce8b6 100644 --- a/doc/md/fundamentals/basic-syntax/text.md +++ b/doc/md/fundamentals/basic-syntax/text.md @@ -5,7 +5,10 @@ sidebar_position: 7 # Text Sequences of characters are handled using the `Text` type, which represents immutable strings of unicode characters (`"`) delimited. - + ```motoko let greeting: Text = "Hello, world!"; ``` diff --git a/doc/md/fundamentals/declarations/class_declarations.md b/doc/md/fundamentals/declarations/class_declarations.md index 94de13a9d02..33ab1c54141 100644 --- a/doc/md/fundamentals/declarations/class_declarations.md +++ b/doc/md/fundamentals/declarations/class_declarations.md @@ -1,4 +1,8 @@ -# Classes +--- +sidebar_position: 4 +--- + +# Class declarations A class in Motoko is a blueprint for creating objects. It encapsulates state (fields) and behavior (methods) while allowing instances to be created with specific data. Unlike records and objects, classes support constructors, enabling each instance to have unique values upon creation. diff --git a/doc/md/fundamentals/declarations/expression_declarations.md b/doc/md/fundamentals/declarations/expression_declarations.md index 3676c912a9d..0c056c92226 100644 --- a/doc/md/fundamentals/declarations/expression_declarations.md +++ b/doc/md/fundamentals/declarations/expression_declarations.md @@ -2,6 +2,10 @@ sidebar_position: 6 --- +--- +sidebar_position: 6 +--- + # Expression declarations An expression declaration is a statement where an expression is evaluated only for its side effects without assigning it to a variable. It does not introduce any new bindings. diff --git a/doc/md/fundamentals/declarations/function_declarations.md b/doc/md/fundamentals/declarations/function_declarations.md index f0297090eb0..d60c158f045 100644 --- a/doc/md/fundamentals/declarations/function_declarations.md +++ b/doc/md/fundamentals/declarations/function_declarations.md @@ -35,7 +35,7 @@ add(3, 5); ## Anonymous functions -Motoko supports anonymous functions (functions without names), often used in expressions or passed as arguments. +Motoko supports anonymous functions (functions without names). They are often used in expressions or passed as arguments. ```motoko let multiply = func (x: Int, y: Int) : Int { x * y }; @@ -66,6 +66,7 @@ func factorial(n: Nat) : Nat { if (n == 0) { return 1; }; +// Calls itself with factorial(n - 1), reducing n until reaching 0. return n * factorial(n - 1); } ``` @@ -99,6 +100,7 @@ One key advantage of `shared` functions is that they can access the caller's `Pr ```motoko actor Example { +// msg.caller retrieves the Principal of the caller. // msg.caller retrieves the Principal of the caller. public shared(msg) func whoAmI() : async Principal { return msg.caller; diff --git a/doc/md/fundamentals/declarations/object_declaration.md b/doc/md/fundamentals/declarations/object_declaration.md index 298f984445e..fa6e9fcf7a8 100644 --- a/doc/md/fundamentals/declarations/object_declaration.md +++ b/doc/md/fundamentals/declarations/object_declaration.md @@ -12,8 +12,10 @@ Objects are declared using the `object` keyword, followed by a block containing ```motoko let alice = object { +// name is an immutable public field of type Text. // name is an immutable public field of type Text. public let name = "Alice"; +// age is a mutable public field of type Int. // age is a mutable public field of type Int. public var age = 30; // greet is a public function that returns a greeting message. diff --git a/doc/md/fundamentals/declarations/type_declarations.md b/doc/md/fundamentals/declarations/type_declarations.md index 08cfc895aae..cbda5a8643f 100644 --- a/doc/md/fundamentals/declarations/type_declarations.md +++ b/doc/md/fundamentals/declarations/type_declarations.md @@ -53,9 +53,11 @@ A type can also define variants, representing different possible states. ```motoko // allows only one of its variants at a time. +// allows only one of its variants at a time. type Status = { #Active; #Inactive; +// carries an additional `Text` value. // carries an additional `Text` value. #Banned : Text; }; @@ -71,6 +73,7 @@ Type declarations can be parameterized to work with multiple types. ```motoko // `Box is a generic type where T represents any type. +// `Box is a generic type where T represents any type. type Box = { value: T; }; diff --git a/doc/md/fundamentals/declarations/variable_declarations.md b/doc/md/fundamentals/declarations/variable_declarations.md index 36aeb1ca29e..6896a86f437 100644 --- a/doc/md/fundamentals/declarations/variable_declarations.md +++ b/doc/md/fundamentals/declarations/variable_declarations.md @@ -2,6 +2,10 @@ sidebar_position: 1 --- +--- +sidebar_position: 1 +--- + # Variable declarations In Motoko, variables are declared using either `let` (immutable) or `var` (mutable). Understanding the difference between immutability and mutability is crucial when writing efficient and predictable code. diff --git a/doc/md/fundamentals/expressions/control-flow/block.md b/doc/md/fundamentals/expressions/control-flow/block.md index 128be7f113c..284466d6af6 100644 --- a/doc/md/fundamentals/expressions/control-flow/block.md +++ b/doc/md/fundamentals/expressions/control-flow/block.md @@ -1,6 +1,9 @@ --- sidebar_position: 9 --- +--- +sidebar_position: 9 +--- # Block expressions A block expression in Motoko is a sequence of statements enclosed in `{ ... }`. It allows grouping multiple operations, defining local variables, and structuring code logically. Blocks are essential to functions, as they define the function body and determine the return value. They follow these guidelines: diff --git a/doc/md/fundamentals/expressions/control-flow/option.md b/doc/md/fundamentals/expressions/control-flow/option.md index 36ce26826cb..5e775e6a7a2 100644 --- a/doc/md/fundamentals/expressions/control-flow/option.md +++ b/doc/md/fundamentals/expressions/control-flow/option.md @@ -2,6 +2,10 @@ sidebar_position: 11 --- +--- +sidebar_position: 11 +--- + # Options An option expression in Motoko is used to represent a value that may or may not be present. It is useful when a value could be missing, and it allows the program to handle both cases (present or absent) safely. An option can either hold a value or be `null` (indicating the absence of a value). diff --git a/doc/md/fundamentals/expressions/control-flow/record.md b/doc/md/fundamentals/expressions/control-flow/record.md index eaf9398bf87..9911c9655da 100644 --- a/doc/md/fundamentals/expressions/control-flow/record.md +++ b/doc/md/fundamentals/expressions/control-flow/record.md @@ -2,6 +2,10 @@ sidebar_position: 12 --- +--- +sidebar_position: 12 +--- + # Records A record is a collection of labeled fields, where each field has a name, type and a value. Records allow grouping related data into a structured format, making it easier to manage and access. @@ -94,6 +98,7 @@ The `with` keyword modifies, overrides, or adds fields when combining records. let person = { name : Text = "Alice"; age : Nat = 25; }; // age = 26; updates the existing age field. // city = "New York" adds a new field to the record. +// city = "New York" adds a new field to the record. let updatedPerson = { person with age : Nat = 26; city : Text = "New York"; }; Debug.print(debug_show (updatedPerson)); diff --git a/doc/md/fundamentals/expressions/control-flow/switch.md b/doc/md/fundamentals/expressions/control-flow/switch.md index 127b227ecc0..965dcb97371 100644 --- a/doc/md/fundamentals/expressions/control-flow/switch.md +++ b/doc/md/fundamentals/expressions/control-flow/switch.md @@ -2,6 +2,10 @@ sidebar_position: 7 --- +--- +sidebar_position: 7 +--- + # Switch A switch expression is a selection control structure used for pattern matching, allowing a program to evaluate a value and execute a corresponding block of code based on the match. It simplifies multiple conditional checks, making the code more readable and efficient by selecting one of several possible execution paths. diff --git a/doc/md/fundamentals/expressions/control-flow/tuple.md b/doc/md/fundamentals/expressions/control-flow/tuple.md index fa9c90a6407..b26b95724f3 100644 --- a/doc/md/fundamentals/expressions/control-flow/tuple.md +++ b/doc/md/fundamentals/expressions/control-flow/tuple.md @@ -2,6 +2,10 @@ sidebar_position: 10 --- +--- +sidebar_position: 10 +--- + # Tuples A tuple is a fixed-size, ordered collection of values, where each element can have a different type. Tuples provide a way to group multiple values together without defining a structured data type. diff --git a/doc/md/fundamentals/expressions/control-flow/while_loop.md b/doc/md/fundamentals/expressions/control-flow/while_loop.md index abacdbe582a..c041ef32d1c 100644 --- a/doc/md/fundamentals/expressions/control-flow/while_loop.md +++ b/doc/md/fundamentals/expressions/control-flow/while_loop.md @@ -2,6 +2,10 @@ sidebar_position: 5 --- +--- +sidebar_position: 5 +--- + # While loop A `while` loop in Motoko follows this structure: