template generation

Configuration templates are often a means to provide end users with a description of the properties that should be set (or that could be overwritten) for the proper operation of an application or library. Based on the template, end users will then enter the concrete settings that are appropriate.

On the other hand, configuration "specs," as used for tscfg generation, are mainly intended to be used by the developer of such application or library.

tscfg can also generate template configuration files from the given spec so the developer does not have to manually create/edit such templates.

For example, from the configuration spec:

#! Comments starting with #! are not transferred to template.
# Description of the required endpoint section.
endpoint {
  # The path associated with the endpoint.
  # For example, "/home/foo/bar"
  #@envvar ENDPOINT_PATH
  path = "string"

  # Port for the endpoint service.
  #@envvar ENDPOINT_PORT
  port = "int | 8080"

  # Configuration for notifications
  notifications {
    # Emails to send notifications to.
    emails = [ {
      email: string
      name: "string?"
    } ]
  }

  # Some optional stuff.
  #@optional
  stuff {
    # Coefficient matrix
    coefs: [[double]]

    #@sysprop endpoint.port
    port2: int
  }
}

the generated template (with the --tpl <filename> option) will look like:

## 'endpoint': required section.
## Description of the required endpoint section.
endpoint {
  ## 'notifications': required section.
  ## Configuration for notifications
  notifications {
    ## 'emails': required list of object.
    ## Emails to send notifications to.
    emails = [{
      ## 'email': required string.
      email = ?
      
      ## 'name': optional string.
      #name = ?
    }, ...]
  }
  
  ## 'path': required string.
  ## The path associated with the endpoint.
  ## For example, "/home/foo/bar"
  path = ?
  path = ${?ENDPOINT_PATH}
  
  ## 'port': optional integer. Default: 8080.
  ## Port for the endpoint service.
  #port = ?
  port = ${?ENDPOINT_PORT}
  
  ## 'stuff': optional section.
  ## Some optional stuff.
  #stuff {
  #  ## 'coefs': required list of list of double.
  #  ## Coefficient matrix
  #  coefs = [[double, ...], ...]
  #  
  #  ## 'port2': required integer.
  #  port2 = ?
  #  port2 = ${endpoint.port}
  #}
}

Note:

Comments starting with #! are not transferred to the template.
The #@sysprop annotation allows to indicate the name of the system property that can be used to provide the value for the entry.
The #@envvar annotation allows to indicate the name of the environment variable that can be used to provide the value for the entry.
Optional values/sections are commented out.