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
# => ...
# => 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. Try it out:

   # Go to the parent directory of my-utils
   cd ..
   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

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

Try it out using the same commands as above:

# Go to the parent directory of my-utils
cd ..
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 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.

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 examine the help:

use my-utils *
help my-utils

# => A collection of helpful utility functions

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 $env.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, 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
# => Returns the directory name
cd $env.NU_MODULES_DIR

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:

use go.nu
go home
# => Works
go modules
# => Error: $env.NU_MODULES_DIR is not found

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 home 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 keeps my-utils environment inside the go.nu module's scope. The second, on the other hand, re-exports my-utils environment into the user scope.

Module files and commands cannot be named after parent module

A .nu file cannot have the same name as its module directory (e.g., spam/spam.nu) as this would create an ambiguous condition with the name being defined twice. This is similar to the situation described above where a command cannot have the same name as its parent.

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:
# => 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. For example:

use my-utils *
home
# => works
go home
# => Error: command not found

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

# Replace the existing `export use` 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.

use my-utils *
# => As expected:
go home
# => works
home
# => Error: command not found