Creating Modules

Overview

Modules (and Submodules, to be covered below) are created in one of two ways:

• Most commonly, by creating a file with a series of export statements of definitions to be exported from the module.
• For submodules inside a module, using the module command

The module file can be either:

• A file named mod.nu, in which case its directory becomes the module name
• Any other <module_name>.nu file, in which case the filename becomes the module name

Simple Module Example

Create a file named inc.nu with the following:

export def increment []: int -> int  {
    $in + 1
}

This is a module! We can now import it and use the increment command:

use inc.nu *
5 | increment
# => 6

Of course, you can easily distribute a file like this so that others can make use of the module as well.

Exports

We covered the types of definitions that are available in modules briefly in the main Modules Overview above. While this might be enough explanation for an end-user, module authors will need to know how to create the export definitions for:

• Commands (export def)
• Aliases (export alias)
• Constants (export const)
• Known externals (export extern)
• Submodules (export module)
• Imported symbols from other modules (export use)
• Environment setup (export-env)

main Exports

In the Basic Example above, we had a module named inc with a command named increment. However, if we rename that file to increment.nu, it will fail to import.

mv inc.nu increment.nu

use increment.nu *
# => Error: nu::parser::named_as_module
# =>
# =>   × Can't export command named same as the module.
# =>    ╭─[/home/me/modules/increment.nu:1:12]
# =>  1 │ export def increment []: int -> int  {
# =>    ·            ────┬────
# =>    ·                ╰── can't export from module increment
# =>  2 │     $in + 1
# =>    ╰────
# =>   help: Module increment can't export command named the same as the module. Either change the module name, or export `main` command.

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:

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

Now it works as expected:

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

use <module> <other_definition>
# or
use <module> [ <other_definitions> ]

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:

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.

Subcommands

As covered in Custom Commands, 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:

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:

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.

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

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

2. In the my-utils directory, create a range-into-list.nu file with the following:

   export def main []: range -> list {
       # It looks odd, yes, but the following is just
       # a simple way to convert ranges to lists
       each {||}
   }

3. Test it:

   use range-into-list.nu
   1..5 | range-into-list | describe
   # => list<int> (stream)

4. We should now have a my-utils directory with the:

   • increment.nu module
   • range-into-list.nu module

The following examples show how to create a module with submodules.

Example: Submodule with export module

The most common form for a submodule definition is with export module.

1. Create a new module named my-utils. Since we're in the my-utils directory, we will create a mod.nu to define it. This version of my-utils/mod.nu will contain:

   export module ./increment.nu
   export module ./range-into-list.nu

2. We now have a module my-utils with the two submodules. Go to the parent directory of my-utils:

   cd ..

   Then try it out:

   use my-utils *
   5 | increment by 4
   # => 9
   
   let file_indices = 0..2..<10 | range-into-list
   ls | select ...$file_indices
   # Returns the 1st, 3rd, 5th, 7th, and 9th file in the directory

   Note the *. Without it, use my-utils would import nothing at all, since everything in my-utils is in one of its two submodules. use my-utils increment would import just the increment submodule (increment and increment by).

Before proceeding to the next section, run scope modules and look for the my-utils module. Notice that it has no commands of its own; just the two submodules.

Example: Submodule with export use

Alternatively, we can (re)export the definitions from other modules. This is slightly different from the first form, in that the commands (and other definitions, if they were present) from increment and range-into-list become members of the my-utils module itself. We'll be able to see the difference in the output of the scope modules command.

Let's change my-utils/mod.nu to:

export use ./increment.nu
export use ./range-into-list.nu

Start a new shell in the parent directory of my-utils (see the note at the start of this chapter) and try it out using the same commands as above:

use my-utils *
5 | increment by 4
# => 9

let file_indices = 0..2..<10 | range-into-list
ls / | sort-by modified | select ...$file_indices
# Returns the 1st, 3rd, 5th, 7th, and 9th file in the root directory, oldest-to-newest

Run scope modules again and notice that all of the commands from the submodules are re-exported into the my-utils module.

Because the commands are now members of my-utils itself, importing the module without * also works. The commands then become subcommands of my-utils:

use my-utils
5 | my-utils increment by 4
# => 9

Documenting Modules

As with custom commands, modules can include documentation that can be viewed with help <module_name>. The documentation is simply a series of commented lines at the beginning of the module file. Let's document the my-utils module:

# A collection of helpful utility functions

export use ./increment.nu
export use ./range-into-list.nu

Now, in a new shell, examine the help:

use my-utils *
help my-utils
# => A collection of helpful utility functions
# =>
# => Module: my-utils
# =>
# => Exported commands:
# =>   increment, increment by, range-into-list
# =>
# => Exported aliases:
# =>
# =>
# => This module does not export environment.

Also notice that, because the commands from increment and range-into-list are re-exported with export use ..., those commands show up in the help for the main module as well.

Environment Variables

Modules can define an environment using export-env. Let's extend our my-utils module with an environment variable export for a common directory where we'll place our modules in the future. This directory is (by default) in the $NU_LIB_DIRS search path discussed in Using Modules - Module Path.

# A collection of helpful utility functions

export use ./increment.nu
export use ./range-into-list.nu

export-env {
    $env.NU_MODULES_DIR = ($nu.default-config-dir | path join "scripts")
}

When this module is imported with use (again in a new shell), the code inside the export-env block is run and the its environment merged into the current scope:

use my-utils
$env.NU_MODULES_DIR
# => /home/me/.config/nushell/scripts

export def examine-config-dir [] {
    # Changes the PWD environment variable
    cd $nu.default-config-dir
    ls
}

Caveats

export-env runs only when the use call is evaluated

Attempting to import a module's environment within another environment may not work as expected. Let's create a new module go.nu that creates "shortcuts" to common directories. One of these will be the $env.NU_MODULES_DIR defined above in my-utils.

We might try:

# go.nu, in the parent directory of my-utils
use my-utils

export def --env home [] {
    cd ~
}

export def --env modules [] {
    cd $env.NU_MODULES_DIR
}

And then import it. (The first line removes $env.NU_MODULES_DIR in case it is still set from the example above.)

hide-env -i NU_MODULES_DIR
use go.nu
go home  # works: changes to your home directory
cd -     # go back
go modules
# => Error: nu::shell::column_not_found
# =>
# =>   × Cannot find column 'NU_MODULES_DIR'
# =>     ╭─[/home/me/modules/go.nu:9:8]
# =>   8 │ export def --env modules [] {
# =>   9 │     cd $env.NU_MODULES_DIR
# =>     ·        ─────────┬─────────┬
# =>     ·                 │         ╰── value originates here
# =>     ·                 ╰── column 'NU_MODULES_DIR' is missing in one or more values
# =>  10 │ }
# =>     ╰────
# =>   help: If some rows have this column, try using 'NU_MODULES_DIR?' for optional access, or pre-fill using the `default` command

This doesn't work because my-utils isn't evaluated in this case; it is only parsed when the go.nu module is imported. While this brings all of the other exports into scope, it does not run the export-env block.

To bring my-utils exported environment into scope for the go.nu module, there are two options:

1. Import the module in each command where it is needed

   By placing use my-utils in the go modules command itself, its export-env will be evaluated when the command is. For example:

   # go.nu
   export def --env home [] {
       cd ~
   }
   
   export def --env modules [] {
       use my-utils
       cd $env.NU_MODULES_DIR
   }

2. Import the my-utils environment inside an export-env block in the go.nu module

   use my-utils
   export-env {
       use my-utils []
   }
   
   export def --env home [] {
       cd ~
   }
   
   export def --env modules [] {
       cd $env.NU_MODULES_DIR
   }

   In the example above, go.nu imports my-utils twice:

   1. The first use my-utils imports the module and its definitions (except for the environment) into the module scope.
   2. The second use my-utils [] imports nothing but the environment into go.nu's exported environment block. Because the export-env of go.nu is executed when the module is first imported, the use my-utils [] is also evaluated.

Note that the first method only loads the my-utils environment when go modules runs. (Because go modules is defined with --env, the environment it sets, including $env.NU_MODULES_DIR, is then kept in the caller's scope.) The second, on the other hand, re-exports my-utils environment into the user scope as soon as go.nu is imported.

Exports cannot be named after their module

A module cannot export a command, alias, or known external defined inside it that has the same name as the module itself. For commands and known externals, name the definition main instead, as covered in main Exports above. The same restriction applies to a submodule declared by name, so export module spam inside a module named spam is rejected:

module spam { export module spam { } }
# => Error: nu::parser::named_as_module
# =>
# =>   × Can't export module named same as the module.
# =>    ╭─[repl_entry #1:1:29]
# =>  1 │ module spam { export module spam { } }
# =>    ·                             ──┬─
# =>    ·                               ╰── can't export from module spam
# =>    ╰────
# =>   help: Module spam can't export module named the same as the module. Either change the module name, or export `mod` module.

Parser keywords cannot be used as names

Parser keywords such as if, match, source, or use can't be used as the name of a command or alias, whether it's exported from a module or not. Such a definition fails with nu::parser::name_is_keyword. You can list the keywords with help commands | where command_type == keyword.

The same applies to a module named after a keyword: it can't export a main command, because the parser would always handle the name as the keyword instead:

module match { export def main [] { "matched" } }
use match
# => Error: nu::parser::keyword_shadow_module_main
# =>
# =>   × Module `match` has a `main` command but `match` is a built-in parser keyword.
# =>    ╭─[repl_entry #1:2:5]
# =>  1 │ module match { export def main [] { "matched" } }
# =>  2 │ use match
# =>    ·     ──┬──
# =>    ·       ╰── `match` is a parser keyword
# =>    ╰────
# =>   help: The `main` command cannot be invoked because `match` is intercepted by the parser. Either rename the module file, or remove `export def main` and use `use match.nu *` to import other
# =>         commands.

Windows Path Syntax

Additional Examples

Local Definitions

As mentioned above, definitions in a module without the export keyword are only accessible in the module's scope.

To demonstrate, create a new module is-alphanumeric.nu. Inside this module, we'll create a str is-alphanumeric command. If any of the characters in the string are not alpha-numeric, it returns false:

# is-alphanumeric.nu
def alpha-num-range [] {
    [
        ...(seq char 'a' 'z')
        ...(seq char 'A' 'Z')
        ...(seq 0 9 | each { into string })
    ]
}

export def "str is-alphanumeric" []: string -> bool {
    if ($in == '') {
        false
    } else {
        let chars = (split chars)
        $chars | all {|char| $char in (alpha-num-range)}
    }
}

Notice that we have two definitions in this module -- alpha-num-range and str is-alphanumeric, but only the second is exported.

use is-alphanumeric.nu *
'Word' | str is-alphanumeric
# => true
'Some punctuation?!' | str is-alphanumeric
# => false
'a' in (alpha-num-range)
# => Error: nu::shell::external_command
# =>
# =>   × External command failed
# =>    ╭─[repl_entry #4:1:9]
# =>  1 │ 'a' in (alpha-num-range)
# =>    ·         ───────┬───────
# =>    ·                ╰── Command `alpha-num-range` not found
# =>    ╰────
# =>   help: `alpha-num-range` is neither a Nushell built-in or a known external command

Selective Export from a Submodule

As mentioned in the Submodules section above, only export use can selectively export definitions from a submodule.

To demonstrate, let's add a modified form of the go.nu module example above to my-utils:

# go.nu, in the my-utils directory
export def --env home [] {
    cd ~
}

export def --env modules [] {
    cd ($nu.default-config-dir | path join "scripts")
}

export alias h = home
export alias m = modules

This go.nu includes the following changes from the original:

• It doesn't rely on the my-utils mod since it will now be a submodule of my-utils instead
• It adds "shortcut" aliases: h: Goes to the home directory (alias of go home) m: Goes to the modules directory (alias of go modules)

A user could import just the aliases with:

use my-utils/go.nu [h, m]

However, let's say we want to have go.nu be a submodule of my-utils. When a user imports my-utils, they should only get the commands, but not the aliases. Edit my-utils/mod.nu and add:

export use ./go.nu [home, modules]

That almost works -- It selectively exports home and modules, but not the aliases. However, it does so without the go prefix. To see this, start a new shell in the parent directory of my-utils, then:

use my-utils *
home  # works: changes to your home directory
cd -  # go back
go home
# => Error: nu::shell::external_command
# =>
# =>   × External command failed
# =>    ╭─[repl_entry #1:4:1]
# =>  3 │ cd -  # go back
# =>  4 │ go home
# =>    · ─┬
# =>    ·  ╰── Command `go` not found
# =>    ╰────
# =>   help: Did you mean `do`?

To export them as go home and go modules, make the following change to my-utils/mod.nu:

# Replace the `export use ./go.nu [home, modules]` line with ...
export module go {
    export use ./go.nu [home, modules]
}

This creates a new, exported submodule go in my-utils with the selectively (re)exported definitions for go home and go modules. In a new shell in the parent directory of my-utils, it works as expected:

use my-utils *
go home  # works: changes to your home directory
cd -     # go back
home
# => Error: nu::shell::external_command
# =>
# =>   × External command failed
# =>    ╭─[repl_entry #1:4:1]
# =>  3 │ cd -     # go back
# =>  4 │ home
# =>    · ──┬─
# =>    ·   ╰── Command `home` not found
# =>    ╰────
# =>   help: Did you mean `go home`?