rougail-tutorials/README.md

- [Summary](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/branch/1.1/README.md)
- [[tutorial 013] A variable with type "choice"](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_013/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_013~1..v1.1_013))

# [tutorial 014] Choice type is optional

[View the diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_014~1..v1.1_014)


## Screenshot


<img src="firefox.png" width=50% height=50% alt="Firefox Proxy setting"/>


## Structure


### firefox/00-proxy.yml


```yml
---
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

```
### Generated documentation

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -o doc -do github
```
### Variables

| Variable&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   | Description&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |


## User data

### Example 1

#### config/01/config.yaml


```yml
---

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/01/config.yaml
```
<pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
│ <span style="color: #ffaf00">Unmodifiable variable</span>                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
</pre>
### Example 2

#### config/02/config.yaml


```yml
---
proxy_mode: No proxy

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/02/config.yaml
```
<pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
│ <span style="color: #ffaf00">Unmodifiable variable</span>                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy (<span style="color: #00aa00">No proxy</span>)
</pre>
### Example 3

#### config/03/config.yaml


```yml
---
proxy_mode: Manual proxy configuration

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/03/config.yaml
```
<pre>╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
│ <span style="color: #ffaf00">Unmodifiable variable</span>                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
</pre>
### Example 4

#### config/04/config.yaml


```yml
---
proxy_mode: foo

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/04/config.yaml
```
<pre>🛑 ERRORS
<span style="color: #ff0000">┗━━ </span>"foo" is an invalid choice for "proxy_mode (Configure Proxy Access to the Internet)", only 
<span style="color: #ff0000">    </span>"Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy 
<span style="color: #ff0000">    </span>configuration", "No proxy" and "Use system proxy settings" are allowed
╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
│ <span style="color: #ffaf00">Unmodifiable variable</span>                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
</pre>
### Example 5

#### config/05/config.yaml


```yml
---
proxy_mode: 1

```
#### Output

```console
foo@bar:~$ rougail -v 1.1 -m firefox/ -u file -ff config/05/config.yaml
```
<pre>🛑 ERRORS
<span style="color: #ff0000">┗━━ </span>"1" is an invalid choice for "proxy_mode (Configure Proxy Access to the Internet)", only "Auto-detect
<span style="color: #ff0000">    </span>proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy configuration", 
<span style="color: #ff0000">    </span>"No proxy" and "Use system proxy settings" are allowed
╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           <span style="color: #ffd700">Default value</span>            │
│ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
│ <span style="color: #ffaf00">Unmodifiable variable</span>                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
</pre>


- [[tutorial 020] A family](https://forge.cloud.silique.fr/stove/rougail-tutorials/src/commit/v1.1_020/README.md) ([diff](https://forge.cloud.silique.fr/stove/rougail-tutorials/compare/v1.1_020~1..v1.1_020))