Configuration

geomdl-cli allows users to override existing commands and configuration variables with and option add custom commands and configuration variables for the custom commands as well.

These changes can be directly applied by creating a special directory, .geomdl-cli. geomdl-cli automatically checks for the existence of this directory in the following locations:

  • user home directory (e.g. /home/user/.geomdl-cli, C:\Users\user\.geomdl-cli)
  • directory that you are running geomdl-cli

In the listed directories, geomdl-cli tries to load the custom configuration file config.json which is in JSON format with special directives discussed below. If the file doesn’t exist, geomdl-cli will continue working without any problems.

The following sections discuss the details of the JSON file and the customization options.

Structure of the config file

The config file is structured as follows:

{
  "configuration": {
    "test_configuration": "default configuration data"
  },
  "commands": {
    "test": {
      "desc": "command description, displayed when 'geomdl-cli help' is called",
      "module": "geomdl-test.test_module",
      "func": "test_function",
      "func_args": "0"
    }
  }
}

There are two main sections: configuration and commands, which are used to create user-defined configuration variables and commands for geomdl-cli.

In the example above, a command named test is created and this command will be executed when geomdl-cli test is called from the command line. A command definition can contain 4 elements:

  • desc contains the command description text displayed when geomdl help is called
  • func is the function to be called when the command is called, e.g. geomdl-cli test
  • func_args is the number of arguments that the function func takes
  • module points to the Python module that is required to import for calling the function func

Configuration variables will be available in the code via the following import statement:

from geomdl.cli import config

config is a dictionary containing the default and the user-defined configuration variables. In the example above, the configuration variable can be accessed using config['test_configuration'].

Creating commands

To create commands, the initial step is creating .geomdl-cli custom configuration directory and config.json file as instructed above. geomdl-cli tool adds the custom configuration directories to the Python path; therefore, any Python packages inside the custom configuration directory will be available to the geomdl-cli tool at the run time.

As an example, let’s create a directory geomdl-test inside the custom configuration directory and then create an empty file __init__.py inside geomdl-test directory. A directory with an empty __init__.py file defines a basic Python package. Additionally, let’s create another file test.py inside geomdl-test directory and put the following code in test.py file:

def test_function(**kwargs):
    print("my test function")

We have created a Python module with a simple function. Let’s assign this function to a command. Create the file config.json inside the custom configuration directory and put the following in the file:

{
  "commands": {
    "test": {
      "desc": "test command description",
      "module": "geomdl-test.test",
      "func": "test_function"
    }
  }
}

Now, let’s test our new command. Open your command-line and type geomdl-cli help. You will see your new command at the bottom of the list.

$ geomdl-cli help
GEOMDL-CLI - Run NURBS-Python (geomdl) from the command line

geomdl-cli is a command line tool for 'geomdl', a pure Python NURBS and B-Spline library.

Usage:

    geomdl-cli {command} {options}

Individual command help available via

    geomdl-cli {command} --help

Available commands:

    help                displays the help message
    version             displays the package version
    config              displays the configuration
    plot                plots single or multiple NURBS curves and surfaces using matplotlib
    eval                evaluates NURBS shapes and exports the evaluated points in various formats
    export              exports NURBS shapes in common CAD exchange formats
    test                test command description

Let’s also test the output of our new command. Type geomdl-cli test to see the command output.

$ geomdl-cli test
my test function

Let’s update our new command to take user input from the command line. Update test.py as follows:

def test_function(test_input, **kwargs):
    print("my test function prints", str(test_input))

and also update config.json

{
  "commands": {
    "test": {
      "desc": "test command description",
      "module": "geomdl-test.test",
      "func": "test_function",
      "func_args": 1
    }
  }
}

Now, our command expects 1 argument and prints it. In the following example the input argument is hey and testing_input:

$ geomdl-cli test hey
my test function prints hey

$ geomdl-cli test testing_input
my test function prints testing_input

If we omit the input, we will see a warning message:

$ geomdl-cli test
TEST expects 1 argument(s). Please run 'geomdl-cli test --help' for command help.

Let’s update our command to add a help text. Update test.py as follows:

def test_function(test_input, **kwargs):
    """\
TEST: Prints input arguments.

It would be good idea to put more details here...\
    """
    print("my test function prints", str(test_input))

and then type geomdl-cli test –help.

$ geomdl-cli test --help
TEST: Prints input arguments.

It would be good idea to put more details here...

We have successfully created a very simple command for geomdl-cli tool.

Overriding commands

Overriding commands is a very simple task. You might need to extend or change the functionality of an existing command, then overriding would be a simple option. Let’s update config.json as follows:

{
  "commands": {
    "export": {
      "desc": "test command description",
      "module": "geomdl-test.test",
      "func": "test_function",
      "func_args": 1
    }
  }
}

Please note that we changed the command name from test to export and we expect to see the output of test command when we run geomdl-cli export. Let’s first test the change with geomdl-cli help:

$ geomdl-cli help
GEOMDL-CLI - Run NURBS-Python (geomdl) from the command line

geomdl-cli is a command line tool for 'geomdl', a pure Python NURBS and B-Spline library.

Usage:

    geomdl-cli {command} {options}

Individual command help available via

    geomdl-cli {command} --help

Available commands:

    help                displays the help message
    version             displays the package version
    config              displays the configuration
    plot                plots single or multiple NURBS curves and surfaces using matplotlib
    eval                evaluates NURBS shapes and exports the evaluated points in various formats
    export              test command description

Have you noticed the change in export command’s description text? Let’s try it again with one of our previous examples:

$ geomdl-cli export testing_input
my test function prints testing_input

We have successfully overridden an existing geomdl-cli command.

Creating configuration variables

A configuration variable can be used to store default values for your custom command. Custom configuration variables are also defined in config.json file:

{
  "configuration": {
    "test_configuration": "default configuration text"
  },
  "commands": {
    "test": {
      "desc": "test command description",
      "module": "geomdl-test.test",
      "func": "test_function",
    }
  }
}

Let’s update test.py file as follows:

from geomdl.cli import config

def test_function(**kwargs):
    print("The value of the config variable is '" + config['test_configuration'] + "'")

Have you noticed that test_configuration is a key defined under configuration in config.json? Then, let’s test the command output:

$ geomdl-cli test
The value of the config variable is 'default configuration text'

Additionally, you can find the list of active configuration variables by typing geomdl-cli config.

$ geomdl-cli config
Configuration variables:
- user_override: True
- plot_vis: legend:off
- plot_name: None
- eval_format: screen
- export_format: json
- test_configuration: default configuration text

You can check commands.py file for examples on using configuration variables.

Overriding configuration variables

Overriding configuration variables is very similar to overriding commands. For instance, plot_vis is a configuration variable used by plot command. It defines the visualization configuration, such as displaying and hiding figure elements, like legend, axes, control points grid/polygon. The default configuration can be displayed by running geomdl-cli config command:

$ geomdl-cli config
Configuration variables:
- user_override: False
- plot_vis: legend:off
- plot_name: None
- eval_format: screen
- export_format: json

Let’s update config.json file as follows and override the value of plot_vis configuration variable:

{
  "configuration": {
    "plot_vis": "legend:on;ctrlpts:off"
  }
}

To verify the change, we can run geomdl-cli config command:

$ geomdl-cli config
Configuration variables:
- user_override: True
- plot_vis: legend:on;ctrlpts:off
- plot_name: None
- eval_format: screen
- export_format: json

If geomdl-cli loads the configuration variables from config.json file, the value of user_override variable changes to True.