2 Syntax
This page is the syntax map for #lang sciencelogo. Read Getting started to learn the basic pattern; follow the links below for each form’s full rule. Most forms run. Paired stages and their location calls are read and checked as a written method but are not executed. The specification guide links the language contracts separately from rationale and earlier design notes. Within an interface, must [...] groups required entries and their defaults. name [...] gives a part its own nested entries. Bare entries without defaults are optional. An is constraint outside must, such as notes is text, checks the field when supplied; see Records and interfaces.
Compact grammar collects all compact forms and their parsing rules in one reference, with a standalone grammar for implementations in other languages.
Compact and verbose syntax gives the accepted word-based equivalents and examples of mixed source. All spellings normalize to compact syntax before the same parsing and language checks.
2.1 How to read the forms
In a form such as to name :input [ ... ], command words such as to are written literally; name, input, and ... stand for content you supply. Square brackets shown in a form are literal ScienceLogo brackets. Quoted text is a text value. Commands may share a line or use separate lines.
At command position, name = value assigns a value. Equality comparisons use ==. Within a record or dotted update, = supplies a field value; within an interface, it supplies a default. At command position, name += [field = value] updates or adds record fields, while name.field += number adds to an existing numeric field. On a list, name += value appends one item. See Procedures and control flow for scope.
2.2 Names and labels
Names are case-sensitive. The table gives the project’s spelling convention. These conventions are optional guidance for readable workflows. Capitalization and hyphens do not determine what a name represents and are not validation requirements. The declaration identifies an interface. For example, Timing, timing, and timing_shape can each name an interface; they remain distinct names because names are case-sensitive.
What is named | Preferred form | Example |
Library and repository | Lowercase words joined by hyphens | pendulum-tools |
Import or implementation alias | Lowercase words joined by hyphens | timing-tools |
Procedure | Lowercase words joined by hyphens | estimate-period |
Input | Lowercase words joined by hyphens, preceded by : in code | :swing-count |
Value, call result, or loop name | Lowercase words joined by hyphens | trial-duration |
Performer | Lowercase words joined by hyphens | researcher |
Resource | Lowercase words joined by hyphens | timing-data |
Proposition | Lowercase words joined by hyphens | swing-period |
Record field or required part | Lowercase words joined by hyphens | mean-period |
Interface | First letter capitalized; later words lowercase and joined by hyphens | Timed-observation |
Stage | Lowercase words joined by hyphens | measure-the-pendulum |
Workflow title | Readable quoted text | "Measure the pendulum" |
Source file or directory | Lowercase words joined by hyphens | methods/estimate-period.rkt |
Names are unquoted identifiers in declarations and references. Quotes mark string values, including descriptions, file paths, URLs, versions, and the workflow’s human-readable title. An interface is declared as interface Timed-observation [ ... ], and referred to as Timed-observation. An imported interface is alias.Timed-observation; an imported procedure is alias.estimate-period. A library also declares an unquoted name, as in library pendulum-tools [ ... ]; imports use its Git URL and the chosen alias. A stage is declared as stage measure and referenced as measure, including in implementation mappings and must stages in order [prepare measure].
The reader rejects reserved command words as most user names. A dot separates parts of a path: record fields, list positions, stage state locations, and imported names. Simple procedure, input, value, result, loop, performer, resource, proposition, import alias, stage, library, and interface names do not contain dots. A name used as a word has no spaces. Stage, library, and interface names cannot start with a number. Hyphenation and capitalization remain optional conventions. A workflow title is a string and can contain spaces. Procedure names must be distinct; interface names must be distinct from each other and from procedures; performer and resource names follow their declaration rules; proposition names are unique within their type and parent; stage names must be distinct across the assembled workflow. Each procedure has distinct input names, and record fields are distinct within a record. Procedures and control flow explains local value scope and result names.
A stage reference in an implement mapping is resolved from its declaration, including a later declaration or an imported qualified name such as timing.measure. Quotes and capitalization do not select the target’s kind. If that reference could also identify a visible value or another definition, the reader reports an ambiguous implementation target. A stage name does not become a data value or a callable function.
2.3 Source files
Every ScienceLogo source file begins with #lang sciencelogo. The entry workflow is the file to run or assess. Its optional workflow "title" is the first form and labels the whole method without enclosing it in brackets. Definitions may appear after their uses.
Form | Where it belongs | Purpose |
workflow "title" | First form of an entry workflow | Names the method; at most one per file |
about "Markdown text" | After the optional workflow title, before imports | Describes the workflow; also attaches to stages and procedures |
library name [ ... ] | library.rkt | Declares reusable procedures and record interfaces |
import "Git URL" at "tag" as alias | After an optional workflow title and description, before method forms; or directly in a library | Loads a pinned library |
include "relative/path.rkt" | Top level of a workflow or library file | Loads another file from the same repository |
interface name [ ... ] | Top level of a workflow or library, or alone in a file | Declares record fields or workflow requirements |
performer name [field = value ...] | Top level of a workflow | Declares an open performer object for paired stages |
resource name [field = value ...] | Top level of a workflow | Names a data source or storage location |
hypothesis name [text = "..."] (also assumption, conclusion) | Top level of a workflow | Declares a named proposition |
A library import selects a tag or full commit ID on its main branch. Files and libraries explains import, include, repository layout, and dependency rules. Records and interfaces explains the two interface forms. Workflow files may contain commands, procedures, stages, performers, resources, propositions, interfaces, obligations, and includes. A library file may contain imports, includes, procedures, and record interfaces; it has no top-level executable commands.
2.4 Describe a workflow, stage, or procedure
about "text" supplies an optional description in CommonMark Markdown. It uses ordinary quoted text, which may span lines; escaped quotes and backslashes follow the usual string rules. No headings or template are required. A short opening summary is recommended. Explain purpose, assumptions, limits, or how to interpret results when that helps a reader.
What it describes | Where to place about |
Workflow | After its optional title, before imports and other forms |
Procedure | First inside the opening bracket of its to definition |
Simple stage | Immediately after its stage header |
Paired stage | Immediately after its complete opening header and entry state |
Compact
#lang sciencelogo |
workflow "Review a timing plan" |
about "Explain how to time a pendulum as the swing gets smaller." |
|
stage Prepare |
about "Prepare the timing plan." |
do make-plan as plan |
|
to make-plan [ |
about "Return a timing plan, with its **purpose**." |
output "Time ten swings as the swing gets smaller." |
] |
|
stage Review |
about "Read the plan." |
print plan |
Verbose
#lang sciencelogo |
workflow "Review a timing plan" |
about "Explain how to time a pendulum as the swing gets smaller." |
|
start stage Prepare |
about "Prepare the timing plan." |
do make-plan as plan |
|
to make-plan [ |
about "Return a timing plan, with its **purpose**." |
output "Time ten swings as the swing gets smaller." |
] |
|
start stage Review |
about "Read the plan." |
print plan |
Each workflow, stage, or procedure may have one description. Whitespace and comments may separate it from its header; commands may not. A workflow without a title may begin with about. Procedures in libraries and included files follow the same rule. A description on a nested stage belongs to that stage, separately from its procedure’s description.
A workflow description can summarize the question, scope, and limits. A stage description can explain its checkpoint or work. A procedure description can explain a reusable method and its limitations; its inputs and results remain defined by the code. An empty description is allowed.
The reader preserves the text and its source location for inspection and external documentation tools. It does not render Markdown or treat prose as a declaration or a condition. Descriptions have no effect on execution or check results. Anonymous do, if, and loop blocks, libraries, and interfaces have no about attachment; use comments for local notes. The description contract records these rules and the workflow model accessors.
2.5 Where to find each form
Topic | Forms covered | Purpose and behavior |
about "Markdown text" | Optional explanation attached to a workflow, stage, or procedure | |
numbers, text, true, false, unknown, lists, records | Values used by runnable forms | |
range, .field, .[ ... ], .count, arithmetic, comparisons, in, is, not, and, xor, or | Expressions used by runnable forms | |
value u [declared = [ ... ] omitted = [ ... ]], value.u | Attached descriptions of named uncertainty sources | |
to, :input, do, as, output, name = value, name += value, print | Definitions and executable commands | |
repeat, until, for each, while, if, else if, else | Executable control flow | |
stage name | Section header for runnable commands | |
performer, stage ... by ... from state, do ... by ... into, end stage with state, at | Read and checked; paired body not executed | |
hypothesis, assumption, conclusion, +=, dotted paths | Named declarations, nesting, and updates | |
resource name [ ... ], name.field = value, value = name.field | Data flow represented; no external I/O | |
interface, version, extends, must [...], if, else if, else, for each, affects | Declarations checked for structure | |
library, import, include | Files and revisions resolved by reader | |
subject implement Interface.part, must do, must stages in order | Interface mappings and requirements on the written method |
2.6 Comments and whitespace
; begins a line comment. #| and |# enclose a block comment; block comments can nest. Whitespace is flexible, and empty blocks are allowed. Parentheses group value expressions; brackets delimit blocks, lists, and named-field records. The reader and workflow model preserve every explicit parenthesis group, including nested and redundant groups. Evaluation and checks respect the written grouping.
2.7 What the reader checks
Before running a workflow, the reader rejects malformed brackets, unsupported commands, duplicate names, unknown procedures or values, wrong input counts, a requested result from a procedure without output, recursive procedure calls, invalid interface inheritance, and misplaced file-level forms. For state stages it also checks named input locations, compulsory return locations, resource paths, and the declared exit state. A state stage is read and checked, but its body is not executed by the reference interpreter. Reading or writing data outside the workflow requires a declared resource; see Data sources and storage. Proposition declarations use named collections. The reader catches repeated top-level additions; the interpreter rejects other duplicates when a runnable += command executes. See Propositions. Uncertainty descriptions accept only declared and omitted collections of named sources; see Uncertainty descriptions. Source-code paths in imports and includes have separate rules. Structural obligations are assessed separately; a successful read does not establish that scientific work occurred.