Playground Documentation Challenges Full Docs

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-root directories. 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 as a 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 import is at the top level of the file.

Command Properties

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 import node (the file is checked first if needed). Whatever is open at the end of the file — its declarations — stays open: the code after import continues 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

▶ Run

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.

▶ Run

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.

▶ Run

Using the module

The full code inlines theory.fl (and bool.fl through it).

▶ Run

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.project file — the cache is the directory .formall next 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 DIR or $FORMALL_CACHE choose 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 if of 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-level if closed 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 instance in 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 as axiom(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 copy C: 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 with O, gives O.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 .fl files 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 the import.
  • import("f.fl") <…>; — an import followed by a statement in the same chain ends with that statement.
  • import cannot 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.