Skip to content
This repository has been archived by the owner on Apr 20, 2024. It is now read-only.

Commit

Permalink
Convert grammars to EBNF, for better or worse
Browse files Browse the repository at this point in the history 
Affects: #24
  • Loading branch information
@io7m
io7m committed Jul 19, 2020
1 parent 6c0f426 commit ec25eb3
Show file tree
Hide file tree
Showing 7 changed files with 111 additions and 100 deletions.
52 changes: 26 additions & 26 deletions com.io7m.waxmill.cmdline/src/main/resources/com/io7m/waxmill/cmdline/internal/Messages.xml
View file
Expand Up @@ -5,13 +5,13 @@
<properties>

<entry key="ttyBackendSpec"><![CDATA[
TTY backend syntax:
"stdio" ";" <port>
| "file" ";" <port> ";" <path>
| "nmdm" ";" <port>
EBNF syntax for TTY backends:
Where:
<port> = "com1" | "com2" | "bootrom"
port = "com1" | "com2" | "bootrom" ;
stdioBackend = "stdio" , ";" , port ;
fileBackend = "file" , ";" , port , ";" , path ;
nmdmBackend = "nmdm" , ";" , port ;
ttyBackend = stdioBackend | fileBackend | nmdmBackend ;
Examples:
stdio;com1
Expand All @@ -20,14 +20,13 @@ Examples:
]]></entry>

<entry key="storageBackendSpec"><![CDATA[
Storage backend syntax:
"file" ";" <path>
| "zfs-volume"
| "zfs-volume" ";" <size>
EBNF syntax for storage backends:
Where:
<path> = Any UNIX-like path
<size> = Any non-negative multiple of 128000 (bytes)
path = ? Any UNIX-like path ? ;
size = ? Any non-negative multiple of 128000 (bytes) ? ;
fileBackend = "file" , ";" , path ;
zfsBackend = "zfs-volume" , [ ";" , size ] ;
storageBackend = fileBackend | zfsBackend ;
Examples:
file;/tmp/xyz
Expand All @@ -36,14 +35,16 @@ Examples:
]]></entry>

<entry key="networkBackendSpec"><![CDATA[
Virtio network backend syntax:
"tap" ";" <tapDevice> ";" <macAddress>
| "vmnet" ";" <vmnetDevice> ";" <macAddress>
EBNF syntax for Virtio network backends:
Where:
<tapDevice> = "tap[0-9]'{'1,13'}'"
<vmnetDevice> = "vmnet[0-9]'{'1,11'}'"
<macAddress> = "[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}'"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
hexDigit = "a" | "b" | "c" | "d" | "e" | "f" ;
macPart = hexDigit , hexDigit ;
macAddress = macPart , ":" , macPart , ":" , macPart , ":" , macPart , ":" , macPart , ":" , macPart ;
tapDeviceName = "tap" , '{' digit '}' ;
vmnetDeviceName = "vmnet" , '{' digit '}' ;
tapDevice = "tap" , ";" , tapDeviceName , ";" , macAddress ;
vmnetDevice = "vmnet" , ";" , vmnetDeviceName , ";" , macAddress ;
Examples:
tap;tap23;d9:63:c0:d9:09:e8
Expand All @@ -53,13 +54,12 @@ Examples:
]]></entry>

<entry key="deviceSlotSpec"><![CDATA[
Device slot syntax:
<deviceSlot> = <bus> ":" <slot> ":" <function>
EBNF syntax for device slots:
Where:
<bus> = [0 .. 255]
<slot> = [0 .. 31]
<function> = [0 .. 7]
bus = ? [0 .. 255] ? ;
slot = ? [0 .. 31] ? ;
function = ? [0 .. 7] ? ;
deviceSlot = bus , ":" , slot , ":" , function ;
Examples:
0:0:0
Expand Down
11 changes: 5 additions & 6 deletions ...axmill.documentation/src/main/resources/com/io7m/waxmill/documentation/address-syntax.txt
View file
@@ -1,9 +1,8 @@
<ipv4> | <ipv6> | <name>

Where:
<name> = Any valid domain/host name
<ipv4> = Any valid IPv4 address
<ipv6> = Any valid IPv6 address
ipv4Part = ? [0 .. 255]{1,3} ? ;
ipv4 = ipv4Part , ".", ipv4Part , "." , ipv4Part , "." , ipv4Part , ;
ipv6 = ? Any https://tools.ietf.org/html/rfc4291 IPv6 address ? ;
name = ? Any host name ? ;
address = ipv4 | ipv6 | name ;

Examples:
127.0.0.1
Expand Down
95 changes: 55 additions & 40 deletions com.io7m.waxmill.documentation/src/main/resources/com/io7m/waxmill/documentation/cmdline.xml
View file
Expand Up @@ -6,46 +6,61 @@
tableOfContentsDepth="1">

<Section title="Overview">
<Paragraph>
The <Term type="package">waxmill</Term> package provides a command-line interface and API
for creating, configuring, and running <LinkExternal target="https://www.bhyve.org">bhyve</LinkExternal>
virtual machines. The base <Term type="command">waxmill</Term> command is broken into a number of subcommands
which are documented over the following sections.
</Paragraph>
<FormalItem title="Command-Line Overview">
<Verbatim>
<xi:include parse="text"
href="usage.txt"/>
</Verbatim>
</FormalItem>
<Paragraph>
All subcommands accept a <Term type="parameter">--verbose</Term> parameter that may be set to one of
<Term type="constant">trace</Term>, <Term type="constant">debug</Term>, <Term type="constant">info</Term>,
<Term type="constant">warn</Term>, or <Term type="constant">error</Term>. This parameter sets the lower bound for
the severity of messages that will be logged. For example, at <Term type="constant">debug</Term> verbosity, only
messages of severity <Term type="constant">debug</Term> and above will be logged. Setting the verbosity to
<Term type="constant">trace</Term>
level effectively causes everything to be logged, and will produce large volumes of debugging output.
</Paragraph>
<FormalItem title="Log Levels">
<xi:include href="verbosity.xml"/>
</FormalItem>
<Paragraph>
The <Term type="package">waxmill</Term> command-line tool uses <LinkExternal target="https://jcommander.org/">
jcommander
</LinkExternal> to parse command-line arguments, and therefore supports placing command-line arguments into a file,
one argument per line, and then referencing that file with <Term type="constant">@</Term>. For example:
</Paragraph>
<FormalItem title="@ Syntax">
<Verbatim>
<xi:include parse="text"
href="at-syntax.txt"/>
</Verbatim>
</FormalItem>
<Paragraph>
All subcommands, unless otherwise specified, yield an exit code of <Term type="constant">0</Term> on success, and
a non-zero exit code on failure.
</Paragraph>
<Subsection title="Usage">
<Paragraph>
The <Term type="package">waxmill</Term> package provides a command-line interface and API
for creating, configuring, and running <LinkExternal target="https://www.bhyve.org">bhyve</LinkExternal>
virtual machines. The base <Term type="command">waxmill</Term> command is broken into a number of subcommands
which are documented over the following sections.
</Paragraph>
<FormalItem title="Command-Line Overview">
<Verbatim>
<xi:include parse="text"
href="usage.txt"/>
</Verbatim>
</FormalItem>
</Subsection>
<Subsection title="Verbosity">
<Paragraph>
All subcommands accept a <Term type="parameter">--verbose</Term> parameter that may be set to one of
<Term type="constant">trace</Term>, <Term type="constant">debug</Term>, <Term type="constant">info</Term>,
<Term type="constant">warn</Term>, or <Term type="constant">error</Term>. This parameter sets the lower bound for
the severity of messages that will be logged. For example, at <Term type="constant">debug</Term> verbosity, only
messages of severity <Term type="constant">debug</Term> and above will be logged. Setting the verbosity to
<Term type="constant">trace</Term>
level effectively causes everything to be logged, and will produce large volumes of debugging output.
</Paragraph>
<FormalItem title="Log Levels">
<xi:include href="verbosity.xml"/>
</FormalItem>
</Subsection>
<Subsection title="@ Syntax">
<Paragraph>
The <Term type="package">waxmill</Term> command-line tool uses <LinkExternal target="https://jcommander.org/">
jcommander
</LinkExternal> to parse command-line arguments, and therefore supports placing command-line arguments into a file,
one argument per line, and then referencing that file with <Term type="constant">@</Term>. For example:
</Paragraph>
<FormalItem title="@ Syntax">
<Verbatim>
<xi:include parse="text"
href="at-syntax.txt"/>
</Verbatim>
</FormalItem>
</Subsection>
<Subsection title="Exit Code">
<Paragraph>
All subcommands, unless otherwise specified, yield an exit code of <Term type="constant">0</Term> on success, and
a non-zero exit code on failure.
</Paragraph>
</Subsection>
<Subsection title="EBNF">
<Paragraph>
The specification gives grammar definitions in
<LinkExternal target="https://en.wikipedia.org/wiki/ISO_14977">ISO/IEC 14977:1996 Extended Backus-Naur</LinkExternal>
form.
</Paragraph>
</Subsection>
</Section>

<xi:include href="cmdline-help.xml" />
Expand Down
10 changes: 4 additions & 6 deletions ...ll.documentation/src/main/resources/com/io7m/waxmill/documentation/device-slot-syntax.txt
View file
@@ -1,9 +1,7 @@
<deviceSlot> = <bus> ":" <slot> ":" <function>

Where:
<bus> = [0 .. 255]
<slot> = [0 .. 31]
<function> = [0 .. 7]
bus = ? [0 .. 255] ? ;
slot = ? [0 .. 31] ? ;
function = ? [0 .. 7] ? ;
deviceSlot = bus , ":" , slot , ":" , function ;

Examples:
0:0:0
Expand Down
14 changes: 7 additions & 7 deletions ...7m.waxmill.documentation/src/main/resources/com/io7m/waxmill/documentation/lpc-syntax.txt
View file
@@ -1,11 +1,11 @@
"stdio" ";" <port>
| "file" ";" <port> ";" <path>
| "nmdm" ";" <port>

Where:
<port> = "com1" | "com2" | "bootrom"
path = ? Any unix-like path ? ;
port = "com1" | "com2" | "bootrom" ;
stdioBackend = "stdio" , ";" , port ;
fileBackend = "file" , ";" , port , ";" , path ;
nmdmBackend = "nmdm" , ";" , port ;
ttyBackend = stdioBackend | fileBackend | nmdmBackend ;

Examples:
stdio;com1
file;bootrom;/tmp/xyz
nmdm;com2
nmdm;com2
17 changes: 9 additions & 8 deletions ...ocumentation/src/main/resources/com/io7m/waxmill/documentation/network-backend-syntax.txt
View file
@@ -1,13 +1,14 @@
"tap" ";" <tapDevice> ";" <macAddress>
| "vmnet" ";" <vmnetDevice> ";" <macAddress>

Where:
<tapDevice> = "tap[0-9]'{'1,13'}'"
<vmnetDevice> = "vmnet[0-9]'{'1,11'}'"
<macAddress> = "[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}':[a-f0-9]'{'2'}'"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
hexDigit = "a" | "b" | "c" | "d" | "e" | "f" ;
macPart = hexDigit , hexDigit ;
macAddress = macPart , ":" , macPart , ":" , macPart , ":" , macPart , ":" , macPart , ":" , macPart ;
tapDeviceName = "tap" , { digit } ;
vmnetDeviceName = "vmnet" , { digit } ;
tapDevice = "tap" , ";" , tapDeviceName , ";" , macAddress ;
vmnetDevice = "vmnet" , ";" , vmnetDeviceName , ";" , macAddress ;

Examples:
tap;tap23;d9:63:c0:d9:09:e8
tap;tap0000000000001;d9:63:c0:d9:09:e8
vmnet;vmnet23;d9:63:c0:d9:09:e8
vmnet;vmnet00000000001;d9:63:c0:d9:09:e8
vmnet;vmnet00000000001;d9:63:c0:d9:09:e8
12 changes: 5 additions & 7 deletions ...ocumentation/src/main/resources/com/io7m/waxmill/documentation/storage-backend-syntax.txt
View file
@@ -1,10 +1,8 @@
"file" ";" <path>
| "zfs-volume"
| "zfs-volume" ";" <size>

Where:
<path> = Any UNIX-like path
<size> = Any non-negative multiple of 128000 (bytes)
path = ? Any UNIX-like path ? ;
size = ? Any non-negative multiple of 128000 (bytes) ? ;
fileBackend = "file" , ";" , path ;
zfsBackend = "zfs-volume" , [ ";" , size ] ;
storageBackend = fileBackend | zfsBackend ;

Examples:
file;/tmp/xyz
Expand Down

0 comments on commit ec25eb3

Please sign in to comment.