import
Using another file as a context
Overview
The import command makes the contents of another .fl file a context for the code that follows — exactly like for or if make their atoms or assumptions a context. Types, atoms, assumptions, rules, locks and labels of the imported file are visible inside the import, and nowhere else.
import("filePath");import("filePath") { ... }import("filePath1") import("filePath2");import("theoryFilePath", typeParameterName := argumentType, parameterAtomName := functionExpression, otherParameterAtomName := argumentExpression); // interpretationimport(namespaceName := "theoryFilePath"); // namespace: namespaceName.memberNameimport(namespaceName := "theoryFilePath", typeParameterName := argumentType, …); // interpretation in a namespace- "
filePath" - The file to import, relative to the importing file; by default only inside its directory, the project root (
formall.project) and--import-rootdirectories. Its theorems and declarations become visible here; it is checked once, as a module. typeParameterName := argumentType, …- An interpretation: the theory's type parameters, atoms and axioms are given values here (
G := ℤ, ∘ := +, e := 0); its axioms must then be facts here, and its theorems hold for these values. namespaceName := …- Optional: everything the import brings is visible as
namespaceName.name(an operation asa namespaceName.+ b), so two imports of one theory do not clash. { … }- Optional: the imported content is visible only in the block. Without it, the code after
importis at the top level of the file.
Command Properties
- Group
- Transparent headers
- Produces
- Nothing by itself — the imported file's commands produce their statements as usual
- Delivery & Label
- No label is allowed on
import. - Creates scope
- Yes.
import("f.fl");is a declaration: it lasts until the end of the enclosing block or file.import("f.fl") { ... }limits it to the braces. - Mechanism
- The module's checked result — its block tree with statements, labels and rules — is loaded from its object as children of the
importnode (the file is checked first if needed). Whatever is open at the end of the file — its declarations — stays open: the code afterimportcontinues at the top level of the imported file.
Basic examples
A file is a context
Suppose bool.fl declares a type and two atoms:
bool.fl
Then importing it gives the same context as writing its text in place:
Two equivalent programs
The full code is the second program: the text of bool.fl in place of the import.
Details
An imported file is a module: it is checked on its own, as a main file, and sees only what it imports itself — not the file that imports it. Each module is checked once; its result is kept as a module object and loaded by later runs.
Modules
A module declares what it needs (usually by importing other modules) and then states its theorems at its top level. Everything the module declares at the top level — atoms, assumptions, locks, labels — is visible to the importer. The proofs themselves stay in their blocks; their results are reached through labels, as usual:
theory.fl
The full code inlines bool.fl.
Using the module
The full code inlines theory.fl (and bool.fl through it).
Projects of several files
Each module imports what it needs: a module cannot use a name of the file that imports it. If a file is already imported in an enclosing context (on the same path of the scope tree), a repeated import is skipped with a notice and its names are shared — so "diamond" dependencies work naturally. An import cycle is an error.
main.fl
The repository contains a library built this way (tests/08_corpus/library): common logic, set theory, Peano arithmetic and the Einstein puzzle; the set theory produces exactly the same statements as the single-file version.
Module objects and the cache
There is no separate build step: run formall main.fl. For every imported module the interpreter
finds its object in the cache and checks that it is current: the module's text, the files it read and the objects of
its own imports are unchanged, and so is the interpreter. A module that is not current is checked again — in a child
run, as a main file — and only such modules: after an edit of one file, the files that import it are checked again,
the rest of the project is loaded. The results are the same as without the cache; reports (--log,
--statements, --certificate-journal …) describe the main file, while --trust covers the
theorems of all modules.
- Where. In a project — a directory with a
formall.projectfile — the cache is the directory.formallnext to it. Paths inside are relative to the project, so the project can be moved or copied together with its cache. Without a project the cache is~/.cache/formall($XDG_CACHE_HOME/formall);--cache DIRor$FORMALL_CACHEchoose another directory. The cache can be deleted at any time. Stale modules are compiled in parallel (-j N; by default as many as there are processors). - Errors. An error in a module is reported with its file and position, followed by the place of each import that led to it.
- Interpretations are instances of the theory's object (below): an interpretation of a large theory costs about as much as loading it.
Interpretation: a theory in another model
A theory proved once can be used for every structure that satisfies its axioms. The second argument of
import is a substitution: import("group.fl", G := Z2, ∘ := ⊕, e := 0, ⁻¹ := −) reads the
theory of groups with its parameters replaced by the model — this is interpretation in Isabelle and an
instance in Lean.
- Parameters. A type of the theory named in the substitution becomes the model's type — a named
type or a compound one:
Point := [Axis -> ℝ]makes the points of a theory functions from axes to numbers (library/geometry/real_space.fl); an atom becomes the model's expression of the same type — an atom (⊕), a constant (0) or a λ (⁻¹ := {x: Z2 | x}). The theory's operator notation stays with the theory's text (a⁻¹is read as−(a)), the model keeps its own. - Axioms are obligations. A top-level
ifof the theory's files that speaks about the substituted parameters and about nothing new of the theory must already be a fact of the model, the same statement after the substitution; it is not assumed again, and the theory's label of the axiom points to the model's fact. A missing axiom is an error. The kernel checks the same where the import is written: the file's certificate applies the theory's axiom to the model's values with the model's fact for it, so that the fact is the axiom after the substitution, whether or not a theorem of the instance is used later. An assumption that mentions something the theory itself introduces stays an assumption, as with an ordinary import: the condition of a theorem about its own atoms (for(a, b) if(a + b = 0) T:: …), the definition of a new constant (for(2) if(2 = S(1))), an axiom of a new notion (the order of the indices of sequences). A top-levelifclosed by a call that takes it (contradict,deduce,obtain) is a step of a proof. - The theory is checked once. The theory is a module: its proofs were checked for arbitrary
parameters when its object was built. The interpretation is an instance of that object (as an
instancein Lean): every statement, definition, abbreviation and rule of the theory and of the modules it imports that declare a parameter is copied with the parameters replaced by the model's values — proofs are not checked again, and a new constant of the theory (define) gets a copy of its own. The theory's theorems become available for the model:InvMul[]now gives− b ⊕ − a = −(a ⊕ b). - The names of the parameters (
G,∘,e) are not declared by the instance; they do not hide the model's names. - Axioms of a lock are not obligations. A theory written without
if, with its axioms asaxiom(L, …)in a lock (the style of reducibility), is imported as well, but the import checks nothing against the model: the theorems stay inside the lock, and every call realizes its axioms with the model's facts —RightInv[| ZA, ZI, ZV], as with an ordinary import of such a theory. This is sound, only the check «the model satisfies the axioms» moves from the import to each use.
An optional condition of a theorem can mention only the model parameters, without mentioning that theorem's own arguments. Put such a condition inside the theorem's explicit body. A file-level header chain treats a condition about substituted parameters as an obligation of the interpretation. For example, the convergence library puts nonemptiness of base sets inside its uniqueness proofs; its sum proof and the import itself do not require that extra condition.
type(Z2 = 0 | 1);
for(⊕: [Z2, Z2 -> Z2]; −: [Z2 -> Z2]); …
// the axioms of a group for Z2 — proved by cases: ∀{a, b, c: Z2 | a ⊕ b ⊕ c = a ⊕ (b ⊕ c)}, …
import("algebra/group.fl", G := Z2, ∘ := ⊕, e := 0, ⁻¹ := −);
for(a, b: Z2) InvMul[]; // − b ⊕ − a -> −(a ⊕ b)
The library uses the same mechanism in library/analysis/real_sequences.fl: natural
indices inside ℝ supply the index type and order required by library/analysis/sequences.fl.
The obligations are proved before the theory is imported. To interpret a theory twice in one file,
or next to its ordinary import, give each interpretation a namespace;
otherwise its theorem labels clash.
What a transferred theorem proves
Interpreting theory A in theory B proves the translated theorems of A inside B. The proof must establish the required axioms of A for the chosen type and operations. The resulting theorems retain the assumptions used to establish those facts. Changing names does not remove assumptions.
For example, library/reals/naturals.fl constructs natural numbers inside ℝ,
and library/reals/peano.fl interprets the Peano theory on that type.
It also proves that the imported addition and multiplication agree with the operations
inherited from ℝ. These operation identities let an arithmetic theorem be written in
either representation.
The reverse question has two parts. A proved correspondence between two number representations can translate a statement back to the original representation. To obtain a proof from Peano assumptions alone, the proof must also avoid extra real-number assumptions, or those assumptions must themselves be justified in the target theory. An embedding, even an isomorphism, does not by itself establish this independence.
In practice, write a reusable theorem with the weakest assumptions its proof needs,
then prove those assumptions in each model. Use a proved correspondence to translate
operations and predicates when the models have different representations. A subtype
supplies membership and an injective embedding; it does not supply a general reverse
transfer procedure. tools/trust.py helps inspect the assumptions of a
particular theorem, while show displays its contract.
The Peano module uses induction quantified over predicates of type
[ℕ -> 𝔹]. Its axioms should not be silently identified with the first-order
induction schema of textbook PA when discussing logical strength or independence.
Namespaces
The last argument of import may be a prefix: import(R := "reals/main.fl"). Everything the
import brings — types, atoms, values of enumerations, operators, abbreviations, labels — is visible after it only with
the prefix: R.ℝ, R.sup(X), R.TArchimedes[]. An operator keeps its notation and
is written with the prefix too: n N.+ N.1. Inside the theory's own files the names are plain. Without a
prefix, import works as before.
import("logic/uniqueness.fl"); // shared logic: ∀, =, ∃! — one for both theories
import(N := "peano/main.fl"); // N.ℕ, N.S, N.+, N.T➕Associative, …
import("reals/main.fl"); // ℝ, +, ×, 0, 1 — without a prefix
for(x: ℝ) L0Add[x]; // 0 + x = x
for(m, k: N.ℕ) N.T➕Associative[m, k, m]; // m N.+ (k N.+ m) = m N.+ k N.+ m
- Why. Both Peano arithmetic and the reals declare
+,×,1,<. Without a prefix the later import hides the earlier names: the theorems of Peano stay true (their atoms are different), calls still apply them, but the sum of two natural numbers can no longer be written. With interpretations, a prefix lets one theory be read for two models (import(A := "group.fl", G := Z2, …)and"B"), or for a model next to the ordinary import of the same theory (the reals and their copyC:C.TWeierstrass). - The prefix covers everything the import brings, including the files it imports — unless they
are already imported outside: a shared file (
logic/…) is imported once, before the prefixed imports, and stays shared. A file imported only under a prefix has prefixed names everywhere:N.=, not=. An error on an undeclared name says when it is visible with a prefix. - Inside an interpretation, a file of the theory that is also imported ordinarily outside (it declares the
parameters, like
reals/language.fl) is read again for the model, not shared. - The same import with the same prefix again is skipped; an ordinary import after a prefixed one is a separate copy. A prefixed import without a substitution of a file already imported without a prefix is an error: it would be the same theory under other names.
- Namespaces nest: a theory that imports another one with the prefix
M, imported itself withO, givesO.M.name. .is reserved for namespaces: it cannot appear in declared names of atoms, types, values and labels, nor in the prefix itself.
Rules
- Paths are relative to the importing file (absolute paths are allowed too); spaces in paths are not supported. Only
.flfiles can be imported. - An imported file must be complete: balanced braces, closed comments, no unfinished command, label definition or trailing comma, and no trailing statement chain without
;. A trailing chain of scope commands is a declaration. - Files are walls in both directions:
;and}inside an imported file never close the importer's chain, and the importer's;never closes the declarations of the imported file — they end together with theimport. import("f.fl") <…>;— an import followed by a statement in the same chain ends with that statement.importcannot be an argument of another command and cannot carry a label.- Messages and statements from imported files show their position as
file.fl:line:column.
Security
By default the interpreter imports only files inside the directory of the main file and inside the project root — the nearest parent directory containing a formall.project file (paths are compared after resolving .. and symbolic links). Command-line flags widen this: --import-root DIR adds an allowed directory, --allow-any-import lifts the restriction for trusted local use.
Running a project
The interpreter always gets one file; its imports are resolved and checked recursively. Any module of a project can also be checked on its own — it imports its dependencies itself, and the end of a file closes its declarations. The same file imported twice on one path of the scope tree (also via .., an absolute path or a symbolic link) is used once.