From: Jorge Pereira <jpereiran@gmail.com>
Date: Thu, 31 Jan 2019 23:51:33 +0000 (-0200)
Subject: Update raddb/mods-available/json
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=01b8ea9b33d4dbe3ae85e6ebf92a746413f80401;p=thirdparty%2Ffreeradius-server.git

Update raddb/mods-available/json
---

diff --git a/raddb/mods-available/json b/raddb/mods-available/json
index cfe71c0f6ba..434fdba4fee 100644
--- a/raddb/mods-available/json
+++ b/raddb/mods-available/json
@@ -1,51 +1,84 @@
 # -*- text -*-
 #
+#  :toc:
+#
 #  $Id$
 #
-# JSON module registers a map function to allow mapping fields from JSON
-# structures to attributes.
+
+#######################################################################
 #
-# The path through the JSON document's tree is specified with FR jpath,
-# which is the FreeRADIUS implementation of the jpath grammar described here:
+#  = JSON Module
 #
-#	  http://goessner.net/articles/JsonPath/
+# The `json` module registers a `map` function to allow mapping fields
+# from JSON structures to attributes.
+#
+# The path through the JSON document's tree is specified with FR jpath,
+# which is the FreeRADIUS implementation of the jpath grammar described
+# at http://goessner.net/articles/JsonPath/
 #
 # Selectors currently implemented are:
-#   - $                         Root node (only valid at the start of the path).
-#   - @                         Current node (only valid at the start of the path).
-#   - .<name>                   A field within an object.
-#   - [<idx>]                   Index within an array.
-#   - [<start>:<end>[:<step>]]  A slice within an array (identical to the Python syntax).
-#   - [<idx>,<start>:<end>]     Multiple indexes/slices within an array.
-#   - .*                        All the children of the current node.
-#   - ..                        Recursive descent.
-#
-# Automatic casting will occur between JSON and attribute types where possible.
-#
-# Assignment of JSON objects/arrays to strings is supported, in which case the
-# JSON serialized form of the object/array is used.
-#
-# If a jpath matches multiple nodes, unless the map includes the += operator
-# only the first node's value will be used.
-# If the map uses += then multiple instances of the attribute will be created,
-# each holding a different node value.
-#
-# Simple example:
-# {
-#	"user": "bob",
-#	"account number": 7124503,
-#	"groups": {
-#		"admin",
-#		"networks",
-#		"bob"
-#	}
 #
+# [options="header,autowidth"]
+# |===
+# | Selector                 | Description
+# | $                        | Root node (only valid at the start of the path).
+# | @                        | Current node (only valid at the start of the path).
+# | .<name>                  | A field within an object.
+# | [<idx>]                  | Index within an array.
+# | [<start>:<end>[:<step>]] | A slice within an array (identical to the Python syntax).
+# | [<idx>,<start>:<end>]    | Multiple indexes/slices within an array.
+# | .*                       | All the children of the current node.
+# | ..                       | Recursive descent.
+# |===
+#
+# [NOTE]
+# ====
+# * Automatic casting will occur between JSON and attribute types where possible.
+# * Assignment of JSON objects/arrays to strings is supported, in which case the
+#   JSON serialized form of the object/array is used.
+# * If a jpath matches multiple nodes, unless the map includes the `+=` operator
+# * only the first node's value will be used.
+# * If the map uses `+=` then multiple instances of the attribute will be created,
+#   each holding a different node value.
+# ====
+#
+
+#
+# ## Sample
+#
+# Assuming that you have the url http://example.org/api/user/$username
+# service replying some JSON content as below.
+#
+# [source, json]
+# ----
+# {
+#   "user": "bob",
+#   "account number": 7124503,
+#     "groups": {
+#       "admin",
+#       "networks",
+#       "bob"
+#     }
+#   }
 # }
+# ----
 #
+# Then, you can call using the module `rest` and access the JSON fields as below example.
+#
+# [source, unlang]
+# ----
 # map json "%{rest:GET http://example.org/api/user/%{User-Name}" {
-#	&Tmp-Integer-0 	:= '$.account number'
-#	&Group		+= '$.groups.*"
+#   &Tmp-Integer-0  := '$.account number'
+#   &Group          += '$.groups.*'
 # }
+# ----
+#
+
+#
+# ## Default instance
+#
+# This module takes no configuration.
+#
 json {
 
 }