Reading & writing
Reading a Vision program
This small build report has enough moving parts to show how a Vision file hangs together: one described thing, three helper verbs, a loop, and a final line of output.
The example is complete and runnable with the current compiler. Read it once before following the notes. The compiler-backed build checks its output byte for byte.
kind buildstate:
owner: text
project: text
checks: whole
warnings: whole
minutes: whole
to greet(a name), returns text:
answer "hello, {the name}"
to status(report: buildstate), returns text:
when report.warnings is 0:
answer "ready"
else:
answer "needs review"
to describe(report: buildstate), returns text:
answer "{greet(report.owner)} — {report.project}: {report.checks} checks in {report.minutes} minutes — {status(report)}"
to begin:
the durations are 4, 3, 5
the total is 0
each duration in the durations:
the total is the total plus duration
the result is a buildstate:
owner is "Ada"
project is "Vision"
checks is 12
warnings is 0
minutes is total
say describe(result)kind buildstate:
owner: text
project: text
checks: whole
warnings: whole
minutes: whole
to greet(a name), returns text:
answer "hello, {the name}"
to status(report: buildstate), returns text:
when report.warnings is 0:
answer "ready"
else:
answer "needs review"
to describe(report: buildstate), returns text:
answer "{greet(report.owner)} — {report.project}: {report.checks} checks in {report.minutes} minutes — {status(report)}"
to begin:
the durations are 4, 3, 5
the total is 0
each duration in the durations:
the total is the total plus duration
the result is a buildstate:
owner is "Ada"
project is "Vision"
checks is 12
warnings is 0
minutes is total
say describe(result)1. Describe the result
The file begins with the data it cares about. buildstatenames five fields and their types. Later code can pass the report as one value instead of keeping its owner, project, counts, and timing in sync by hand.
This declaration creates a shape; it does not create a report yet. The value appears near the bottom, after the program has calculated the total run time.
2. Name the decisions
greet handles the opening words. status turns a warning count into a short verdict. Its when branch answers early for a clean report; the else covers the remaining case. These decisions live under useful names, sodescribe does not need to repeat them.
All three helpers declare what they answer with using returns text. Field reads such asreport.warnings stay close to the value they belong to. The call status(report) is an expression, so its answer can sit directly inside the final text.
3. Follow begin in order
begin is where execution starts. The first line makes a list of three durations. The each block visits them in order and adds each value to total. Indentation shows the one line that belongs to the loop.
Once the indentation returns, the loop is over. The construction block then makes a buildstate. Each indented assignment fills a named field; minutes is total carries the calculated value into the report.
4. Read the boundary last
The final line calls describe and sends its answer to the console. Everything before that line works with values inside the program. As explained in How Vision thinks, direct say output is the small unmarked exception to Vision's >> world-touch rule.
That gives the file a useful reading order: understand the shape, read the helper verbs, then trace begin. You can usually leave the details inside a well-named helper until you need them.
Change one decision
Set warnings is 2 in the construction block and run the program again. The loop and report stay the same, but the last words become needs review. Then add another duration to the list and watch the total change. The next guide looks more closely at the values, text, and lists doing that work.