OpenEng Docs
Follow updates
Menu
Follow updates
Browse the documentation

AEL 1.0.0

Explaining what a file may call

In AEL, the Agent Engineering Language, a file can call the global functions of its own folder and the folders above it, and the reuse functions that its header imports. ael scope shows, for one file, which of those it can call and why, and when a function is not callable it names the line that would fix that. It reads your project and changes nothing, unless you ask for the edit below.

Usage

ael scope <project> pricing/quote.ael
ael scope <project> pricing/quote.ael --json
ael scope <project> pricing/quote.ael --add-header pricing/discount.reuse.ael
Argument or optionMeaning
<project>The project folder.
<file>The file to explain, by its path in the project.
--target <target>The target to check for, as for ael check.
--jsonA machine-readable report.

What it shows

The report walks the file's folder and then each folder above it, nearest first. At each folder it lists the functions available there and what became of each:

  • Callable. The nearest folder wins a name.
  • Shadowed. A function of the same name in a nearer folder hides it. The report names the one that wins.
  • Ambiguous. Two functions of one name sit in the nearest folder where the name occurs. The check refuses a call to that name.
  • Not callable, with the reason: a global function in a sibling or deeper folder, a reuse function the file has no import for, or an import that names a reuse function outside the file's folder and the folders above it.

It also lists the calls in the file and the function each one resolved to. For a reuse function that the file could call but does not import, it prints the exact line, such as import "./discount.reuse.ael";, that makes it callable. Functions and visibility describes the rules.

Adding the missing import

--add-header <provider> plans the edit that inserts that one import line into the file's header, and checks it before anything is written:

ael scope <project> pricing/quote.ael --add-header pricing/discount.reuse.ael --dry-run
ael scope <project> pricing/quote.ael --add-header pricing/discount.reuse.ael \
  --apply --expect-snapshot <digest> --expect-plan <digest>
OptionMeaning
--add-header <file>The reuse file to import.
--dry-runPlan only. This is the default. The plan reports a digest of the project and a digest of the plan.
--applyMake the edit. It needs --expect-snapshot and --expect-plan with the digests of the plan you reviewed.
--expect-snapshot <digest>, --expect-plan <digest>Refuse to apply if the project or the plan is no longer the one you reviewed.
--packageThe project is a package project.
--max-output-bytes <n>A limit on the size of the report.
  • Both versions are checked. The complete project as it is and the complete project with the line added are checked. Every call must still reach the function it reached before: an import that would make a name reach a different function is refused, never planned.
  • One file changes. --apply publishes the edited file in one step, so it is either as it was or fully edited.
  • A function out of reach is moved first. A provider outside the file's folder and the folders above it cannot be imported until it is moved, with ael rename --owner.