cisco_node_utils 1.2.0 → 1.3.0

data/lib/cisco_node_utils/client/utils.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+#
+# January 2016, Glenn F. Matthews
+#
+# Copyright (c) 2015-2016 Cisco and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require_relative '../constants'
+require_relative '../logger'
+
+# Utility methods for clients of various RPC formats
+class Cisco::Client
+  # Make a best effort to convert a given input value to an Array.
+  # Strings are split by newlines, and nil becomes an empty Array.
+  def self.munge_to_array(val)
+    val = [] if val.nil?
+    val = val.split("\n") if val.is_a?(String)
+    val
+  end
+
+  def munge_to_array(val)
+    self.class.munge_to_array(val)
+  end
+
+  # Helper function that subclasses may use with get(data_format: :cli)
+  # Method for working with hierarchical show command output such as
+  # "show running-config". Searches the given multi-line string
+  # for all matches to the given value query. If context is provided,
+  # the matches will be filtered to only those that are located "under"
+  # the given context sequence (as determined by indentation).
+  #
+  # @param cli_output [String] The body of text to search
+  # @param context [*Regex] zero or more regular expressions defining
+  #                the parent configs to filter by.
+  # @param value [Regex] The regular expression to match
+  # @return [[String], nil] array of matching (sub)strings, else nil.
+  #
+  # @example Find all OSPF router names in the running-config
+  #   ospf_names = filter_cli(cli_output: running_cfg,
+  #                           value:      /^router ospf (\d+)/)
+  #
+  # @example Find all address-family types under the given BGP router
+  #   bgp_afs = filter_cli(cli_output: show_run_bgp,
+  #                        context:    [/^router bgp #{ASN}/],
+  #                        value:      /^address-family (.*)/)
+  def self.filter_cli(cli_output: nil,
+                      context:    nil,
+                      value:      nil)
+    return cli_output if cli_output.nil?
+    context ||= []
+    context.each { |filter| cli_output = find_subconfig(cli_output, filter) }
+    return nil if cli_output.nil? || cli_output.empty?
+    return cli_output if value.nil?
+    value = to_regexp(value)
+    match = cli_output.scan(value)
+    return nil if match.empty?
+    # find matches and return as array of String if it only does one match.
+    # Otherwise return array of array.
+    match.flatten! if match[0].is_a?(Array) && match[0].length == 1
+    match
+  end
+
+  # Returns the subsection associated with the given
+  # line of config
+  # @param [String] the body of text to search
+  # @param [Regex] the regex key of the config for which
+  # to retrieve the subsection
+  # @return [String, nil] the subsection of body, de-indented
+  # appropriately, or nil if no such subsection exists.
+  def self.find_subconfig(body, regexp_query)
+    return nil if body.nil? || regexp_query.nil?
+    regexp_query = to_regexp(regexp_query)
+
+    rows = body.split("\n")
+    match_row_index = rows.index { |row| regexp_query =~ row }
+    return nil if match_row_index.nil?
+
+    cur = match_row_index + 1
+    subconfig = []
+
+    until (/\A\s+.*/ =~ rows[cur]).nil? || cur == rows.length
+      subconfig << rows[cur]
+      cur += 1
+    end
+    return nil if subconfig.empty?
+    # Strip an appropriate minimal amount of leading whitespace from
+    # all lines in the subconfig
+    min_leading = subconfig.map { |line| line[/\A */].size }.min
+    subconfig = subconfig.map { |line| line[min_leading..-1] }
+    subconfig.join("\n")
+  end
+
+  # Helper method for CLI getters
+  #
+  # Convert a string or array of strings to a Regexp or array thereof
+  def self.to_regexp(input)
+    if input.is_a?(Regexp)
+      return input
+    elsif input.is_a?(Array)
+      return input.map { |item| to_regexp(item) }
+    else
+      # The string might be explicitly formatted as a regexp
+      if input[0] == '/' && input[-1] == '/'
+        # '/foo/' => %r{foo}
+        return Regexp.new(input[1..-2])
+      elsif input[0] == '/' && input[-2..-1] == '/i'
+        # '/foo/i' => %r{foo}i
+        return Regexp.new(input[1..-3], Regexp::IGNORECASE)
+      else
+        # 'foo' => %r{^foo$}i
+        return Regexp.new("^#{input}$", Regexp::IGNORECASE)
+      end
+    end
+  end
+
+  # Helper method for get(data_format: :nxapi_structured).
+  #
+  # @param data [Array, Hash] structured output from node
+  # @param keys [Array] lookup sequence
+  def self.filter_data(data: nil,
+                       keys: nil)
+    return nil if data.nil?
+    keys ||= []
+    keys.each do |filter|
+      # if filter is a Hash and data is an array, check each
+      # array index (which should return another hash) to see if
+      # it contains the matching key/value pairs specified in token,
+      # and return the first match (or nil)
+      if filter.kind_of?(Hash)
+        fail "Expected Array, got #{data.class}" unless data.is_a? Array
+        data = data.select { |x| filter.all? { |k, v| x[k] == v } }
+        fail "Multiple matches found for #{filter}" if data.length > 1
+        fail "No match found for #{filter}" if data.length == 0
+        data = data[0]
+      else # data is array or hash
+        filter = filter.to_i if data.is_a? Array
+        fail "No key \"#{filter}\" in #{data}" if data[filter].nil?
+        data = data[filter]
+      end
+    end
+    data
+  end
+
+  # Helper method for calls into third-party code - suppresses Ruby warnings
+  # for the given block since we have no control over that code.
+  def self.silence_warnings(&block)
+    warn_level = $VERBOSE
+    $VERBOSE = nil
+    result = block.call
+    $VERBOSE = warn_level
+    result
+  end
+end

data/lib/cisco_node_utils/cmd_ref/README_YAML.md

@@ -12,25 +12,27 @@ This document describes the structure and semantics of these files.
   * [Wildcard substitution](#wildcard-substitution)
     * [Printf-style wildcards](#printf-style-wildcards)
     * [Key-value wildcards](#key-value-wildcards)
+      * [Optional tokens in key-value lists](#optional-tokens-in-key-value-lists)
 * [Advanced attribute definition](#advanced-attribute-definition)
   * [`_template`](#_template)
-  * [Platform and API variants](#platform-and-api-variants)
+  * [Data format variants](#data-format-variants)
+  * [Platform variants](#platform-variants)
   * [Product variants](#product-variants)
   * [`_exclude`](#_exclude)
+  * [YAML anchors and aliases](#YAML-anchors-and-aliases)
   * [Combinations of these](#combinations-of-these)
 * [Attribute properties](#attribute-properties)
-  * [`config_get`](#config_get)
-  * [`config_get_token`](#config_get_token)
-  * [`config_get_token_append`](#config_get_token_append)
-  * [`config_set`](#config_set)
-  * [`config_set_append`](#config_set_append)
+  * [`get_data_format`](#get_data_format)
+  * [`get_command`](#get_command)
+  * [`get_context`](#get_context)
+  * [`get_value`](#get_value)
+  * [`set_context`](#set_context)
+  * [`set_value`](#set_value)
   * [`default_value`](#default_value)
   * [`default_only`](#default_only)
   * [`kind`](#kind)
   * [`multiple`](#multiple)
   * [`auto_default`](#auto_default)
-  * [`test_config_get` and `test_config_get_regex`](#test_config_get-and-test_config_get_regex)
-  * [`test_config_result`](#test_config_result)
 * [Style Guide](#style-guide)
 
 ## Introduction
@@ -59,14 +61,14 @@ An example:
 ```yaml
 # vtp.yaml
 domain:
-  config_get: "show vtp status"
-  config_get_token: "domain_name"
-  config_set: "vtp domain <domain>"
+  get_command: "show vtp status"
+  get_value: "domain_name"
+  set_value: "vtp domain <domain>"
 
 filename:
-  config_get: "show running vtp"
-  config_get_token: '/vtp file (\S+)/'
-  config_set: "<state> vtp file <filename>"
+  get_command: "show running vtp"
+  get_value: '/vtp file (\S+)/'
+  set_value: "<state> vtp file <filename>"
   default_value: ""
 ```
 
@@ -79,16 +81,36 @@ needed. In the above, example 'domain' does not have a value defined for
 
 ### Wildcard substitution
 
-The `config_get_token` and `config_set` properties (and their associated
-`_append` variants) all support two forms of wildcarding - printf-style and
-key-value. Key-value is generally preferred, as described below.
+The `(get|set)_(context|value)` properties all support two forms of wildcarding - printf-style and key-value. Each has advantages and disadvantages but key-value is generally preferred for a number of reasons as seen below:
+
+<table>
+<tr><th></th><th>Advantages</th><th>Disadvantages</th></tr>
+<tr>
+  <th>Printf-style</th>
+  <td><ul><li>Quick to implement, concise</li></ul></td>
+  <td><ul><li>Can't handle differences in wildcard order between nodes</li>
+    <li>Can't handle differences in wildcard count between nodes</li>
+    <li>Can't support optional tokens (e.g., VRF context)</li>
+    <li>Less readable in Ruby code (not obvious which parameters mean what)</li>
+  </ul></td>
+</tr><tr>
+  <th>Key-Value</th>
+  <td><ul><li>Can handle differences in wildcard order/count between nodes</li>
+    <li>Can handle differences in which wildcards are used on various nodes</li>
+    <li>Can flag tokens as optional (see below)</li>
+    <li>More readable Ruby code due to parameter labels</li>
+  </ul></td>
+  <td><ul><li>Slightly more complex to implement than printf-style</li>
+    <li>Slightly more verbose YAML and Ruby code</li>
+  </ul></td>
+</tr></table>
 
 #### Printf-style wildcards
 
 ```yaml
 # tacacs_server_host.yaml
 encryption:
-  config_set: '%s tacacs-server host %s key %s %s'
+  set_value: '%s tacacs-server host %s key %s %s'
 ```
 
 This permits parameter values to be passed as a simple sequence to generate the resulting string or regexp:
@@ -108,7 +130,8 @@ the Ruby code.
 ```yaml
 # ospf.yaml
 auto_cost:
-  config_set: ['router ospf <name>', 'auto-cost reference-bandwidth <cost> <type>']
+  set_context: 'router ospf <name>'
+  set_value: 'auto-cost reference-bandwidth <cost> <type>'
 ```
 
 This requires parameter values to be passed as a hash:
@@ -119,16 +142,33 @@ irb(main):016:0> ref.config_set(name: 'red', cost: '40', type: 'Gbps')
 => ["router ospf red", "auto-cost reference-bandwidth 40 Gbps"]
 ```
 
-Array elements that contain a parameter that is *not* included in the argument hash are not included in the result:
+Key-value wildcards are moderately more complex to implement than Printf-style wildcards but they are more readable in the Ruby code and are flexible enough to handle significant platform differences in CLI. Key-value wildcards are therefore the recommended approach for new development.
 
-```ruby
-irb(main):017:0> ref.config_set(name: 'red', cost: '40')
-=> ["router ospf red"]
+##### Optional tokens in key-value lists
+
+When defining `(get|set)_context` entries with key-value wildcards, it is possible to mark some or all of the tokens in the context as optional by prepending `(?)` to them. A common example of this is to support properties that can be defined either globally or under a VRF routing context:
+
+```yaml
+# bgp.yaml
+confederation_peers:
+  ios_xr:
+    get_context:
+      - 'router bgp <asnum>'
+      - '(?)/^vrf <vrf>$/i'
+      - 'bgp confederation peers'
 ```
 
-If this process results in an empty array, then an `ArgumentError` is raised to indicate that not enough parameters were supplied.
+An optional token will be omitted if any of the wildcards in this token do not have an assigned value. By contrast, mandatory tokens (i.e., any token not explicitly flagged as optional) will raise an ArgumentError if wildcard values are missing:
 
-Key-value wildcards are moderately more complex to implement than Printf-style wildcards but they are more readable in the Ruby code and are flexible enough to handle significant platform differences in CLI. Key-value wildcards are therefore the recommended approach for new development.
+```ruby
+irb(main):003:0> ref = node.cmd_ref.lookup('bgp', 'confederation_peers')
+irb(main):006:0> ref.getter(asnum: 1)[:context]
+=> ["router bgp 1", "bgp confederation peers"]
+irb(main):007:0> ref.getter(asnum: 1, vrf: 'red')[:context]
+=> ["router bgp 1", "/^vrf red$/i", "bgp confederation peers"]
+irb(main):008:0> ref.getter(vrf: 'red')[:context]
+ArgumentError: No value specified for 'asnum' in 'router bgp <asnum>'
+```
 
 ## Advanced attribute definition
 
@@ -143,17 +183,17 @@ with the `interface <name>` configuration command. Thus, you might have:
 ```yaml
 # interface.yaml
 _template:
-  config_get: 'show running-config interface all'
-  config_get_token: '/^interface <name>$/'
-  config_set: 'interface <name>'
+  get_command: 'show running-config interface all'
+  get_context: 'interface <name>'
+  set_context: 'interface <name>'
 
 access_vlan:
-  config_get_token_append: '/^switchport access vlan (.*)$/'
-  config_set_append: 'switchport access vlan <number>'
+  get_value: 'switchport access vlan (.*)'
+  set_value: 'switchport access vlan <number>'
 
 description:
-  config_get_token_append: '/^description (.*)$/'
-  config_set_append: 'description <desc>'
+  get_value: '/^description (.*)$/'
+  set_value: 'description <desc>'
 
 ...
 ```
@@ -163,64 +203,67 @@ instead of the more repetitive (but equally valid):
 ```yaml
 # interface.yaml
 access_vlan:
-  config_get: 'show running interface all'
-  config_get_token: ['/^interface <name>$/i', '/^switchport access vlan (.*)$/']
-  config_set: ['interface <name>', 'switchport access vlan <number>']
+  get_command: 'show running interface all'
+  get_context: 'interface <name>'
+  get_value: 'switchport access vlan (.*)'
+  set_context: 'interface <name>'
+  set_value: 'switchport access vlan <number>'
 
 description:
-  config_get: 'show running-config interface all'
-  config_get_token: ['/^interface <name>$/i', '/^description (.*)$/']
-  config_set: ['interface <name>', 'description <desc>']
+  get_command: 'show running-config interface all'
+  get_context: 'interface <name>'
+  get_value: '/^description (.*)$/'
+  set_context: 'interface <name>'
+  set_value: 'description <desc>'
 
 ...
 ```
 
-### Platform and API variants
+### Data format variants
 
-Clients for different Cisco platforms may use different APIs. Currently the only supported API is NXAPI (CLI-based API used for Cisco Nexus platforms). Often the CLI or other input/output formats (YANG, etc.) needed will vary between APIs, so the YAML must be able to accomodate this.
+Clients for different Cisco platforms may use different data formats. NXAPI (used for Cisco Nexus platforms) supports a CLI-based data format (essentially a wrapper for the Nexus CLI) as well as a NXAPI-specific structured format for some 'show' commands. Currently the gRPC client provided here (used for Cisco IOS XR platforms) supports a CLI-based format. Other platforms may have other formats such as YANG. As different formats have different requirements, the YAML must be able to accommodate this.
 
-Any of the attribute properties can be subdivided by platform and API type by using the
-combination of API type and platform type as a key. For example, interface VRF membership defaults to "" (no VRF) on both Nexus and IOS XR platforms, but the CLI is 'vrf member <vrf>' for Nexus and 'vrf <vrf>' for IOS XR. Thus, the YAML could be written as:
+CLI is the lowest common denominator, so YAML entries not otherwise flagged as applicable to a specific API type will be assumed to reference CLI. Other API types can be indicated by using the API type as a key (`cli`, `nxapi_structured`, `yang`, etc.). For example, Nexus platforms support a structured form of 'show version', while other clients might use the same command but will need to parse CLI output with a regular expression:
 
 ```yaml
-# interface.yaml
-vrf:
-  default_value: ""
-  cli_nexus:
-    config_get_token_append: '/^vrf member (.*)/'
-    config_set_append: "<state> vrf member <vrf>"
+# show_version.yaml
+description:
+  get_command: 'show version'
+  nexus:
+    data_format: nxapi_structured
+    get_value: 'chassis_id'
+  else:
+    data_format: cli
+    get_value: '/Hardware\n  cisco (([^(\n]+|\(\d+ Slot\))+\w+)/'
 ```
 
-and later, once we have a CLI-based API for IOS XR, this could be extended:
+### Platform variants
+
+Even for clients using the same data format (e.g., CLI), there may be differences between classes of Cisco platform.  Any of the attribute properties can be subdivided by platform type by using the platform type as a key. For example, interface VRF membership defaults to `""` (no VRF) on both Nexus and IOS XR platforms, but the CLI is `vrf member <vrf>` for Nexus and `vrf <vrf>` for IOS XR. Thus, the YAML could be written as:
 
 ```yaml
 # interface.yaml
 vrf:
   default_value: ""
-  cli_nexus:
-    config_get_token_append: '/^vrf member (.*)/'
-    config_set_append: "<state> vrf member <vrf>"
-  cli_ios_xr:
-    config_get_token_append: '/^vrf (.*)/'
-    config_set_append: "<state> vrf <vrf>"
+  nexus:
+    get_value: 'vrf member (.*)'
+    set_value: "<state> vrf member <vrf>"
+  ios_xr:
+    get_value: 'vrf (.*)'
+    set_value: "<state> vrf <vrf>"
 ```
 
 ### Product variants
 
-Any of the attribute properties can be subdivided by platform product ID string
-using a regexp against the product ID as a key. When one or more regexp keys
-are defined thus, you can also use the special key `else` to provide values
-for all products that do not match any of the given regexps:
+Various product categories can also be used as keys to subdivide attributes as needed. Supported categories currently include the various Nexus switch product lines (`N3k`, `N5k`, `N6k`. `N7k`, `N9k`). When using one or more product keys in this fashion, you can also use the special key `else` to handle all other products not specifically called out:
 
 ```yaml
 # show_version.yaml
 system_image:
-  /N9/:
-    config_get_token: "kick_file_name"
-    test_config_get_regex: '/.*NXOS image file is: (.*)$.*/'
+  N9k:
+    get_value: "kick_file_name"
   else:
-    config_get_token: "isan_file_name"
-    test_config_get_regex: '/.*system image file is:    (.*)$.*/'
+    get_value: "isan_file_name"
 ```
 
 ### `_exclude`
@@ -230,7 +273,7 @@ Related to product variants, an `_exclude` entry can be used to mark an entire f
 ```yaml
 # fabricpath.yaml
 ---
-_exclude: [/N3/, /N9/]
+_exclude: [N3k, N9k]
 
 _template:
 ...
@@ -241,221 +284,176 @@ Individual feature attributes can also be excluded in this way:
 ```yaml
 attribute:
   _exclude:
-    - /N7/
+    - N7k
   default_value: true
-  config_get: 'show attribute'
-  config_set: 'attribute'
+  get_command: 'show attribute'
+  set_value: 'attribute'
 ```
 
 When a feature or attribute is excluded in this way, attempting to call `config_get` or `config_set` on an excluded node will result in a `Cisco::UnsupportedError` being raised. Calling `config_get_default` on such a node will always return `nil`.
 
+### YAML anchors and aliases
+
+To reduce repetition, YAML provides the functionality of [node anchors](http://www.yaml.org/spec/1.2/spec.html#id2785586) and [node aliases](http://www.yaml.org/spec/1.2/spec.html#id2786196). A node anchor can be defined with the syntax `&anchor_name` and other nodes can alias against this anchor with the syntax `*anchor_name`. For example, to provide the same data for N3k and N9k platforms:
+
+```yaml
+  vn_segment_vlan_based:
+   # MT-lite only
+   N3k: &vn_segment_vlan_based_mt_lite
+     kind: boolean
+     config_get: 'show running section feature'
+     config_get_token: '/^feature vn-segment-vlan-based$/'
+     config_set: 'feature vn-segment-vlan-based'
+     default_value: false
+   N9k: *vn_segment_vlan_based_mt_lite
+```
+
 ### Combinations of these
 
 In many cases, supporting multiple platforms and multiple products will require
 using several or all of the above options.
 
-Using `_template` in combination with API variants:
+Using `_template` in combination with platform and data format variants:
 
 ```yaml
 # inventory.yaml
 _template:
-  cli_ios_xr:
-    config_get: 'show inventory | begin "Rack 0"'
-    test_config_get: 'show inventory'
-  cli_nexus:
-    config_get: 'show inventory'
-    test_config_get: 'show inventory | no-more'
+  ios_xr:
+    get_command: 'show inventory | begin "Rack 0"'
+    get_data_format: cli
+  nexus:
+    get_command: 'show inventory'
+    get_data_format: nxapi_structured
 
 productid:
-  cli_ios_xr:
-    config_get_token: '/PID: ([^ ,]+)/'
-  cli_nexus:
-    config_get_token: ["TABLE_inv", "ROW_inv", 0, "productid"]
+  ios_xr:
+    get_value: '/PID: ([^ ,]+)/'
+  nexus:
+    get_context: ["TABLE_inv", "ROW_inv", 0]
+    get_value: "productid"
 ```
 
 Using platform variants and product variants together:
 
 ```yaml
-# inventory.yaml
-description:
-  config_get_token: "chassis_id"
-  cli_nexus:
-    /N7/:
-      test_config_get_regex: '/.*Hardware\n  cisco (\w+ \w+ \(\w+ \w+\) \w+).*/'
+# interface.yaml
+negotiate_auto_portchannel:
+  kind: boolean
+  _exclude: [ios_xr]
+  nexus:
+    N7k:
+      default_only: false
     else:
-      test_config_get_regex: '/Hardware\n  cisco (([^(\n]+|\(\d+ Slot\))+\w+)/'
-  cli_ios_xr:
-    config_get: 'show inventory | inc "Rack 0"'
-    config_get_token: '/DESCR: "(.*)"/'
-    test_config_get: 'show inventory | inc "Rack 0"'
-    test_config_get_regex: '/DESCR: "(.*)"/'
+      get_value: '(no )?negotiate auto'
+      set_value: "<state> negotiate auto"
+      default_value: true
 ```
 
 ## Attribute properties
 
-### `config_get`
+### `get_data_format`
+
+The `get_data_format` key is optionally used to specify which data format a given client should use for a get operation. Supported values are `cli` and `nxapi_structured`. If not specified, this key defaults to `cli`.
+
+```yaml
+# inventory.yaml
+productid:
+  get_command: 'show inventory'
+  nexus:
+    get_data_format: nxapi_structured
+    get_context: ['TABLE_inv', 'ROW_inv', 0]
+```
+
+### `get_command`
 
-`config_get` must be a single string representing the CLI command (usually a
+`get_command` must be a single string representing the CLI command (usually a
 `show` command) to be used to display the information needed to get the
 current value of this attribute.
 
 ```yaml
 # interface_ospf.yaml
 area:
-  config_get: 'show running interface all'
+  get_command: 'show running interface all'
 ```
 
-### `config_get_token`
-
-`config_get_token` can be a single string, a single regex, an array of strings,
-or an array of regexs.
+### `get_context`
 
-If this value is a string or array of strings, then the `config_get` command
-will be executed to produce _structured_ output and the string(s) will be
-used as lookup keys.
+`get_context` is an optional sequence of tokens used to filter the output from the `get_command` down to the desired context where the `get_value` can be found. For CLI properties, these tokens are implicitly Regexps used to filter down through the hierarchical CLI output, while for `nxapi_structured` properties, the tokens are used as string keys.
 
-**WARNING: structured output, although elegant, may not be supported for all commands or all platforms. Use with caution.**
-
-```yaml
-# show_version.yaml
-cpu:
-  config_get: 'show version'
-  config_get_token: 'cpu_name'
-  # config_get('show_version', 'cpu') returns structured_output['cpu_name']
-```
 
 ```yaml
 # inventory.yaml
 productid:
-  config_get: 'show inventory'
-  config_get_token: ['TABLE_inv', 'ROW_inv', 0, 'productid']
-  # config_get('inventory', 'productid') returns
-  # structured_output['TABLE_inv']['ROW_inv'][0]['productid']
+  get_command: 'show inventory'
+  nexus:
+    get_data_format: nxapi_structured
+    get_context: ['TABLE_inv', 'ROW_inv', 0]
+    get_value: 'productid'
+    # config_get('inventory', 'productid') returns
+    # structured_output['TABLE_inv']['ROW_inv'][0]['productid']
 ```
 
-If this value is a regexp or array of regexps, then the `config_get` command
-will be executed to produce _plaintext_ output.
-
-For a single regexp, it will be used to match against the plaintext.
-
-```yaml
-# memory.yaml
-total:
-  config_get: 'show system resources'
-  config_get_token: '/Memory.* (\S+) total/'
-  # config_get('memory', 'total') returns
-  # plaintext_output.scan(/Memory.* (\S+) total/)
-```
-
-For an array of regex, then the plaintext is assumed to be hierarchical in
-nature (like `show running-config`) and the regexs are used to filter down
-through the hierarchy.
-
 ```yaml
 # interface.yaml
 description:
-  config_get: 'show running interface all'
-  config_get_token: ['/^interface <name>$/i', '/^description (.*)/']
-  # config_get('interface', 'description', name: 'Ethernet1/1') gets the
-  # plaintext output, finds the subsection under /^interface Ethernet1/1$/i,
-  # then finds the line matching /^description (.*)$/ in that subsection
+  get_command: 'show running interface all'
+  ios_xr:
+    get_context: 'interface <name>'
+    get_value: '/^description (.*)/'
+    # config_get('interface', 'description', name: 'Ethernet1/1') gets the
+    # plaintext output, finds the subsection under /^interface Ethernet1/1$/i,
+    # then finds the line matching /^description (.*)$/ in that subsection
 ```
 
-### `config_get_token_append`
+If the context is defined using the recommended key-value wildcarding style, it is possible to define individual tokens as [optional](#optional-tokens-in-key-value-lists).
 
-When using a `_template` section, an attribute can use
-`config_get_token_append` to extend the `config_get_token` value provided by
-the template instead of replacing it:
-
-```yaml
-# interface.yaml
-_template:
-  config_get: 'show running-config interface all'
-  config_get_token: '/^interface <name>$/i'
+### `get_value`
 
-description:
-  config_get_token_append: '/^description (.*)$/'
-  # config_get_token value for 'description' is now:
-  # ['/^interface <name>$/i', '/^description (.*)$/']
-```
+`get_value` is the specific token used to locate the desired value. As with `get_context`, this is implicitly a Regexp for a CLI command, and implicitly a Hash key for a `nxapi_structured` command.
 
-This can also be used to specify conditional tokens which may or may not be
-used depending on the set of parameters passed into `config_get()`:
+When using a `_template` section, a common pattern is to place the `get_context` in the template to be shared among all attributes, then have specific `get_value` defined for each individual attribute:
 
 ```yaml
-# ospf.yaml
+# interface.yaml
 _template:
-  config_get: 'show running ospf all'
-  config_get_token: '/^router ospf <name>$/'
-  config_get_token_append:
-    - '/^vrf <vrf>$/'
-
-router_id:
-  config_get_token_append: '/^router-id (\S+)$/'
-```
+  get_command: 'show running-config interface all'
+  get_context: 'interface <name>'
 
-In this example, the `vrf` parameter is optional and a different
-`config_get_token` value will be generated depending on its presence or absence:
+description:
+  get_value: '/^description (.*)$/'
 
-```ruby
-irb(main):008:0> ref = cr.lookup('ospf', 'router_id')
-irb(main):012:0> ref.config_get_token(name: 'red')
-=> [/^router ospf red$/, /^router-id (\S+)?$/]
-irb(main):013:0> ref.config_get_token(name: 'red', vrf: 'blue')
-=> [/^router ospf red$/, /^vrf blue$/, /^router-id (\S+)?$/]
+duplex:
+  get_value: 'duplex (.*)'
 ```
 
-### `config_set`
+### `set_context`
 
-The `config_set` parameter is a string or array of strings representing the
-configuration CLI command(s) used to set the value of the attribute.
+The optional `set_context` parameter is a sequence of strings representing the
+configuration CLI command(s) used to enter the necessary configuration submode before configuring the attribute's `set_value`.
 
 ```yaml
 # interface.yaml
-create:
-  config_set: 'interface <name>'
-
 description:
-  config_set: ['interface <name>', 'description <desc>']
+  set_context: ['interface <name>']
+  set_value: 'description <desc>'
 ```
 
-### `config_set_append`
+If the context is defined using the recommended key-value wildcarding style, it is possible to define individual tokens as [optional](#optional-tokens-in-key-value-lists).
+
+### `set_value`
 
-When using a `_template` section, an attribute can use `config_set_append` to
-extend the `config_set` value provided by the template instead of replacing it:
+`set_value` is the specific command used to set the desired attribute value. As with `get_value`, a common pattern is to specify a `set_context` in the `_template` section and specify `set_value` on a per-attribute basis:
 
 ```yaml
 # interface.yaml
 _template:
-  config_set: 'interface <name>'
+  set_context: ['interface <name>']
 
 access_vlan:
-  config_set_append: 'switchport access vlan <number>'
-  # config_set value for 'access_vlan' is now:
-  # ['interface <name>', 'switchport access vlan <number>']
-```
-
-Much like `config_get_token_append`, this can also be used to specify optional
-commands that can be included or omitted as needed:
-
-```yaml
-# ospf.yaml
-_template:
-  config_set: 'router ospf <name>'
-  config_set_append:
-    - 'vrf <vrf>'
-
-router_id:
-  config_set_append: 'router-id <router_id>'
-```
+  set_value: 'switchport access vlan <number>'
 
-```ruby
-irb(main):008:0> ref = cr.lookup('ospf', 'router_id')
-irb(main):017:0> ref.config_set(name: 'red', state: nil, router_id: '1.1.1.1')
-=> ["router ospf red", " router-id 1.1.1.1"]
-irb(main):019:0> ref.config_set(name: 'red', vrf: 'blue',
-                                state: 'no', router_id: '1.1.1.1')
-=> ["router ospf red", "vrf blue", "no router-id 1.1.1.1"]
+description:
+  set_value: '<state> description <desc>'
 ```
 
 ### `default_value`
@@ -479,22 +477,22 @@ ipv4_address:
 
 By convention, a `default_value` of `''` (empty string) represents a configurable property that defaults to absent, while a default of `nil` (Ruby) or `~` (YAML) represents a property that has no meaningful default at all.
 
-`config_get()` will return the defined `default_value` if the defined `config_get_token` does not match anything on the node. Normally this is desirable behavior, but you can use [`auto_default`](#auto_default) to change this behavior if needed.
+`config_get()` will return the defined `default_value` if the defined `get_value` does not match anything on the node. Normally this is desirable behavior, but you can use [`auto_default`](#auto_default) to change this behavior if needed.
 
 ### `default_only`
 
-Some attributes may be hard-coded in such a way that they have a meaningful default value but no relevant `config_get_token` or `config_set` behavior. For such attributes, the key `default_only` should be used as an alternative to `default_value`. The benefit of using this key is that it causes the `config_get()` API to always return the default value and `config_set()` to raise a `Cisco::UnsupportedError`.
+Some attributes may be hard-coded in such a way that they have a meaningful default value but no relevant `get_value` or `set_value` behavior. For such attributes, the key `default_only` should be used as an alternative to `default_value`. The benefit of using this key is that it causes the `config_get()` API to always return the default value and `config_set()` to raise a `Cisco::UnsupportedError`.
 
 ```yaml
 negotiate_auto_ethernet:
   kind: boolean
-  cli_nexus:
+  nexus:
     /(N7|C3064)/:
       # this feature is always off on these platforms and cannot be changed
       default_only: false
     else:
-      config_get_token_append: '/^(no )?negotiate auto$/'
-      config_set_append: "%s negotiate auto"
+      get_value: '(no )?negotiate auto'
+      set_value: "%s negotiate auto"
       default_value: true
 ```
 
@@ -510,39 +508,39 @@ The `kind` attribute is used to specify the type of value that is returned by `c
 # interface.yaml
 ---
 access_vlan:
-  config_get_token_append: '/^switchport access vlan (.*)$/'
-  config_set_append: "switchport access vlan %s"
+  get_value: 'switchport access vlan (.*)'
+  set_value: "switchport access vlan <vlan>"
   kind: int
   default_value: 1
 
 description:
   kind: string
-  config_get_token_append: '/^description (.*)/'
-  config_set_append: "%s description %s"
+  get_value: 'description (.*)'
+  set_value: "<state> description <desc>"
   default_value: ""
 
 feature_lacp:
   kind: boolean
-  config_get: "show running | i ^feature"
-  config_get_token: '/^feature lacp$/'
-  config_set: "%s feature lacp"
+  get_command: "show running | i ^feature"
+  get_value: 'feature lacp'
+  set_value: "<state> feature lacp"
 ```
 
 ### `multiple`
 
-By default, `config_get_token` should uniquely identify a single configuration entry, and `config_get()` will raise an error if more than one match is found. For a small number of attributes, it may be desirable to permit multiple matches (in particular, '`all_*`' attributes that are used up to look up all interfaces, all VRFs, etc.). For such attributes, you must specify the key `multiple:`. When this key is present, `config_get()` will permit multiple matches and will return an array of matches (even if there is only a single match).
+By default, `get_value` should uniquely identify a single configuration entry, and `config_get()` will raise an error if more than one match is found. For a small number of attributes, it may be desirable to permit multiple matches (in particular, '`all_*`' attributes that are used up to look up all interfaces, all VRFs, etc.). For such attributes, you must specify the key `multiple:`. When this key is present, `config_get()` will permit multiple matches and will return an array of matches (even if there is only a single match).
 
 ```yaml
 # interface.yaml
 ---
 all_interfaces:
   multiple:
-  config_get_token: '/^interface (.*)/'
+  get_value: 'interface (.*)'
 ```
 
 ### `auto_default`
 
-Normally, if `config_get_token` produces no match, `config_get()` will return the defined `default_value` for this attribute. For some attributes, this may not be desirable. Setting `auto_default: false` will force `config_get()` to return `nil` in the non-matching case instead.
+Normally, if `get_value` produces no match, `config_get()` will return the defined `default_value` for this attribute. For some attributes, this may not be desirable. Setting `auto_default: false` will force `config_get()` to return `nil` in the non-matching case instead.
 
 ```yaml
 # bgp_af.yaml
@@ -554,38 +552,8 @@ dampen_igp_metric:
   default_value: 600
   auto_default: false
   kind: int
-  config_get_token_append: '/^dampen-igp-metric (\d+)$/'
-  config_set_append: '<state> dampen-igp-metric <num>'
-```
-
-### `test_config_get` and `test_config_get_regex`
-
-Test-only equivalents to `config_get` and `config_get_token` - a show command
-to be executed over telnet by the minitest unit test scripts, and a regex
-(or array thereof) to match in the resulting plaintext output.
-Should only be referenced by test scripts, never by a feature provider itself.
-
-```yaml
-# show_version.yaml
-boot_image:
-  test_config_get: 'show version | no-more'
-  test_config_get_regex: '/NXOS image file is: (.*)$/'
-```
-
-### `test_config_result`
-
-Test-only container for input-result pairs that might differ by platform.
-Should only be referenced by test scripts, never by a feature provider itself.
-
-```yaml
-# vtp.yaml
-version:
-  /N7/:
-    test_config_result:
-      3: 3
-  else:
-    test_config_result:
-      3: 'Cisco::CliError'
+  get_value: 'dampen-igp-metric (\d+)'
+  set_value: '<state> dampen-igp-metric <num>'
 ```
 
 ## Style Guide