Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

Your first program

From bogo new to a run, a check, a test and a run on saved answers.

All documentation pages

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:

Bogolang
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.

Bogolang
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.1 is an address and 50ms is 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_all and PingResult are built-in names. Every program has them with no import. reach.md describes them, and bogo doc ping_all prints 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