txt: ## module-packages.md
  Module packages
  
  Creating module packages for code reuse
  
  *N.B.* "Module" is an overloaded term in Raku; this document focuses on use of the `module` declarator.
  
  # [What are modules?](#Module_packages "go to top of document")[§](#What_are_modules? "direct link")
  
  Modules, like classes and grammars, are a kind of [package](/language/packages). Module objects are instances of the `ModuleHOW` metaclass; this provides certain capabilities useful for creating namespaces, versioning, delegation and data encapsulation (see also [class](/syntax/class) and [role](/syntax/role)).
  
  To create a module, use the `module` declarator:
  
  ```raku
  module M {}
  say M.HOW;   # OUTPUT: «Perl6::Metamodel::ModuleHOW.new␤»
  ```
  
  Here we define a new module named `M`; introspection with `HOW` confirms that the metaclass underlying `M` is `Perl6::Metamodel::ModuleHOW`.
  
  ## [When to use modules](#Module_packages "go to top of document")[§](#When_to_use_modules "direct link")
  
  Modules are primarily useful for encapsulating code and data that do not belong inside a class or role definition. Module contents (classes, subroutines, variables, etc.) can be exported from a module with the `is export` trait; these are available in the caller's namespace once the module has been imported with `import` or `use`. A module can also selectively expose symbols within its namespace for qualified reference via `our`.
  
  ## [Working with modules](#Module_packages "go to top of document")[§](#Working_with_modules "direct link")
  
  To illustrate module scoping and export rules, let's begin by defining a simple module `M`:
  
  ```raku
  module M {
    sub greeting ($name = 'Camelia') { "Greetings, $name!" }
    our sub loud-greeting (--> Str)  { greeting().uc       }
    sub friendly-greeting is export  { greeting('friend')  }
  }
  ```
  
  Recall that subroutines are lexically scoped unless otherwise specified (declarator [`sub`](/syntax/sub) is equivalent to `my sub`), so `greeting` in the above example is lexically scoped to the module and inaccessible outside of it. We've also defined `loud-greeting` with the `our` declarator, which means that in addition to being lexically scoped it is aliased in the module's symbol table. Finally, `friendly-greeting` is marked for export; it will be registered in the *caller's* symbol table when the module is imported:
  
  ```raku
  import M;               # import the module
  say M::loud-greeting;   # OUTPUT: «GREETINGS, CAMELIA!␤»
  say friendly-greeting;  # OUTPUT: «Greetings, friend!␤»
  
  ```
  
  # [Modules on disk](#Module_packages "go to top of document")[§](#Modules_on_disk "direct link")
  
  While `.raku` and `.rakumod` files are sometimes referred to as "modules", they are really just normal files that are loaded and compiled when you write `need`, `use` or `require`.
  
  For a `.rakumod` file to provide a module in the sense that we've been using, it needs to declare one with `module` as documented above. For example, by placing module `M` inside `Foo.rakumod`, we can load and use the module as follows:
  
  ```raku
  use Foo;                # find Foo.rakumod, run need followed by import
  say M::loud-greeting;   # OUTPUT: «GREETINGS, CAMELIA!␤»
  say friendly-greeting;  # OUTPUT: «Greetings, friend!␤»
  
  ```
  
  Note the decoupling between file and module names—a `.rakumod` file can declare zero or more modules with arbitrary identifiers.
  
  ## [File and module naming](#Module_packages "go to top of document")[§](#File_and_module_naming "direct link")
  
  Often we want a `.rakumod` file to provide a *single* module and nothing more. Here a common convention is for the file basename to match the module name. Returning to `Foo.rakumod`, it is apparent that it only provides a single module, `M`; in this case, we might want to rename `M` to `Foo`. The amended file would then read:
  
  ```raku
  module Foo {
    sub greeting ($name = 'Camelia') { "Greetings, $name!" }
    our sub loud-greeting (--> Str)  { greeting().uc       }
    sub friendly-greeting is export  { greeting('friend')  }
  }
  
  ```
  
  which can be used more consistently by the caller (note the relationship between the `use Foo` and `Foo::`):
  
  ```raku
  use Foo;
  say Foo::loud-greeting;  # OUTPUT: «GREETINGS, CAMELIA!␤»
  say friendly-greeting;   # OUTPUT: «Greetings, friend!␤»
  
  ```
  
  If `Foo.rakumod` is placed deeper within the source tree, e.g. at `lib/Utils/Foo.rakumod`, we can elect to name the module `Utils::Foo` to maintain consistency.
  
  ### [The `unit` keyword](#Module_packages "go to top of document")[§](#The_unit_keyword "direct link")
  
  Files that only provide a single module can be written more concisely with the `unit` keyword; `unit module` specifies that the rest of the compilation unit is part of the declared module. Here's `Foo.rakumod` rewritten with `unit`:
  
  ```raku
  unit module Foo;
  
  sub greeting ($name = 'Camelia') { "Greetings, $name!" }
  our sub loud-greeting (--> Str)  { greeting().uc       }
  sub friendly-greeting is export  { greeting('friend')  }
  
  ```
  
  Everything following the unit declaration is part of the `Foo` module specification.
  
  (Note that `unit` can also be used with `class`, `grammar` and `role`.)
  
  ## [What happens if I omit `module`?](#Module_packages "go to top of document")[§](#What_happens_if_I_omit_module? "direct link")
  
  To better understand what the `module` declarator is doing in `Foo.rakumod`, let's contrast it with a variant file, `Bar.rakumod`, that omits the declaration. The subroutine definitions below are almost identical (the only difference is in the body of `greeting`, modified for clarity):
  
  ```raku
  sub greeting ($name = 'Camelia') { "Greetings from Bar, $name!" }
  our sub loud-greeting (--> Str)  { greeting().uc                }
  sub friendly-greeting is export  { greeting('friend')           }
  
  ```
  
  As a reminder, here's how we used `Foo.rakumod` before,
  
  ```raku
  use Foo;
  say Foo::loud-greeting;  # OUTPUT: «GREETINGS, CAMELIA!␤»
  say friendly-greeting;   # OUTPUT: «Greetings, friend!␤»
  
  ```
  
  and here's how we use `Bar.rakumod`,
  
  ```raku
  use Bar;
  say loud-greeting;       # OUTPUT: «GREETINGS FROM BAR, CAMELIA!␤»
  say friendly-greeting;   # OUTPUT: «Greetings from Bar, friend!␤»
  
  ```
  
  Note the use of `loud-greeting` rather than `Bar::loud-greeting` as `Bar` is not a known symbol (we didn't create a `module` of that name in `Bar.rakumod`). But why is `loud-greeting` callable even though we didn't mark it for export? The answer is simply that `Bar.rakumod` doesn't create a new package namespace—`$?PACKAGE` is still set to `GLOBAL`—so when we declare `loud-greeting` as `our`, it is registered in the `GLOBAL` symbol table.
  
  ### [Lexical aliasing and safety](#Module_packages "go to top of document")[§](#Lexical_aliasing_and_safety "direct link")
  
  Thankfully, Raku protects us from accidentally clobbering call site definitions (e.g. builtins). Consider the following addition to `Bar.rakumod`:
  
  ```raku
  our sub say ($ignored) { print "oh dear\n" }
  ```
  
  This creates a lexical alias, hiding the `say` builtin *inside* `Bar.rakumod` but leaving the caller's `say` unchanged. Consequently, the following call to `say` still works as expected:
  
  ```raku
  use Bar;
  say 'Carry on, carry on...';  # OUTPUT: «Carry on, carry on...␤»
  
  ```
  