This page takes you from an empty folder to a project that runs, passes the check and passes its tests. The last step runs the program on saved answers, so it contacts no host at all.
You need an installed Bogolang (install.md). Every command here is typed in a
terminal. Folder paths in the output are shortened to ... on this page.
1. Make a project
bogo new linkcheck
Made project linkcheck in ...\linkcheck
Next: cd linkcheck and bogo run main.bogo
The project is a folder with three things in it:
| Name | What it is |
|---|---|
bogo.toml |
The project file: its name, its edition, its engine and the packages it adds |
main.bogo |
The program |
tests/ |
The folder for test files, empty for now |
bogo.toml as bogo new writes it:
[project]
name = "linkcheck"
edition = "2027"
engine = "3.15"
[packages]
main.bogo as bogo new writes it:
edition 2027
class Main:
@staticmethod
def main(args: list[str]) -> None:
greeting: str = "Hello from linkcheck"
print(greeting)
Three rules show already. The first line names the edition. All code stands inside a class.
The program starts in main, a static method of the class named after the file
(main.bogo holds class Main). language.md gives the full rule.
2. Run it
cd linkcheck
bogo run main.bogo
Hello from linkcheck
bogo main.bogo is the short form of bogo run main.bogo. Before each run the file is
checked. A program with a mistake does not start.
The first run makes a folder .bogo in the project. It holds the environment of the project
and the Python that Bogolang generates from your file. Do not share it or put it in version
control: bogo sync makes it again.
3. Write a real program
Replace main.bogo with this. It pings two routers at the same time and gives one word for
each.
edition 2027
class Main:
"""Says which routers answer, and how well."""
routers: list[IP] = [192.0.2.1, 192.0.2.2]
slow: Duration = 50ms
@staticmethod
def state(r: PingResult, slow: Duration) -> str:
"""One word for a ping result."""
if not r.ok:
return "DOWN"
if r.avg is not None and r.avg > slow:
return "SLOW"
return "ok"
@staticmethod
def main(args: list[str]) -> None:
results: list[PingResult] = ping_all(Main.routers, count=3)
for r in results:
print(f"{r.host} {Main.state(r, Main.slow):5} {r}")
What is new here:
192.0.2.1is an address and50msis a duration. They are written bare, with no quotes. types-and-units.md lists every such literal.- Each method says the type of each input and of its result.
ping_allandPingResultare built-in names. Every program has them with no import. reach.md describes them, andbogo doc ping_allprints the entry in the terminal.
4. Check it
bogo check
main.bogo: no errors
In a project, bogo check with no file checks main.bogo and the other .bogo files of the
project. It runs nothing and contacts nothing.
A mistake is shown with its file, line and column, the line itself, and, when there is one,
how to mend it. This file, link_check.bogo, adds a rate to a power level:
```bogo skip edition 2027
class LinkCheck: @staticmethod def main(args: list[str]) -> None: speed = 20Mbps level = -18.5dBm total = speed + level print(total)
`bogo check link_check.bogo` says:
link_check.bogo:9:25: error: cannot use + between Rate and Power total = speed + level ^^^^^
The program is not run. The same mistake in Python would show only when the line runs, if
ever.
## 5. Test it
A test file is named `test_*.bogo` and stands in the folder `tests`. A test is a method whose
name starts with `test_`, in a class whose name starts with `Test`. It takes `self` only and
passes when it ends with no error. Save this as `tests/test_main.bogo`:
```bogo skip
edition 2027
from main import Main
class TestState:
def test_no_answer_is_down(self) -> None:
r: PingResult = PingResult(3, 0, 100pct, None, None, None)
assert Main.state(r, 50ms) == "DOWN"
def test_slow(self) -> None:
r: PingResult = PingResult(3, 3, 0pct, 70ms, 80ms, 90ms)
assert Main.state(r, 50ms) == "SLOW"
def test_fast(self) -> None:
r: PingResult = PingResult(3, 3, 0pct, 1ms, 2ms, 3ms)
assert Main.state(r, 50ms) == "ok"
PingResult(sent, received, loss, min, avg, max) builds a result by hand, so the test needs
no network.
bogo test
tests/test_main.bogo
passed TestState.test_no_answer_is_down
passed TestState.test_slow
passed TestState.test_fast
3 passed, 0 failed
A failed test shows the line and the message of its assert:
FAILED TestState.test_wrong_on_purpose
tests/test_main.bogo:20: assert Main.state(r, 50ms) == "SLOW", "a fast host is not slow"
AssertionError: a fast host is not slow
3 passed, 1 failed
bogo test -k slow runs only the tests whose shown name holds slow. The exit code is 0 when
every test passes and 1 otherwise.
A test never contacts anything. A device command, a ping or a web call in a test answers
from the folder tests/replay, and a command with no saved answer fails that test.
6. Run it on saved answers
bogo run main.bogo would now send real pings. To try the program with no network, give it
saved answers with --replay FOLDER. Then nothing is contacted.
A saved answer of ping is a small file in the folder reach of the replay folder, named
after the address. Make the folder saved/reach in the project and write these two files.
saved/reach/ping_192.0.2.1.txt, three answers:
{"sent": 3, "times_ms": [1.2, 1.4, 1.1], "reason": ""}
saved/reach/ping_192.0.2.2.txt, no answer (null is a lost packet):
{"sent": 3, "times_ms": [null, null, null], "reason": ""}
Then:
bogo run --replay saved main.bogo
192.0.2.1 ok 3 sent, 3 received, 0% loss, min/avg/max 1.1ms/1.233ms/1.4ms, jitter 0.25ms
192.0.2.2 DOWN 3 sent, 0 received, 100% loss
Options go before the file name. Words after the file name go to the program, in args.
You do not have to write saved answers by hand. bogo run --save-replay saved main.bogo runs
the program for real and keeps every answer in saved, for a later --replay. That run does
contact the hosts.
Add --record to see every command the program sent, with its time in local time and in UTC:
bogo run --replay saved --record main.bogo
device command start_local start_utc seconds ok error
192.0.2.2 ping 2026-11-20T18:04:58+01:00 2026-11-20T17:04:58+00:00 0.00 False no reply
192.0.2.1 ping 2026-11-20T18:04:58+01:00 2026-11-20T17:04:58+00:00 0.00 True
Where to go next
- language.md: the class rule, the types, the new statements.
- tools.md: every
bogocommand and option. - devices.md: sessions to devices, read-only by default.
- ../examples: thirteen programs, each with saved answers, ready for
--replay. The one closest to this page is ../examples/reach_hosts.