Modes

Objectives

For information on the concept we will be using in this section, please refer to the definition of the mode in the documentation, and you can read all the description of the modes in the structuring data point of view.

Prerequisites

We assume that Rougail’s library is installed on your computer.
It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step by checking out the corresponding tag of the rougail-tutorials git repository. Each tag corresponds to a stage of progress in the tutorial. Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.

If you want to follow this tutorial with the help of the corresponding rougail-tutorials git repository, this workshop page corresponds to the tag v1.1_150 in the repository.

git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
git switch --detach v1.1_150

A variable in avanced mode

To specify the various possible modes, we must declare them on the command line with the --modes_level command line option:

rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/01/config.yml

Next, we can set a mode parameter with a value from the list: basic, standard, advanced.

The proxy_dns_socks5 variable in the firefox/55-proxy_dns_socks5.yml file

%YAML 1.2
---
version: 1.1

proxy_dns_socks5:
  description: Use proxy DNS when using SOCKS v5
  mode: advanced
  default: false
  disabled:
    jinja: |-
      {{ _.manual.socks_proxy.version is propertyerror or _.manual.socks_proxy.version == 'v4' }}
    return_type: boolean
    description: |-
      if "_.manual.socks_proxy.version" is accessible and equals "v4"
...

Here, we have set the mode to advanced for the proxy_dns_socks5 variable because we want to classify it as a variable intended for use by advanced users.

What is it actually used for?

Well, to begin with, reading the structure file provides a clear piece of information: this variable is intended to be manipulated by an experienced user.

Furthermore, if you integrate Rougail as a library into your business applications, you will have access to different types of views corresponding to each mode.

A useful application within Rougail itself involves filtering the display of certain variables when generating documentation, based on the mode.

In our case, this makes it possible to generate documentation for standard users where the proxy_dns_socks5 won’t be present, and a different, more detailed documentation for advanced users where the proxy_dns_socks5 will be explained in detail.