Custom type

Objectives

In this sections we are going to learn how to create custom types. In short, a custom type is nothing more than a kind of family template.

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 tags v1.1_080 to v1.1_081 in the repository.

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

HTTP Proxy with “proxy” type

Let’s look now at the possibilities for adding types. This feature is essential for having a truly adaptable tool.

Note

It is actually possible to add types, but that involves adding predefined types to the tiramisu underlying consistency library itself, and that’s a different matter altogether. There is a simpler way to do this.

More simply, it’s possible in Rougail to create custom types, much like defining families.

Our folder structure will be expanded a bit:

.
├── firefox
│   ├── 00-proxy.yml
│   ├── 10-manual.yml
│   └── 20-manual.yml
└── types
    └── proxy
        └── 00_type.yml

Notice that we have now a new types folder in our tree structure. This is where we place our new proxy type definition.

In accordance with our naming policy, we have created a file named 00_type.yml inside the proxy folder. Let’s examine this more closely this types/proxy/00_type.yml type definition file:

The types/proxy/00_type.yml type structure file that defines our new proxy type.

%YAML 1.2
---
version: 1.1

proxy:

  address:
    description: Proxy address
    type: domainname
    params:
      allow_ip: true
    default:
      variable: __.http_proxy.address

  port:
    description: Proxy port
    type: port
    default:
      variable: __.http_proxy.port
...

The new type named proxy is declared. It’s more or less like a family declaration except it will be used as a type definition.

How do we use a new type?

Very simply. In the usual way: we will use the type parameter.

Here, we will declare that a family is of type proxy as follows:

The firefox/10-manual.yml structure file with less code due to the proxy type definition

%YAML 1.2
---
version: 1.1

manual:
  description: Manual proxy configuration
  disabled:
    variable: _.proxy_mode
    when_not: Manual proxy configuration

  http_proxy:
    description: HTTP Proxy
    type: proxy

    address:
      default: null

    port:
      default: 8080
...

We can see that the type declared for the http_proxy family is type: proxy. Very simple. For example in the address it is not necessary to specify the domainname type nor the allow_ip parameter:

We can omit this now due to the type definition

   description: HTTP address
           type: domainname
           params:
             allow_ip: true

So we have declared our new type. How do we make it available? Well, the Rougail CLI has a --types type declaration command line option. Let’s launch the rougail CLI:

rougail -m firefox/ --types types/proxy -u yaml -yf config/01/config.yml

The CLI output is entirely standard and does not specifically mention the call to a new type. The result is the same as usual, as if the type declaration were omitted, which is what we want. We want the same behavior.

╭────────────── Caption ───────────────╮
│ Variable Default value               │
│          Modified value              │
│          (⏳ Original default value) │
╰──────────────────────────────────────╯
Variables:
┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Manual proxy 
┃   configuration ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
┃   proxy)
┗━━ 📂 manual (Manual proxy configuration)
    ┣━━ 📂 http_proxy (HTTP Proxy)
    ┃   ┣━━ 📓 address (Proxy address): http.proxy.net ◀ loaded from the YAML 
    ┃   ┃   file "config/01/config.yml"
    ┃   ┗━━ 📓 port (Proxy port): 3128 ◀ loaded from the YAML file 
    ┃       "config/01/config.yml" (⏳ 8080)
    ┣━━ 📓 use_for_https (Also use this proxy for HTTPS): false ◀ loaded from 
    ┃   the YAML file "config/01/config.yml" (⏳ true)
    ┣━━ 📂 https_proxy (HTTPS Proxy)
    ┃   ┣━━ 📓 address (HTTPS address): https.proxy.net ◀ loaded from the YAML 
    ┃   ┃   file "config/01/config.yml" (⏳ http.proxy.net)
    ┃   ┗━━ 📓 port (HTTPS port): 3128
    ┗━━ 📂 socks_proxy (SOCKS Proxy)
        ┣━━ 📓 address (SOCKS address): http.proxy.net
        ┣━━ 📓 port (SOCKS port): 3128
        ┗━━ 📓 version (SOCKS host version used by proxy): v5

Key points

type declaration
type usage