remove non ascii whitespaces
This commit is contained in:
parent
598a10bc28
commit
5a6d6c4d13
GPG key ID:
901B2ADDF27C2263
117 changed files with 1928 additions and 1928 deletions
technology/tools
Ansible/modules
ansible.builtin.assert.mdansible.builtin.blockinfile.mdansible.builtin.copy.mdansible.builtin.cron.mdansible.builtin.debug.mdansible.builtin.fail.mdansible.builtin.fetch.mdansible.builtin.lineinfile.mdansible.builtin.replace.mdansible.builtin.systemd_service.mdansible.builtin.tempfile.mdansible.builtin.template.mdansible.builtin.uri.mdansible.builtin.user.mdansible.builtin.wait_for.md
JSON Schema.mdJSONPatch.mdJinja.mdMonero.mdRSS.md|
|
@ -5,9 +5,9 @@ This module asserts that given expressions are true with an optional custom mess
|
|||
| Parameter | Type | Description |
|
||||
| ----------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| **fail_msg** | string | The customized message used for a failing assertion |
|
||||
| **quiet** | boolean | Set this to `true` to avoid verbose output |
|
||||
| **quiet** | boolean | Set this to `true` to avoid verbose output |
|
||||
| **success_msg** | string | The customized message used for a successful assertion |
|
||||
| **that** | list / elements=string / required | A list of string expressions of the same form that can be passed to the ‘when’ statement |
|
||||
| **that** | list / elements=string / required | A list of string expressions of the same form that can be passed to the ‘when’ statement |
|
||||
|
||||
## Examples
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -9,16 +9,16 @@ This module will insert/update/remove a block of multi-line text surrounded by c
|
|||
| **block** | string | "" | The text to insert inside the marker lines. If it is missing or an empty string, the block will be removed as if state were specified to absent. |
|
||||
| **create** | boolean | false | Create a new file if it does not exist. |
|
||||
| **group** | string | - | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
||||
| **insertafter** | string | "EOF" | If specified and no begin/ending marker lines are found, the block will be inserted after the last match of specified regular expression. A special value is available; EOF for inserting the block at the end of the file. If specified regular expression has no matches, EOF will be used instead. The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines. This behaviour was added in ansible-core 2.14. |
|
||||
| **insertbefore** | string | - | If specified and no begin/ending marker lines are found, the block will be inserted before the last match of specified regular expression. A special value is available; BOF for inserting the block at the beginning of the file. If specified regular expression has no matches, the block will be inserted at the end of the file. The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines. This behaviour was added in ansible-core 2.14. |
|
||||
| **marker** | string | "# {mark} ANSIBLE MANAGED BLOCK" | The marker line template. {mark} will be replaced with the values in marker_begin (default=”BEGIN”) and marker_end (default=”END”). Using a custom marker without the {mark} variable may result in the block being repeatedly inserted on subsequent playbook runs. Multi-line markers are not supported and will result in the block being repeatedly inserted on subsequent playbook runs. A newline is automatically appended by the module to marker_begin and marker_end. |
|
||||
| **marker_begin** | string | "BEGIN" | This will be inserted at `{mark}` in the opening ansible block marker. |
|
||||
| **marker_end** | string | "END" | This will be inserted at `{mark}` in the closing ansible block marker. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **insertafter** | string | "EOF" | If specified and no begin/ending marker lines are found, the block will be inserted after the last match of specified regular expression. A special value is available; EOF for inserting the block at the end of the file. If specified regular expression has no matches, EOF will be used instead. The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines. This behaviour was added in ansible-core 2.14. |
|
||||
| **insertbefore** | string | - | If specified and no begin/ending marker lines are found, the block will be inserted before the last match of specified regular expression. A special value is available; BOF for inserting the block at the beginning of the file. If specified regular expression has no matches, the block will be inserted at the end of the file. The presence of the multiline flag (?m) in the regular expression controls whether the match is done line by line or with multiple lines. This behaviour was added in ansible-core 2.14. |
|
||||
| **marker** | string | "# {mark} ANSIBLE MANAGED BLOCK" | The marker line template. {mark} will be replaced with the values in marker_begin (default=”BEGIN”) and marker_end (default=”END”). Using a custom marker without the {mark} variable may result in the block being repeatedly inserted on subsequent playbook runs. Multi-line markers are not supported and will result in the block being repeatedly inserted on subsequent playbook runs. A newline is automatically appended by the module to marker_begin and marker_end. |
|
||||
| **marker_begin** | string | "BEGIN" | This will be inserted at `{mark}` in the opening ansible block marker. |
|
||||
| **marker_end** | string | "END" | This will be inserted at `{mark}` in the closing ansible block marker. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **path** | path / required | - | The file to modify. |
|
||||
| **state** | string | "present" | Whether the block should be there or not. **Choices:** (`"absent"`, `"present"`) |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so [shell](../../../applications/cli/Shell.md) features such as expansion and pipes will not work. |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so [shell](../../../applications/cli/Shell.md) features such as expansion and pipes will not work. |
|
||||
|
||||
## Examples
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -1,23 +1,23 @@
|
|||
# ansible.builtin.copy
|
||||
The `copy` module copies a file from the local or remote machine to a location on the remote machine.
|
||||
The `copy` module copies a file from the local or remote machine to a location on the remote machine.
|
||||
|
||||
## Parameter
|
||||
| Parameter | Type | Default | Description |
|
||||
| ---------------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **attributes** | string | - | The attributes the resulting filesystem object should have. To get supported flags look at the man page for [chattr](../../../applications/cli/system/chattr.md) on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string. |
|
||||
| **backup** | boolean | false | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. |
|
||||
| **checksum** | string | - | SHA1 checksum of the file being transferred. Used to validate that the copy of the file was successful. If this is not provided, ansible will use the local calculated checksum of the src file. |
|
||||
| **content** | string | - | When used instead of src, sets the contents of a file directly to the specified value. Works only when dest is a file. Creates the file if it does not exist. For advanced formatting or if content contains a variable, use the ansible.builtin.template module. |
|
||||
| **checksum** | string | - | SHA1 checksum of the file being transferred. Used to validate that the copy of the file was successful. If this is not provided, ansible will use the local calculated checksum of the src file. |
|
||||
| **content** | string | - | When used instead of src, sets the contents of a file directly to the specified value. Works only when dest is a file. Creates the file if it does not exist. For advanced formatting or if content contains a variable, use the ansible.builtin.template module. |
|
||||
| **decrypt** | boolean | true | This option controls the autodecryption of source files using vault. |
|
||||
| **dest** | path / required | - | Remote absolute path where the file should be copied to. If `src` is a directory, this must be a directory too. If `dest` is a non-existent path and if either `dest` ends with “/” or `src` is a directory, `dest` is created. If _dest_ is a relative path, the starting directory is determined by the remote host. If `src` and `dest` are files, the parent directory of `dest` is not created and the task fails if it does not already exist. |
|
||||
| **dest** | path / required | - | Remote absolute path where the file should be copied to. If `src` is a directory, this must be a directory too. If `dest` is a non-existent path and if either `dest` ends with “/” or `src` is a directory, `dest` is created. If _dest_ is a relative path, the starting directory is determined by the remote host. If `src` and `dest` are files, the parent directory of `dest` is not created and the task fails if it does not already exist. |
|
||||
| **follow** | boolean | false | This flag indicates that filesystem links in the destination, if they exist, should be followed. |
|
||||
| **force** | boolean | true | Influence whether the remote file must always be replaced. If `true`, the remote file will be replaced when contents are different than the source. If `false`, the file will only be transferred if the destination does not exist. |
|
||||
| **group** | string | - | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
||||
| **force** | boolean | true | Influence whether the remote file must always be replaced. If `true`, the remote file will be replaced when contents are different than the source. If `false`, the file will only be transferred if the destination does not exist. |
|
||||
| **group** | string | - | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
||||
| **local_follow** | boolean | true | This flag indicates that filesystem links in the source tree, if they exist, should be followed. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **src** | path | - | Local path to a file to copy to the remote server. This can be absolute or relative. If path is a directory, it is copied recursively. In this case, if path ends with “/”, only inside contents of that directory are copied to destination. Otherwise, if it does not end with “/”, the directory itself with all contents is copied. This behavior is similar to the rsync command line tool. |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so shell features such as expansion and pipes will not work. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **src** | path | - | Local path to a file to copy to the remote server. This can be absolute or relative. If path is a directory, it is copied recursively. In this case, if path ends with “/”, only inside contents of that directory are copied to destination. Otherwise, if it does not end with “/”, the directory itself with all contents is copied. This behavior is similar to the rsync command line tool. |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so shell features such as expansion and pipes will not work. |
|
||||
|
||||
## Return Values
|
||||
| Value | Type | When | Description |
|
||||
|
|
|
|||
|
|
@ -4,19 +4,19 @@ Use this module to manage crontab entries. This module allows you to create name
|
|||
## Parameter
|
||||
| Parameter | Type | Default | Description |
|
||||
| ---------------- | ---------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **backup** | boolean | false | If set, create a backup of the crontab before it is modified. The location of the backup is returned in the `backup_file` variable by this module. |
|
||||
| **cron_file** | path | - | If specified, uses this file instead of an individual user’s crontab. The assumption is that this file is exclusively managed by the module, do not use if the file contains multiple entries, NEVER use for /etc/crontab. If this is a relative path, it is interpreted with respect to /etc/cron.d. Many linux distros expect (and some require) the filename portion to consist solely of upper- and lower-case letters, digits, underscores, and hyphens. Using this parameter requires you to specify the user as well, unless state is not present. Either this parameter or name is required |
|
||||
| **day** | string | "\*" | Day of the month the job should run (`1-31`, `*`, `*/2`, and so on). |
|
||||
| **disabled** | boolean | false | If the job should be disabled (commented out) in the crontab. Only has effect if state=present. |
|
||||
| **hour** | string | "\*" | Hour when the job should run (`0-23`, `*`, `*/2`, and so on). |
|
||||
| **backup** | boolean | false | If set, create a backup of the crontab before it is modified. The location of the backup is returned in the `backup_file` variable by this module. |
|
||||
| **cron_file** | path | - | If specified, uses this file instead of an individual user’s crontab. The assumption is that this file is exclusively managed by the module, do not use if the file contains multiple entries, NEVER use for /etc/crontab. If this is a relative path, it is interpreted with respect to /etc/cron.d. Many linux distros expect (and some require) the filename portion to consist solely of upper- and lower-case letters, digits, underscores, and hyphens. Using this parameter requires you to specify the user as well, unless state is not present. Either this parameter or name is required |
|
||||
| **day** | string | "\*" | Day of the month the job should run (`1-31`, `*`, `*/2`, and so on). |
|
||||
| **disabled** | boolean | false | If the job should be disabled (commented out) in the crontab. Only has effect if state=present. |
|
||||
| **hour** | string | "\*" | Hour when the job should run (`0-23`, `*`, `*/2`, and so on). |
|
||||
| **job** | string | - | The command to execute. |
|
||||
| **minute** | string | "\*" | Minute when the job should run (`0-59`, `*`, `*/2`, and so on). |
|
||||
| **month** | string | "\*" | Month of the year the job should run (`1-12`, `*`, `*/2`, and so on). |
|
||||
| **minute** | string | "\*" | Minute when the job should run (`0-59`, `*`, `*/2`, and so on). |
|
||||
| **month** | string | "\*" | Month of the year the job should run (`1-12`, `*`, `*/2`, and so on). |
|
||||
| **name** | string / required | - | Description of a crontab entry. |
|
||||
| **special_time** | "annually"<br>"daily"<br>"hourly"<br>"monthly"<br>"reboot"<br>"weekly"<br>"yearly" | - | Special time specification nickname. |
|
||||
| **state** | "absent"<br>"present" | "present" | Whether to ensure the job is present or absent. |
|
||||
| **user** | string | - | The specific user whose crontab should be modified. When unset, this parameter defaults to the current user. |
|
||||
| **weekday** | string | "\*" | Day of the week that the job should run (`0-6` for Sunday-Saturday, `*`, and so on). |
|
||||
| **user** | string | - | The specific user whose crontab should be modified. When unset, this parameter defaults to the current user. |
|
||||
| **weekday** | string | "\*" | Day of the week that the job should run (`0-6` for Sunday-Saturday, `*`, and so on). |
|
||||
|
||||
## Examples
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@ This module prints statements during execution and can be useful for debugging v
|
|||
## Parameter
|
||||
| Parameter | Type | Default | Description |
|
||||
| ------------- | ------- | -------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| **msg** | string | "Hello world!" | The customized message that is printed. If omitted, prints a generic message. |
|
||||
| **var** | string | - | A variable name to debug. Mutually exclusive with the msg option. |
|
||||
| **msg** | string | "Hello world!" | The customized message that is printed. If omitted, prints a generic message. |
|
||||
| **var** | string | - | A variable name to debug. Mutually exclusive with the msg option. |
|
||||
| **verbosity** | integer | 0 | A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above. |
|
||||
|
||||
## Examples
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@ This module fails the progress with a custom message.
|
|||
## Parameter
|
||||
| Parameter | Type | Default | Description |
|
||||
| --------- | ------ | ------------------------------- | -------------------------------------------------- |
|
||||
| **msg** | string | "Failed as requested from task" | The customized message used for failing execution. |
|
||||
| **msg** | string | "Failed as requested from task" | The customized message used for failing execution. |
|
||||
|
||||
## Examples
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -8,8 +8,8 @@
|
|||
| Parameter | Type | Default | Description |
|
||||
| --------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------- |
|
||||
| **dest** | string / required | - | A directory to save the file into. |
|
||||
| **fail_on_missing** | boolean | true | When set to `true`, the task will fail if the remote file cannot be read for any reason. |
|
||||
| **src** | string / required | - | The file on the remote system to fetch. This must be a file, not a directory. |
|
||||
| **fail_on_missing** | boolean | true | When set to `true`, the task will fail if the remote file cannot be read for any reason. |
|
||||
| **src** | string / required | - | The file on the remote system to fetch. This must be a file, not a directory. |
|
||||
| **validate_checksum** | boolean | true | Verify that the source and destination checksums match after the files are fetched. |
|
||||
|
||||
## Examples
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ This module ensures a particular line is in a file, or replace an existing line
|
|||
| **attributes** | string | - | The attributes the resulting filesystem object should have. To get supported flags look at the man page for [chattr](../../../applications/cli/system/chattr.md) on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string. |
|
||||
| **backup** | boolean | false | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. |
|
||||
| **create** | boolean | false | Create a new file if it does not exist. |
|
||||
| **firstmatch** | boolean | false | Used with `insertafter` or `insertbefore`. If set, `insertafter` and `insertbefore` will work with the first line that matches the given [regular expression](../../Regex.md). |
|
||||
| **firstmatch** | boolean | false | Used with `insertafter` or `insertbefore`. If set, `insertafter` and `insertbefore` will work with the first line that matches the given [regular expression](../../Regex.md). |
|
||||
| **group** | string | false | Name of the group that should own the filesystem object, as would be fed to _chown_. |
|
||||
| **insertafter** | string | - | Used with `state=present`.<br><br>If specified, the line will be inserted after the last match of specified [regular expression](../../Regex.md).<br><br>If the first match is required, use(`firstmatch=yes`).<br><br>A special value is available; `EOF` for inserting the line at the end of the file.<br><br>If specified [regular expression](../../Regex.md) has no matches, `EOF` will be used instead.<br><br>If `insertbefore` is set, default value `EOF` will be ignored. |
|
||||
| **insertbefore** | string | - | Used with `state=present`.<br><br>If specified, the line will be inserted before the last match of specified [regular expression](../../Regex.md).<br><br>If the first match is required, use `firstmatch=yes`.<br><br>A value is available; `BOF` for inserting the line at the beginning of the file.<br><br>If specified [regular expression](../../Regex.md) has no matches, the line will be inserted at the end of the file. |
|
||||
|
|
|
|||
|
|
@ -8,15 +8,15 @@ Replace all instances of a particular string in a file using a back-referenced r
|
|||
| **before** | string | - | If specified, only content before this match will be replaced/removed. |
|
||||
| **path** | path / required | - | The file to modify. |
|
||||
| **regexp** | string / required | - | The regular expression to look for in the contents of the file. |
|
||||
| **replace** | string | "" | The string to replace regexp matches. May contain backreferences that will get expanded with the regexp capture groups if the regexp matches. If not set, matches are removed entirely. |
|
||||
| **replace** | string | "" | The string to replace regexp matches. May contain backreferences that will get expanded with the regexp capture groups if the regexp matches. If not set, matches are removed entirely. |
|
||||
| **attributes** | string | - | The attributes the resulting filesystem object should have. To get supported flags look at the man page for [chattr](../../../applications/cli/system/chattr.md) on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string. |
|
||||
| **backup** | boolean | false | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. |
|
||||
| **follow** | boolean | false | This flag indicates that filesystem links in the destination, if they exist, should be followed. |
|
||||
| **force** | boolean | true | Influence whether the remote file must always be replaced. If `true`, the remote file will be replaced when contents are different than the source. If `false`, the file will only be transferred if the destination does not exist. |
|
||||
| **group** | string | - | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so [shell](../../../applications/cli/Shell.md) features such as expansion and pipes will not work. |
|
||||
| **force** | boolean | true | Influence whether the remote file must always be replaced. If `true`, the remote file will be replaced when contents are different than the source. If `false`, the file will only be transferred if the destination does not exist. |
|
||||
| **group** | string | - | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so [shell](../../../applications/cli/Shell.md) features such as expansion and pipes will not work. |
|
||||
|
||||
## Examples
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -5,17 +5,17 @@ Controls [systemd](../../../linux/systemd/Systemd.md) units (services, timers, a
|
|||
| Parameter | Type | Default | Description |
|
||||
| ----------------- | --------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **daemon_reload** | boolean | false | Run daemon-reload before doing any other operations, to make sure systemd has read any changes. |
|
||||
| **enabled** | boolean | - | Whether the unit should start on boot. **At least one of state and enabled are required.** |
|
||||
| **enabled** | boolean | - | Whether the unit should start on boot. **At least one of state and enabled are required.** |
|
||||
| **force** | boolean | - | Whether to override existing symlinks. |
|
||||
| **masked** | boolean | - | Whether the unit should be masked or not, a masked unit is impossible to start. |
|
||||
| **name** | string | - | Name of the unit. This parameter takes the name of exactly one unit to work with. When no extension is given, it is implied to a `.service` as systemd. |
|
||||
| **scope** | "system"<br>"user"<br>"global" | "system" | Run systemctl within a given service manager scope, either as the default system scope `system`, the current user’s scope `user`, or the scope of all users `global`. For systemd to work with ‘user’, the executing user must have its own instance of dbus started and accessible (systemd requirement). |
|
||||
| **state** | "reloaded"<br>"restarted"<br>"started"<br>"stopped" | - | `started`/`stopped` are idempotent actions that will not run commands unless necessary. `restarted` will always bounce the unit. `reloaded` will always reload. |
|
||||
| **name** | string | - | Name of the unit. This parameter takes the name of exactly one unit to work with. When no extension is given, it is implied to a `.service` as systemd. |
|
||||
| **scope** | "system"<br>"user"<br>"global" | "system" | Run systemctl within a given service manager scope, either as the default system scope `system`, the current user’s scope `user`, or the scope of all users `global`. For systemd to work with ‘user’, the executing user must have its own instance of dbus started and accessible (systemd requirement). |
|
||||
| **state** | "reloaded"<br>"restarted"<br>"started"<br>"stopped" | - | `started`/`stopped` are idempotent actions that will not run commands unless necessary. `restarted` will always bounce the unit. `reloaded` will always reload. |
|
||||
|
||||
## Return Values
|
||||
| Value | Type | When | Description |
|
||||
| ---------- | ---------- | ------- | --------------------------------------------------------------------- |
|
||||
| **status** | dictionary | success | A dictionary with the key=value pairs returned from `systemctl show`. |
|
||||
| **status** | dictionary | success | A dictionary with the key=value pairs returned from `systemctl show`. |
|
||||
|
||||
## Examples
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# ansible.builtin.tempfile
|
||||
The `tempfile` module creates temporary files and directories.
|
||||
The `tempfile` module creates temporary files and directories.
|
||||
|
||||
## Parameter
|
||||
| Parameter | Type | Default | Description |
|
||||
| ---------- | --------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **path** | path | - | Location where temporary file or directory should be created. If path is not specified, the default system temporary directory will be used. |
|
||||
| **path** | path | - | Location where temporary file or directory should be created. If path is not specified, the default system temporary directory will be used. |
|
||||
| **prefix** | string | "ansible." | Prefix of file/directory name created by module. |
|
||||
| **state** | "directory"<br>"file" | "file" | Whether to create file or directory. |
|
||||
| **suffix** | string | "" | Suffix of file/directory name created by module. |
|
||||
|
|
|
|||
|
|
@ -5,15 +5,15 @@ Template a file out to a target host using Jinja Template Engine.
|
|||
| Parameter | Type | Default | Description |
|
||||
| -------------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **dest** | path / required | - | Location to render the template to on the remote machine. |
|
||||
| **src** | path / required | - | Path of a Jinja2 formatted template on the Ansible controller. This can be a relative or an absolute path. |
|
||||
| **src** | path / required | - | Path of a Jinja2 formatted template on the Ansible controller. This can be a relative or an absolute path. |
|
||||
| **attributes** | string | - | The attributes the resulting filesystem object should have. To get supported flags look at the man page for [chattr](../../../applications/cli/system/chattr.md) on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string. |
|
||||
| **backup** | boolean | false | Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly. |
|
||||
| **follow** | boolean | false | This flag indicates that filesystem links in the destination, if they exist, should be followed. |
|
||||
| **force** | boolean | true | Influence whether the remote file must always be replaced. If `true`, the remote file will be replaced when contents are different than the source. If `false`, the file will only be transferred if the destination does not exist. |
|
||||
| **group** | string | - | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so shell features such as expansion and pipes will not work. |
|
||||
| **force** | boolean | true | Influence whether the remote file must always be replaced. If `true`, the remote file will be replaced when contents are different than the source. If `false`, the file will only be transferred if the destination does not exist. |
|
||||
| **group** | string | - | Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. |
|
||||
| **mode** | any | - | The permissions the resulting filesystem object should have. For those used to _/usr/bin/chmod_ remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, `0755`) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination filesystem object **does not** exist, the default `umask` on the system will be used when setting the mode for the newly created filesystem object. If `mode` is not specified and the destination filesystem object **does** exist, the mode of the existing filesystem object will be used. |
|
||||
| **owner** | string | - | Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. |
|
||||
| **validate** | string | - | The validation command to run before copying the updated file into the final destination. A temporary file path is used to validate, passed in through ‘%s’ which must be present as in the examples below. Also, the command is passed securely so shell features such as expansion and pipes will not work. |
|
||||
|
||||
|
||||
## Examples
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@ Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE H
|
|||
| Parameter | Type | Default | Description |
|
||||
| ------------------ | -------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **attributes** | string | - | The attributes the resulting filesystem object should have. To get supported flags look at the man page for [chattr](../../../applications/cli/system/chattr.md) on the target system. The = operator is assumed as default, otherwise + or - operators need to be included in the string. |
|
||||
| **body** | any | - | The body of the http request/response to the web service. If `body_format` is set to ‘json’ it will take an already formatted JSON string or convert a data structure into JSON. |
|
||||
| **body_format** | "form-urlencoded"<br>"json"<br>"raw"<br>"form-multipart" | "raw" | The serialization format of the body. When set to `json`, `form-multipart`, or `form-urlencoded`, encodes the body argument, if needed, and automatically sets the Content-Type header accordingly. |
|
||||
| **body** | any | - | The body of the http request/response to the web service. If `body_format` is set to ‘json’ it will take an already formatted JSON string or convert a data structure into JSON. |
|
||||
| **body_format** | "form-urlencoded"<br>"json"<br>"raw"<br>"form-multipart" | "raw" | The serialization format of the body. When set to `json`, `form-multipart`, or `form-urlencoded`, encodes the body argument, if needed, and automatically sets the Content-Type header accordingly. |
|
||||
| **creates** | path | - | A filename, when it already exists, this step will not be run. |
|
||||
| **dest** | path | - | A path of where to download the file to (if desired). If dest is a directory, the basename of the file on the remote server will be used. |
|
||||
| **headers** | dictionary | {} | Add custom HTTP headers to a request in the format of a YAML hash |
|
||||
|
|
@ -17,7 +17,7 @@ Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE H
|
|||
| **url** | string / required | - | HTTP or HTTPS URL |
|
||||
| **url_password** | string | - | A password for the module to use for Digest, Basic or WSSE authentication. |
|
||||
| **url_username** | string | - | A username for the module to use for Digest, Basic or WSSE authentication. |
|
||||
| **validate_certs** | boolean | true | If `false`, SSL certificates will not be validated. |
|
||||
| **validate_certs** | boolean | true | If `false`, SSL certificates will not be validated. |
|
||||
|
||||
## Return Values
|
||||
| Value | Type | When | Description |
|
||||
|
|
|
|||
|
|
@ -4,49 +4,49 @@ Manage user accounts and user attributes.
|
|||
## Parameter
|
||||
| Parameter | Type | Default | Description |
|
||||
| ---------------------- | ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **append** | boolean | false | If `true`, add the user to the groups specified in `groups`. <br>If `false`, user will only be added to the groups specified in `groups`, removing them from all other groups. |
|
||||
| **create_home** | boolean | true | Unless set to `false`, a home directory will be made for the user when the account is created or if the home directory does not exist. |
|
||||
| **append** | boolean | false | If `true`, add the user to the groups specified in `groups`. <br>If `false`, user will only be added to the groups specified in `groups`, removing them from all other groups. |
|
||||
| **create_home** | boolean | true | Unless set to `false`, a home directory will be made for the user when the account is created or if the home directory does not exist. |
|
||||
| **expires** | float | - | An expiry time for the user in epoch, it will be ignored on platforms that do not support this. Currently supported on GNU/[Linux](../../../linux/Linux.md), [FreeBSD](../../../bsd/FreeBSD.md), and DragonFlyBSD. Since Ansible 2.6 you can remove the expiry time by specifying a negative value. Currently supported on GNU/[Linux](../../../linux/Linux.md) and [FreeBSD](../../../bsd/FreeBSD.md) |
|
||||
| **force** | boolean | false | This only affects `state=absent`, it forces removal of the user and associated directories on supported platforms. The behavior is the same as `userdel --force`, check the man page for `userdel` on your system for details and support. When used with `generate_ssh_key=yes` this forces an existing key to be overwritten. |
|
||||
| **generate_ssh_key** | boolean | false | Whether to generate a [SSH](../../../applications/network/SSH.md) key for the user in question. This will **not** overwrite an existing [SSH](../../../applications/network/SSH.md) key unless used with `force=yes`. |
|
||||
| **force** | boolean | false | This only affects `state=absent`, it forces removal of the user and associated directories on supported platforms. The behavior is the same as `userdel --force`, check the man page for `userdel` on your system for details and support. When used with `generate_ssh_key=yes` this forces an existing key to be overwritten. |
|
||||
| **generate_ssh_key** | boolean | false | Whether to generate a [SSH](../../../applications/network/SSH.md) key for the user in question. This will **not** overwrite an existing [SSH](../../../applications/network/SSH.md) key unless used with `force=yes`. |
|
||||
| **group** | string | - | Optionally sets the user’s primary group (takes a group name). |
|
||||
| **groups** | list / elements=string | - | List of groups user will be added to. By default, the user is removed from all other groups. Configure `append` to modify this. When set to an empty string `''`, the user is removed from all groups except the primary group. |
|
||||
| **groups** | list / elements=string | - | List of groups user will be added to. By default, the user is removed from all other groups. Configure `append` to modify this. When set to an empty string `''`, the user is removed from all groups except the primary group. |
|
||||
| **home** | path | - | Optionally set the user’s home directory. |
|
||||
| **move_home** | boolean | false | If set to `true` when used with `home:` , attempt to move the user’s old home directory to the specified directory if it isn’t there already and the old home exists. |
|
||||
| **move_home** | boolean | false | If set to `true` when used with `home:` , attempt to move the user’s old home directory to the specified directory if it isn’t there already and the old home exists. |
|
||||
| **name** | string / required | - | Name of the user to create, remove or modify. |
|
||||
| **password** | string | - | If provided, set the user’s password to the provided encrypted hash ([Linux](../../../linux/Linux.md)) or plain text password ([macOS](../../../macos/macOS.md)). You can generate the encrypted hash with the `mkpasswd` command. |
|
||||
| **remove** | boolean | false | This only affects `state=absent`, it attempts to remove directories associated with the user. The behavior is the same as `userdel --remove`, check the man page for details and support. |
|
||||
| **remove** | boolean | false | This only affects `state=absent`, it attempts to remove directories associated with the user. The behavior is the same as `userdel --remove`, check the man page for details and support. |
|
||||
| **shell** | string | - | Optionally set the user’s [shell](../../../applications/cli/Shell.md). |
|
||||
| **ssh_key_bits** | integer | - | Optionally specify number of bits in [SSH](../../../applications/network/SSH.md) key to create. The default value depends on ssh-keygen. |
|
||||
| **ssh_key_comment** | string | "ansible-generated on $HOSTNAME" | Optionally define the comment for the [SSH](../../../applications/network/SSH.md) key. |
|
||||
| **ssh_key_file** | path | .ssh/id_rsa | Optionally specify the [SSH](../../../applications/network/SSH.md) key filename. If this is a relative filename then it will be relative to the user’s home directory. |
|
||||
| **ssh_key_passphrase** | string | - | Set a passphrase for the [SSH](../../../applications/network/SSH.md) key. If no passphrase is provided, the [SSH](../../../applications/network/SSH.md) key will default to having no passphrase. |
|
||||
| **ssh_key_bits** | integer | - | Optionally specify number of bits in [SSH](../../../applications/network/SSH.md) key to create. The default value depends on ssh-keygen. |
|
||||
| **ssh_key_comment** | string | "ansible-generated on $HOSTNAME" | Optionally define the comment for the [SSH](../../../applications/network/SSH.md) key. |
|
||||
| **ssh_key_file** | path | .ssh/id_rsa | Optionally specify the [SSH](../../../applications/network/SSH.md) key filename. If this is a relative filename then it will be relative to the user’s home directory. |
|
||||
| **ssh_key_passphrase** | string | - | Set a passphrase for the [SSH](../../../applications/network/SSH.md) key. If no passphrase is provided, the [SSH](../../../applications/network/SSH.md) key will default to having no passphrase. |
|
||||
| **ssh_key_type** | string | "rsa" | Optionally specify the type of [SSH](../../../applications/network/SSH.md) key to generate. |
|
||||
| **state** | "present"<br>"absent" | present | Whether the account should exist or not, taking action if the state is different from what is stated. |
|
||||
| **system** | boolean | false | When creating an account `state=present`, setting this to `true` makes the user a system account. |
|
||||
| **system** | boolean | false | When creating an account `state=present`, setting this to `true` makes the user a system account. |
|
||||
| **uid** | integer | - | Optionally sets the UID of the user. |
|
||||
| **update_password** | "always"<br>"on_create" | "always" | `always` will update passwords if they differ. <br>`on_create` will only set the password for newly created users. |
|
||||
| **update_password** | "always"<br>"on_create" | "always" | `always` will update passwords if they differ. <br>`on_create` will only set the password for newly created users. |
|
||||
|
||||
## Return Values
|
||||
| Value | Type | When | Description |
|
||||
| ------------------- | ------- | ----------------------------------------------------------- | -------------------------------------------------------- |
|
||||
| **append** | boolean | When state is `present` and the user exists | Whether or not to append the user to groups. |
|
||||
| **append** | boolean | When state is `present` and the user exists | Whether or not to append the user to groups. |
|
||||
| **comment** | string | When user exists | Comment section from passwd file, usually the user name. |
|
||||
| **create_home** | boolean | When user does not exist and not check mode | Whether or not to create the home directory. |
|
||||
| **force** | boolean | When _state_ is `absent` and user exists | Whether or not a user account was forcibly deleted. |
|
||||
| **force** | boolean | When _state_ is `absent` and user exists | Whether or not a user account was forcibly deleted. |
|
||||
| **group** | integer | When user exists | Primary user group ID |
|
||||
| **groups** | string | When _groups_ is not empty and _state_ is `present` | List of groups of which the user is a member. |
|
||||
| **home** | string | When _state_ is `present` | Path to user’s home directory. |
|
||||
| **move_home** | boolean | When _state_ is `present` and user exists | Whether or not to move an existing home directory. |
|
||||
| **groups** | string | When _groups_ is not empty and _state_ is `present` | List of groups of which the user is a member. |
|
||||
| **home** | string | When _state_ is `present` | Path to user’s home directory. |
|
||||
| **move_home** | boolean | When _state_ is `present` and user exists | Whether or not to move an existing home directory. |
|
||||
| **name** | string | always | User account name. |
|
||||
| **remove** | boolean | When _state_ is `absent` and user exists | Whether or not to remove the user account. |
|
||||
| **shell** | string | When _state_ is `present` | User login [shell](../../../applications/cli/Shell.md). |
|
||||
| **ssh_fingerprint** | string | When _generate_ssh_key_ is `True` | Fingerprint of generated [SSH](../../../applications/network/SSH.md) key. |
|
||||
| **ssh_key_file** | string | When _generate_ssh_key_ is `True` | Path to generated [SSH](../../../applications/network/SSH.md) private key file. |
|
||||
| **ssh_public_key** | string | When _generate_ssh_key_ is `True` | Generated [SSH](../../../applications/network/SSH.md) public key file. |
|
||||
| **remove** | boolean | When _state_ is `absent` and user exists | Whether or not to remove the user account. |
|
||||
| **shell** | string | When _state_ is `present` | User login [shell](../../../applications/cli/Shell.md). |
|
||||
| **ssh_fingerprint** | string | When _generate_ssh_key_ is `True` | Fingerprint of generated [SSH](../../../applications/network/SSH.md) key. |
|
||||
| **ssh_key_file** | string | When _generate_ssh_key_ is `True` | Path to generated [SSH](../../../applications/network/SSH.md) private key file. |
|
||||
| **ssh_public_key** | string | When _generate_ssh_key_ is `True` | Generated [SSH](../../../applications/network/SSH.md) public key file. |
|
||||
| **stderr** | string | When stderr is returned by a command that is run | Standard error from running commands. |
|
||||
| **stdout** | string | When standard output is returned by the command that is run | Standard output from running commands. |
|
||||
| **uid** | integer | When _uid_ is passed to the module | User ID of the user account. |
|
||||
| **uid** | integer | When _uid_ is passed to the module | User ID of the user account. |
|
||||
|
||||
## Examples
|
||||
```yaml
|
||||
|
|
|
|||
|
|
@ -8,12 +8,12 @@ Waits for a condition before continuing
|
|||
| **delay** | integer | 0 | Number of seconds to wait before starting to poll. |
|
||||
| **host** | string | "127.0.0.1" | A resolvable hostname or IP address to wait for. |
|
||||
| **msg** | string | - | This overrides the normal error message from a failure to meet the required conditions. |
|
||||
| **path** | path | - | Path to a file on the filesystem that must exist before continuing. `path` and `port` are mutually exclusive parameters. |
|
||||
| **port** | integer | - | Port number to poll. `path` and `port` are mutually exclusive parameters. |
|
||||
| **path** | path | - | Path to a file on the filesystem that must exist before continuing. `path` and `port` are mutually exclusive parameters. |
|
||||
| **port** | integer | - | Port number to poll. `path` and `port` are mutually exclusive parameters. |
|
||||
| **search_regex** | string | - | Can be used to match a string in either a file or a socket connection. |
|
||||
| **sleep** | integer | 1 | Number of seconds to sleep between checks. |
|
||||
| **timeout** | integer | 300 | Maximum number of seconds to wait for, when used with another condition it will force an error. |
|
||||
| **state** | string | "started" | Either `present`, `started`, or `stopped`, `absent`, or `drained`. <br>When checking a port `started` will ensure the port is open, `stopped` will check that it is closed, `drained` will check for active connections. <br>When checking for a file or a search string `present` or `started` will ensure that the file or string is present before continuing, `absent` will check that file is absent or removed. <br>**Choices:** (`"absent"`, `"drained"`, `"present"`, `"started"`, `"stopped"`) |
|
||||
| **state** | string | "started" | Either `present`, `started`, or `stopped`, `absent`, or `drained`. <br>When checking a port `started` will ensure the port is open, `stopped` will check that it is closed, `drained` will check for active connections. <br>When checking for a file or a search string `present` or `started` will ensure that the file or string is present before continuing, `absent` will check that file is absent or removed. <br>**Choices:** (`"absent"`, `"drained"`, `"present"`, `"started"`, `"stopped"`) |
|
||||
|
||||
## Return Values
|
||||
| Value | Type | When | Description |
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ The length of a string can be constrained:
|
|||
```
|
||||
|
||||
#### [Regex](Regex.md)
|
||||
The `pattern` keyword is used to restrict a string to a particular [regular expression](Regex.md)
|
||||
The `pattern` keyword is used to restrict a string to a particular [regular expression](Regex.md)
|
||||
```json
|
||||
{
|
||||
"type": "string",
|
||||
|
|
@ -43,45 +43,45 @@ Optionally, validator implementations can provide a configuration option to enab
|
|||
The following is the list of formats specified in the JSON Schema specification.
|
||||
|
||||
###### Dates and times
|
||||
Dates and times are represented in [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). This is a subset of the date format also commonly known as [ISO8601 format](https://www.iso.org/iso-8601-date-and-time-format.html).
|
||||
- `"date-time"`: Date and time together, for example, `2018-11-13T20:20:39+00:00`.
|
||||
- `"time"`: Time, for example, `20:20:39+00:00`
|
||||
- `"date"`: Date, for example, `2018-11-13`.
|
||||
- `"duration"`: A duration as defined by the [ISO 8601 ABNF for "duration"](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). For example, `P3D` expresses a duration of 3 days.
|
||||
Dates and times are represented in [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). This is a subset of the date format also commonly known as [ISO8601 format](https://www.iso.org/iso-8601-date-and-time-format.html).
|
||||
- `"date-time"`: Date and time together, for example, `2018-11-13T20:20:39+00:00`.
|
||||
- `"time"`: Time, for example, `20:20:39+00:00`
|
||||
- `"date"`: Date, for example, `2018-11-13`.
|
||||
- `"duration"`: A duration as defined by the [ISO 8601 ABNF for "duration"](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). For example, `P3D` expresses a duration of 3 days.
|
||||
|
||||
###### [Email](../internet/eMail.md) addresses
|
||||
- `"email"`: Internet email address, see [RFC 5321, section 4.1.2](http://tools.ietf.org/html/rfc5321#section-4.1.2).
|
||||
- `"idn-email"`: The internationalized form of an Internet email address, see [RFC 6531](https://tools.ietf.org/html/rfc6531).
|
||||
- `"email"`: Internet email address, see [RFC 5321, section 4.1.2](http://tools.ietf.org/html/rfc5321#section-4.1.2).
|
||||
- `"idn-email"`: The internationalized form of an Internet email address, see [RFC 6531](https://tools.ietf.org/html/rfc6531).
|
||||
|
||||
###### Hostnames
|
||||
- `"hostname"`: Internet host name, see [RFC 1123, section 2.1](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1).
|
||||
- `"idn-hostname"`: An internationalized Internet host name, see [RFC5890, section 2.3.2.3](https://tools.ietf.org/html/rfc5890#section-2.3.2.3).
|
||||
- `"hostname"`: Internet host name, see [RFC 1123, section 2.1](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1).
|
||||
- `"idn-hostname"`: An internationalized Internet host name, see [RFC5890, section 2.3.2.3](https://tools.ietf.org/html/rfc5890#section-2.3.2.3).
|
||||
|
||||
###### IP Addresses
|
||||
- `"ipv4"`: IPv4 address, according to dotted-quad ABNF syntax as defined in [RFC 2673, section 3.2](http://tools.ietf.org/html/rfc2673#section-3.2).
|
||||
- `"ipv6"`: IPv6 address, as defined in [RFC 2373, section 2.2](http://tools.ietf.org/html/rfc2373#section-2.2).
|
||||
- `"ipv4"`: IPv4 address, according to dotted-quad ABNF syntax as defined in [RFC 2673, section 3.2](http://tools.ietf.org/html/rfc2673#section-3.2).
|
||||
- `"ipv6"`: IPv6 address, as defined in [RFC 2373, section 2.2](http://tools.ietf.org/html/rfc2373#section-2.2).
|
||||
|
||||
###### Resource identifiers
|
||||
- `"uuid"`: A Universally Unique Identifier as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). Example: `3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a`
|
||||
- `"uri"`: A universal resource identifier (URI), according to [RFC3986](http://tools.ietf.org/html/rfc3986).
|
||||
- `"uri-reference"`: A URI Reference (either a URI or a relative-reference), according to [RFC3986, section 4.1](http://tools.ietf.org/html/rfc3986#section-4.1).
|
||||
- `"iri"`: The internationalized equivalent of a "uri", according to [RFC3987](https://tools.ietf.org/html/rfc3987).
|
||||
- `"iri-reference"`: New in draft 7The internationalized equivalent of a "uri-reference", according to [RFC3987](https://tools.ietf.org/html/rfc3987)
|
||||
- `"uuid"`: A Universally Unique Identifier as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). Example: `3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a`
|
||||
- `"uri"`: A universal resource identifier (URI), according to [RFC3986](http://tools.ietf.org/html/rfc3986).
|
||||
- `"uri-reference"`: A URI Reference (either a URI or a relative-reference), according to [RFC3986, section 4.1](http://tools.ietf.org/html/rfc3986#section-4.1).
|
||||
- `"iri"`: The internationalized equivalent of a "uri", according to [RFC3987](https://tools.ietf.org/html/rfc3987).
|
||||
- `"iri-reference"`: New in draft 7The internationalized equivalent of a "uri-reference", according to [RFC3987](https://tools.ietf.org/html/rfc3987)
|
||||
|
||||
If the values in the schema have the ability to be relative to a particular source path (such as a link from a webpage), it is generally better practice to use `"uri-reference"` (or `"iri-reference"`) rather than `"uri"` (or `"iri"`). `"uri"` should only be used when the path must be absolute.
|
||||
If the values in the schema have the ability to be relative to a particular source path (such as a link from a webpage), it is generally better practice to use `"uri-reference"` (or `"iri-reference"`) rather than `"uri"` (or `"iri"`). `"uri"` should only be used when the path must be absolute.
|
||||
|
||||
###### URI template
|
||||
- `"uri-template"`: A URI Template (of any level) according to [RFC6570](https://tools.ietf.org/html/rfc6570). If you don't already know what a URI Template is, you probably don't need this value.
|
||||
- `"uri-template"`: A URI Template (of any level) according to [RFC6570](https://tools.ietf.org/html/rfc6570). If you don't already know what a URI Template is, you probably don't need this value.
|
||||
|
||||
###### JSON Pointer
|
||||
- `"json-pointer"`: A JSON Pointer, according to [RFC6901](https://tools.ietf.org/html/rfc6901). There is more discussion on the use of JSON Pointer within JSON Schema in [Structuring a complex schema](https://json-schema.org/understanding-json-schema/structuring). Note that this should be used only when the entire string contains only JSON Pointer content, e.g. `/foo/bar`. JSON Pointer URI fragments, e.g. `#/foo/bar/` should use `"uri-reference"`.
|
||||
- `"relative-json-pointer"`: A [relative JSON pointer](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01).
|
||||
- `"json-pointer"`: A JSON Pointer, according to [RFC6901](https://tools.ietf.org/html/rfc6901). There is more discussion on the use of JSON Pointer within JSON Schema in [Structuring a complex schema](https://json-schema.org/understanding-json-schema/structuring). Note that this should be used only when the entire string contains only JSON Pointer content, e.g. `/foo/bar`. JSON Pointer URI fragments, e.g. `#/foo/bar/` should use `"uri-reference"`.
|
||||
- `"relative-json-pointer"`: A [relative JSON pointer](https://tools.ietf.org/html/draft-handrews-relative-json-pointer-01).
|
||||
|
||||
###### Regular Expressions
|
||||
- `"regex"`: A [regular expression](Regex.md), which should be valid according to the [ECMA 262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/) dialect.
|
||||
- `"regex"`: A [regular expression](Regex.md), which should be valid according to the [ECMA 262](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/) dialect.
|
||||
|
||||
### `integer`
|
||||
The `integer` type is used for integral numbers. JSON does not have distinct types for integers and floating-point values. Therefore, the presence or absence of a decimal point is not enough to distinguish between integers and non-integers. For example, `1` and `1.0` are two ways to represent the same value in JSON. JSON Schema considers that value an integer no matter which representation was used.
|
||||
The `integer` type is used for integral numbers. JSON does not have distinct types for integers and floating-point values. Therefore, the presence or absence of a decimal point is not enough to distinguish between integers and non-integers. For example, `1` and `1.0` are two ways to represent the same value in JSON. JSON Schema considers that value an integer no matter which representation was used.
|
||||
|
||||
For differencing float and integer values these types can be used.
|
||||
```json
|
||||
|
|
@ -90,7 +90,7 @@ For differencing float and integer values these types can be used.
|
|||
```
|
||||
|
||||
#### Multiples
|
||||
Numbers can be restricted to a multiple of a given number, using the `multipleOf` keyword. It may be set to any positive number.
|
||||
Numbers can be restricted to a multiple of a given number, using the `multipleOf` keyword. It may be set to any positive number.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -100,7 +100,7 @@ Numbers can be restricted to a multiple of a given number, using the `multipleO
|
|||
```
|
||||
|
||||
#### Range
|
||||
Ranges of numbers are specified using a combination of the `minimum` and `maximum` keywords, (or `exclusiveMinimum` and `exclusiveMaximum` for expressing exclusive range).
|
||||
Ranges of numbers are specified using a combination of the `minimum` and `maximum` keywords, (or `exclusiveMinimum` and `exclusiveMaximum` for expressing exclusive range).
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -118,7 +118,7 @@ Objects are the mapping type in [JSON](../files/JSON.md). They map "keys" to "va
|
|||
```
|
||||
|
||||
#### Properties
|
||||
The properties (key-value pairs) on an object are defined using the `properties` keyword. The value of `properties` is an object, where each key is the name of a property and each value is a schema used to validate that property. Any property that doesn't match any of the property names in the `properties` keyword is ignored by this keyword.
|
||||
The properties (key-value pairs) on an object are defined using the `properties` keyword. The value of `properties` is an object, where each key is the name of a property and each value is a schema used to validate that property. Any property that doesn't match any of the property names in the `properties` keyword is ignored by this keyword.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -132,7 +132,7 @@ The properties (key-value pairs) on an object are defined using the `properties
|
|||
```
|
||||
|
||||
#### Pattern Properties
|
||||
Sometimes you want to say that, given a particular kind of property name, the value should match a particular schema. That's where `patternProperties` comes in: it maps regular expressions to schemas. If a property name matches the given [regular expression](Regex.md), the property value must validate against the corresponding schema.
|
||||
Sometimes you want to say that, given a particular kind of property name, the value should match a particular schema. That's where `patternProperties` comes in: it maps regular expressions to schemas. If a property name matches the given [regular expression](Regex.md), the property value must validate against the corresponding schema.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -145,9 +145,9 @@ Sometimes you want to say that, given a particular kind of property name, the va
|
|||
```
|
||||
|
||||
#### Additional Properties
|
||||
The `additionalProperties` keyword is used to control the handling of extra stuff, that is, properties whose names are not listed in the `properties` keyword or match any of the regular expressions in the `patternProperties` keyword. By default any additional properties are allowed.
|
||||
The `additionalProperties` keyword is used to control the handling of extra stuff, that is, properties whose names are not listed in the `properties` keyword or match any of the regular expressions in the `patternProperties` keyword. By default any additional properties are allowed.
|
||||
|
||||
The value of the `additionalProperties` keyword is a schema that will be used to validate any properties in the instance that are not matched by `properties` or `patternProperties`. Setting the `additionalProperties` schema to `false` means no additional properties will be allowed.
|
||||
The value of the `additionalProperties` keyword is a schema that will be used to validate any properties in the instance that are not matched by `properties` or `patternProperties`. Setting the `additionalProperties` schema to `false` means no additional properties will be allowed.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -162,7 +162,7 @@ The value of the `additionalProperties` keyword is a schema that will be used
|
|||
```
|
||||
|
||||
#### Required Properties
|
||||
By default, the properties defined by the `properties` keyword are not required. However, one can provide a list of required properties using the `required` keyword.
|
||||
By default, the properties defined by the `properties` keyword are not required. However, one can provide a list of required properties using the `required` keyword.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -190,7 +190,7 @@ The names of properties can be validated against a schema, irrespective of their
|
|||
```
|
||||
|
||||
#### Size
|
||||
The number of properties on an object can be restricted using the `minProperties` and `maxProperties` keywords. Each of these must be a non-negative integer.
|
||||
The number of properties on an object can be restricted using the `minProperties` and `maxProperties` keywords. Each of these must be a non-negative integer.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -208,7 +208,7 @@ Arrays are used for ordered elements. In [JSON](../files/JSON.md), each element
|
|||
```
|
||||
|
||||
#### Items
|
||||
List validation is useful for arrays of arbitrary length where each item matches the same schema. For this kind of array, set the `items` keyword to a single schema that will be used to validate all of the items in the array.
|
||||
List validation is useful for arrays of arbitrary length where each item matches the same schema. For this kind of array, set the `items` keyword to a single schema that will be used to validate all of the items in the array.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -235,7 +235,7 @@ Tuple validation is useful when the array is a collection of items where each ha
|
|||
```
|
||||
|
||||
#### Additional Items
|
||||
The `items` keyword can be used to control whether it's valid to have additional items in a tuple beyond what is defined in `prefixItems`. The value of the `items` keyword is a schema that all additional items must pass in order for the keyword to validate.
|
||||
The `items` keyword can be used to control whether it's valid to have additional items in a tuple beyond what is defined in `prefixItems`. The value of the `items` keyword is a schema that all additional items must pass in order for the keyword to validate.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -251,13 +251,13 @@ The `items` keyword can be used to control whether it's valid to have addition
|
|||
```
|
||||
|
||||
#### Unevaluated Items
|
||||
The `unevaluatedItems` keyword is useful mainly when you want to add or disallow extra items to an array.
|
||||
The `unevaluatedItems` keyword is useful mainly when you want to add or disallow extra items to an array.
|
||||
|
||||
`unevaluatedItems` applies to any values not evaluated by an `items`, `prefixItems`, or `contains` keyword. Just as `unevaluatedProperties` affects only **properties** in an object, `unevaluatedItems` affects only **items** in an array.
|
||||
`unevaluatedItems` applies to any values not evaluated by an `items`, `prefixItems`, or `contains` keyword. Just as `unevaluatedProperties` affects only **properties** in an object, `unevaluatedItems` affects only **items** in an array.
|
||||
|
||||
Watch out! The word "unevaluated" _does not mean_ "not evaluated by `items`, `prefixItems`, or `contains`." "Unevaluated" means "not successfully evaluated", or "does not evaluate to true".
|
||||
Watch out! The word "unevaluated" _does not mean_ "not evaluated by `items`, `prefixItems`, or `contains`." "Unevaluated" means "not successfully evaluated", or "does not evaluate to true".
|
||||
|
||||
Like with `items`, if you set `unevaluatedItems` to `false`, you can disallow extra items in the array.
|
||||
Like with `items`, if you set `unevaluatedItems` to `false`, you can disallow extra items in the array.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -269,7 +269,7 @@ Like with `items`, if you set `unevaluatedItems` to `false`, you can disallo
|
|||
```
|
||||
|
||||
#### Contains
|
||||
While the `items` schema must be valid for every item in the array, the `contains` schema only needs to validate against one or more items in the array.
|
||||
While the `items` schema must be valid for every item in the array, the `contains` schema only needs to validate against one or more items in the array.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -281,7 +281,7 @@ While the `items` schema must be valid for every item in the array, the `cont
|
|||
```
|
||||
|
||||
#### minContains / maxContains
|
||||
`minContains` and `maxContains` can be used with `contains` to further specify how many times a schema matches a `contains` constraint. These keywords can be any non-negative number including zero.
|
||||
`minContains` and `maxContains` can be used with `contains` to further specify how many times a schema matches a `contains` constraint. These keywords can be any non-negative number including zero.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -306,7 +306,7 @@ The length of the array can be specified using the minItems and maxItems keyword
|
|||
```
|
||||
|
||||
#### Uniqueness
|
||||
A schema can ensure that each of the items in an array is unique. Simply set the `uniqueItems` keyword to `true`.
|
||||
A schema can ensure that each of the items in an array is unique. Simply set the `uniqueItems` keyword to `true`.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -316,7 +316,7 @@ A schema can ensure that each of the items in an array is unique. Simply set the
|
|||
```
|
||||
|
||||
### `boolean`
|
||||
The boolean type matches only two special values: `true` and `false`. Note that values that _evaluate_ to `true` or `false`, such as 1 and 0, are not accepted by the schema.
|
||||
The boolean type matches only two special values: `true` and `false`. Note that values that _evaluate_ to `true` or `false`, such as 1 and 0, are not accepted by the schema.
|
||||
|
||||
```json
|
||||
{ "type": "boolean" }
|
||||
|
|
@ -332,15 +332,15 @@ When a schema specifies a type of null, it has only one acceptable value: null.
|
|||
## Annotations
|
||||
JSON Schema includes a few keywords, that aren't strictly used for validation, but are used to describe parts of a schema. None of these "annotation" keywords are required, but they are encouraged for good practice, and can make your schema "self-documenting".
|
||||
|
||||
The `title` and `description` keywords must be strings. A "title" will preferably be short, whereas a "description" will provide a more lengthy explanation about the purpose of the data described by the schema.
|
||||
The `title` and `description` keywords must be strings. A "title" will preferably be short, whereas a "description" will provide a more lengthy explanation about the purpose of the data described by the schema.
|
||||
|
||||
The `default` keyword specifies a default value. This value is not used to fill in missing values during the validation process. Non-validation tools such as documentation generators or form generators may use this value to give hints to users about how to use a value. However, `default` is typically used to express that if a value is missing, then the value is semantically the same as if the value was present with the default value. The value of `default` should validate against the schema in which it resides, but that isn't required.
|
||||
The `default` keyword specifies a default value. This value is not used to fill in missing values during the validation process. Non-validation tools such as documentation generators or form generators may use this value to give hints to users about how to use a value. However, `default` is typically used to express that if a value is missing, then the value is semantically the same as if the value was present with the default value. The value of `default` should validate against the schema in which it resides, but that isn't required.
|
||||
|
||||
The `examples` keyword is a place to provide an array of examples that validate against the schema. This isn't used for validation, but may help with explaining the effect and purpose of the schema to a reader. Each entry should validate against the schema in which it resides, but that isn't strictly required. There is no need to duplicate the `default` value in the `examples` array, since `default` will be treated as another example.
|
||||
The `examples` keyword is a place to provide an array of examples that validate against the schema. This isn't used for validation, but may help with explaining the effect and purpose of the schema to a reader. Each entry should validate against the schema in which it resides, but that isn't strictly required. There is no need to duplicate the `default` value in the `examples` array, since `default` will be treated as another example.
|
||||
|
||||
The boolean keywords `readOnly` and `writeOnly` are typically used in an API context. `readOnly` indicates that a value should not be modified. It could be used to indicate that a `PUT` request that changes a value would result in a `400 Bad Request` response. `writeOnly` indicates that a value may be set, but will remain hidden. In could be used to indicate you can set a value with a `PUT` request, but it would not be included when retrieving that record with a `GET` request.
|
||||
The boolean keywords `readOnly` and `writeOnly` are typically used in an API context. `readOnly` indicates that a value should not be modified. It could be used to indicate that a `PUT` request that changes a value would result in a `400 Bad Request` response. `writeOnly` indicates that a value may be set, but will remain hidden. In could be used to indicate you can set a value with a `PUT` request, but it would not be included when retrieving that record with a `GET` request.
|
||||
|
||||
The `deprecated` keyword is a boolean that indicates that the instance value the keyword applies to should not be used and may be removed in the future.
|
||||
The `deprecated` keyword is a boolean that indicates that the instance value the keyword applies to should not be used and may be removed in the future.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -358,7 +358,7 @@ The `deprecated` keyword is a boolean that indicates that the instance value t
|
|||
```
|
||||
|
||||
## Enumerated values
|
||||
The `enum` keyword is used to restrict a value to a fixed set of values. It must be an array with at least one element, where each element is unique.
|
||||
The `enum` keyword is used to restrict a value to a fixed set of values. It must be an array with at least one element, where each element is unique.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -367,7 +367,7 @@ The `enum` keyword is used to restrict a value to a fixed set of values. It mu
|
|||
```
|
||||
|
||||
## Constant Values
|
||||
The `const` keyword is used to restrict a value to a single value.
|
||||
The `const` keyword is used to restrict a value to a single value.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -383,17 +383,17 @@ The `const` keyword is used to restrict a value to a single value.
|
|||
JSON schema has a set of keywords to describe and optionally validate non-JSON data stored inside [JSON](../files/JSON.md) strings. Since it would be difficult to write validators for many media types, JSON schema validators are not required to validate the contents of [JSON](../files/JSON.md) strings based on these keywords. However, these keywords are still useful for an application that consumes validated [JSON](../files/JSON.md).
|
||||
|
||||
### contentMediaType
|
||||
The `contentMediaType` keyword specifies the [MIME](../files/MIME.md) type of the contents of a string, as described in [RFC 2046](https://tools.ietf.org/html/rfc2046). There is a list of [MIME types officially registered by the IANA](http://www.iana.org/assignments/media-types/media-types.xhtml), but the set of types supported will be application and operating system dependent. Mozilla Developer Network also maintains a [shorter list of MIME types that are important for the web](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types)
|
||||
The `contentMediaType` keyword specifies the [MIME](../files/MIME.md) type of the contents of a string, as described in [RFC 2046](https://tools.ietf.org/html/rfc2046). There is a list of [MIME types officially registered by the IANA](http://www.iana.org/assignments/media-types/media-types.xhtml), but the set of types supported will be application and operating system dependent. Mozilla Developer Network also maintains a [shorter list of MIME types that are important for the web](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types)
|
||||
|
||||
### contentEncoding
|
||||
The `contentEncoding` keyword specifies the encoding used to store the contents, as specified in [RFC 2054, part 6.1](https://tools.ietf.org/html/rfc2045) and [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648).
|
||||
The `contentEncoding` keyword specifies the encoding used to store the contents, as specified in [RFC 2054, part 6.1](https://tools.ietf.org/html/rfc2045) and [RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648).
|
||||
|
||||
The acceptable values are `7bit`, `8bit`, `binary`, `quoted-printable`, `base16`, `base32`, and `base64`. If not specified, the encoding is the same as the containing [JSON](../files/JSON.md) document.
|
||||
The acceptable values are `7bit`, `8bit`, `binary`, `quoted-printable`, `base16`, `base32`, and `base64`. If not specified, the encoding is the same as the containing [JSON](../files/JSON.md) document.
|
||||
|
||||
Without getting into the low-level details of each of these encodings, there are really only two options useful for modern usage:
|
||||
|
||||
- If the content is encoded in the same encoding as the enclosing [JSON](../files/JSON.md) document (which for practical purposes, is almost always UTF-8), leave `contentEncoding` unspecified, and include the content in a string as-is. This includes text-based content types, such as `text/html` or `application/xml`.
|
||||
- If the content is binary data, set `contentEncoding` to `base64` and encode the contents using [Base64](https://tools.ietf.org/html/rfc4648). This would include many image types, such as `image/png` or audio types, such as `audio/mpeg`.
|
||||
- If the content is encoded in the same encoding as the enclosing [JSON](../files/JSON.md) document (which for practical purposes, is almost always UTF-8), leave `contentEncoding` unspecified, and include the content in a string as-is. This includes text-based content types, such as `text/html` or `application/xml`.
|
||||
- If the content is binary data, set `contentEncoding` to `base64` and encode the contents using [Base64](https://tools.ietf.org/html/rfc4648). This would include many image types, such as `image/png` or audio types, such as `audio/mpeg`.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -412,7 +412,7 @@ Without getting into the low-level details of each of these encodings, there are
|
|||
|
||||
## Conditional Schemas
|
||||
### dependentRequired
|
||||
The `dependentRequired` keyword conditionally requires that certain properties must be present if a given property is present in an object. For example, suppose we have a schema representing a customer. If you have their credit card number, you also want to ensure you have a billing address. If you don't have their credit card number, a billing address would not be required. We represent this dependency of one property on another using the `dependentRequired` keyword. The value of the `dependentRequired` keyword is an object. Each entry in the object maps from the name of a property, _p_, to an array of strings listing properties that are required if _p_ is present.
|
||||
The `dependentRequired` keyword conditionally requires that certain properties must be present if a given property is present in an object. For example, suppose we have a schema representing a customer. If you have their credit card number, you also want to ensure you have a billing address. If you don't have their credit card number, a billing address would not be required. We represent this dependency of one property on another using the `dependentRequired` keyword. The value of the `dependentRequired` keyword is an object. Each entry in the object maps from the name of a property, _p_, to an array of strings listing properties that are required if _p_ is present.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -430,7 +430,7 @@ The `dependentRequired` keyword conditionally requires that certain properties
|
|||
```
|
||||
|
||||
### dependentSchemas
|
||||
The `dependentSchemas` keyword conditionally applies a subschema when a given property is present. This schema is applied in the same way [allOf](https://json-schema.org/understanding-json-schema/reference/combining#allof) applies schemas. Nothing is merged or extended. Both schemas apply independently.
|
||||
The `dependentSchemas` keyword conditionally applies a subschema when a given property is present. This schema is applied in the same way [allOf](https://json-schema.org/understanding-json-schema/reference/combining#allof) applies schemas. Nothing is merged or extended. Both schemas apply independently.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ A JSON Patch document is just a [JSON](../files/JSON.md) file containing an arra
|
|||
## JSON Pointer
|
||||
JSON Pointer ([IETF RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901/)) defines a string format for identifying a specific value within a [JSON](../files/JSON.md) document. It is used by all operations in JSON Patch to specify the part of the document to operate on.
|
||||
|
||||
A JSON Pointer is a string of tokens separated by `/` characters, these tokens either specify keys in objects or indexes into arrays. For example, given the [JSON](../files/JSON.md)
|
||||
A JSON Pointer is a string of tokens separated by `/` characters, these tokens either specify keys in objects or indexes into arrays. For example, given the [JSON](../files/JSON.md)
|
||||
```json
|
||||
{
|
||||
"biscuits": [
|
||||
|
|
@ -49,13 +49,13 @@ A JSON Pointer is a string of tokens separated by `/` characters, these tokens
|
|||
}
|
||||
```
|
||||
|
||||
`/biscuits` would point to the array of biscuits and `/biscuits/1/name` would point to `"Choco Leibniz"`.
|
||||
`/biscuits` would point to the array of biscuits and `/biscuits/1/name` would point to `"Choco Leibniz"`.
|
||||
|
||||
To point to the root of the document use an empty string for the pointer. The pointer `/` doesn’t point to the root, it points to a key of `""` on the root (which is totally valid in [JSON](../files/JSON.md)).
|
||||
To point to the root of the document use an empty string for the pointer. The pointer `/` doesn’t point to the root, it points to a key of `""` on the root (which is totally valid in [JSON](../files/JSON.md)).
|
||||
|
||||
If you need to refer to a key with `~` or `/` in its name, you must escape the characters with `~0` and `~1` respectively. For example, to get `"baz"` from `{ "foo/bar~": "baz" }` you’d use the pointer `/foo~1bar~0`.
|
||||
If you need to refer to a key with `~` or `/` in its name, you must escape the characters with `~0` and `~1` respectively. For example, to get `"baz"` from `{ "foo/bar~": "baz" }` you’d use the pointer `/foo~1bar~0`.
|
||||
|
||||
Finally, if you need to refer to the end of an array you can use `-` instead of an index. For example, to refer to the end of the array of biscuits above you would use `/biscuits/-`. This is useful when you need to insert a value at the end of an array.
|
||||
Finally, if you need to refer to the end of an array you can use `-` instead of an index. For example, to refer to the end of the array of biscuits above you would use `/biscuits/-`. This is useful when you need to insert a value at the end of an array.
|
||||
|
||||
## Operations
|
||||
### Add
|
||||
|
|
@ -63,7 +63,7 @@ Finally, if you need to refer to the end of an array you can use `-` instead o
|
|||
{ "op": "add", "path": "/biscuits/1", "value": { "name": "Ginger Nut" } }
|
||||
```
|
||||
|
||||
Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The `-` character can be used instead of an index to insert at the end of an array.
|
||||
Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The `-` character can be used instead of an index to insert at the end of an array.
|
||||
|
||||
### Remove
|
||||
```json
|
||||
|
|
@ -75,7 +75,7 @@ Removes a value from an object or array.
|
|||
{ "op": "remove", "path": "/biscuits/0" }
|
||||
```
|
||||
|
||||
Removes the first element of the array at `biscuits` (or just removes the “0” key if `biscuits` is an object)
|
||||
Removes the first element of the array at `biscuits` (or just removes the “0” key if `biscuits` is an object)
|
||||
|
||||
### Replace
|
||||
```json
|
||||
|
|
@ -89,14 +89,14 @@ Replaces a value. Equivalent to a "remove" followed by an "add".
|
|||
{ "op": "copy", "from": "/biscuits/0", "path": "/best_biscuit" }
|
||||
```
|
||||
|
||||
Copies a value from one location to another within the [JSON](../files/JSON.md) document. Both `from` and `path` are JSON Pointers.
|
||||
Copies a value from one location to another within the [JSON](../files/JSON.md) document. Both `from` and `path` are JSON Pointers.
|
||||
|
||||
### Move
|
||||
```json
|
||||
{ "op": "move", "from": "/biscuits", "path": "/cookies" }
|
||||
```
|
||||
|
||||
Moves a value from one location to the other. Both `from` and `path` are JSON Pointers.
|
||||
Moves a value from one location to the other. Both `from` and `path` are JSON Pointers.
|
||||
|
||||
### Test
|
||||
```json
|
||||
|
|
|
|||
|
|
@ -31,12 +31,12 @@ Below is a minimal template that illustrates a few basics using the default Jinj
|
|||
```
|
||||
|
||||
There are a few kinds of delimiters. The default Jinja delimiters are configured as follows:
|
||||
- `{% ... %}` for Statements
|
||||
- `{{ ... }}` for Expressions to print to the template output
|
||||
- `{# ... #}` for Comments not included in the template output
|
||||
- `{% ... %}` for Statements
|
||||
- `{{ ... }}` for Expressions to print to the template output
|
||||
- `{# ... #}` for Comments not included in the template output
|
||||
|
||||
### Comments
|
||||
To comment-out part of a line in a template, use the comment syntax which is by default set to `{# ... #}`. This is useful to comment out parts of the template for debugging or to add information for other template designers or yourself:
|
||||
To comment-out part of a line in a template, use the comment syntax which is by default set to `{# ... #}`. This is useful to comment out parts of the template for debugging or to add information for other template designers or yourself:
|
||||
```
|
||||
{# note: commented-out template because we no longer use this
|
||||
{% for user in users %}
|
||||
|
|
@ -51,19 +51,19 @@ Jinja allows basic expressions everywhere. These work very similarly to regular
|
|||
#### Literals
|
||||
The simplest form of expressions are literals. Literals are representations for [Python](../dev/programming/languages/Python.md) objects such as strings and numbers. The following literals exist:
|
||||
|
||||
`"Hello World"`
|
||||
`"Hello World"`
|
||||
|
||||
Everything between two double or single quotes is a string. They are useful whenever you need a string in the template (e.g. as arguments to function calls and filters, or just to extend or include a template).
|
||||
|
||||
`42` / `123_456`
|
||||
`42` / `123_456`
|
||||
|
||||
Integers are whole numbers without a decimal part. The ‘_’ character can be used to separate groups for legibility.
|
||||
|
||||
`42.23` / `42.1e2` / `123_456.789`
|
||||
`42.23` / `42.1e2` / `123_456.789`
|
||||
|
||||
Floating point numbers can be written using a ‘.’ as a decimal mark. They can also be written in scientific notation with an upper or lower case ‘e’ to indicate the exponent part. The ‘_’ character can be used to separate groups for legibility, but cannot be used in the exponent part.
|
||||
|
||||
`['list', 'of', 'objects']`
|
||||
`['list', 'of', 'objects']`
|
||||
|
||||
Everything between two brackets is a list. Lists are useful for storing sequential data to be iterated over. For example, you can easily create a list of links using lists and tuples for (and with) a for loop:
|
||||
|
||||
|
|
@ -76,34 +76,34 @@ Everything between two brackets is a list. Lists are useful for storing sequenti
|
|||
</ul>
|
||||
```
|
||||
|
||||
`('tuple', 'of', 'values')`
|
||||
`('tuple', 'of', 'values')`
|
||||
|
||||
Tuples are like lists that cannot be modified (“immutable”). If a tuple only has one item, it must be followed by a comma (`('1-tuple',)`). Tuples are usually used to represent items of two or more elements. See the list example above for more details.
|
||||
|
||||
`{'dict': 'of', 'key': 'and', 'value': 'pairs'}`
|
||||
`{'dict': 'of', 'key': 'and', 'value': 'pairs'}`
|
||||
|
||||
A dict in [Python](../dev/programming/languages/Python.md) is a structure that combines keys and values. Keys must be unique and always have exactly one value. Dicts are rarely used in templates; they are useful in some rare cases such as the `xmlattr()` filter.
|
||||
A dict in [Python](../dev/programming/languages/Python.md) is a structure that combines keys and values. Keys must be unique and always have exactly one value. Dicts are rarely used in templates; they are useful in some rare cases such as the `xmlattr()` filter.
|
||||
|
||||
`true` / `false`
|
||||
`true` / `false`
|
||||
|
||||
`true` is always true and `false` is always false.
|
||||
`true` is always true and `false` is always false.
|
||||
|
||||
#### If Expression
|
||||
It is also possible to use inline if expressions. These are useful in some situations. For example, you can use this to extend from one template if a variable is defined, otherwise from the default layout template:
|
||||
It is also possible to use inline if expressions. These are useful in some situations. For example, you can use this to extend from one template if a variable is defined, otherwise from the default layout template:
|
||||
```
|
||||
{% extends layout_template if layout_template is defined else 'default.html' %}
|
||||
```
|
||||
|
||||
The general syntax is `<do something> if <something is true> else <do something else>`.
|
||||
The general syntax is `<do something> if <something is true> else <do something else>`.
|
||||
|
||||
The else part is optional. If not provided, the else block implicitly evaluates into an `Undefined` object (regardless of what `undefined` in the environment is set to):
|
||||
The else part is optional. If not provided, the else block implicitly evaluates into an `Undefined` object (regardless of what `undefined` in the environment is set to):
|
||||
```
|
||||
{{ "[{}]".format(page.title) if page.title }}
|
||||
```
|
||||
|
||||
#### Builtin Filters
|
||||
##### batch(value, linecount: int, fill_with: 'Optional' = None)
|
||||
A filter that batches items. It works pretty much like slice just the other way round. It returns a list of lists with the given number of items. If you provide a second parameter this is used to fill up missing items. See this example:
|
||||
A filter that batches items. It works pretty much like slice just the other way round. It returns a list of lists with the given number of items. If you provide a second parameter this is used to fill up missing items. See this example:
|
||||
```
|
||||
<table>
|
||||
{%- for row in items|batch(3, ' ') %}
|
||||
|
|
@ -125,7 +125,7 @@ If the value is undefined it will return the passed default value, otherwise the
|
|||
{{ my_variable|default('my_variable is not defined') }}
|
||||
```
|
||||
|
||||
This will output the value of `my_variable` if the variable was defined, otherwise `'my_variable is not defined'`. If you want to use default with variables that evaluate to false you have to set the second parameter to true:
|
||||
This will output the value of `my_variable` if the variable was defined, otherwise `'my_variable is not defined'`. If you want to use default with variables that evaluate to false you have to set the second parameter to true:
|
||||
```
|
||||
{{ ''|default('the string was empty', true) }}
|
||||
```
|
||||
|
|
@ -147,18 +147,18 @@ Sort a dict and yield (key, value) pairs. [Python](../dev/programming/languages/
|
|||
```
|
||||
|
||||
##### escape(value)
|
||||
Replace the characters `&`, `<`, `>`, `'`, and `"` in the string with HTML-safe sequences. Use this if you need to display text that might contain such characters in [HTML](../internet/HTML.md).
|
||||
Replace the characters `&`, `<`, `>`, `'`, and `"` in the string with HTML-safe sequences. Use this if you need to display text that might contain such characters in [HTML](../internet/HTML.md).
|
||||
|
||||
If the object has an `__html__` method, it is called and the return value is assumed to already be safe for [HTML](../internet/HTML.md).
|
||||
If the object has an `__html__` method, it is called and the return value is assumed to already be safe for [HTML](../internet/HTML.md).
|
||||
|
||||
##### filesizeformat(value, binary: bool = False)
|
||||
Format the value like a ‘human-readable’ file size (i.e. 13 kB, 4.1 MB, 102 Bytes, etc). Per default decimal prefixes are used (Mega, Giga, etc.), if the second parameter is set to True the binary prefixes are used (Mebi, Gibi).
|
||||
Format the value like a ‘human-readable’ file size (i.e. 13 kB, 4.1 MB, 102 Bytes, etc). Per default decimal prefixes are used (Mega, Giga, etc.), if the second parameter is set to True the binary prefixes are used (Mebi, Gibi).
|
||||
|
||||
##### first(seq)
|
||||
Return the first item of a sequence.
|
||||
|
||||
##### float(value, default: float = 0.0)
|
||||
Convert the value into a floating point number. If the conversion doesn’t work it will return `0.0`. You can override this default using the first parameter.
|
||||
Convert the value into a floating point number. If the conversion doesn’t work it will return `0.0`. You can override this default using the first parameter.
|
||||
|
||||
##### forceescape(value)
|
||||
Enforce [HTML](../internet/HTML.md) escaping. This will probably double escape variables.
|
||||
|
|
@ -177,9 +177,9 @@ In most cases it should be more convenient and efficient to use the `%` operator
|
|||
```
|
||||
|
||||
##### groupby(value, attribute: str | int, default: Any | None = None, case_sensitive: bool = False)
|
||||
Group a sequence of objects by an attribute using [Python](../dev/programming/languages/Python.md)’s `itertools.groupby()`. The attribute can use dot notation for nested access, like `"address.city"`. Unlike [Python](../dev/programming/languages/Python.md)’s `groupby`, the values are sorted first so only one group is returned for each unique value.
|
||||
Group a sequence of objects by an attribute using [Python](../dev/programming/languages/Python.md)’s `itertools.groupby()`. The attribute can use dot notation for nested access, like `"address.city"`. Unlike [Python](../dev/programming/languages/Python.md)’s `groupby`, the values are sorted first so only one group is returned for each unique value.
|
||||
|
||||
For example, a list of `User` objects with a `city` attribute can be rendered in groups. In this example, `grouper` refers to the `city` value of the group.
|
||||
For example, a list of `User` objects with a `city` attribute can be rendered in groups. In this example, `grouper` refers to the `city` value of the group.
|
||||
```
|
||||
<ul>{% for city, items in users|groupby("city") %}
|
||||
<li>{{ city }}
|
||||
|
|
@ -190,14 +190,14 @@ For example, a list of `User` objects with a `city` attribute can be rendere
|
|||
{% endfor %}</ul>
|
||||
```
|
||||
|
||||
`groupby` yields namedtuples of `(grouper, list)`, which can be used instead of the tuple unpacking above. `grouper` is the value of the attribute, and `list` is the items with that value.
|
||||
`groupby` yields namedtuples of `(grouper, list)`, which can be used instead of the tuple unpacking above. `grouper` is the value of the attribute, and `list` is the items with that value.
|
||||
```
|
||||
<ul>{% for group in users|groupby("city") %}
|
||||
<li>{{ group.grouper }}: {{ group.list|join(", ") }}
|
||||
{% endfor %}</ul>
|
||||
```
|
||||
|
||||
You can specify a `default` value to use if an object in the list does not have the given attribute.
|
||||
You can specify a `default` value to use if an object in the list does not have the given attribute.
|
||||
```
|
||||
<ul>{% for city, items in users|groupby("city", default="NY") %}
|
||||
<li>{{ city }}: {{ items|map(attribute="name")|join(", ") }}</li>
|
||||
|
|
@ -208,16 +208,16 @@ You can specify a `default` value to use if an object in the list does not hav
|
|||
Return a copy of the string with each line indented by 4 spaces. The first line and blank lines are not indented by default.
|
||||
|
||||
Parameters:
|
||||
- **width** – Number of spaces, or a string, to indent by.
|
||||
- **first** – Don’t skip indenting the first line.
|
||||
- **blank** – Don’t skip indenting empty lines.
|
||||
- **width** – Number of spaces, or a string, to indent by.
|
||||
- **first** – Don’t skip indenting the first line.
|
||||
- **blank** – Don’t skip indenting empty lines.
|
||||
|
||||
##### items(value)
|
||||
Return an iterator over the `(key, value)` items of a mapping.
|
||||
Return an iterator over the `(key, value)` items of a mapping.
|
||||
|
||||
`x|items` is the same as `x.items()`, except if `x` is undefined an empty iterator is returned.
|
||||
`x|items` is the same as `x.items()`, except if `x` is undefined an empty iterator is returned.
|
||||
|
||||
This filter is useful if you expect the template to be rendered with an implementation of Jinja in another programming language that does not have a `.items()` method on its mapping type.
|
||||
This filter is useful if you expect the template to be rendered with an implementation of Jinja in another programming language that does not have a `.items()` method on its mapping type.
|
||||
```
|
||||
<dl>
|
||||
{% for key, value in my_dict|items %}
|
||||
|
|
@ -261,7 +261,7 @@ Return the smallest item from the sequence.
|
|||
Return a random item from the sequence.
|
||||
|
||||
##### replace(s: str, old: str, new: str, count: int | None = None)
|
||||
Return a copy of the value with all occurrences of a substring replaced with a new one. The first argument is the substring that should be replaced, the second is the replacement string. If the optional third argument `count` is given, only the first `count` occurrences are replaced:
|
||||
Return a copy of the value with all occurrences of a substring replaced with a new one. The first argument is the substring that should be replaced, the second is the replacement string. If the optional third argument `count` is given, only the first `count` occurrences are replaced:
|
||||
```
|
||||
{{ "Hello World"|replace("Hello", "Goodbye") }}
|
||||
-> Goodbye World
|
||||
|
|
@ -274,12 +274,12 @@ Return a copy of the value with all occurrences of a substring replaced with a n
|
|||
Reverse the object or return an iterator that iterates over it the other way round.
|
||||
|
||||
##### round(value: float, precision: int = 0, method: Literal\["common", "ceil", "floor"]' = 'common')
|
||||
Round the number to a given precision. The first parameter specifies the precision (default is `0`), the second the rounding method:
|
||||
- `'common'` rounds either up or down
|
||||
- `'ceil'` always rounds up
|
||||
- `'floor'` always rounds down
|
||||
Round the number to a given precision. The first parameter specifies the precision (default is `0`), the second the rounding method:
|
||||
- `'common'` rounds either up or down
|
||||
- `'ceil'` always rounds up
|
||||
- `'floor'` always rounds down
|
||||
|
||||
If you don’t specify a method `'common'` is used.
|
||||
If you don’t specify a method `'common'` is used.
|
||||
```
|
||||
{{ 42.55|round }}
|
||||
-> 43.0
|
||||
|
|
@ -287,7 +287,7 @@ If you don’t specify a method `'common'` is used.
|
|||
-> 42.5
|
||||
```
|
||||
|
||||
Note that even if rounded to 0 precision, a float is returned. If you need a real integer, pipe it through int:
|
||||
Note that even if rounded to 0 precision, a float is returned. If you need a real integer, pipe it through int:
|
||||
```
|
||||
{{ 42.55|round|int }}
|
||||
-> 43
|
||||
|
|
@ -297,7 +297,7 @@ Note that even if rounded to 0 precision, a float is returned. If you need a rea
|
|||
Strip leading and trailing characters, by default whitespace.
|
||||
|
||||
##### truncate(s: str, length: int = 255, killwords: bool = False, end: str = '...', leeway: int | None = None)
|
||||
Return a truncated copy of the string. The length is specified with the first parameter which defaults to `255`. If the second parameter is `true` the filter will cut the text at length. Otherwise it will discard the last word. If the text was in fact truncated it will append an ellipsis sign (`"..."`). If you want a different ellipsis sign than `"..."` you can specify it using the third parameter. Strings that only exceed the length by the tolerance margin given in the fourth parameter will not be truncated.
|
||||
Return a truncated copy of the string. The length is specified with the first parameter which defaults to `255`. If the second parameter is `true` the filter will cut the text at length. Otherwise it will discard the last word. If the text was in fact truncated it will append an ellipsis sign (`"..."`). If you want a different ellipsis sign than `"..."` you can specify it using the third parameter. Strings that only exceed the length by the tolerance margin given in the fourth parameter will not be truncated.
|
||||
```
|
||||
{{ "foo bar baz qux"|truncate(9) }}
|
||||
-> "foo..."
|
||||
|
|
@ -319,8 +319,8 @@ Returns a list of unique items from the given iterable.
|
|||
The unique items are yielded in the same order as their first occurrence in the iterable passed to the filter.
|
||||
|
||||
Parameters:
|
||||
- **case_sensitive** – Treat upper and lower case strings as distinct.
|
||||
- **attribute** – Filter objects with unique values for this attribute.
|
||||
- **case_sensitive** – Treat upper and lower case strings as distinct.
|
||||
- **attribute** – Filter objects with unique values for this attribute.
|
||||
|
||||
##### urlencode(value)
|
||||
Quote data for use in a URL path or query using UTF-8.
|
||||
|
|
@ -339,11 +339,11 @@ Count the words in that string.
|
|||
Wrap a string to the given width. Existing newlines are treated as paragraphs to be wrapped separately.
|
||||
|
||||
Parameters:
|
||||
- **s** – Original text to wrap.
|
||||
- **width** – Maximum length of wrapped lines.
|
||||
- **break_long_words** – If a word is longer than `width`, break it across lines.
|
||||
- **break_on_hyphens** – If a word contains hyphens, it may be split across lines.
|
||||
- **wrapstring** – String to join each wrapped line. Defaults to `Environment.newline_sequence`.
|
||||
- **s** – Original text to wrap.
|
||||
- **width** – Maximum length of wrapped lines.
|
||||
- **break_long_words** – If a word is longer than `width`, break it across lines.
|
||||
- **break_on_hyphens** – If a word contains hyphens, it may be split across lines.
|
||||
- **wrapstring** – String to join each wrapped line. Defaults to `Environment.newline_sequence`.
|
||||
|
||||
#### Builtin Tests
|
||||
##### boolean(value)
|
||||
|
|
@ -359,7 +359,7 @@ Return true if the variable is defined:
|
|||
{% endif %}
|
||||
```
|
||||
|
||||
See the `default()` filter for a simple way to set undefined variables.
|
||||
See the `default()` filter for a simple way to set undefined variables.
|
||||
|
||||
##### divisibleby(value, num: int)
|
||||
Check if a variable is divisible by a number.
|
||||
|
|
@ -375,7 +375,7 @@ Return true if the variable is odd.
|
|||
|
||||
### Statements
|
||||
#### for
|
||||
Loop over each item in a sequence. For example, to display a list of users provided in a variable called users:
|
||||
Loop over each item in a sequence. For example, to display a list of users provided in a variable called users:
|
||||
```
|
||||
<h1>Members</h1>
|
||||
<ul>
|
||||
|
|
@ -403,7 +403,7 @@ Inside of a for-loop block, you can access some special variables:
|
|||
| loop.nextitem | The item from the following iteration of the loop. Undefined during the last iteration. |
|
||||
| loop.changed(*val) | True if previously called with a different value (or not called at all). |
|
||||
|
||||
Within a for-loop, it’s possible to cycle among a list of strings/variables each time through the loop by using the special loop.cycle helper:
|
||||
Within a for-loop, it’s possible to cycle among a list of strings/variables each time through the loop by using the special loop.cycle helper:
|
||||
```
|
||||
{% for row in rows %}
|
||||
<li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
|
||||
|
|
@ -411,7 +411,7 @@ Within a for-loop, it’s possible to cycle among a list of strings/variables ea
|
|||
```
|
||||
|
||||
#### if
|
||||
The if statement in Jinja is comparable with the Python if statement. In the simplest form, you can use it to test if a variable is defined, not empty and not false:
|
||||
The if statement in Jinja is comparable with the Python if statement. In the simplest form, you can use it to test if a variable is defined, not empty and not false:
|
||||
```
|
||||
{% if kenny.sick %}
|
||||
Kenny is sick.
|
||||
|
|
@ -423,7 +423,7 @@ The if statement in Jinja is comparable with the Python if statement. In the s
|
|||
```
|
||||
|
||||
#### include
|
||||
The `include` tag renders another template and outputs the result into the current template.
|
||||
The `include` tag renders another template and outputs the result into the current template.
|
||||
```
|
||||
{% include 'header.html' %}
|
||||
Body goes here.
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ Monero's privacy features are implemented through a combination of cryptographic
|
|||
- Monero adjusts block size and fees dynamically, allowing for scalability and preventing congestion.
|
||||
|
||||
## monero-cli-wallet
|
||||
`monero-wallet-cli` is the wallet software shipped in the Monero archives. It is a console program, and manages an account.
|
||||
`monero-wallet-cli` is the wallet software shipped in the Monero archives. It is a console program, and manages an account.
|
||||
|
||||
Generate new wallet:
|
||||
```shell
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ Although RSS formats have evolved from as early as March 1999, it was between 20
|
|||
|
||||
## Example
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<?xml version="1.0" encoding="UTF-8" ?>
|
||||
<rss version="2.0">
|
||||
<channel>
|
||||
<title>RSS Title</title>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue