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