- [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md)
- [[tutorial v1.1_032] An hidden family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_032/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_032~1..v1.1_032))
# [tutorial v1.1_033)] A conditional hidden family with a variable
[View the diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_033~1..v1.1_033)
## Screenshot
## Structure
### firefox/00-proxy.yml
```yml
%YAML 1.2
---
version: 1.1
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
...
```
### firefox/10-manual.yml
```yml
%YAML 1.2
---
version: 1.1
manual:
description: Manual proxy configuration
disabled:
variable: _.proxy_mode
when_not: Manual proxy configuration
http_proxy: # HTTP Proxy
address:
description: HTTP address
type: domainname
params:
allow_ip: true
port:
description: HTTP Port
type: port
default: 8080
...
```
### firefox/20-manual.yml
```yml
%YAML 1.2
---
version: 1.1
manual:
use_for_https: true # Also use this proxy for HTTPS
https_proxy:
description: HTTPS Proxy
hidden:
variable: _.use_for_https
address:
description: HTTPS address
type: domainname
params:
allow_ip: true
port:
description: HTTPS Port
type: port
default: 8080
...
```
### Let's generate the documentation
```console
foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -o doc -do github
```
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **proxy_mode**
[`choice`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | Configure Proxy Access to the Internet.
**Choices**:
- No proxy **← (default)**
- Auto-detect proxy settings for this network
- Use system proxy settings
- Manual proxy configuration
- Automatic proxy configuration URL |
#### 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**
[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP address.
**Validator**: the domain name can be an IP |
| **manual.http_proxy.port**
[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTP Port.
**Validators**:
- well-known ports (1 to 1023) are allowed
- registred ports (1024 to 49151) are allowed
- private ports (greater than 49152) are allowed
**Default**: 8080 |
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual.use_for_https**
[`boolean`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | Also use this proxy for HTTPS.
**Default**: true |
##### HTTPS Proxy
**manual.https_proxy**
*`hidden`*
**Hidden**: when the variable "manual.use_for_https" has the value "true"
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual.https_proxy.address**
[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTPS address.
**Validator**: the domain name can be an IP |
| **manual.https_proxy.port**
[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTPS Port.
**Validators**:
- well-known ports (1 to 1023) are allowed
- registred ports (1024 to 49151) are allowed
- private ports (greater than 49152) are allowed
**Default**: 8080 |
### Let's generate the changelog
```console
foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -o doc --doc.contents changelog -do github
```
#### New variables
| Variable | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual.https_proxy.address**
[`domainname`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTPS address.
**Validator**: the domain name can be an IP |
| **manual.https_proxy.port**
[`port`](https://rougail.readthedocs.io/en/latest/variable.html#variables-types) `mandatory` | HTTPS Port.
**Validators**:
- well-known ports (1 to 1023) are allowed
- registred ports (1024 to 49151) are allowed
- private ports (greater than 49152) are allowed
**Default**: 8080 |
## User datas
### Example 1
#### config/01/config.yaml
```yml
---
```
#### Output
```console
foo@bar:~$ git switch --detach v1.1_033
foo@bar:~$ rougail -m firefox/ -u yaml -ff config/01/config.yaml
```
╭─────── Caption ────────╮ │ Variable Default value │ ╰────────────────────────╯ Variables: ┗━━ 📓 Configure Proxy Access to the Internet: No proxy### Example 2 #### config/02/config.yaml ```yml --- proxy_mode: No proxy ``` #### Output ```console foo@bar:~$ git switch --detach v1.1_033 foo@bar:~$ rougail -m firefox/ -u yaml -ff config/02/config.yaml ```
╭────────────── Caption ───────────────╮ │ Variable Modified value │ │ (⏳ Original default value) │ ╰──────────────────────────────────────╯ Variables: ┗━━ 📓 Configure Proxy Access to the Internet: No proxy ◀ loaded from the YAML file "config/02/config.yaml" (⏳ No proxy)### Example 3 #### config/03/config.yaml ```yml --- proxy_mode: Manual proxy configuration ``` #### Output ```console foo@bar:~$ git switch --detach v1.1_033 foo@bar:~$ rougail -m firefox/ -u yaml -ff config/03/config.yaml ```
🛑 ERRORS ┗━━ The following variables are mandatory but have no value: ┗━━ Manual proxy configuration ┗━━ HTTP Proxy ┗━━ HTTP address### Example 4 #### config/04/config.yaml ```yml --- proxy_mode: foo ``` #### Output ```console foo@bar:~$ git switch --detach v1.1_033 foo@bar:~$ rougail -m firefox/ -u yaml -ff config/04/config.yaml ```
🔔 WARNINGS ┗━━ the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy Access to the Internet), only "Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yaml" ╭─────── Caption ────────╮ │ Variable Default value │ ╰────────────────────────╯ Variables: ┗━━ 📓 Configure Proxy Access to the Internet: No proxy### Example 5 #### config/05/config.yaml ```yml --- proxy_mode: 1 ``` #### Output ```console foo@bar:~$ git switch --detach v1.1_033 foo@bar:~$ rougail -m firefox/ -u yaml -ff config/05/config.yaml ```
🔔 WARNINGS ┗━━ the value "1" is an invalid choice for "proxy_mode" (Configure Proxy Access to the Internet), only "Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/05/config.yaml" ╭─────── Caption ────────╮ │ Variable Default value │ ╰────────────────────────╯ Variables: ┗━━ 📓 Configure Proxy Access to the Internet: No proxy- [[tutorial v1.1_034] A calculated default value](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_034/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_034~1..v1.1_034))