py-xbc/README.md

py-xbc

py-xbc is a pure-Python library for reading and writing files in the eXtra BootConfig (XBC) file format specified by the Linux kernel. This is not a strictly-conforming implementation: in particular, this implementation does not enforce the 32,767-byte ceiling on XBC files, nor does it enforce the 16-level cap on keys and blocks.

Requirements

py-xbc currently requires pyparsing and Python 3.7+.

Usage

py-xbc exports four functions:

• loads_xbc parses a string.
• load_xbc opens a file and then parses a string.
• saves_xbc renders to a string.
• save_xbc renders to a string and writes the string to a file.

Format

XBC files consist of a series of statements, of which there are three kinds:

• A key is a sequence of one or more bytes in the range a-zA-Z0-9_-. They are namespaced with periods (.) and may be followed by an equals sign (=). Key statements are terminated by a semicolon (;), a linefeed, or a semicolon followed by a linefeed.

• A key/value statement is a key followed by an operator, followed in turn by one or more values. There are three operators:

  • Assignment (=) specifies an initial value.
  • Updates (:=) overwrites whatever value was previously there.
  • Appends (+=) appends one or more values.

  There are two kinds of values: strings and arrays. Strings can be either 'bare' or quoted.

  • Bare strings are a sequence of one or more bytes that are not in the range {}#=+:;,\n'" .
  • Quoted strings are a sequence of bytes that begins with a single quote (') or a double quote (") and ends only with the same quote. Quotes cannot be escaped.
  • Arrays are a sequence of one or more values delimited by a comma (,).

• A block is a key followed by a pair of curly braces, inside which is one or more key or key/value statements.

Keys are composable. The following examples are equivalent:

foo {
	bar {
		fluff = 1
	}
}
# is equivalent to
foo.bar.fluff = 1
# is equivalent to
foo.bar { fluff = 1 }
# is equivalent to
foo { bar.fluff = 1 }

Licence

py-xbc is published under the MIT license. See LICENSE for more information.