jsKeyPaths

Searches containers and sub-containers for all occurrences of a key or index and returns a path for each occurrence of the key or index.

Syntax:

jsKeyPaths ( container-handle, key-name [, key-delimiter] )

Parameters:

(s) container-handle: handle to an object or array that is at the root of the returned paths.

(s) key-name: JSON key name with optional array index to search for or empty string ("") to return all paths. The key name may optionally be proceeded by partial path information.

(s) key-delimiter: [optional] single character used between key names in a path (defaults to a dot character(".")).

Returns:

(a) json-paths: single dimension array of JSON paths. One array element for each occurrence of the key-name or index in the JSON container and any child container. Empty array if the key-name is not found.

JSON containers hold either key/value pairs or indexed values. The values of these pairs can be any valid JSON data type, including another JSON object or array. This means that it is possible to have multiple indexed values or pairs with the same index or key name. The way to distinguish between Identically named keys or indices is by using the unique JSON container path to differentiate specific values. This function creates a unique JSON paths for each key or index matching the key-name parameter value. These paths are accepted by other extender functions. JSON paths therefore make it possible to access any value associated with a multi-level JSON contain. See the discussion below for more information about the extender's JSON paths.

Container-Handle

The unique identifier returned from a call to the jsParse, jsConNew, jsValueGet functions, or by accessing WIL map element returned by the jsConMap function.

Key-Name

The name of the key to search for in the JSON container or an empty string ("") to return the paths to all values in the container and any sub-containers.  The Key-Name parameter can include a JSON array name with index or an anonymous array "[]" with ani index. The function returns an empty array (WIL array with no elements) when the supplied key-name  does not exist in the container or one of the containers's sub-containers.

This parameter can optionally include partial JSON path information. The path information restricts the key-name search to the container named before the last name in the supplied path. The last name in the path is the search target key-name. The optional path information must include a complete path to the desired search starting point. If the path does not start with a container name in the JSON handle container or contains nonexistent container name up to but not including the last name, the function will generate an error. See the About JSON Paths topic for more information about the extender's JSON paths.

Important:

• JSON key names are case sensitive, so make sure the key-name is spelled correctly and matches the case of the key stored in the JSON data.

• A key-name and any path container names must always be surrounded by square brackets when the name contains embedded square brackets or the current key-name delimiter.

Key-Delimiter

This optional parameter is a single character used between key-names in the input and is also used by the function in the output paths. The default value is a dot (".") and the space(' '), backslash('\'), single-quote("'"), double-quote('"'), dollar-sign("$"), left-bracket("["), right-bracket("]") and grave-accent("`") cannot be used as delimiters.   

JSON Paths

A JSON paths consists of a series of key names. Each key name is delimited by a character of your choice and is associated with a JSON container.  See the About JSON Paths topic for more information about the extender's JSON paths.

Example:

  AddExtender('ilcjs44i.dll', 0, 'ilcjs64i.dll')
  
  ; JSON object text.
  strJson = $"{
    "pi":: 3.141,
    "happy":: true,
    "name":: "WIL JSON Extender",
    "nothing":: null,
    "answer":: {
      "everything":: 42
    },
    "list":: [1, 0, 2],
    "object":: {
      "currency":: "USD",
       "value":: 42.99,
  
       "nested object":: {
         "value":: "bird egg"
       }
    },
    "value":: "Top level value"
  }$"
  Json = jsParse(strJson)
  
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ; Get all values of the key "value"
  Key = '[value]' ; Key to search for.
  
  ; Find the paths for all occurrences of the key.
  Paths = jsKeyPaths(Json , Key)
  Values = ''
  ForEach Path In Paths
     Values := jsValueGet(Json, Path):@lf
  Next
  
  ; Show found values of the key .
  Message('Values For the Key ':Key, Values)
  ;; Output:
  ;;   Top level value
  ;;   42.990000
  ;;   bird egg
  
  ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  ; Now search for the same key in a subset of
  ; the JSON data.
  
  Key = '[object].[value]' ; Key to search for with partial path.
  
  ; Find the paths for all occurrences of the key.
  Paths = jsKeyPaths(Json, Key)
  Values = ''
  ForEach Path In Paths
     Values := jsValueGet(Json, Path):@lf
  Next
  
  jsConClose(Json)
  
  ; Show found values of the key in and below the "object" container.
  Message('Values with Path Restrictions ':Key, Values)
  ;; Output:
  ;;   42.990000
  ;;   bird egg
  

See Also:

jsParse, jsConNew, jsConMap, jsValueGet