Skip to content

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

bogolang
FR

← Documentation

Types and units

Addresses, subnets, interfaces, VLANs and the units, with what may be added to what.

All documentation pages

This page lists the network types and the units that Bogolang knows, how each is written, what may be added to or compared with what, and what the check refuses. Every name here is there in every program with no import.

A value written in the program, such as 192.0.2.0/24 or 20Mbps, is checked when the program is checked, before it runs. A wrong address is found before any device is touched.

Literals

A literal is written bare, with no quotes. It is recognised outside strings and comments only.

Written Type Rule
192.0.2.10 IP Four numbers 0 to 255
192.0.2.0/24 Net An address, /, a prefix 0 to 32, no spaces. The host part is zero
192.0.2.10/24 IfAddr An address with its prefix, as on an interface: the host part is not zero
00:1a:2b:3c:4d:5e MAC Six pairs of hex digits
20Mbps Rate bps, kbps, Mbps, Gbps
5s Duration ms, s, min, h, d
12.4km Distance m, km, and also ft, mi
-18.5dBm Power dBm, dBW, mW, W
2.5dB Gain dB, dBi
5.8GHz Frequency Hz, kHz, MHz, GHz
1550nm Wavelength nm
100MB Size B, kB, MB, GB (powers of 1000), KiB, MiB, GiB (powers of 1024)
5pct Percent pct
2.4erl Traffic erl (erlangs)
1500pps PacketRate pps

A number followed at once by its unit is one literal: 5s. With a space, 5 s, it is not. The case of a unit counts: Mbps is a rate, MB a size.

Some values would clash with Python if written bare. They are written as a word and a quoted text:

Written Type
intf"Gi1/0/24" Intf
vlan"10-20,30" VlanSet
ip"2001:db8::1", ip"2001:db8::/32" IP, Net (IPv6)
mac"001a.2b3c.4d5e" MAC (the dotted form)
time"02:00" ClockTime
Bogolang
core: IP = 192.0.2.1
lan: Net = 192.0.2.0/24
gw: IfAddr = 192.0.2.1/24
v6: Net = ip"2001:db8::/32"
uplink: Intf = intf"Gi1/0/24"
voice: VlanSet = vlan"100-110"
start: ClockTime = time"02:00"
print(core in lan, gw.net == lan, v6.version, uplink.long, 105 in voice, start)

Each type can also be made from a text while the program runs, for values read from a file or a device: IP("192.0.2.1"), Net("192.0.2.0/24"), MAC("00-1A-2B-3C-4D-5E"), Rate(20, "Mbps"). A wrong text then stops the program with the same message the check gives.

A minus sign belongs to the literal when nothing stands on its left: -18.5dBm. After a value it is a subtraction: a - 3dB.

The network types

IP

One IPv4 or IPv6 address.

Expression Result
ip + 5, ip - 5 IP, the address 5 further or 5 before
ip < other, >, <=, >= bool, between two addresses of the same version
ip in net bool
.version 4 or 6
.is_private bool
.to_python() the address object of Python's ipaddress module

Net

A subnet. The host part must be zero: 192.0.2.5/24 written as a Net is refused.

Expression Result
.address, .mask, .wildcard, .broadcast IP
.prefix, .size, .version int (.size counts every address)
.hosts every usable address, one after another
.split(26) list[Net], the subnets of that prefix (at most 65536)
.overlaps(other) bool
ip in net, small in net bool, for an address or a smaller subnet
.to_python() the network object of Python's ipaddress module
Bogolang
n = 192.0.2.0/24
print(n.size, n.mask, n.wildcard, n.broadcast, len(list(n.hosts)))
print(n.split(26)[1], (10.0.0.0/8).overlaps(10.1.0.0/16))

This prints:

256 255.255.255.0 0.0.0.255 192.0.2.255 254
192.0.2.64/26 True

Four functions plan addresses with Net values. planning-routes-acl.md describes them.

Function Result
summarize(nets) the shortest list of subnets that covers the same addresses
next_free(block, prefix, used) the first subnet of that prefix in the block that overlaps no used subnet
free_nets(block, used) the free space of the block as the fewest subnets
net_of(address, mask) the network that holds the address, from a mask or a wildcard (IPv4)

IfAddr

An address with its prefix, as configured on an interface. .ip gives the IP, .net the Net, .prefix the length.

MAC

Written 00:1a:2b:3c:4d:5e, 00-1A-2B-3C-4D-5E or 001a.2b3c.4d5e; all three are the same address. It prints with colons. .cisco gives the dotted form, .oui the first three pairs. vendor(mac) gives the maker from the public list of the IEEE.

Intf

An interface name. Gi1/0/24, Gig1/0/24 and GigabitEthernet1/0/24 are the same interface, as IOS reads them. .short, .long, .kind and .numbers give its parts. Interfaces sort by kind, then by number, so Gi1/0/2 comes before Gi1/0/10.

Bogolang
p = intf"Gi1/0/24"
print(p, p.long, p.numbers, p == intf"GigabitEthernet1/0/24")
Gi1/0/24 GigabitEthernet1/0/24 (1, 0, 24) True

VlanSet

A set of VLAN numbers, 1 to 4094, written as a list with ranges.

Expression Result
15 in v bool
a + b the union
a - b the difference
len(v) the number of VLANs
for n in v each number, in order
Bogolang
v = vlan"10-20,30"
print(v + vlan"21", v - vlan"15-20", len(v), list(vlan"5-7"))
10-21,30 10-14,30 12 [5, 6, 7]

The units

Each kind of quantity is its own type. A value is kept in the base unit of its kind and never rounded. It prints in the largest unit in which the number is at least 1, with at most three decimals: 1.5Gbps, 250ms, and 90s prints as 1.5min. A power always prints in dBm and a gain in dB. .to("kbps") gives the plain number in a unit of your choice.

Type Base unit Units
Rate bps bps, kbps, Mbps, Gbps
Duration s ms, s, min, h, d
Distance m m, km, ft, mi (shown in m or km)
Power dBm dBm, dBW, mW, W (shown in dBm; mW and W must be above zero)
Gain dB dB, dBi (the same number)
Frequency Hz Hz, kHz, MHz, GHz
Wavelength nm nm
Size B B, kB, MB, GB, KiB, MiB, GiB (shown in B to GB)
Percent pct pct; values below 0 and above 100 are allowed; .fraction gives 0.05 for 5pct
Traffic erl erl
PacketRate pps pps
ClockTime time"HH:MM", 00:00 to 23:59

What may be added to what

Operation Result
Rate + Rate, Rate - Rate Rate. Prefixes are handled: 1Gbps + 500Mbps is 1.5Gbps
The same for Duration, Distance, Size, Frequency, Wavelength, Percent, Traffic, PacketRate The same kind
Rate * Duration, Duration * Rate Size
Size / Duration Rate. Bits and bytes differ by 8: 100MB / 10s is 80Mbps
Size / Rate Duration
A quantity / a quantity of the same kind float
A quantity * or / a plain number The same kind
Power - Power Gain
Power + Gain, Power - Gain, Gain + Power Power
Gain + Gain, Gain - Gain Gain
Power + Power Refused. Use combine(a, b), which adds them in milliwatts
freq.wavelength, wl.frequency A Wavelength from a Frequency, and back. Never by itself
<, >, <=, >= Between two values of the same kind only
Anything else Refused before the program runs
Bogolang
print(1Gbps + 500Mbps, 100MB / 10s, 20Mbps * 1min, 1GB / 100Mbps)
print(-18.5dBm - -21dBm, -18.5dBm + 3dB, combine(-10dBm, -10dBm))
print(12.4km / 2, 12.4km / 3.1km, 90s, 20Mbps.to("kbps"), 2W)

This prints:

1.5Gbps 80Mbps 150MB 1.333min
2.5dB -15.5dBm -6.99dBm
6.2km 4.0 1.5min 20000.0 33.01dBm

ClockTime values compare with each other (time"02:00" < time"04:00") and are used in only between (language.md).

What the check refuses

A wrong literal is found when the file is read, with the literal underlined. Each message below is what the check printed.

Written Message
192.0.2.256 '192.0.2.256' is not a valid IP address: Octet 256 (> 255) not permitted in '192.0.2.256'
ip"192.0.2.5/24" '192.0.2.5/24' is not a subnet: the host part is not zero. It belongs to 192.0.2.0/24. Write 192.0.2.0/24, or use IfAddr for an interface address.
20Mbs "Mbs" is not a known unit, with the hint Did you mean 20Mbps?
vlan"0-10" VLAN 0 in '0-10' is out of range. VLAN numbers are 1 to 4094.
vlan"20-10" the range 20-10 in '20-10' is reversed. Write 10-20.
mac"001a.2b3c.4d5" '001a.2b3c.4d5' is not a MAC address. It has 11 hex digits, a MAC has 12. Write it as 00:1a:2b:3c:4d:5e, 00-1A-2B-3C-4D-5E or 001a.2b3c.4d5e.
intf"1/0/1" '1/0/1' is not an interface name. Write a kind then numbers, such as Gi1/0/24 or Vlan10.
time"25:00" time must be HH:MM from 00:00 to 23:59, got '25:00'

A wrong sum is found by the type check:

Written Message
20Mbps + -18.5dBm cannot use + between Rate and Power
-10dBm + -12dBm cannot use + between Power and Power, with the hint Use combine(a, b) to add two power levels.
20Mbps < 5s cannot use < between Rate and Duration
1550nm + 5GHz cannot use + between Wavelength and Frequency
192.0.2.1 + 1.5 cannot use + between IP and float
20Mbps * 20Mbps No overload variant of "__mul__" of "Rate" matches argument type "Rate", with the forms that are allowed

The check runs before the program, so these lines never run. Where no check runs, as in bogo shell or on a value from an Untyped object, the types refuse the wrong kind themselves when the line runs, with a TypeError of the same words, such as cannot use + between Rate and Size.

Limits

  • == between two different kinds is not refused before the run. It is False: 20Mbps == 5s is False.
  • A literal inside the {} of an f-string is not recognised. Put the value in a variable first.
  • For an unknown unit the nearest known one is proposed: first the same letters in another case (5Kbps gets Did you mean 5kbps?), then the nearest spelling.
  • A file that defines its own class named Net, Power or another built-in type cannot also write the matching literal.