TSYAMLRecCfgFieldData

Parse a record yaml file.

Synopsis

#include <ts/ts.h>
#include <ts/apidefs.h>

type TSYAMLRecCfgFieldData

Configuration field info.

typedef TSReturnCode (*TSYAMLRecNodeHandler)(const TSYAMLRecCfgFieldData *cfg, void *data);

Record field callback (called on every parsed record field(last node field on each YAML map))

TSReturnCode TSRecYAMLConfigParse(TSYaml node, TSYAMLRecNodeHandler handler, void *data);

Parse a YAML node following the record structure. Handler will be called on every final field.

Description

TSYAMLRecCfgFieldData

This contains information about the parsed record field. This will be passed back to the TSYAMLRecNodeHandler when you call TSRecYAMLConfigParse. This class holds the record name as well as the YAML node in case the caller wants to use this information to manipulate the record. The record name set is just a reflection of what was build from the YAML document parsing. This API will not perform any check against the internal ATS records. The record validation should be done by the caller, for instance, by calling TSHttpTxnConfigFind.

const char *field_name

A null-terminated string with the YAML field name. This holds the name of the scalar field. This is mostly to be used for logging.

const char *record_name

A null-terminated string with the record name which was built when parsing the YAML file. Example: proxy.config.diags.debug.enabled. Use this to validate or do any check base on a record name.

TSYaml value_node

A YAML::Node type holding the value of the field. Field value must be extracted from here. You can use the YAML::Node API to deduce the type, etc.

C:tye:

TSYAMLRecNodeHandler

Callback function for the caller to deal with each parsed node. cfg holds the details of the parsed field. data can be used to pass information along.

C:func:

TSRecYAMLConfigParse

Parse a YAML node following the record structure internals. On every scalar node the handler callback will be invoked with the appropriate parsed fields. data can be used to pass information along to every callback, this could be handy when you need to read/set data inside the TSYAMLRecNodeHandler to be read at a later stage.

Example:

ts:
  plugin_x:
    field_1: 1
    data:
      data_field_1: XYZ

TSRecYAMLConfigParse will parse the node and will call back on each field (field_1 and data_field_1)

A coding example using the above yaml file would look like:

TSReturnCode
field_handler(const TSYAMLRecCfgFieldData *cfg, void *data/*optional*/)
{
   YAML::Node value = *reinterpret_cast<YAML::Node *>(cfg->value_node);

   /*
    Th callback function will be invoked twice:

    1:
      cfg->field_name = field_1
      cfg->record_name = ts.plugin_x.field_1

    2:
      cfg->field_name = data_field_1
      cfg->record_name = ts.plugin_x.data.data_field_1


    If we need to check the type, we either get the type from the YAML::Node::Tag if set, or from @c TSHttpTxnConfigFind
   */

   return TS_SUCCESS;
}

void my_plugin_function_to_parse_a_records_like_yaml_file(const char* path) {
   try {
      YAML::Node root = YAML::LoadFile(path);

      auto ret = TSRecYAMLConfigParse(reinterpret_cast<TSYaml>(&root), field_handler, nullptr);
      if (ret != TS_SUCCESS) {
         TSError("We found an error while parsing '%s'.", path.c_str());
         return;
      }
  } catch(YAML::Exception const&ex) {
    // :(
  }
}

Return Values

TSRecYAMLConfigParse()

TSRecYAMLConfigParse() This will return TS_ERROR if there was an issue while parsing the file. Particular node errors should be handled by the TSYAMLRecNodeHandler implementation.