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.
Splitting a program across files is not mainly about size; it is about design. Put code in a separate file when:
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.
intern StatementNex 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.
intern Resolves Filesintern searches in this order:
~/.nex/depsFor 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.
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.
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:
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 are useful when:
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.
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.
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.
A good file boundary usually matches a good class boundary. As a rough rule:
Ask of every file:
Files are design documents as much as storage containers.
These belong together:
Stack class and helper routines whose only purpose is to support the stackThese do not:
Stack, Customer, and Image_Loader in the same fileIf 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.
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.
Imagine a program with these concepts:
TransactionAccountLedger_ReportA 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.
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:
So an extension can never break a class: everything it does goes through the class’s own contracts.
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.
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.
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.
intern path/Class_Name to load Nex classes from other filespath 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 guesspath/Class) directly, or by giving one side a path-qualified alias with asas when a local alias improves clarity, even without a collisionintern 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 divisionextend 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 statedeferred 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 filesextend Array [T -> Comparable]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.