Modules and imports
One file, one module #
Each .agc file is a module. Every declaration is public, so other files can use it, except the ones after a private line, which stay private to the file.
Save this as shapes.agc:
struct Square
side: Int
end
def area(s: Square) -> Int = s.side * s.side
private
def secret() -> Int = 42private stands alone on its line, with a blank line before and after it, once per file. Imports are never public. A file without private is public as a whole. export before a declaration is an error (PARSE-UNEXPECTED-TOKEN); only export Alias.name is left, to re-export a name.
File layout #
Each file lists its declarations in this order (CHECK-DECL-ORDER otherwise):
# module doc and imports
# the public part:
# constants and re-exports (see Constants and Re-exports)
# struct, enum, type alias, module block and extern block with a resource or a struct (its defs too), in any order
# def
# private
# the private part, in the same order: constants, then types and blocks, then defA blank line goes before each declaration after the first.
A struct after a private function is CHECK-DECL-ORDER:
def main() -> Void
puts(secret())
end
private
def secret() -> Int = 42
struct Box
value: Int
enderror[CHECK-DECL-ORDER]Import a file #
import loads a file and gives it a name, the alias. Use the alias in front of every name from that file.
import Shapes from "shapes"
def main() -> Void
s = Shapes.Square(side: 3)
puts(Shapes.area(s))
end9Paths are relative to the importing file and leave out the .agc extension: "shapes" loads shapes.agc. Aliases start with an uppercase letter. Calling a private function is an error:
import Shapes from "shapes"
def main() -> Void
puts(Shapes.secret())
enderror[CHECK-IMPORT-NAME]Types and enums from a module #
Imported types use the alias too: in annotations, in construction and in patterns.
enum Status
Active
Banned(String)
endimport S from "status"
def show(s: S.Status) -> String
case s
S.Status.Active -> "active"
S.Status.Banned(why) -> "banned: #{why}"
end
end
def main() -> Void
puts(show(S.Status.Banned("spam")))
endbanned: spamA transparent type alias may be public and imported in the same way. For example, type Names = List[String] is used as S.Names or imported with import {Names} from "status". A generic alias such as type Matrix[T] = List[List[T]] works the same way: S.Matrix[Int], or Matrix[Int] after import {Matrix} from "status".
Import names #
import Alias from "path" gives the file the alias Alias. To skip the alias, list the exported names you want in braces and use them bare:
import {Square, area} from "shapes"
def main() -> Void
s = Square(side: 3)
puts(area(s))
end9This works for functions, structs, enums and constants. For an enum, import the enum, not its variants: its values and patterns keep the enum name in front.
import {Status} from "status"
def show(s: Status) -> String
case s
Status.Active -> "active"
Status.Banned(why) -> "banned: #{why}"
end
end
def main() -> Void
puts(show(Status.Banned("spam")))
endbanned: spamAn entry may rename with as. A type keeps a capital name and a function a lowercase one (CHECK-IMPORT-RENAME). Renaming also lets two modules that export the same name both be imported:
import {Square as Box, area as box_area} from "shapes"
def main() -> Void
puts(box_area(Box(side: 4)))
end16A name the module does not export, or keeps private, is an error at the import:
import {Square, secret} from "shapes"
def main() -> Void
puts(secret())
enderror[CHECK-IMPORT-NAME]An imported name cannot clash with a declaration, an alias, another import or a builtin (CHECK-REDEFINED-NAME). A path may appear in two imports, one with an alias and one with names. A module imported only by names has no alias.
An import alias that the file never uses is an error at the alias (CHECK-UNUSED-IMPORT); remove the import. A regex literal counts as a use of the std/regex import and a <<~EAG template as a use of the std/eag import. The query commands such as type-at and symbol do not report it in the file they are asked about (the files it imports keep the rule). An alias written without a member, such as x: Shapes, is CHECK-IMPORT-NAME. Unused names of an import list are not reported.
Only the root file needs main. Imported files have no top-level code, so importing a file never runs anything.
Re-exports #
A module can pass on a name it imports with export Alias.name, so a small facade file collects the API of several files. Save this as geometry.agc:
import Shapes from "shapes"
export Shapes.Square
export Shapes.areaThe importer sees the original declaration: Geometry.Square and Shapes.Square are one type, and &Geometry.area and &Shapes.area are one function.
import Geometry from "geometry"
def main() -> Void
puts(Geometry.area(Geometry.Square(side: 5)))
end25The alias must be an import of the file, and the module must export the name (CHECK-IMPORT-NAME). The name must not be a declaration, another re-export or an import alias of the file (CHECK-REDEFINED-NAME). There is no as and no wildcard: a facade that wants another name writes a wrapper function. A re-export adds no local name, so inside the facade the name is still Shapes.area. Re-exports follow the imports, and one after a declaration needs a blank line (PARSE-MISSING-BLANK-LINE).
Module blocks #
module Name ... end groups declarations under a name, so one file can hold several modules. A block holds constants, structs, enums, type aliases and functions with the layout rules of a file, its own private line included: what is above it is visible outside the block, and a block with no private is public as a whole. Save this as agents.agc:
module Counter
LIMIT = 100
enum Msg
Add(Int)
Get
end
def start(initial: Int) -> Int = step(initial, Msg.Add(1))
private
def step(count: Int, msg: Msg) -> Int
case msg
Msg.Add(n) -> count + n
Msg.Get -> count
end
end
end
module Greeter
def hello(name: String) -> String = "hello #{name}, up to #{Counter.LIMIT}"
endInside a block its own names are bare, and the imports, top-level names and other blocks of the file are visible too. Outside, write the block’s name first. import {Counter} from "agents" imports a public block like an alias, and import Agents from "agents" reads it as Agents.Counter:
import {Counter, Greeter} from "agents"
import Agents from "agents"
def main() -> Void
puts(Counter.start(1))
puts(Greeter.hello("Ana"))
msg = Agents.Counter.Msg.Add(2)
puts(Agents.Counter.start(0) + Counter.LIMIT)
puts(msg == Counter.Msg.Add(2))
end2
hello Ana, up to 100
101
trueA private name of a block is CHECK-IMPORT-NAME, as a private name of a file:
import {Counter} from "agents"
def main() -> Void
puts(Counter.step(1, Counter.Msg.Get))
enderror[CHECK-IMPORT-NAME]The name of a block follows the rules of an import alias (CHECK-REDEFINED-NAME), a block sits at the top level with the structs and enums (a block inside a block is PARSE-NESTED-MODULE), and it holds no import, re-export or extern block. A block after the file’s private line is private to its file. Inside a block, a name the file already declares or imports is CHECK-SHADOWED-NAME (one name means one thing), and main is CHECK-MAIN; two blocks may each have a start.
The standard library #
Paths that start with std/ load the standard library that ships with Agentica. std/queue is a first-in, first-out queue of strings:
import Queue from "std/queue"
def main() -> Void
q = Queue.new()
q = Queue.push(q, "first")
q = Queue.push(q, "second")
case Queue.pop(q)
ok(popped) ->
puts(popped.value)
puts(Queue.size(popped.remaining))
error(message) -> puts(message)
end
endfirst
1See Queue for every function.
Other libraries #
Paths that start with pkg/ load installed libraries: import Tools from "pkg/acme/tools" looks for acme/tools.agc in agc_libs/ next to the main program, then in the folders of AGENTICA_PATH and the user and system library folders (search order).
Packages #
A package is a git repository of .agc files. A project with an agentica.toml next to its main file, or in a folder above it, can import the packages the manifest declares. Each dependency has a local name and one pin, a tag or a ref (a commit):
name = "notes"
[dependencies]
sqlite = { git = "https://github.com/owner/sqlite-ac", tag = "v1.2.0" }
json5 = { git = "https://gitlab.com/someone/json5", ref = "3f2a9c1" }Import a package by its local name, then a path inside the package, without .agc:
import Sqlite from "pkg/sqlite/db"A manifest that declares dependencies needs an agentica.lock beside it, with the exact commit and a hash of every package. A build never downloads anything: it reads each package from deps/<name>/ and checks its hash. Three commands keep deps/ and the lock, through the system git:
agentica installfetches what the lock names intodeps/; it never changes the lock.agentica add NAME URL --tag TAG(or--ref COMMIT,--subdir DIR) adds a dependency toagentica.toml, the lock anddeps/.agentica update [NAME]fetches the tag pins again and repairs a lock that is out of date.
agentica install
agentica add sqlite https://github.com/owner/sqlite-ac --tag v1.2.0
agentica update sqliteA dependency that only the tests use, such as a property-testing package, takes group = "test" (agentica add NAME URL --tag TAG --group test writes it). The project locks and installs it, but only its *_test.agc files and its step program import it; any other program that imports it stops with CHECK-IMPORT-PACKAGE. A project that depends on your package never fetches it.
[dependencies]
prop = { git = "https://github.com/owner/prop", tag = "v1.0.0", group = "test" }A manifest may name the oldest Agentica it needs, agentica = "0.31.0"; an older Agentica stops install, check, run and test with PKG-AGENTICA-TOO-OLD.
Problems are reported with PKG- codes. Workspaces, path and override dependencies, native libraries and modules built from C, the [style] and [tool.NAME] tables, and every limit and code are in the modules reference; native code is in Native code.