The Base Configuration¶

The heart of ycleptic is the base configuration file, which the app developer must write. The base configuration is the developer’s expression of what a user can configure when they run the developer’s app. Below is an example:

attributes:
  - name: attribute_1
    type: dict
    text: This is a description of Attribute 1
    attributes:
      - name: attribute_1_1
        type: list
        text: This is a description of Attribute 1.1
        default:
          - 1
          - 2
          - 3
      - name: attribute_1_2
        type: str
        text: This is a description of Attribute 1.2
        options: [ValA, ValB]
  - name: attribute_2
    type: list
    text: Attribute 2 is interpretable as an ordered list of attributes
    attributes:
      - name: attribute_2a
        type: dict
        text: Attribute 2a is one possible attribute in a user's list
        attributes:
          - name: d2a_val1
            type: float
            text: A floating point value for Value 1 of Attribute 2a
            default: 1.0
          - name: d2a_val2
            type: int
            text: An int for Value 2 of Attribute 2a
            default: 6
          - name: d2_a_dict
            type: dict
            text: this is a dict
            default:
              a: 123
              b: 567
              c: 987
      - name: attribute_2b
        type: dict
        text: Attribute 2b is another possible attribute
        attributes:
          - name: val1
            type: str
            text: Val 1 of D2b
            default: a_nice_value
          - name: val2
            type: str
            text: Val 2 of D2b
            default: a_not_so_nice_value
  - name: attribute_3
    type: dict
    text: Attribute 3 has a lot of nesting
    attributes:
      - name: attribute_3_1
        type: dict
        text: This is a description of Attribute 3.1
        attributes:
          - name: attribute_3_1_1
            type: dict
            text: This is a description of Attribute 3.1.1
            attributes:
              - name: attribute_3_1_1_1
                type: dict
                text: This is a description of Attribute 3.1.1.1
                attributes:
                  - name: d3111v1
                    type: str
                    text: Value 1 of D 3.1.1.1
                    default: ABC
                  - name: d3111v2
                    type: float
                    text: Value 2 of D 3.1.1.1
                    required: False
      - name: attribute_3_2
        type: dict
        text: This is a description of Attribute 3.2
        attributes:
          - name: d322
            type: list
            text: Attribute 3.2.2 has a list of possible subattributes
            attributes:
              - name: d322a
                type: dict
                text: D 3.2.2a executes a series of flips
                attributes:
                  - name: nflips
                    type: int
                    text: Number of flips
                    default: 0
                  - name: flipaxis
                    type: str
                    text: Axis around which flip is performed
                    options: ['x','y','z']
              - name: d322b
                type: dict
                text: Subattribute D 3.2.2b saves the result
                attributes:
                  - name: filename
                    type: str
                    text: name of file to save
                    default: flipfile.dat

The base config must open with the single identifier attributes, under which is a list of one or more top-level attributes. Every attribute must have a declared type, and attributes can be nested.

type can be one of int, float, str, bool, list, or dict. The data content in a attribute is of type type unless two conditions are met:

type is either list or dict; and
the keyword attributes is present.

In this case, there are subattributes. If the type was dict, then the subattributes are children of the parent attribute and all operate at the same level. If the type was list, then the subattributes defined are expected to be ordered as a list of tasks that the parent attribute executes in the order they appear in the user’s config file. In the base file, both are entered as lists of attributes.

text is just meant for helpful text describing the attribute, and it can be completely free-form as long as it is on one line or blocked multiline using |.

There are four other keys that a attribute may have:

default: as you might expect, this are default values to assign to the attribute if the user “declares” the attribute but does not provide it any values.
required: a boolean. If False, that means no defaults are assigned; if a user declares this attribute without providing values, an error occurs, but a user need not declare this attribute at all. If True, the attribute must be declared (and if it is nested, all the antecedant attributes must also be declared).
options: a list of allowed values; if the user declares this attribute with a value not in this list, an error occurs.
docs: this is a subattribute that can have title, text, and example keys. title and text are strings used in automatic documentation generation using yclept make-doc. example is a YAML-format example of how to use the attribute in a config file. This is used in the documentation generation as well.