en cs

Nocheto script standard

This document describe the format of scripts for Nocheto ver. 3.1.0 and newer.

  1. Purpose of the scripts
  2. Placement of the scripts
  3. Script directory
  4. Content of the script directory
    1. Content of the cofig.ini file
    2. Content of the short.txt file
    3. Content of the long.txt file
  5. The executable(s)
  6. Useful commands for scripts

1. Purpose of the scripts

Scripts can create a new command(s) based on existing ones, define new aliases or both.

You shoud create one script per command.

2. Placement of the scripts

Nocheto consider a script any directory in the ~/.nocheto/scripts directory with a config.ini file in it.

3. Script directory

The name of the directory can constist only of small english letters, numbers or underscores ([a-z0-9_]+).
The name of the directory will become the name of the script in Nocheto.

4. Content of the script directory

~/.nocheto/scripts/
                <scriptname>/
                    config.ini
                    main.sh
                    lang/
                        en/
                            help/
                                short.txt
                                long.txt
                    LICENSE.txt
                    INSTALL.txt
                    README.txt
                    setup.ini

config.ini is the only required file.

main.sh is the default bash script executed by nocheto when the user calls script <scriptname>.
There might be more executable scripts called by script <scriptname>/<executable.sh>.

It is NOT recommended to create other scripts than the main.sh, unless they are ment to be executed by the main.sh executable.

short.txt file contains help shown by the help script command.
If the file doesn't exit, the script will be "hidden" (user will not see it in the help), but the script will be still working. This is perfectly OK for scripts which only define new aliases or scripts ment to be used by other scripts only.

long.txt file contains help shown by the help script <scriptname> command (or help! <scriptname>).

LICENSE.txt should contain the license to the script.

INSTALL.txt should contain install instructions to the script. Describe installation of everything the script depends on.

README.txt describe how to setup the script (if there is any configuration).

setup.ini or setup.xml etc. is the recomended name of a configuration file for the script (if needed). In the README.txt should be described what and how could/should the user change in it.

4.1 Content of the cofig.ini file

This configuration file can constist of these sections: [manifest], [setup], and [aliases]. None of these sections is required.

Example:
[manifest]
require="3.1.0"
version="1.0.0"

[setup]
stdin=none

[aliases]
@SCRIPT@="script @SCRIPT@"

See also About config files.

require3.1.0

require="3.1.0"

Minimal required version of nocheto. Nocheto will ignore scripts with require version number higher than its own.
If no require is defined, nocheto assume 3.1.0.

version3.1.0

version="1.1.0"

Version of the script (any string). Ignored by Nocheto.

stdin3.1.0

stdin="pgn"

What should nocheto send to the script standard input.

Possible values are:

none3.1.0
nothing will be sent
pgn3.1.0
PGN in the JSON format will be sent

If not defined, Nocheto assume none.

Works the same as aliases in the standard nocheto config files. The only difference is, that in the script configuration file nocheto is @SCRIPT@ replaced with the name of the script (= the name of the script's directory).

It is NOT recommended to define other aliases than @SCRIPT@="script @SCRIPT@". Especially not to define aliases with the same name as standard nocheto commands. Let the users create such aliases for themselves (you can recommend them in the README.txt).

You can create script which only define aliases in the config.ini (for example to translate standard commands to your language) and doesn't have any executables.

4.2 Content of the short.txt file

This file contains help shown by the help script command.

Every odd line is shown on the left side of the help, every even line is shown on the right side of the help.

Maximum recommended length of the odd lines is 25 characters.
Maximum recommended length of the even lines is 50 characters.

Nocheto substitutes the @SCRIPT@ string in this file with the name of the script.

Note: Even if scripts are executed by script <scriptname> command, if you add alias @SCRIPT@="script @SCRIPT@" in the [aliases] section in the config.ini file, it is recommended use the @SCRIPT@ only in the help as a command.

Example:
@SCRIPT@ [max] [username]
download [max] last games from lichess

played by [username]

4.3 Content of the long.txt file

This file contains the help shown by help script <scriptname>.

Maximum recommended length of a line in this file is 70 characters.

Nocheto substitutes the @SCRIPT@ string in this file with the name of the script.

5. The executable(s)

Executables must have set the execute privilege.

The default executable file name is main.sh. It is used when the script <scriptname> is called without the executable name.

Script can be called with any executable name, but the script must be located in the script directory:
script <scriptname>/<executable>

The standard output from the executable is interpreted by Nochto the same way as if the user wrote the input into the Nocheto input.

Example of the executable content:

#!/bin/bash
echo 'echo hello world!'

Nocheto can send data to executable through its standard input (see the pgn value in the stdin property in the [setup] section in the config.ini file).

Every input sent by nocheto is a text. This text might consists of one or more lines. The input is ended by "*MESSAGE_END\n" line.

If nocheto close the standard input or output, executable should exit as quickly as possible.

6. Useful commands for scripts

This is a list of the useful commands to use in your scripts.
You can use any nocheto command, but these were created to by used mainly in the scripts.