Skip to content

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

bogolang
FR

← Documentation

The Bogolang language reference

The definition of the language, in numbered rules: literals, statements, structure, types, editions.

All documentation pages

Edition 2027. Bogolang version 0.1.0.

This page defines the Bogolang language. The other pages teach; this one states the rules. Where another page and this one disagree, this page is right and the other is at fault. Where this page and the bogo command disagree, one of the two has a fault, and it is reported as a bug.

Each rule has a number. The programs of the folder conformance are tied to these numbers: each one shows a rule at work, and one test runs them all.

1. What Bogolang is

1.1 Bogolang is a programming language for network and telecommunications engineers, built on Python. A Bogolang program is written in files whose name ends in .bogo.

1.2 Bogolang is defined as Python 3.15 with additions and restrictions:

  • Additions: the edition line (section 3), the literals (section 4), the statements (section 8) and the built-in names (section 9).
  • Restrictions: the structure of a program (section 5) and the type rules (section 6).

1.3 Everything this page does not state is as in Python 3.15, defined by The Python Language Reference of that version. A .bogo file is not a Python file: Python cannot read the additions, and Bogolang refuses Python programs that break the restrictions.

1.4 A Bogolang program runs on the Python engine that Bogolang carries. Every Python package can be imported and used (section 11).

2. Source text

2.1 A source file is text in UTF-8. A byte order mark at its start is accepted. Lines end with a line feed, or with a carriage return and a line feed.

2.2 Lines, indentation, comments, names, strings, numbers and operators are those of Python, with the additions of sections 3, 4 and 8.

2.3 An addition is recognised outside strings and comments only. Inside a string, also an f-string and its {}, and inside a comment, the text is never read as Bogolang.

2.4 A file keeps its lines: line N of a .bogo file is line N of what is checked and run. Every message names the line and the column of the .bogo file.

3. The edition line

3.1 The form is the word edition, spaces, and the name of an edition. A comment may follow. It is the first line of the file that is neither empty nor a comment.

edition 2027

3.2 The known editions are: 2027. Another name is an error that lists the known ones.

3.3 An edition fixes the meaning of the language. A file with an edition line has the meaning of that edition in every later version of Bogolang (section 12).

3.4 A file with no edition line takes the edition of its project (bogo.toml). With no project it takes the newest edition and gets a warning.

4. Literals

A literal is a value written bare in the source. Each literal has one type.

4.1 Addresses

Form Type Example
Four decimal numbers joined by dots IP 192.0.2.10
The same, /, a prefix length Net when the host part is zero, else IfAddr 192.0.2.0/24, 192.0.2.10/24
Six pairs of hex digits joined by colons MAC 00:1a:2b:3c:4d:5e

4.1.1 Each number of an address has one to three digits, with no leading zero, and a value of 0 to 255. The prefix length is 0 to 32. No space stands inside the literal.

4.1.2 An address literal starts where the character before it is not a letter, a digit, an underscore or a dot. It ends where the next character is not a letter, a digit or an underscore, and is not a dot followed by a digit. So 1.2.3.4.5 is not a literal.

4.1.3 A value that has the form and is not valid, such as 192.0.2.256, is an error at the literal.

4.2 Quantities

4.2.1 A quantity is a number followed at once by a unit: 20Mbps, 1.5s. The number is digits, with an optional dot and more digits. It has no exponent and no underscore. No space stands between the number and the unit.

4.2.2 The unit decides the type. The case of a unit counts.

Type Units
Rate bps, kbps, Mbps, Gbps
Duration ms, s, min, h, d
Distance m, km, ft, mi
Power dBm, dBW, mW, W
Gain dB, dBi
Frequency Hz, kHz, MHz, GHz
Wavelength nm
Size B, kB, MB, GB, KiB, MiB, GiB
Percent pct
Traffic erl
PacketRate pps

4.2.3 A number followed at once by letters that are not a unit is an error at the literal. The number forms of Python are left to Python: 0x1F, 0o17, 0b101, 2.5e3, 3j. So are letters that are a word of Python, as in 1if x else 2.

4.2.4 A minus sign in front of a quantity belongs to the literal when it is a sign: at the start of a line, after an operator, an opening bracket, a comma, = or :, or after a word of Python such as return. After a value it is a subtraction: a - 3dB.

4.2.5 A value its type does not allow, such as 0W for a Power, is an error at the literal.

4.3 Prefixed texts

4.3.1 A prefixed text is one of five words followed at once by a quoted text on one line. The quotes are " or '. The text holds no backslash.

Form Type
ip"..." IP, or Net when the text holds a /. IPv4 and IPv6
mac"..." MAC, in any of its written forms
intf"..." Intf
vlan"..." VlanSet
time"..." ClockTime, as HH:MM

4.3.2 An IPv6 address is written only so: ip"2001:db8::1". There is no bare IPv6 literal.

4.3.3 A text that is not valid for its type is an error at the literal.

4.4 Where a literal is read

4.4.1 A literal is read anywhere an expression of Python may stand: after =, inside brackets, in a list, as an argument, in a field of a class.

4.4.2 A literal is checked when the file is read, before the type check and before the program runs. A file with a wrong literal does not run.

Bogolang
core: IP = 192.0.2.1
lan: Net = 192.0.2.0/24
gw: IfAddr = 192.0.2.1/24
link: Rate = 20Mbps
low: Power = -18.5dBm
v6: Net = ip"2001:db8::/32"
print(core in lan, gw.net == lan, link, low, v6.version, [1s, 250ms])

5. The structure of a program

5.1 The top of a file

5.1.1 The top of a file holds only: the edition line; a describing text as the first statement; imports; classes. A comment stands anywhere.

5.1.2 Every other statement at the top of a file is an error: code must be inside a class. An on block at the top gets the message of 8.10.3 in its place.

5.2 The body of a class

5.2.1 The body of a class holds only: a describing text as its first statement; ...; pass; fields, with or without a written type; methods; classes; type aliases; rule blocks (8.9); on blocks (8.10).

5.2.2 Every other statement in the body of a class is an error: this line cannot stand in the body of a class. The rule holds for every class, wherever it is written.

5.2.3 Inside a method, every statement of Python and every statement of section 8 is allowed, but on.

5.3 Where a program starts

5.3.1 The start class of a file is the class at its top whose name matches the name of the file. Only letters and digits are compared, without regard to case: link_check.bogo matches class LinkCheck.

5.3.2 A program starts in the method main of the start class, written exactly so:

@staticmethod
def main(args: list[str]) -> None:

5.3.3 args holds the words given after the name of the file on the command line.

5.3.4 When a program runs, the file is read from top to bottom first: the fields of every class get their values, the rules are registered and the listeners open. Then main is called. A file that is imported is read the same way and its main is not called.

5.3.5 A start class with its main is asked only of a file that is run. A file that is checked or imported may be a library with no start class.

Bogolang
edition 2027
"""Says which hosts answer."""


class Page:
    hosts: list[IP] = [192.0.2.1, 192.0.2.10]

    @staticmethod
    def main(args: list[str]) -> None:
        for h in Page.hosts:
            print(h, tcping(h, 22))

5.4 Tests

5.4.1 A test is a method whose name starts with test_, in a class whose name starts with Test, at the top of a file.

5.4.2 A test takes self only. Each test runs on a new object of its class. Tests run in the order they are written.

5.4.3 A test contacts nothing: every built-in command that would reach the network answers from saved answers, or fails the test.

6. Types

6.1 Every value has a type that is known before the program runs. The type check runs before every run. A program with a type error does not run.

6.2 Every method states the type of each input and of its result. self and cls take no type. __init__ may leave out -> None when one of its inputs has a type.

6.3 A variable has one type. It takes the type of its first value, or the type written on its first line: rows: list[str] = []. A later value of another type is an error. One case is as in Python: a variable that holds a float takes an int.

6.4 No value may have an unknown type. The type Any may not be written.

6.5 A value that comes from Python code with no types gets its type on the line where it enters, in a method: count: int = json.loads(text). That line is tested when the program runs: a value of another type stops the program there. For a container such as list[int] only the container is tested, not what it holds.

6.6 An object of a package with no types is declared Untyped. It may be called, read from, written to, indexed, looped over and used in a with block. Each result gets its type on a line of its own, by 6.5: after t: Untyped = lib.make(), the line n = t.count() is an error, and n: int = t.count() is right. A result may be declared Untyped in its turn, to leave it unchecked on purpose. What is done with an Untyped object is not checked before the run.

6.7 A value that may be None (a type written T | None) is tested before it is used as a T.

6.8 The types of the literals, and every built-in type, are ordinary classes. Each can be made while the program runs. An address type is made from one text: IP("192.0.2.1"), Net("192.0.2.0/24"). A quantity is made from a number and the text of its unit: Rate(20, "Mbps"). A wrong text then raises ValueError with the message the check gives for the literal.

7. Quantities and addresses: what may be done with what

7.1 A quantity of one type never becomes another type by itself.

7.2 The operations between quantities. Anything not in this table is an error before the program runs.

Operation Result
X + X, X - X, for Rate, Duration, Distance, Size, Frequency, Wavelength, Percent, Traffic, PacketRate, Gain X
X * number, number * X, X / number, for every quantity but Power X
-X, for every quantity X
X / X float
X < X, <=, >, >= bool
Rate * Duration, Duration * Rate Size
Size / Duration Rate
Size / Rate Duration
Power - Power Gain
Power + Gain, Gain + Power, Power - Gain Power
Power + Power An error. combine(a, b) adds two power levels

7.3 == and != are allowed between any two values. A quantity or an address is never equal to a value of another type. Between two values of Python, == is as in Python.

7.4 A size counts bytes and a rate counts bits: 100MB / 10s is 80Mbps.

7.5 Where no check runs before the line (in bogo shell, or on a value from an Untyped object), an operation that 7.2 does not allow raises TypeError when the line runs.

7.6 IP in Net is a bool. An IP takes no arithmetic with a float.

Bogolang
print(1Gbps + 500Mbps, 100MB / 10s, 20Mbps * 1min, 1GB / 100Mbps)
print(-18.5dBm - -21dBm, -18.5dBm + 3dB, combine(-10dBm, -10dBm))
print(20Mbps == 5s, 12.4km / 3.1km, 192.0.2.7 in 192.0.2.0/24)

8. Statements

Bogolang adds ten statements. Each has a header that stands on one line.

8.0.1 A word of a statement is special only in its place in that statement. Anywhere else it is an ordinary name: every = 3 and watch(x) are plain Python.

8.0.2 Inside a header, a word such as where, parallel, timeout, every or per is read as part of the statement only where it stands between the end of one value and the start of the next, outside brackets.

8.0.3 In the forms below, capitals stand for an expression, and square brackets for a part that may be left out. DURATION is an expression of type Duration.

8.1 for ... where ... parallel

for TARGET in ITEMS [where CONDITION] [parallel NUMBER]:
    block

8.1.1 where runs the block only for the items for which CONDITION is true.

8.1.2 parallel NUMBER runs the block for up to NUMBER items at the same time. A variable given a value in the block belongs to that one run. An error in one run stops that run only; last_failures() gives the items that failed.

8.1.3 break and return in a parallel block are errors. continue skips the item.

8.2 wait until

wait until CONDITION timeout DURATION [every DURATION]

8.2.1 It is one line with no block. CONDITION is tested again and again, every 5 seconds or every the time after every, until it is true.

8.2.2 When the timeout passes first, BogoTimeout is raised.

8.2.3 timeout is required. Without it the line is an error.

8.3 retry

retry NUMBER [every DURATION]:
    block

8.3.1 The block runs. If it raises an error it runs again, up to NUMBER runs in all, with the pause of every between two runs. After the last run the last error is raised.

8.3.2 A change block (8.8) inside a retry block is an error.

8.4 every

every DURATION:
    block

8.4.1 The block runs, the program waits until DURATION has passed since the start of that run, and the block runs again, until the program is stopped or the block uses break.

8.5 only between

only between TIME and TIME ZONE:
    block

8.5.1 Each TIME is a ClockTime. ZONE is a plain name such as UTC, or a quoted name such as "Europe/Paris".

8.5.2 The block runs when the time of day in that zone is inside the window. A window may cross midnight. Outside the window BogoWindowError is raised.

8.5.3 In a dry run (--dry) the block is skipped outside the window, with a line that says so, and no error.

8.6 watch

watch EXPRESSION every DURATION [for DURATION]

8.6.1 It is one line with no block. The value of EXPRESSION is worked out again each period and shown, until the program is stopped or the time after for is over.

8.7 alert when

alert when CONDITION for DURATION [per KEY] [as NAME]:
    block

8.7.1 The block runs once when CONDITION has been true for DURATION, and once when it is false again. NAME is an Alert, which says which of the two it is.

8.7.2 An alert when stands inside an every block. Outside one it is an error.

8.7.3 Inside a loop it needs per KEY, so that each item has its own memory. Without per it is an error.

8.7.4 A change block inside the block of an alert is an error.

8.8 change on

change on DEVICE [revert_after DURATION]:
    apply:
        device lines
    rollback:
        device lines
    verify:
        tests, one per line

8.8.1 A change block holds the sections apply, rollback and verify, in this order, and nothing else.

8.8.2 A change with no rollback section, or with an empty one, is an error. A change with no apply lines is an error. A change with no verify gets a warning.

8.8.3 The lines under apply and rollback are device text, not Bogolang: an address in them stays text. {EXPRESSION} in such a line puts a value into the line; the expression is Bogolang and is checked. A real brace is written twice: {{ and }}.

8.8.4 Each line under verify is one expression that is true or false. The name show is there for it: show(COMMAND) gives the output of a show command on the device.

8.8.5 Meaning: the apply lines are sent; then each test of verify is made; if a line is refused by the device or a test is false, the rollback lines are sent and an error is raised. A device session opened outside a change block is read-only.

8.8.6 In a dry run (--dry) the lines that would be sent are shown and nothing is sent.

8.9 rule

rule "NAME" for DEVICE_NAME [where CONDITION]:
    tests, one per line

8.9.1 Each line of the block is one expression that is true or false, on one line. A rule holds no blocks. A rule with no test is an error.

8.9.2 In a test, DEVICE_NAME is the device, config its configuration and show its show commands. audit(...) runs the rules and gives what failed.

8.9.3 A rule stands in the body of a class or in a method.

8.10 on

on KIND [port NUMBER] [address IP] from SENDERS [matching TEXT] [as NAME]:
    block

8.10.1 KIND is syslog, trap or netflow. The block runs for each event received from one of SENDERS. NAME is the event: a SyslogEvent, a Trap or a Flow.

8.10.2 matching keeps the events that hold TEXT (syslog) or whose OID starts with it (trap). on netflow takes no matching: it is an error.

8.10.3 An on block stands in the body of a class only. Anywhere else it is an error. Its listener opens when the class is read, before main (5.3.4).

8.10.4 A change block inside an on block is an error.

Bogolang
edition 2027


class Page:
    devices: list[Device] = [Device(name="core-sw1", ip=192.0.2.1, platform="iosxe")]

    rule "no telnet on the vty lines" for d where d.role != "server":
        not config.has("transport input telnet")

    on syslog port 5514 from devices matching "UPDOWN" as e:
        print(e.received, e.device, e.message)

    @staticmethod
    def main(args: list[str]) -> None:
        for d in Page.devices where d.platform == "iosxe" parallel 4:
            print(d.name)
        wait until tcping(192.0.2.1, 22) timeout 2min every 10s
        retry 3 every 5s:
            print(ping(192.0.2.1, count=2))
        only between time"22:00" and time"04:00" UTC:
            change on Page.devices[0]:
                apply:
                    vlan 30
                     name users-{len(args)}
                rollback:
                    no vlan 30
                verify:
                    "30" in show("vlan brief").text
        every 1min:
            for d in Page.devices:
                r: PingResult = ping(d.ip, count=4)
                alert when r.loss > 5pct for 3min per d.name as a:
                    print(d.name, "raised" if a.raised else "cleared")

9. Built-in names

9.1 Every .bogo file has the built-in names with no import. They are listed, each with its signature and its meaning, in reference.md, which is made from the code. bogo doc NAME prints one entry.

9.2 A file may give a built-in name a meaning of its own, as it may with a built-in of Python. Inside that file its own meaning wins.

9.3 One case is not allowed: a file that defines, at its top, its own class with the name of the type of a literal, such as Net or Power, cannot also write that literal. A class of that name inside another class does not hide the type.

10. Checking and running

10.1 A program is never compiled ahead. Each time, it is read (sections 3, 4, 8), checked (sections 5, 6, 7), then run. The three stages are in this order, and a stage with an error stops the next.

10.2 bogo check FILE does the first two stages. Its exit code is 0 with no error, 1 with errors, 2 when the check could not be made.

10.3 An error names the file, the line, the column, what is wrong, and where it helps, what to write. A warning does not stop the run.

10.4 A file is checked together with the .bogo files it imports.

10.4.1 An import of a package that is not installed is an error at the line of the import. An import inside a try that catches ImportError is left to the program.

10.5 bogo run [OPTIONS] FILE [WORDS] checks and runs. The options of bogo stand before the file. Every word after the file is given to the program (5.3.3).

10.6 A word after the file that is an option of bogo, such as --replay or --dry, is refused and nothing runs: there it would not be applied, and a run meant to use saved answers would be a live one. The program gets such a word when it stands after --. The -- itself is not given to the program.

11. What is Python as it is

11.1 Inside a method: every expression and statement of Python 3.15.

11.2 Classes, with the limits of 5.2: inheritance, properties, static and class methods, data classes, generics.

11.3 The standard library and every Python package, imported as they are. A package with types is used with no more. A package with no types is used by 6.5 and 6.6.

11.4 A plain .py file beside a program can be imported. The rules of sections 5 and 6 hold for .bogo files only.

11.5 The types of Bogolang are ordinary Python objects, so a Python package can receive them. .to_python() on an IP or a Net gives the object of Python's ipaddress module.

12. Editions and what is promised

12.1 A program that states an edition and passes the check keeps its meaning in every later version of Bogolang.

12.2 A change that would alter what such a program does, or remove something it uses, comes only in a new edition. The edition before it warns first.

12.3 A new version may add built-in names, units and statements to an edition, as long as no program that passed the check before changes its meaning. A file's own names win over new built-in names (9.2).

12.4 The Python engine inside Bogolang may move to a newer Python. What 1.3 leaves to Python then follows that version of Python, within what Python itself keeps compatible.

13. Limits of version 0.1.0

These are limits of the first version, not rules of the language. They are stated so that nobody has to find them.

13.1 A literal inside the {} of an f-string is not read (2.3). Put the value in a variable first.

13.2 The header of a statement of section 8 stands on one line.

13.3 where and parallel are read in the header of a for only, outside brackets and strings.

13.4 A program that reads, after a parallel loop, a variable given a value inside it is not refused by the check. It stops when it runs.

13.5 The messages of the type check for rare mistakes are those of the type checker underneath, with the names of the types as Bogolang writes them.

13.6 Rule 6.6 finds an Untyped object by its name: a variable, an input, a field or a method declared Untyped, and the name of a for or with over one. A result of an Untyped object reached another way, such as an item of a list of them, is not refused.