2025-11-04 19:22:03 +01:00
- [Summary ](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md )
2025-11-04 19:22:14 +01:00
- [[tutorial v1.1_026] A disabled family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_026/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_026~1..v1.1_026))
2025-11-04 19:22:03 +01:00
2025-11-04 19:22:14 +01:00
# [tutorial v1.1_027)] A conditional disabled family with a variable
2025-11-04 19:22:03 +01:00
2025-11-04 19:22:14 +01:00
[View the diff ](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_027~1..v1.1_027 )
2025-11-04 19:22:03 +01:00
2025-11-04 19:22:02 +01:00
## Screenshot
< img src = "firefox.png" width = 50% height = 50% alt = "Firefox Proxy setting" / >
## Structure
2025-11-04 19:22:03 +01:00
### firefox/00-proxy.yml
```yml
%YAML 1.2
---
version: 1.1
2025-11-04 19:22:04 +01:00
2025-11-04 19:22:06 +01:00
proxy_mode:
description: Configure Proxy Access to the Internet
choices:
- No proxy
- Auto-detect proxy settings for this network
- Use system proxy settings
- Manual proxy configuration
- Automatic proxy configuration URL
default: No proxy
2025-11-04 19:22:03 +01:00
...
```
2025-11-04 19:22:07 +01:00
### firefox/10-manual.yml
2025-11-04 19:22:04 +01:00
```yml
2025-11-04 19:22:07 +01:00
%YAML 1.2
2025-11-04 19:22:04 +01:00
---
2025-11-04 19:22:07 +01:00
version: 1.1
2025-11-04 19:22:04 +01:00
2025-11-04 19:22:13 +01:00
manual:
description: Manual proxy configuration
2025-11-04 19:22:14 +01:00
disabled:
variable: _.proxy_mode
when_not: Manual proxy configuration
2025-11-04 19:22:08 +01:00
2025-11-04 19:22:09 +01:00
http_proxy: # HTTP Proxy
2025-11-04 19:22:10 +01:00
address:
description: HTTP address
type: domainname
2025-11-04 19:22:11 +01:00
params:
allow_ip: true
2025-11-04 19:22:12 +01:00
port:
description: HTTP Port
type: port
default: 8080
2025-11-04 19:22:07 +01:00
...
2025-11-04 19:22:04 +01:00
```
2025-11-04 19:22:07 +01:00
### Let's generate the documentation
2025-11-04 19:22:04 +01:00
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:07 +01:00
foo@bar:~$ rougail -m firefox/ -o doc -do github
2025-11-04 19:22:04 +01:00
```
2025-11-04 19:22:07 +01:00
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **proxy_mode** < br /> [`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | Configure Proxy Access to the Internet.< br /> **Choices**: < br /> - No proxy ** ← (default)**< br /> - Auto-detect proxy settings for this network< br /> - Use system proxy settings< br /> - Manual proxy configuration< br /> - Automatic proxy configuration URL |
2025-11-04 19:22:04 +01:00
2025-11-04 19:22:14 +01:00
#### Manual proxy configuration
**manual**
*`disabled`*
**Disabled**: when the variable "proxy_mode" hasn't the value "Manual proxy configuration"
##### HTTP Proxy
**manual.http_proxy**
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual.http_proxy.address** < br /> [`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP address.< br /> **Validator**: the domain name can be an IP |
| **manual.http_proxy.port** < br /> [`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP Port.< br /> **Validators**: < br /> - well-known ports (1 to 1023) are allowed< br /> - registred ports (1024 to 49151) are allowed< br /> - private ports (greater than 49152) are allowed< br /> **Default**: 8080 |
2025-11-04 19:22:09 +01:00
### Let's generate the changelog
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -o doc --doc.contents changelog -do github
```
2025-11-04 19:22:14 +01:00
#### New variables
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual.http_proxy.address** < br /> [`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP address.< br /> **Validator**: the domain name can be an IP |
| **manual.http_proxy.port** < br /> [`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP Port.< br /> **Validators**: < br /> - well-known ports (1 to 1023) are allowed< br /> - registred ports (1024 to 49151) are allowed< br /> - private ports (greater than 49152) are allowed< br /> **Default**: 8080 |
2025-11-04 19:22:09 +01:00
## User datas
### Example 1
#### config/01/config.yaml
```yml
---
```
#### Output
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/01/config.yaml
```
2025-11-04 19:22:13 +01:00
< pre > ╭─────── Caption ────────╮
│ Variable < span style = "color: #ffd700 " > Default value</ span > │
╰────────────────────────╯
Variables:
< span style = "color: #5c5cff " > ┗━━ </ span > 📓 Configure Proxy Access to the Internet: < span style = "color: #ffd700 " > No proxy</ span >
2025-11-04 19:22:09 +01:00
< / pre >
#### Output in read write mode
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/01/config.yaml --cli.read_write
```
2025-11-04 19:22:13 +01:00
< pre > ╭─────── Caption ────────╮
│ Variable < span style = "color: #ffd700 " > Default value</ span > │
╰────────────────────────╯
Variables:
< span style = "color: #5c5cff " > ┗━━ </ span > 📓 Configure Proxy Access to the Internet: < span style = "color: #ffd700 " > No proxy</ span >
2025-11-04 19:22:09 +01:00
< / pre >
### Example 2
#### config/02/config.yaml
```yml
---
proxy_mode: Manual proxy configuration
```
#### Output
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/02/config.yaml
```
2025-11-04 19:22:14 +01:00
< pre >< span style = "font-weight: bold; color: #ff0000 " > 🛑 ERRORS</ span >
< span style = "color: #ff0000 " > ┗━━ </ span > The following variables are mandatory but have no value:
< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > ┗━━ </ span > Manual proxy configuration
< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > ┗━━ </ span > HTTP Proxy
< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > ┗━━ </ span > HTTP address
2025-11-04 19:22:09 +01:00
< / pre >
#### Output in read write mode
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/02/config.yaml --cli.read_write
```
2025-11-04 19:22:14 +01:00
< pre >< span style = "font-weight: bold; color: #ff0000 " > 🛑 ERRORS</ span >
< span style = "color: #ff0000 " > ┗━━ </ span > The following variables are mandatory but have no value:
< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > ┗━━ </ span > Manual proxy configuration
< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > ┗━━ </ span > HTTP Proxy
< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > </ span >< span style = "color: #ff0000 " > ┗━━ </ span > HTTP address
2025-11-04 19:22:09 +01:00
< / pre >
### Example 3
#### config/03/config.yaml
```yml
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: example.net
```
#### Output
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/03/config.yaml
```
2025-11-04 19:22:14 +01:00
< pre > ╭────────────── Caption ───────────────╮
│ Variable < span style = "color: #ffd700 " > Default value</ span > │
│ Modified value │
2025-11-04 19:22:09 +01:00
│ (< span style = "color: #00aa00 " > ⏳ Original default value</ span > ) │
╰──────────────────────────────────────╯
Variables:
2025-11-04 19:22:14 +01:00
< span style = "color: #5c5cff " > ┣━━ </ span > 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yaml" (⏳ < span style = "color: #00aa00 " > No proxy</ span > )
< span style = "color: #5c5cff " > ┗━━ </ span > 📂 Manual proxy configuration
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📂 HTTP Proxy
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┣━━ </ span > 📓 HTTP address: example.net ◀ loaded from the YAML file "config/03/config.yaml"
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📓 HTTP Port: < span style = "color: #ffd700 " > 8080</ span >
2025-11-04 19:22:09 +01:00
< / pre >
#### Output in read write mode
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/03/config.yaml --cli.read_write
```
2025-11-04 19:22:14 +01:00
< pre > ╭────────────── Caption ───────────────╮
│ Variable < span style = "color: #ffd700 " > Default value</ span > │
│ Modified value │
2025-11-04 19:22:09 +01:00
│ (< span style = "color: #00aa00 " > ⏳ Original default value</ span > ) │
╰──────────────────────────────────────╯
Variables:
2025-11-04 19:22:14 +01:00
< span style = "color: #5c5cff " > ┣━━ </ span > 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yaml" (⏳ < span style = "color: #00aa00 " > No proxy</ span > )
< span style = "color: #5c5cff " > ┗━━ </ span > 📂 Manual proxy configuration
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📂 HTTP Proxy
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┣━━ </ span > 📓 HTTP address: example.net ◀ loaded from the YAML file "config/03/config.yaml"
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📓 HTTP Port: < span style = "color: #ffd700 " > 8080</ span >
2025-11-04 19:22:09 +01:00
< / pre >
### Example 4
#### config/04/config.yaml
```yml
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: example.net
port: '3128'
```
#### Output
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/04/config.yaml
```
2025-11-04 19:22:14 +01:00
< pre > ╭────────────── Caption ───────────────╮
2025-11-04 19:22:09 +01:00
│ Variable Modified value │
│ (< span style = "color: #00aa00 " > ⏳ Original default value</ span > ) │
╰──────────────────────────────────────╯
Variables:
2025-11-04 19:22:14 +01:00
< span style = "color: #5c5cff " > ┣━━ </ span > 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/04/config.yaml" (⏳ < span style = "color: #00aa00 " > No proxy</ span > )
< span style = "color: #5c5cff " > ┗━━ </ span > 📂 Manual proxy configuration
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📂 HTTP Proxy
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┣━━ </ span > 📓 HTTP address: example.net ◀ loaded from the YAML file "config/04/config.yaml"
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📓 HTTP Port: 3128 ◀ loaded from the YAML file "config/04/config.yaml" (⏳ < span style = "color: #00aa00 " > 8080</ span > )
2025-11-04 19:22:09 +01:00
< / pre >
#### Output in read write mode
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/04/config.yaml --cli.read_write
```
2025-11-04 19:22:14 +01:00
< pre > ╭────────────── Caption ───────────────╮
2025-11-04 19:22:09 +01:00
│ Variable Modified value │
│ (< span style = "color: #00aa00 " > ⏳ Original default value</ span > ) │
╰──────────────────────────────────────╯
Variables:
2025-11-04 19:22:14 +01:00
< span style = "color: #5c5cff " > ┣━━ </ span > 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/04/config.yaml" (⏳ < span style = "color: #00aa00 " > No proxy</ span > )
< span style = "color: #5c5cff " > ┗━━ </ span > 📂 Manual proxy configuration
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📂 HTTP Proxy
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┣━━ </ span > 📓 HTTP address: example.net ◀ loaded from the YAML file "config/04/config.yaml"
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📓 HTTP Port: 3128 ◀ loaded from the YAML file "config/04/config.yaml" (⏳ < span style = "color: #00aa00 " > 8080</ span > )
2025-11-04 19:22:09 +01:00
< / pre >
### Example 5
#### config/05/config.yaml
```yml
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: http.proxy.net
port: '3128'
use_for_https: false
https_proxy:
address: https.proxy.net
```
#### Output
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/05/config.yaml
```
< pre >< span style = "font-weight: bold; color: #ffff00 " > 🔔 WARNINGS</ span >
< span style = "color: #ffff00 " > ┣━━ </ span > variable or family "manual.use_for_https" does not exist, it will be ignored when loading from the YAML file "config/05/config.yaml"
< span style = "color: #ffff00 " > ┗━━ </ span > variable or family "manual.https_proxy" does not exist, it will be ignored when loading from the YAML file "config/05/config.yaml"
╭────────────── Caption ───────────────╮
│ Variable Modified value │
│ (< span style = "color: #00aa00 " > ⏳ Original default value</ span > ) │
╰──────────────────────────────────────╯
Variables:
2025-11-04 19:22:14 +01:00
< span style = "color: #5c5cff " > ┣━━ </ span > 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/05/config.yaml" (⏳ < span style = "color: #00aa00 " > No proxy</ span > )
< span style = "color: #5c5cff " > ┗━━ </ span > 📂 Manual proxy configuration
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📂 HTTP Proxy
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┣━━ </ span > 📓 HTTP address: http.proxy.net ◀ loaded from the YAML file "config/05/config.yaml"
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📓 HTTP Port: 3128 ◀ loaded from the YAML file "config/05/config.yaml" (⏳ < span style = "color: #00aa00 " > 8080</ span > )
2025-11-04 19:22:09 +01:00
< / pre >
#### Output in read write mode
```console
2025-11-04 19:22:14 +01:00
foo@bar:~$ git switch --detach v1.1_027
2025-11-04 19:22:09 +01:00
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/05/config.yaml --cli.read_write
```
< pre >< span style = "font-weight: bold; color: #ffff00 " > 🔔 WARNINGS</ span >
< span style = "color: #ffff00 " > ┣━━ </ span > variable or family "manual.use_for_https" does not exist, it will be ignored when loading from the YAML file "config/05/config.yaml"
< span style = "color: #ffff00 " > ┗━━ </ span > variable or family "manual.https_proxy" does not exist, it will be ignored when loading from the YAML file "config/05/config.yaml"
╭────────────── Caption ───────────────╮
│ Variable Modified value │
│ (< span style = "color: #00aa00 " > ⏳ Original default value</ span > ) │
╰──────────────────────────────────────╯
Variables:
2025-11-04 19:22:14 +01:00
< span style = "color: #5c5cff " > ┣━━ </ span > 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/05/config.yaml" (⏳ < span style = "color: #00aa00 " > No proxy</ span > )
< span style = "color: #5c5cff " > ┗━━ </ span > 📂 Manual proxy configuration
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📂 HTTP Proxy
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┣━━ </ span > 📓 HTTP address: http.proxy.net ◀ loaded from the YAML file "config/05/config.yaml"
< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > </ span >< span style = "color: #5c5cff " > ┗━━ </ span > 📓 HTTP Port: 3128 ◀ loaded from the YAML file "config/05/config.yaml" (⏳ < span style = "color: #00aa00 " > 8080</ span > )
2025-11-04 19:22:09 +01:00
< / pre >
2025-11-04 19:22:04 +01:00
2025-11-04 19:22:14 +01:00
- [[tutorial v1.1_030] A variable with type "boolean"](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_030/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_030~1..v1.1_030))