Home Explore Blog CI



nushell

2nd chunk of `book/modules/creating_modules.md`
7047068209056f7b0141ac16ca96bca93381846d800edeef0000000100000fa0
As helpfully mentioned in the error message, you can simply rename the export `main`, in which case it will take on the name of the module when imported. Edit the `increment.nu` file:

```nu
export def main []: int -> int {
    $in + 1
}
```

Now it works as expected:

```nu
use ./increment.nu
2024 | increment
# => 2025
```

::: note
`main` can be used for both `export def` and `export extern` definitions.
:::

::: tip
`main` definitions are imported in the following cases:

- The entire module is imported with `use <module>` or `use <module.nu>`
- The `*` glob is used to import all of the modules definitions (e.g., `use <module> *`, etc.)
- The `main` definition is explicitly imported with `use <module> main`, `use <module> [main]`, etc.)

Conversely, the following forms do _not_ import the `main` definition:

````nu
use <module> <other_definition>
# or
use <module> [ <other_definitions> ]
:::

::: note
Additionally, `main` has special behavior if used in a script file, regardless of whether it is exported or not. See the [Scripts](scripts.html#parameterizing-scripts) chapter for more details.
:::

## Module Files

As mentioned briefly in the Overview above, modules can be created either as:

1. `<module_name>.nu`: "File-form" - Useful for simple modules
2. `<module_name>/mod.nu`: "Directory-form" - Useful for organizing larger module projects where submodules can easily map to subdirectories of the main module

The `increment.nu` example above is clearly an example of (1) the file-form. Let's try converting it to the directory-form:

```nu
mkdir increment
mv increment.nu increment/mod.nu

use increment *
41 | increment
# => 42
````

Notice that the behavior of the module once imported is identical regardless of whether the file-form or directory-form is used; only its path changes.

::: note
Technically, you can import this either using the directory form above or explicitly with `use increment/mod.nu *`, but the directory shorthand is preferred when using a `mod.nu`.
:::

## Subcommands

As covered in [Custom Commands](../custom_commands.md), subcommands allow us to group commands logically. Using modules, this can be done in one of two ways:

1. As with any custom command, the command can be defined as `"<command> <subcommand>"`, using a space inside quotes. Let's add an `increment by` subcommand to the `increment` module we defined above:

```nu
export def main []: int -> int {
    $in + 1
}

export def "increment by" [amount: int]: int -> int {
    $in + $amount
}
```

It can then be imported with `use increment *` to load both the `increment` command and `increment by` subcommand.

2. Alternatively, we can define the subcommand simply using the name `by`, since importing the entire `increment` module will result in the same commands:

```nu
export def main []: int -> int {
    $in + 1
}

export def by [amount: int]: int -> int {
    $in + $amount
}
```

This module is imported using `use increment` (without the glob `*`) and results in the same `increment` command and `increment by` subcommand.

::: note
We'll continue to use this version for further examples below, so notice that the import pattern has changed to `use increment` (rather than `use increment *`) below.
:::

## Submodules

Submodules are modules that are exported from another module. There are two ways to add a submodule to a module:

1. With `export module`: Exports (a) the submodule and (b) its definitions as members of the submodule
2. With `export use`: Exports (a) the submodule and (b) its definitions as members of the parent module

To demonstrate the difference, let's create a new `my-utils` module, with our `increment` example as a submodule. Additionally, we'll create a new `range-into-list` command in its own submodule.

1. Create a directory for the new `my-utils` and move the `increment.nu` into it

   ```nu
   mkdir my-utils
   # Adjust the following as needed
   mv increment/mod.nu my-utils/increment.nu
   rm increment
   cd my-utils
   ```

Title: Module Files, Subcommands, and Submodules in Nushell
Summary
This section covers different ways to structure modules in Nushell. It explains how to use the `main` export to name a module after the file it is in. It also details the "file-form" and "directory-form" of module creation. Additionally, it explains how to create subcommands within modules, either by defining them with a space in the command name or by defining them as separate functions and importing the module without the `*` glob. The section then moves on to describe submodules, which are modules exported from another module, using `export module` and `export use`.