<commit_before># Chat commands

!!! note

    For security reasons commands can only be added via the
    command line. `./occ  talk:command:add --help` gives you
    a short overview of the required arguments, but they are
    explained here in more depth.

---

## "Add command" arguments

Argument | Allowed chars | Description
---|---|---
`cmd` | [a-z0-9] | The keyword the user has to type to run this command (min. 1, max. 64 characters)
`name` | * | The author name of the response that is posted by the command (min. 1, max. 64 characters)
`script` | * | Actual command that is being ran. The script must be executable by the user of your webserver. See the parameter table below for options. The script is invoked with `--help` as argument on set up, to check if it can be executed correctly.
`response` | 0-2 | Who should see the response: 0 - No one, 1 - User who executed the command, 2 - Everyone
`enabled` | 0-3 |  Who can use the command: 0 - No one, 1 - Moderators of the room, 2 - Logged in users, 3 - Everyone

## Script parameter

Parameter | Description
---|---
`{ROOM}` | The token of the room the command was used in
`{USER}` | ID of the user that called the command
`{ARGUMENTS}` | Everything the user write after the actual command
`{ARGUMENTS_DOUBLEQUOTE_ESCAPED}` | … but with double quotes `"` escaped.

## Example

* `/path/to/calc.sh`:

```
    while test $# -gt 0; do
      case "$1" in
        --help)
          echo "/calc - A Nextcloud Talk chat wrapper for gnome-calculator"
          echo " "
          echo "Simple equations: /calc 3 + 4 * 5"
          echo "Complex equations: /calc sin(3) + 3^3 * sqrt(5)"
          exit 0
          ;;
        *)
          break
          ;;
     esac
    done

    set -f
    echo "$@ ="
    echo $(gnome-calculator --solve="$@")
```
    
Please note, that your command should also understand the argument `--help`.
It should return a useful description, the first line is also displayed in a list of all commands when the user just types `/help`.

* `./occ` command used to add the command:

    ```
    ./occ talk:command:add calculator calculator "/path/to/calc.sh \"{ARGUMENTS_DOUBLEQUOTE_ESCAPED}\" {ROOM} {USER}" 1 3
    ```
    
* User input by user `my user id` in the chat of room `index.php/call/4tf349j`:
    
    ```
    /calculator 1 + 2 + 3 + "hello"
    ```

    
* Executed shell command:

    ```
    /path/to/calc.sh "1 + 2 + 3 + \"hello\"" '4tf349j' 'my user id'
    ```

## Aliases

It is also possible to define an alias for a command. This allows e.g. to get the `/help` command also with the german word `/hilfe`.

An alias for the `/calculator` command from above could be created using the following command:

```
./occ talk:command:add calc calculator "alias:calculator" 1 3
```

Now `/calculator 1 + 2 + 3` and `/calc 1 + 2 + 3` result in the same message.

**Note:** The enabled and response flag of the alias are ignored and the flags of the original command will be used and respected.<commit_msg>Better styling of the commands example<commit_after># Chat commands

!!! note

    For security reasons commands can only be added via the
    command line. `./occ  talk:command:add --help` gives you
    a short overview of the required arguments, but they are
    explained here in more depth.

---

## "Add command" arguments

Argument | Allowed chars | Description
---|---|---
`cmd` | [a-z0-9] | The keyword the user has to type to run this command (min. 1, max. 64 characters)
`name` | * | The author name of the response that is posted by the command (min. 1, max. 64 characters)
`script` | * | Actual command that is being ran. The script must be executable by the user of your webserver. See the parameter table below for options. The script is invoked with `--help` as argument on set up, to check if it can be executed correctly.
`response` | 0-2 | Who should see the response: 0 - No one, 1 - User who executed the command, 2 - Everyone
`enabled` | 0-3 |  Who can use the command: 0 - No one, 1 - Moderators of the room, 2 - Logged in users, 3 - Everyone

## Script parameter

Parameter | Description
---|---
`{ROOM}` | The token of the room the command was used in
`{USER}` | ID of the user that called the command
`{ARGUMENTS}` | Everything the user write after the actual command
`{ARGUMENTS_DOUBLEQUOTE_ESCAPED}` | … but with double quotes `"` escaped.

## Example

### Create `/path/to/calc.sh`

```
    while test $# -gt 0; do
      case "$1" in
        --help)
          echo "/calc - A Nextcloud Talk chat wrapper for gnome-calculator"
          echo " "
          echo "Simple equations: /calc 3 + 4 * 5"
          echo "Complex equations: /calc sin(3) + 3^3 * sqrt(5)"
          exit 0
          ;;
        *)
          break
          ;;
     esac
    done

    set -f
    echo "$@ ="
    echo $(gnome-calculator --solve="$@")
```
    
Please note, that your command should also understand the argument `--help`.
It should return a useful description, the first line is also displayed in a list of all commands when the user just types `/help`.

### Register command

```
./occ talk:command:add calculator calculator "/path/to/calc.sh \"{ARGUMENTS_DOUBLEQUOTE_ESCAPED}\" {ROOM} {USER}" 1 3
```

### Explanation
* User input by user `my user id` in the chat of room `index.php/call/4tf349j`:
    
    ```
    /calculator 1 + 2 + 3 + "hello"
    ```

    
* Executed shell command:

    ```
    /path/to/calc.sh "1 + 2 + 3 + \"hello\"" '4tf349j' 'my user id'
    ```

## Aliases

It is also possible to define an alias for a command. This allows e.g. to get the `/help` command also with the german word `/hilfe`.

An alias for the `/calculator` command from above could be created using the following command:

```
./occ talk:command:add calc calculator "alias:calculator" 1 3
```

Now `/calculator 1 + 2 + 3` and `/calc 1 + 2 + 3` result in the same message.


!!! note

    The enabled and response flag of the alias are ignored and the flags of the original command will be used and respected.
{'fraction_non_alphanumeric': 0.11353058510638298, 'fraction_numerical': 0.01761968085106383, 'mean_word_length': 2.734947237740534, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2921420', 'n_tokens_mistral': 1910, 'n_tokens_neox': 1768, 'n_words': 833}