Coco Module

Module is a complete source code of a logic that can be compiled into a manifest. It contains one or more .coco files and a coco.nut configuration file. It can import packages, that are reusable collection of .coco and coco.nut files in their own folders.

Organization of a Module

A module in Coco is a collection of all .coco files in a folder that all start with the same coco <module_name> as the first line of the program. If a .coco file exists in the folder with a module name that's different from the others, compilation will fail.

coco Flipper

Configuration (coco.nut)

The coco.nut file is the configuration file for your module, written in TOML format. It controls both the compilation process and the Cocolab test environment.

• Creation: You generate this file using the CLI command: coco nut init <module_name>
• Naming Rule: The module name defined in this file must match the coco <module_name> statement found at the top of your source files.

The default value of coco.nut file is below, comments explain the meaning.

Show full coco.nut file

coco.nut

# Coco compiler version
[coco]
version = "0.7.0"

# Module name and some attributes
[module]
name = "Flipper"
version = "0.0.1"
license = []
repository = ""
authors = []

# Compilation target, MOI-PISA is the only supported target for now
[target]
os = "MOI"
arch = "PISA"

# Manifest format (YAML, JSON or POLO) and manifest name (flipper.yaml in this example)
[target.moi]
format = "YAML"
output = "flipper"

# Format of binary PISA code in the manifest (BIN, HEX or ASM) and PISA version
# Supported versions are 0.3.2, 0.4.0 and 0.5.0, assets are only supported in 0.5.0
# Coco syntax is partially dependent on PISA version, so this setting is very important
[target.pisa]
format = "BIN"
version = "0.5.0"

# Cocolab flags
[lab.render]
big_int_as_hex = true
bytes_as_hex = false

[lab.config.default]
env = "main"

# Cocolab scripts that can be run using `coco lab run test-toggle`
[lab.scripts]
test-toggle = ["engines", "users", "logics"]

# Compiler scripts that are run with `coco nut run test-script`
[scripts]
test-script = "coco compile .; pwd; uname -a"

The Module Superglobal

The name of the module is one of Coco's superglobals. It can be used to access the state information of the module as well as other information about the logic module.

Similar to this in Java/C++ or self in Python

In the NumberStore module, the mutate value -> NumberStore.Logic.value statement is using the module superglobal to access the module's state and mutate it with some value.

number_store.coco

coco NumberStore

state logic:
	value U64

endpoint deploy Init(value U64):
	mutate value -> NumberStore.Logic.value

endpoint LogicId() -> (id Identifier):
	yield id Identifier(NumberStore)

Packages

A package is a collection of reusable source code that can be imported into any module.

Note: Coco 0.7.0 currently only supports local packages. Source code must reside on the local disk and be imported using relative paths.

Directory Structure

To use a package, place the .coco files in a subfolder.

Example: Importing a math package into main.

project/
├ main.coco             // Your Logic
└ math/                    // Package Folder
       └ math.coco    // Package Source Code

Importing & Syntax

• Importing: Use the imports block with the relative path (e.g., "./math")
• Accessing: Use the double-colon syntax package::Element (e.g., math::Point)
• Visibility (pub): By default, code in a package is private. You must add the pub keyword to classes and functions to make them visible to other modules

Code Example

The following example demonstrates how to share a Class (Data Structure) using a package.

1. The Package Provider (math/math.coco)

This file defines a reusable Rectangle class. Notice the use of pub to expose the class and its method.

math/math.coco

// Package `math` in subfolder provides class `Rectangle`
coco package math

pub class Rectangle:
    field width U64
    field height U64

    // Encapsulated logic to calculate area
    pub method area() -> (a U64):
        a = self.width * self.height

2. The Consumer (main.coco)

This module imports the package and uses the Rectangle class to perform a check.

main.coco

// Module `main` imports package `./math`
coco main

imports:
    "./math"

endpoint CheckSize() -> (is_big Bool):
    // 1. Create a Rectangle using the package
    memory rect = math::Rectangle{width: 10, height: 20}

    // 2. Call the method defined in the package
    memory size = (a) <- rect.area()

    // 3. Use the result
    if size > 100:
        is_big = true

coco.nut for packages

Packages have different coco.nut contents that are created using

coco nut init-package <package_name>

Show coco.nut for packages

coco.nut

[coco]
version = "0.7.0"

[package]
name = "package_name"
version = "0.0.1"
license = []
repository = ""
authors = []

[package.targets]
supported = []
unsupported = []