Chapter 23

Modules and Files

Until now, most examples have fit in one file or one REPL session. Real programs do not. They are split into multiple classes and files, with clear boundaries between parts of the system.

In Nex, the main tool for bringing code from another Nex file into the current program is intern.

Why Split a Program

Splitting a program across files is not mainly about size; it is about design. Put code in a separate file when:

  • it represents a distinct concept
  • it can be understood independently
  • it should be reused elsewhere
  • keeping it separate makes the boundary clearer

A Bank_Account class and a Report_Printer class should not live in one file merely because both belong to the same application. They are different concepts with different reasons to change.

The intern Statement

Nex loads classes from other files with intern:

intern math/Calculator

This means: find the Nex file for Calculator under the math path and make that class available in the current program.

An alias may also be given:

intern math/Calculator as Calc

That allows the imported class to be referred to locally as Calc.

How intern Resolves Files

intern searches in this order:

  1. the directory of the currently loaded script, if the code came from a file
  2. the REPL or process working directory
  3. ~/.nex/deps

For a path-qualified intern such as:

intern net/Tcp_Socket

Nex tries these local layouts under each search root:


lib/net/Tcp_Socket.nex
lib/net/tcp_socket.nex
lib/net/src/Tcp_Socket.nex
lib/net/src/tcp_socket.nex

Then it tries the same path forms under:

~/.nex/deps

So all of these are valid examples:

./lib/net/tcp_socket.nex
/some/project/lib/net/Tcp_Socket.nex
~/.nex/deps/net/tcp_socket.nex
~/.nex/deps/net/src/Tcp_Socket.nex

Exact-case filenames are checked first. If they are not found, Nex falls back to a lowercase filename such as tcp_socket.nex.

A Simple Two-File Example

Suppose lib/math/Counter.nex contains:

class Counter
create
  make() do
    count := 0
  end
feature
  count: Integer
  increment() do
    count := count + 1
  end
  value(): Integer do
    result := count
  end
end

Another file may use it with:

intern math/Counter

class Main
create
  make() do
    let c := create Counter.make
    c.increment
    c.increment
    print(c.value)
  end
end

The point is that Counter now has its own module boundary. It can be read, tested, and reused on its own.

Namespaces and Ambiguous References

The path in intern path/Class is not only a way to find a file. It also becomes that class's namespace. Two libraries can each define a class named Account without conflict, right up until a single program interns both of them:

intern finance/Account
intern billing/Account

let a := create Account.make(1)

Nex does not guess which Account is meant here, and it does not let whichever library happened to load first silently win. It rejects the program at compile time:

Ambiguous reference to 'Account': interned from billing.Account and finance.Account.
Reference one directly by its qualified name (e.g. billing.Account), or rename it
on the way in with a path-qualified `intern ... as`.

The fix is to write the class's full name — the same path/Class form used on the intern line — anywhere the class name would otherwise appear: in a type annotation, in create, in inherit, or in a match clause.

intern finance/Account
intern billing/Account

let a: finance/Account := create finance/Account.make(1)
let b: billing/Account := create billing/Account.make(2)
print(a.balance)
print(b.id)

Both classes are now usable in the same program, each referred to unambiguously by its own qualified name. Two things are worth noting about how this behaves:

  • A class declared directly in the current file always wins over an interned one of the same name. Ambiguity is only ever between two interned classes — an unrelated library update can never silently break code that already worked by introducing a name clash with something you defined yourself.
  • If two different intern paths happen to lead to the same file — two libraries that both depend on a third and each intern it — that is not a collision. It is one class, reachable two ways.

A bare, unqualified name — no path at all, like a plain intern Logger — never collides with anything else brought in the same way, so this only comes up once a program starts interning path-qualified libraries.

Aliases

Aliases are useful when:

  • the imported name is long
  • two imported classes would otherwise collide
  • a local short name improves readability

Example:

intern geometry/Long_Polygon_Name as Polygon

let p := create Polygon.with_sides(5)

Use aliases sparingly. The goal is clarity, not abbreviation for its own sake.

Aliasing to resolve a collision

A path-qualified alias is also a second way out of the ambiguity in the previous section — rename one side of a collision (or both) on the way in, and each alias refers unambiguously to its own class from then on:

intern finance/Account
intern billing/Account as Billing_Account

let b := create Billing_Account.make(2)
print(b.id)

Billing_Account reaches billing's class directly, without ever touching the name it collides on. The bare name Account is unchanged, though: it is still ambiguous, so it must not be used while both classes are interned. To refer to both classes by short names, alias both sides:

intern finance/Account as Finance_Account
intern billing/Account as Billing_Account

let a := create Finance_Account.make(1)
let b := create Billing_Account.make(2)

Aliasing only helps this way when the intern being renamed is path-qualified; aliasing a bare, unpathed intern is purely for shortening or readability, since there is no path to disambiguate with.

Free Functions and intern

intern brings in a unit's free functions exactly as it brings in its classes — the whole file, not only the one name written after the path. A function sharing a file with an interned class arrives alongside it, under its own bare name, whether or not you ever use it.

A function's qualified name is the directory path of the intern followed by the function's own name — not the file's name. Interning trade/shipping, whose file defines ship, makes the function callable as trade.ship.

But a function has none of the escape hatches above: as only ever renames a class. Given two warehouses that each define a ship function, rounding a shipment quantity a different way:

-- trade/ship.nex
function ship(qty: Integer): Integer do result := qty + 1 end

-- other/ship.nex
function ship(qty: Integer): Integer do result := qty - 1 end
intern trade/ship
intern other/ship

print(ship(10))

a bare call is rejected the same way a bare class reference is:

Ambiguous reference to 'ship': interned from other.ship and trade.ship.
Call one directly by its qualified name, e.g. other.ship(...).

The fix looks similar to a class's qualified name, but is spelled differently — with . rather than /:

intern trade/ship
intern other/ship

print(trade.ship(10))  -- 11
print(other.ship(10))  -- 9

The different spelling is forced by syntax, not chosen for style. A class's path/Class could only appear in a type annotation, a create, an inherit, or a match clause — never in the middle of an ordinary expression, so / can be used there without being mistaken for division. A function call is an ordinary expression, and / already means division inside one, so a qualified call instead reuses . — the same character an ordinary method call already uses.

trade.ship(…) parses exactly like a method call on a variable named trade. Nex reads it as a qualified call unless trade is bound where the call appears — a local, parameter, or field of that name in the enclosing routine or class, or a global or class of that name. A local only shadows the module inside the routine that declares it:

intern trade/ship

function use(trade: Integer): Integer do
  result := trade + 2
end

print(trade.ship(10))  -- 11

The parameter trade belongs to use alone, so the top-level call still reaches the module. Inside use, however, trade.ship(…) would be an ordinary member access on the parameter — avoid reusing an intern path segment as a local name in a routine that also calls that module.

A multi-segment path is written the same way, one more .:

intern trade/core/ship

print(trade.core.ship(10))

As with classes, none of this is needed until two interned functions actually collide. Most of the time a function is simply called by its bare name, exactly as before.

Designing Module Boundaries

A good file boundary usually matches a good class boundary. As a rough rule:

  • one main class per file
  • helper classes in their own files when they have an identity of their own
  • unrelated utility code should not be stuffed into a random “misc” file

Ask of every file:

  • what concept does this file define?
  • what other files should know about it?
  • what can remain private to this file’s class or classes?

Files are design documents as much as storage containers.

What Belongs Together

These belong together:

  • a Stack class and helper routines whose only purpose is to support the stack

These do not:

  • Stack, Customer, and Image_Loader in the same file

If you feel tempted to group code by when it was written rather than by what it means, stop and redesign.

The best modules reduce mental load. A reader opening a file should have a good guess what they are about to find.

Intern and Contracts

Contracts become even more important once code is split across files. When a class is used from another module, the reader of the calling code should not have to open the original file to learn its basic obligations and guarantees; good preconditions, postconditions, and invariants are what make module boundaries trustworthy.

In a multi-file program, the contract is often the first and most important documentation of a class.

A Worked Example: Splitting a Small Ledger

Imagine a program with these concepts:

  • Transaction
  • Account
  • Ledger_Report

A clean structure would be:

finance/Transaction.nex

class Transaction
create
  make(d: String, a: Real) do
    description := d
    amount := a
  end
feature
  description: String
  amount: Real
end

finance/Account.nex

intern finance/Transaction

class Account
create
  make(name: String) do
    owner := name
    entries := []
  end
feature
  owner: String
  entries: Array[Transaction]
  add_entry(t: Transaction) do
    entries.add(t)
  end
  balance(): Real do
    result := 0.0
    across entries as entry do
      result := result + entry.amount
    end
  end
end

finance/Ledger_Report.nex

intern finance/Account

class Ledger_Report
feature
  print_balance(a: Account) do
    print(a.owner + ": " + a.balance.to_string)
  end
end

Each file has one job. The design is visible in the file structure itself.

Extending a Class from Another File

Sometimes the class that needs a new feature is not yours to edit. It comes from a library, or from a module another part of the program owns. Suppose a report needs the average amount of an account’s entries, and finance/Account is shared code you would rather not change. A free function average_entry(a) would work, but then callers write a.balance for one question about an account and average_entry(a) for the next.

An extend block adds features to an existing class from outside its file:

intern finance/Account

extend Account
feature
  average_entry(): Real
    require
      has_entries: not entries.is_empty
    do
      result := balance / entries.length.to_real
    end
end

let a := create Account.make("Ada")
a.add_entry(create Transaction.make("salary", 3000.0))
a.add_entry(create Transaction.make("rent", -1200.0))
print(a.average_entry)     -- 900.0

Callers now write a.average_entry, as if Account had declared it. The feature is inherited by heirs of Account, its precondition is checked like any other, and Account’s invariant is checked around the call. Calling it on an account with no entries fails at the caller, as a precondition should:

Error: Precondition violation: has_entries
  The call at line 19 does not meet the precondition `has_entries` of Account.average_entry.

An extension is written by a client of the class, not by its author, and the rules follow from that:

  • it sees only the class’s public features; a private one is not visible in its body
  • it cannot assign the class’s fields; it changes an object only by calling the class’s own routines
  • it adds routines only: no fields, constructors or invariants
  • it cannot replace a feature the class already has, and two extensions cannot add the same feature

So an extension can never break a class: everything it does goes through the class’s own contracts.

Adding an Operation to a Family of Classes

Extensions matter most for a family of classes. Suppose a geometry/Shapes module declares a deferred Shape with heirs Circle and Rect, and a second module, geometry/Areas, adds an operation to the whole family:

intern geometry/Shapes

extend Shape
feature
  area(): Real
    deferred
    ensure
      non_negative: result >= 0.0
    end
end

extend Circle
feature
  area: Real do result := 3.14159 * radius * radius end
end

extend Rect
feature
  area: Real do result := width * height end
end

area is deferred in Shape, so every concrete heir must have one, and each implementation inherits the postcondition. A call s.area on a Shape dispatches on the object’s class, as for any routine.

Now a third module, geometry/Triangles, adds a new heir, Triangle, knowing nothing about areas. A program that interns both modules is rejected:

Type error in .../geometry/Triangles.nex: Class 'Triangle' does not implement
deferred feature 'area', declared by 'extend Shape' at .../geometry/Areas.nex,
line 3. Add 'extend Triangle feature area ... end', give 'area' a default body
in 'extend Shape', or declare 'Triangle' 'deferred'.

The program that brings the two together supplies the missing piece:

intern geometry/Areas
intern geometry/Triangles

extend Triangle
feature
  area: Real do result := base * height / 2.0 end
end

let shapes: Array[Shape] := [create Circle.make(1.0), create Triangle.make(4.0, 3.0)]
across shapes as s do
  print(s.area)
end

This is worth pausing on. A family of classes can grow in two directions: new heirs, and new operations on all of them. Inheritance makes the first easy and the second hard; a match over a union does the opposite. With extensions both are easy, neither requires editing existing files, and the compiler still guarantees that every heir has every deferred operation. When not every heir should have an operation, give the Shape extension a default body instead of deferred, and let the heirs that can do better redefine it.

Extending Built-in Types

Built-in types can be extended too. In the body, this is the value, and the type’s own features can be used without it, as in a class:

extend String
feature
  is_palindrome: Boolean do
    let s := to_lower
    result := true
    from
      let i := 0
    until
      i >= length / 2
    do
      if s.char_at(i) /= s.char_at(length - 1 - i) then
        result := false
      end
      i := i + 1
    end
  end
end

print("Level".is_palindrome)     -- true
print("Nex".is_palindrome)       -- false

Because length and to_lower name features of String, a local of the routine may not use those names; the compiler says so rather than guess which one you meant.

A generic built-in type is extended with its own parameter names, and a constraint limits an extension to some type arguments:

extend Array [T -> Comparable]
feature
  maximum: T
    require
      not_empty: not is_empty
    do
      result := get(0)
      across this as x do
        if x > result then result := x end
      end
    end
end

print([3, 9, 4].maximum)                     -- 9
print(["pear", "apple", "plum"].maximum)     -- "plum"

Calling maximum on an array of objects that are not Comparable is a compile-time error. An extension of Any gives a feature to every value, and one of Comparable to every comparable value, your own classes included. Note that an extension of Real does not apply to Integer values: an Integer is converted where a Real is expected, but it is not a kind of Real.

Extensions work in the REPL as well: an extend input adds its features to a class an earlier input declared.

When to Extend

If you own a class and the feature belongs to its concept, put the feature in the class. An extension is for the cases where that is not possible or not right: a library class, a built-in type, or an operation that belongs to a different module than the classes it applies to, as area belongs to geometry/Areas rather than to geometry/Shapes. Keep each extension in the module whose concept it serves, and resist spreading one class across many files: a reader should still be able to find a class’s features.

Summary

  • Split programs into files to express design boundaries, not merely to reduce length
  • Use intern path/Class_Name to load Nex classes from other files
  • The path in intern path/Class is also the class's namespace: two interned classes with the same bare name are a compile-time ambiguous reference error, never a silent guess
  • Resolve a collision by writing the class's qualified name (path/Class) directly, or by giving one side a path-qualified alias with as
  • A class declared in the current file always wins over an interned one of the same name; only two interned classes can collide
  • Use as when a local alias improves clarity, even without a collision
  • intern brings in a unit's free functions the same way it brings in its classes, but a function cannot be renamed with as; a colliding bare call is an ambiguous reference too, resolved instead with a qualified call — path.name(…), spelled with . rather than / because a function call, unlike a class reference, is an ordinary expression where / already means division
  • A qualified call is read that way unless its leading name is bound where the call appears — a local, parameter, or field in the enclosing routine or class, or a global or class of that name; a local shadows the module only inside the routine that declares it
  • Good file boundaries usually follow good class boundaries
  • Contracts make multi-file code easier to trust and reuse
  • A clean module layout reduces coupling and mental overhead
  • extend Class feature ... end adds routines to a class from another file; an extension is a client of the class, sees only its public features, and adds no state
  • A deferred feature an extension adds must be implemented by every concrete heir in the program, so new operations and new heirs can both be added without editing existing files
  • Built-in types can be extended too, generic ones with their own parameter names and optional constraints, as in extend Array [T -> Comparable]

Exercises

1. Split a simple earlier example into two files: one defining a class and one using it with intern.

2. Take a class that currently does too much and divide it into two classes in two files. Explain why the new boundary is better.

3. Write a short example using intern ... as ... and show why the alias is helpful.

4. Sketch a directory layout for a small address-book program with classes Contact, Address_Book, and Csv_Exporter.

5. Write two small libraries that each define a class with the same name, then intern both into one program. Show two different ways to use both classes: a qualified reference, and an alias.

6. Write two small libraries that each define a free function with the same name, then intern both into one program. Show the ambiguous-reference error a bare call produces, then fix it with a qualified call to each.

7. Write a module that extends finance/Account with a query largest_entry(): Transaction, with a precondition. Try to make the extension assign owner, and read the error.

8. Split the shapes example of Adding an Operation to a Family of Classes into its four files. Add a perimeter operation in a module of its own, then a Square heir in another, and write the program that uses all of them.

9.* Choose a chapter 26-sized program idea of your own. Before writing any code, propose the file structure and justify each file in one sentence.