10.1.2 Registering MySQL Shell Reports

To register your user-defined report with MySQL Shell, call the shell.registerReport() method in JavaScript or shell.register_report() in Python. The syntax for the method is as follows:

shell.registerReport(name, type, report[, description])

Where:

• name is a string giving the unique name of the report.

• type is a string giving the report type which determines the output format, either “list”, “report”, or “print”.

• report is the function to be called when the report is invoked.

• description is a dictionary with options that you can use to specify the options that the report supports, additional arguments that the report accepts, and help information that is provided in the MySQL Shell help system.

The name, type, and report parameters are all required. The report name must meet the following requirements:

• It must be unique in your MySQL Shell installation.

• It must be a valid scripting identifier, so the first character must be a letter or underscore character, followed by any number of letters, numbers, or underscore characters.

• It can be in mixed case, but it must still be unique in your MySQL Shell installation when converted to lower case.

The report name is not case-sensitive during the registration process and when running the report using the \show and \watch commands. The report name is case-sensitive when calling the corresponding API function at the shell.reports object. There you must call the function using the exact name that was used to register the report, whether you are in Python or JavaScript mode.

The optional dictionary contains the following keys, which are all optional:

brief

A brief description of the report.

details

A detailed description of the report, provided as an array of strings. This is provided when you use the \help command or the --help option with the \show command.

options

Any report-specific options that the report can accept. Each dictionary in the array describes one option, and must contain the following keys:

• name (string, required): The name of the option in the long form, which must be a valid scripting identifier.

• brief (string, optional): A brief description of the option.

• shortcut (string, optional): An alternate name for the option as a single alphanumeric character.

• details (array of strings, optional): A detailed description of the option. This is provided when you use the \help command or the --help option with the \show command.

• type (string, optional): The value type of the option. The permitted values are “string”, “bool”, “integer”, and “float”, with a default of “string” if type is not specified. If “bool” is specified, the option acts as a switch: it defaults to false if not specified, defaults to true (and accepts no value) when you run the report using the \show or \watch command, and must have a valid value when you run the report using the shell.reports object.

• required (bool, optional): Whether the option is required. If required is not specified, it defaults to false. If the option type is “bool” then required cannot be true.

• values (array of strings, optional): A list of allowed values for the option. Only options with type “string” can have this key. If values is not specified, the option accepts any values.

argc

A string specifying the number of additional arguments that the report expects, which can be one of the following:

• An exact number of arguments, which is specified as a single number.

• Zero or more arguments, which is specified as an asterisk.

• A range of argument numbers, which is specified as two numbers separated by a dash (for example, “1-5”).

• A range of argument numbers with a minimum but no maximum, which is specified as a number and an asterisk separated by a dash (for example, “1-*”).