Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[book] Follow up - .md update #98

Merged
merged 2 commits into from
Oct 21, 2024
Merged

[book] Follow up - .md update #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db007fd
adds module label everywhere
damirka Oct 21, 2024
d58ad8c
follow up, whoopsie
damirka Oct 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 3 additions & 7 deletions book/src/move-basics/comments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,11 @@ comment.

## Line comment

```Move
{{#include ../../../packages/samples/sources/move-basics/comments.move:line}}
```

You can use double slash `//` to comment out the rest of the line. Everything after `//` will be
ignored by the compiler.

```Move
{{#include ../../../packages/samples/sources/move-basics/comments.move:line_2}}
{{#include ../../../packages/samples/sources/move-basics/comments-line.move:main}}
```

## Block comment
Expand All @@ -38,7 +34,7 @@ Everything between `/*` and `*/` will be ignored by the compiler. You can use bl
comment out a single line or multiple lines. You can even use them to comment out a part of a line.

```Move
{{#include ../../../packages/samples/sources/move-basics/comments.move:block}}
{{#include ../../../packages/samples/sources/move-basics/comments-block.move:main}}
```

This example is a bit extreme, but it shows how you can use block comments to comment out a part of
Expand All @@ -51,7 +47,7 @@ They are similar to block comments, but they start with three slashes `///` and
the definition of the item they document.

```Move
{{#include ../../../packages/samples/sources/move-basics/comments.move:doc}}
{{#include ../../../packages/samples/sources/move-basics/comments-doc.move:main}}
```

<!-- TODO: docgen, which members are in the documentation -->
18 changes: 9 additions & 9 deletions book/src/move-basics/constants.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ price for a product, you might define a constant for it. Constants are stored in
bytecode, and each time they are used, the value is copied.

```move
{{#include ../../../packages/samples/sources/move-basics/constants.move:shop_price}}
{{#include ../../../packages/samples/sources/move-basics/constants-shop-price.move:shop_price}}
```

## Naming Convention
Expand All @@ -35,7 +35,7 @@ It's a way to make constants stand out from other identifiers in the code. One e
[error constants](./assert-and-abort.md#assert-and-abort), which are written in ECamelCase.

```move
{{#include ../../../packages/samples/sources/move-basics/constants.move:naming}}
{{#include ../../../packages/samples/sources/move-basics/constants-naming.move:naming}}
```

## Constants are Immutable
Expand All @@ -44,13 +44,13 @@ Constants can't be changed and assigned new values. They are part of the package
inherently immutable.

```move
module book::immutable_constants {
const ITEM_PRICE: u64 = 100;
module book::immutable_constants;

// emits an error
fun change_price() {
ITEM_PRICE = 200;
}
const ITEM_PRICE: u64 = 100;

// emits an error
fun change_price() {
ITEM_PRICE = 200;
}
```

Expand All @@ -61,7 +61,7 @@ codebase. But due to constants being private to the module, they can't be access
modules. One way to solve this is to define a "config" module that exports the constants.

```move
{{#include ../../../packages/samples/sources/move-basics/constants.move:config}}
{{#include ../../../packages/samples/sources/move-basics/constants-config.move:config}}
```

This way other modules can import and read the constants, and the update process is simplified. If
Expand Down
4 changes: 2 additions & 2 deletions book/src/move-basics/function.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ the `fun` keyword at the module level. Just like any other module member, by def
and can only be accessed from within the module.

```move
{{#include ../../../packages/samples/sources/move-basics/function.move:math}}
{{#include ../../../packages/samples/sources/move-basics/function_math.move:math}}
```

In this example, we define a function `add` that takes two arguments of type `u64` and returns their
Expand Down Expand Up @@ -38,7 +38,7 @@ function called `add` in the `math` module in the `book` package, the path to it
`book::math::add`, or, if the module is imported, `math::add`.

```move
{{#include ../../../packages/samples/sources/move-basics/function.move:use_math}}
{{#include ../../../packages/samples/sources/move-basics/function_use.move:use_math}}
```

## Multiple return values
Expand Down
12 changes: 6 additions & 6 deletions book/src/move-basics/importing-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Another module defined in the same package can import the first module using the

```move
// File: sources/module_two.move
{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:module_two}}
{{#include ../../../packages/samples/sources/move-basics/importing-modules-two.move:module_two}}
```

## Importing Members
Expand All @@ -48,7 +48,7 @@ function or a single type from a module. The syntax is the same as for importing
add the member name after the module path.

```move
{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:members}}
{{#include ../../../packages/samples/sources/move-basics/importing-modules-members.move:members}}
```

## Grouping Imports
Expand All @@ -58,7 +58,7 @@ when you need to import multiple members from the same module. Move allows group
same module and from the same package.

```move
{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:grouped}}
{{#include ../../../packages/samples/sources/move-basics/importing-modules-grouped.move:grouped}}
```

Single function imports are less common in Move, since the function names can overlap and cause
Expand All @@ -69,7 +69,7 @@ To import members and the module itself in the group import, you can use the `Se
`Self` keyword refers to the module itself and can be used to import the module and its members.

```move
{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:self}}
{{#include ../../../packages/samples/sources/move-basics/importing-modules-self.move:self}}
```

## Resolving Name Conflicts
Expand All @@ -81,7 +81,7 @@ in different packages. To resolve the conflict and avoid ambiguity, Move offers
rename the imported member.

```move
{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:conflict}}
{{#include ../../../packages/samples/sources/move-basics/importing-modules-conflict-resolution.move:conflict}}
```

## Adding an External Dependency
Expand Down Expand Up @@ -116,5 +116,5 @@ To import a module from another package, you use the `use` keyword followed by t
module path consists of the package address (or alias) and the module name separated by `::`.

```move
{{#include ../../../packages/samples/sources/move-basics/importing-modules.move:external}}
{{#include ../../../packages/samples/sources/move-basics/importing-modules-external.move:external}}
```
20 changes: 16 additions & 4 deletions book/src/move-basics/module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,17 +18,19 @@ learn how to define a module, how to declare its members and how to access them

## Module declaration

Modules are declared using the `module` keyword followed by the package address, module name and the
module body inside the curly braces `{}`. The module name should be in `snake_case` - all lowercase
letters with underscores between words. Modules names must be unique in the package.
Modules are declared using the `module` keyword followed by the package address, module name,
semicolon, and the module body. The module name should be in `snake_case` - all lowercase letters
with underscores between words. Modules names must be unique in the package.

Usually, a single file in the `sources/` folder contains a single module. The file name should match
the module name - for example, a `donut_shop` module should be stored in the `donut_shop.move` file.
You can read more about coding conventions in the
[Coding Conventions](../special-topics/coding-conventions.md) section.

> If you need to declare more than one module in a file, you must use [Module Block](#module-block).

```Move
{{#include ../../../packages/samples/sources/move-basics/module.move:module}}
{{#include ../../../packages/samples/sources/move-basics/module-label.move:module}}
```

Structs, functions, constants and imports all part of the module:
Expand Down Expand Up @@ -63,6 +65,16 @@ book = "0x0"
Module members are declared inside the module body. To illustrate that, let's define a simple module
with a struct, a function and a constant:

```Move
{{#include ../../../packages/samples/sources/move-basics/module-members.move:members}}
```

## Module block

Pre-2024 edition of Move required _module block_ - the contents of the module need to be surrounded
by curly braces `{}`. The main reason to use block and not _label_ is if you need to define more
than one module in a file.

```Move
{{#include ../../../packages/samples/sources/move-basics/module.move:members}}
```
Expand Down
126 changes: 63 additions & 63 deletions book/src/move-basics/ownership-and-scope.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,21 @@ scope and executes every expression and statement. Once the function scope end,
defined in it are dropped or deallocated.

```move
module book::ownership {
public fun owner() {
let a = 1; // a is owned by the `owner` function
} // a is dropped here

public fun other() {
let b = 2; // b is owned by the `other` function
} // b is dropped here

#[test]
fun test_owner() {
owner();
other();
// a & b is not valid here
}
module book::ownership;

public fun owner() {
let a = 1; // a is owned by the `owner` function
} // a is dropped here

public fun other() {
let b = 2; // b is owned by the `other` function
} // b is dropped here

#[test]
fun test_owner() {
owner();
other();
// a & b is not valid here
}
```

Expand All @@ -48,18 +48,18 @@ If we changed the `owner` function to return the variable `a`, then the ownershi
transferred to the caller of the function.

```move
module book::ownership {
public fun owner(): u8 {
let a = 1; // a defined here
a // scope ends, a is returned
}

#[test]
fun test_owner() {
let a = owner();
// a is valid here
} // a is dropped here
module book::ownership;

public fun owner(): u8 {
let a = 1; // a defined here
a // scope ends, a is returned
}

#[test]
fun test_owner() {
let a = owner();
// a is valid here
} // a is dropped here
```

## Passing by Value
Expand All @@ -69,22 +69,22 @@ transferred to this function. When performing this operation, we _move_ the valu
another. This is also called _move semantics_.

```move
module book::ownership {
public fun owner(): u8 {
let a = 10;
a
} // a is returned

public fun take_ownership(v: u8) {
// v is owned by `take_ownership`
} // v is dropped here

#[test]
fun test_owner() {
let a = owner();
take_ownership(a);
// a is not valid here
}
module book::ownership;

public fun owner(): u8 {
let a = 10;
a
} // a is returned

public fun take_ownership(v: u8) {
// v is owned by `take_ownership`
} // v is dropped here

#[test]
fun test_owner() {
let a = owner();
take_ownership(a);
// a is not valid here
}
```

Expand All @@ -95,34 +95,34 @@ sequence of statements and expressions, and it has its own scope. Variables defi
owned by this block, and when the block ends, the variables are dropped.

```move
module book::ownership {
public fun owner() {
let a = 1; // a is owned by the `owner` function's scope
module book::ownership;

public fun owner() {
let a = 1; // a is owned by the `owner` function's scope
{
let b = 2; // b is owned by the block
{
let b = 2; // b is owned by the block
{
let c = 3; // c is owned by the block
}; // c is dropped here
}; // b is dropped here
// a = b; // error: b is not valid here
// a = c; // error: c is not valid here
} // a is dropped here
}
let c = 3; // c is owned by the block
}; // c is dropped here
}; // b is dropped here
// a = b; // error: b is not valid here
// a = c; // error: c is not valid here
} // a is dropped here
```

However, shall we use the return value of a block, the ownership of the variable is transferred to
the caller of the block.

```move
module book::ownership {
public fun owner(): u8 {
let a = 1; // a is owned by the `owner` function's scope
let b = {
let c = 2; // c is owned by the block
c // c is returned
}; // c is dropped here
a + b // both a and b are valid here
}
module book::ownership;

public fun owner(): u8 {
let a = 1; // a is owned by the `owner` function's scope
let b = {
let c = 2; // c is owned by the block
c // c is returned
}; // c is dropped here
a + b // both a and b are valid here
}
```

Expand Down
1 change: 0 additions & 1 deletion book/src/move-basics/references.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@ module book::metro_pass {
{{#include ../../../packages/samples/sources/move-basics/references.move:header}}
{{#include ../../../packages/samples/sources/move-basics/references.move:new}}
}
```

<!-- In [the previous section](./ownership-and-scope.md) we explained the ownership and scope in Move. We showed how the value is *moved* to a new scope, and how it changes the owner. In this section, we will explain how to *borrow* a reference to a value to avoid moving it, and how Move's *borrow checker* ensures that the references are used correctly. -->
Expand Down
4 changes: 2 additions & 2 deletions book/src/move-basics/struct-methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ with `hero_` and `villain_` respectively. However, we can create aliases for the
they can be called on the instances of the structs without the prefix.

```move
{{#include ../../../packages/samples/sources/move-basics/struct-methods.move:hero_and_villain}}
{{#include ../../../packages/samples/sources/move-basics/struct-methods-2.move:hero_and_villain}}
```

As you can see, in the test function, we called the `health` method on the instances of `Hero` and
Expand All @@ -57,7 +57,7 @@ associate it with the `Hero` struct. It will allow serializing the `Hero` struct
bytes.

```move
{{#include ../../../packages/samples/sources/move-basics/struct-methods.move:hero_to_bytes}}
{{#include ../../../packages/samples/sources/move-basics/struct-methods-3.move:hero_to_bytes}}
```

## Further reading
Expand Down
Loading
Loading