HCL Options Editor
The HCL Options Editor is a tool that enhances the editing experience of mainframe options files that are based on key-value pair syntax. This tool is experimental, and is provided as-is. While not required, the Zowe extension is recommended for access to mainframe files through Visual Studio Code.
Users can specify the syntax and definitions of an options format in a schema file using JSON, which will be used by the editor to provide features such as highlighting, hover descriptions, diagnostics, and autocompletion when editing options files of the specified type.
A JSON schema file is provided with this extension, which is used to specify the structure of the options format schema JSON definitions and aid in their creation. It is recommended that users name their format schema files with a '.hof.json' prefix, which the extension will recognise and provide schema validation and suggestions.
Contents
Software Requirements
Ensure that you meet the following prerequisite before using this extension:
Configuration
You can modifiy the HCL Options Editor configuration in the VS Code extension settings menu. The only option that needs to be configured is the schema directory.
This directory will contain the schema specifications of the options formats you would like to uses. All of your '*.hof.json' schema definition files should be contained within this directory. This can be specified as either a local directory path or as a file URL, (however only local directories are supported as a URL currently).
If the schema directory setting is left blank, then the extension will default to using the example schema directory.
Schema Specification
Format schema files should end with the suffix '*.hof.json', which allows the extension to provide JSON validation for schemas you create within VS Code, and will greatly aid in creating a new definition.
The root object of a schema definition can take the following fields:
identfier The ID used by the extension to identify this schema. (required)name The human readable name of the format defined by this schema. (required)version The version of the format defined by this schema. (required)format The object that contains the syntax and option definitions of the format. (required)detectedNames A list of file or DSN member name regex patterns that can be used to autodetect this format. (optional)
For example:
{
"identifier": "exampleformat",
"name": "Example Format",
"version": "1.0.0",
"detectedNames": [
{
"member": "MBRNAME"
},
".*\\.exampleformat"
],
"format": { ... }
}
The format object has the following structure:
{
"syntax": { ... },
"definitions: { ... }
}
Both fields are required.
Syntax
The syntax object can take the following fields:
Where = is the separator.
Where , is the separator.
Where the opening ( and closing ) brackets are the delimiters. Note: Currently, formats that have multiple values assigned to an option without value delimiters are not supported.
booleanTokens An object that contains patterns that identify true and false symbols used by your format. If this is left undefined, it will default to 'true' and 'false'. (optional)
string An object that contains patterns used to identify opening and closing quotation marks for strings, and the escape character. (optional)
blockComment An object that contains patterns used to identify beginning and ending block comment symbols. (optional)
lineComment A pattern used to identify line comment symbols. (optional)
keykeySeparator A pattern used to identify characters that separate key-value pairs in the format. For example:
Option1=50,Option3=20
Where , is the separator. (optional)
This is not compatible if valueDelimiter is undefined, and will cause keyValueSeparator to be ignored. (optional)
keyValueSepAfterEnum A boolean that indicates that enumerated values containing sub-options must have a following key-value separator. For example:
Option4=(50, SubOption1=(T, CDE1150))
(optional)
mustHaveKeyKeySeparator A boolean that indicates if an error should be shown if there is no separator between key-value pairs, even on a new line. (optional)
usesDSNType A boolean that indicates if the format uses DSNs (data set names) outside of quoted strings. (optional)
usesFilePathType A boolean that indicates if the format uses file paths outside of quoted strings. Options format that use this shouldn't have special characters in their file path. (optional)
For example:
{
"keyValueSeparator": "=",
"valueValueSeparator": ",",
"keyKeySeparator": ",",
"valueDelimiter": {
"begin": "\\(",
"end": "\\)"
},
"booleanTokens": {
"trueToken": "T",
"falseToken": "F"
},
"string": {
"begin": "'",
"end": "'",
"escapeCharacter": "\\"
},
"blockComment": {
"begin": "/\\*",
"end": "\\*/"
},
"lineComment": "//",
"isDelimiterKeyValueSeparator": false,
"keyValueSepAfterEnum": true,
"mustHaveKeyKeySeparator": true,
"usesDSNType": true,
"usesFilePathType": false
}
Definitions
The definitions object can take the following fields:
caseSensitive Boolean indicating if the option names are case sensitive. (required)unitTypes A list of possible numeric unit type objects. (optional)options A list of option definition set objects. (required)
For example:
{
"caseSensitive": true,
"unitTypes": [
{ ... },
{ ... }
],
"options": [
{ ... },
{ ... }
]
}
Unit Types
A unit type object can take the following fields:
unitID The identifier of the defined unit type.magnitudes A list of objects defining the unit symbols and their associated magnitude multipliers.isUnitBefore A boolean indicating if the unit symbol should be before the numeric value.
For example:
{
"unitID": "bytes",
"isUnitBefore": false,
"magnitudes": [
{
"unit": "B",
"numericMultiplier": 1
},
{
"unit": "KB",
"numericMultiplier": 1024
},
{
"unit": "MB",
"numericMultiplier": 1048576
}
]
}
Options
Options are contained within definition sets, which are used to group options together that are mutually exclusive (e.g. Option2 and Option2OFF). This is used by editor to provide warnings when two or more conflicting/duplicate options are present.
A definition set takes the following fields:
name The name of the definition set.keywords A list of keyword objects in this definition set.
For example:
{
"name": "Option1"
"keywords": [
{ ... },
{ ... }
]
}
Keyword
A keyword definition object takes the following fields:
name The human readable name of the keyword. Used to identify the keyword symbol. (required)description The description of the option keyword. (required)regex A regular expression pattern used to identify the keyword, if the name is not sufficient. The name will not be used if this is defined. (optional)parameterSet An object that defines the parameters that this option can take. This can also be a list of parameter set objects, if the option has multiple parameter signature overloads.
For example:
{
"name": "Option1",
"description": "Option1 is the first defined option.",
"regex": "(Option1|OptionOne|Opt1),
"parameterSet": { ... }
}
Parameter Set
A parameter set contains an ordered list of fixed parameters, and a specification of possible optional rest parameters, if any. It takes the following fields:
parameters A list of fixed parameter definitions. (required)restParameters An object definition that specifies the minimum and maximum number of rest parameters and the value types they can be. (optional)
Fixed Parameters
Fixed parameter specifications take the following fields:
name The name of the parameter. (required)description The description of the parameter. Currently unused. (optional)valueTypes A list of possible value types this parameter can take. (required)
Rest Parameters
Rest parameters are unfixed parameters provided at the end of an option's input. The specification of rest parameters can take the following fields:
restValueMin The minimum number of rest inputs that must be given to the option. (optional)restValueMax The maximum number of rest inputs can be given to the option. (optional)restTypes A list of possible value types the rest parameters can take. (required)
Value Type
Value types are the specific definition of the type of value that a parameter takes. There can be multiple value types per parameter because a parameter might take more than one value type (e.g. it might take a string or a numeric value).
type The data type. This can be one of: string, numeric, alphanumeric, boolean, enum, path or dsn. (required)unitID The ID of a numeric unit type, as specified in the unit types list. This is only used if the value type is numeric. (optional)numMin The minimum number a numeric value can take. (optional)numMax The maximum number a numeric value can take. (optional)stringMinLength The minimum length of a string or alphanumeric value. (optional)stringMaxLength The maximum length of a string or alphanumeric value. (optional)enumDefinition The definition of an enumerated value or sub-option, which is defined as another keyword. Only used if the type is enum. (optional)
Parameter Set Example
Overall a parameter set can look like this:
{
"parameters": [
{
"name": "param1",
"description": "Param1 is the first parameter of this option.",
"valueTypes": [
{
"type": "numeric",
"unitID": "bytes",
"numMin": 0,
"numMax": 262144,
},
{
"type": "enum",
"enumDefinition": {
"name": "EnumValue",
"description": "This enum value is an alternate input to the parameter."
}
}
]
}
],
"restParameters": {
"restValueMin": 0,
"restValueMax": 2,
"restTypes": [
{
"type": "string",
"stringMinLength": 2,
"stringMaxLength": 4
}
]
}
}
Useage
Once a schema definition has been created and placed within your specified schema directory, it will be used to provide editor features for documents where one of the following occurs:
The document has a header tag on the first line with the format 'hclopts/<identifier>/<version>', typically within a comment. For example:
// hclopts/exampleformat/1.0.0
The document has a file or DSN member name that matches one of the autodetection names specified in your schema definition.
You have manually selected the format you wish to use through the VS Code Command Palette ('HCL Options: Set Options Format...') or through the document editor right-click context menu.
Editor highlighting, validation, and IntelliSense will be available for your detected format. You can determine if your format has been properly detected if its name and version are shown in the bottom right on the status bar.
Palette Commands
The following palette commands are available in this extension:
Set Options Format Used to manually set the options format of the currently active editor. Not available if no editor is open.Reload Format Schemas Reload format schemas from the currently specified schema directory in the extension configuration settings. Use this if you have altered schemas and need to reload them.Display Example Format Schema Shows the example format schema which can be used for reference. This schema is referred to in the examples in this readme.
