Groups

A Quickonf configuration file is composed of multiple sections, called groups. The group name starts at the beginning of the line, instructions are indented.

group name
  instruction A
  instruction B
  ...
  instruction G
    instruction H depending on instruction G
    instruction I depending on instruction G

Indentations length and type (spaces or tabs) is not strict, you may use whichever you want. Keep in mind that, when mixing indentations, tabs are considered to be equivalent to aligning to multiples of 8 spaces (ie. <space><space><tab> is equivalent to 8 spaces).

Some instructions have an impact on multiple other instructions, like conditional execution (if) or repetition (repeat), in this case you must use a 2nd indentation level (or even more). See below for examples.

Commands

The most important type of instruction is the commands. There are many available commands, and probably many more to come. A command is the instruction given to Quickonf for system checking and modification. The commands may need arguments and may return output values (see Variables below). See the Commands section for details on how to use commands.

By convention, commands modifying data only for one user are prefixed with “user.” and take the username as their first argument. Other commands modify system-wide values.

Variables

Some commands return output values, that can be stored in variables if needed. Variables are named with alphanumerical characters. Syntax to store values is the following:

group name
  var1 var2 = command arg1 arg2

Using variables after assignment is as simple as putting the variable name between “<” and “>” anywhere, like:

group name
  var = command1 arg1 arg2
  command2 <var>

… here, the first output of the first command is used as the argument of the second command.

Except for the following global ones, variables are limited to their groups: there is no risk of conflict between variables in different groups.

Global variables

Some global variables are set when Quickonf starts:

Expanding variables content

Sometimes, a variable’s content refers to other variables. Take for instance a file that contains variables names. If you read the file with the file.read command, it may be stored in a variable, but the content of the read file is not processed for variables names. In order to process variables names references inside a variable content, simply use the expand instruction with the variable name as its only argument.

Example:

APT sources
  aptsrc = file.read <confdir>/sources.list.tmpl
  expand aptsrc
  file.content /etc/apt/sources.list <aptsrc>

… here, the sources.list.tmpl file may contain <oscodename>.

Conditional execution

Instructions can be grouped below a if instruction, which executes then only if the condition is true.

Supported conditions are:

Example:

VPN
  if <hostname> = mylaptop
    nm.import openvpn <confdir>/myvpn.ovpn

… here, the nm.import openvpn <confdir>/myvpn.ovpn is only executed if the host name is “mylaptop”. You may of course put multiple instructions with the 2nd indentation level.

Repeating identical commands and arguments

Say you want to apply similar commands multiple times. Instead of writing the same prefix in multiple lines, you can use the repeat instruction. It makes it easier to write and to read your configuration file. It takes as arguments the command to be repeated, optionally with its first arguments.

Quickonf translates it by prepending this command name and these arguments to all lines.

Example:

Wifi
  repeat nm.wifi
    ssid1 psk1
    ssid2 psk2
    ssid3 psk3

My XDG dirs
  repeat user.xdg.userdir alice
    desktop DESKtop
    documents MyDocs
    download UglyStuff

… translates internally to:

Wifi
  nm.wifi ssid1 psk1
  nm.wifi ssid2 psk2
  nm.wifi ssid3 psk3

My XDG dirs
  user.xdg.userdir alice desktop DESKtop
  user.xdg.userdir alice documents MyDocs
  user.xdg.userdir alice download UglyStuff

Priority

Some instructions may need to be executed before other ones, when executing all instructions. For instance, changing the packages sources or adding an installer like snap or flatpak. For that specific case, You may use the priority instruction, which takes an integer as an arguments. The default priority is 0, and larger value means higher priority.

If you use the priority instruction in a conditional block, it impacts the whole group (meaning you may give different priorities depending on conditions).

Keep in mind that it only impacts the order of execution and display in the interface. You still can manually apply instructions of lower priority before instructions of higher priority.

For instance:

Flatpak
  priority 1
  apt.install flatpak

Recipes

In order to keep the configuration simple, some common groups may be defined in cookbooks, available locally on your filesystem or online.

The cookbook instruction, used at the root level of your configuration file (the same place where you usually put groups names), allows defining custom local files or HTTP/HTTPs URLS where to read recipes.

The recipe instruction executes a recipe. It may read existing variables, or specific variables for the recipe may be defined on the 2nd indentation level.

For instance:

cookbook <confdir>/myrecipes.qconf

Apply it
  recipe My wonderful recipe
    package = my-beloved-package

Writing cookbooks

A cookbook may be written as any Quickonf configuration file, it is based on the very same language.

The specificities are the following:

For instance (this cookbook file example matches the cookbook/recipe example above):

My wonderful recipe
  apt.install <package>

Multi-level indentation

You may use multiple level indentation, if needed by the instructions you want to use.

Example:

Wifi
  nm.wifi home homessid
  if <hostname> = worklaptop
    repeat nm.wifi
      worknetwork workssid
      mobilenetwork mobilessid

… here, the “home” network will be known by all computers, but “worknetwork” and “mobilenetwork” are only known by your work laptop.