Modules

module

Syntax

module [attributes]
module ModuleName [attributes]
module ModuleName::SubModule [attributes]

Description

A Rogue module is analogous to a C++ namespace or a Java package. It conceptually groups related clusters of functionality and it reduces the potential for name conflicts between classes and routines of different modules.

Every class definition, routine definition, and group of "global" statements belong to one module or another. If no modules are specified then all program elements belong to the default Rogue module.

The module context can be switched at any time by writing e.g. module Alpha. This would cause successive program elements to be organized under the Alpha module. From the context of any other module, an Alpha element named x would be accessed by writing Alpha::x. The uses command, described below, can simplify module usage.

Writing module with no name switches back to the default module.

Example

println Alpha::name  # alpha
println Beta::name   # beta

module Alpha
routine name->String
  return "alpha"
endRoutine

module Beta
routine name->String
  return "beta"
endRoutine

Module File Organization

If you're defining a module called Alpha, the recommended approach is to have a folder called Alpha containing a file called Alpha.rogue, which in turn includes module-related files with $include Alpha/XZY etc. For example, your source folder might contain:

Alpha/
  Alpha.rogue
  X.rogue
  Y.rogue

Alpha.rogue would contain:

$include Alpha/X
$include Alpha/Y

Attributes

Attribute	Description
api	Every class in the module is marked [api], which declares the class and all methods to be [essential] (immune to culling for being unused).
essential	Every class in the module is marked [essential], which keeps the class from being culled for being unused.

uses

Syntax

uses ModuleName
uses Path/ModuleName
uses Path/ModuleName [export | noInclude]
uses Path/ModuleName::SubModule

A uses Path/ModuleName directive causes two things to happen:

1. An $include Path/ModuleName directive is implicitly issued. Any :: submodule separators are converted to / for the purposes of the $include.
2. The prefix ModuleName is added to the current module's list of used modules that allows ModuleName classes and routines to be found without having to write the ModuleName:: prefix.

The [export] attribute means that when another module uses the current module, it also implicitly uses any exported modules that the current module uses.

The [noInclude] attribute prevents Rogue from $includeing any files when a uses command is issued.

If multiple used modules contain the same element name, writing the unqualified ambiguous name (without a ModuleName:: prefix) will match the current module first, then all used modules in order of their declaration.

Example

module Alpha

routine name->String
  return alpha
endRoutine

routine alpha->String
  return "alpha"
endRoutine

---------------------

module Beta
uses Gamma [export]
uses Delta

routine name->String
  return beta
endRoutine

routine beta->String
  return "beta"
endRoutine

---------------------

module Gamma
routine gamma->String
  return "gamma"
endRoutine

---------------------

module Delta
routine delta->String
  return "delta"
endRoutine

---------------------

module  # back to the default module
uses Alpha
uses Beta
println alpha  # alpha (no need to write Alpha::alpha)
println beta   # beta
println gamma  # gamma (uses Beta and Beta exports its 'uses Gamma')
println delta  # ERROR! (can't find 'delta' in any used namespaces)
println Delta::delta  # delta (there we go)
println name          # alpha (Alpha::name() and Beta::name() both exist, but Alpha was listed first)
println Alpha::name   # (Can still be explicit)
println Beta::name    # beta