Starting a program: zeno new
Every page so far began with a file that was already there. This one is about the first minute of a program that is not: one command makes a folder with a small program in it that runs, and has a test that passes.
zeno new blinker
Made the program `blinker` in blinker/
zeno.package the name of the program, and the packages it needs
main.zeno the program
greeting.zeno a module, with a test
Run it with `zeno run blinker/main.zeno`, and its tests with `zeno test blinker`.
zeno run blinker/main.zeno # Hello, world, from blinker.
zeno test blinker # 1 test: 1 passed, 0 failed.
(In this repository zeno is cargo run --, as on every other
page.) The decisions are 10.22 to 10.24 in
decisions.md.
What it writes
Three files, and each one is one of the three things a program of more than one file is made of.
main.zeno is where the program starts (modules.md):
# The program starts here. In this folder:
#
# zeno run main.zeno
# zeno test
import greeting
print(greeting.hello("world"))
greeting.zeno is a module, a file of the program that another file
imports, and it has a test at its end (testing.md):
# A module: one file of the program. `main.zeno` imports it, and calls
# `greeting.hello`.
function hello(who: str) -> str {
return f"Hello, {who}, from blinker."
}
# A test stands in the file it tests. `zeno test` runs it, `zeno run`
# goes past it, and a build leaves it out.
test "hello says who it greets" {
assert hello("Ada") == "Hello, Ada, from blinker."
}
zeno.package is the project file (packages.md). It
has one line that counts, and comments that show the two lines you
may add to it one day:
# What this program is called, and the packages it needs.
#
# A package in another folder is one line:
#
# needs filters in "../filters"
#
# One that somebody else keeps is named by its git repository and a
# version of it, and `zeno fetch` gets it:
#
# needs units from "https://github.com/someone/zeno-units" at "v1.2.0"
package blinker
Nothing else is written. There is no hidden folder, no settings file
and nothing to delete before you start. The program is what you would
have typed, and you go on by changing it: rename greeting.zeno, or
throw it away and write in main.zeno alone.
A package: --package
A package is a folder of modules for other programs to use. It has no
main.zeno, and the module that matters is the one with the
package's own name, because that is the file import filters reads.
zeno new --package filters
Made the package `filters` in filters/
zeno.package the name of the package, and the packages it needs
filters.zeno the module `import` gets, with a test
Run its tests with `zeno test filters`.
filters.zeno has the same hello and the same test. The comment at
the top of its zeno.package says what a program has to write to use
it:
# This file makes the folder a package: a folder of modules that a
# program in another folder can use. A program that needs it says so
# in its own `zeno.package`:
#
# needs filters in "../filters"
#
# and then writes `import filters`.
package filters
So with both folders side by side, blinker can use filters after
two edits: the needs line in blinker/zeno.package, and import
filters in blinker/main.zeno.
What it refuses, and what it says
| You write | Zeno says |
|---|---|
zeno new my-app |
my-app cannot be the name of a program. A name is letters, digits and _, and does not start with a digit, as every name in a Zeno program is. Try my_app |
zeno new while |
while is a word of the language, so a program cannot have that name |
zeno new --package math |
math is a module that comes with Zeno, so a package cannot have that name |
zeno new blinker, a second time |
there is a blinker here already. zeno new makes a new folder, and writes nothing into one that is there |
zeno new --lib filters |
zeno new has no option --lib. It has one, --package, as in zeno new --package filters |
zeno new |
new needs a name for the program, e.g. zeno new blinker |
The name is the last part of what you write, so zeno new
work/bench/logger makes the program logger in that folder, and the
folders above it if they are not there.
How it works
new in src/package.rs is the whole of it,
about a hundred lines, in four steps.
- The name. The last part of the path. It is checked the way the
lexer would check it: letters, digits and
_, not a digit first. Then two tables that the compiler already has are asked:token::keyword(is it a word of the language?) andbuiltins::comes_with_zeno(is itmath,time, ...?). When the name will not do, a name that will is worked out by putting_for each character that cannot be in one. - The folder. If anything is at the path, a file or a folder,
newstops. This is checked before anything is written. - The files. Each is a
format!with the name put in. A package differs from a program in a list of two files in place of three. - What it says. The lines it gives back are what
main.rsprints.newprints nothing itself, which is what lets a test call it and look at what it said.
The test (zeno_new_makes_a_program_that_runs_and_a_package_it_can_need
in src/main.rs) does what you would do by hand. It makes a program
and a package in a temporary folder, runs the program and reads what
it prints, runs the tests of both, and checks that each file is
already laid out the way zeno format would lay it out. Then it
makes the program need the package and runs it again. What zeno new
writes is therefore checked by the checker, the interpreter and the
formatter every time the compiler's tests run: if the language
changes under it, that test fails.
What is left out
- No templates. There is one program and one package. A program
for a board is the same program with other lines in
main.zeno. - No questions. The command asks nothing and reads nothing from the keyboard.
- Nothing into a folder that is there. There is no
zeno init. - No git. No repository is made and no
.gitignoreis written.packages/is the one folder worth ignoring, and it is only there afterzeno fetch. - No
zeno add. Aneedsline is written by hand.
Things to try
- Run
cargo build, then in an empty folder outside the repository runzeno new blinker(with the full path totarget/debug/zeno). Run the program and its tests. - In
blinker/greeting.zeno, change the texthellogives back and runzeno test blinker. Read what the failure shows on each side. Which of the two do you change to make it pass, and why does it depend on what you meant? - Run
zeno format --check blinker. It says nothing. Find the test insrc/main.rsthat promises this, and the three files it names. - Run
zeno new --package filtersbesideblinker. Makeblinkeruse it: one line inblinker/zeno.package, andimport filtersinmain.zeno. Both modules have ahello. Why is that no clash? (Decision 8.8.) - Run
zeno build --no-collector blinker/main.zenoand run what it built. The module has a test in it. Where did the test go? (Decision 10.20.) - Try
zeno new 9lives,zeno new forandzeno new time. Each is refused for a different reason. Find the three checks innew. - Run
zeno new blinkeragain, thenls blinker. Nothing changed. Innew, move thepath.exists()check belowfs::create_dir_all, run the tests, and read which line of the test catches it. Put it back. - Add a file to what a new program gets: a
README.mdthat says how to run it. You need one more entry in the list of files, and the test's list of file names will tell you it noticed.
This page is docs/new.md in the language repository.