Adds valkey-json module commands documentation to the website.

Makefile

@@ -8,6 +8,7 @@ DATE ?= 2025-01-08
 
 # Path to the code repo.
 VALKEY_ROOT ?= ../valkey
+VALKEY_JSON_ROOT ?= ../valkey-json
 
 # Where to install man pages
 INSTALL_MAN_DIR ?= /usr/local/share/man
@@ -30,6 +31,10 @@ ifeq ("$(wildcard $(VALKEY_ROOT))","")
     $(error Please provide the VALKEY_ROOT variable pointing to the Valkey source code)
 endif
 
+ifeq ("$(wildcard $(VALKEY_JSON_ROOT))","")
+    $(error Please provide the VALKEY_JSON_ROOT variable pointing to the valkey-json source code)
+endif
+
 ifeq ("$(shell which pandoc)","")
     $(error Please install pandoc)
 endif
@@ -54,7 +59,9 @@ endif
 
 documented_commands = $(wildcard commands/*.md)
 commands_json_files = $(wildcard $(VALKEY_ROOT)/src/commands/*.json)
+valkey_json_commands_json_files = $(wildcard $(VALKEY_JSON_ROOT)/src/commands/*.json)
 existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md)
+$(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md)
 
 topics   = $(wildcard topics/*)
 commands = $(filter $(existing_commands),$(documented_commands))
@@ -65,7 +72,9 @@ topics_pics = $(filter-out %.md,$(topics))
 # ---- Temp files ----
 
 # JSON files for the commands that have a .md file (excluding undocumented commands).
-json_for_documented_commands = $(commands:commands/%.md=$(VALKEY_ROOT)/src/commands/%.json)
+json_for_documented_commands = \
+    $(patsubst commands/%.md,$(VALKEY_ROOT)/src/commands/%.json,$(filter $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \
+    $(patsubst commands/%.md,$(VALKEY_JSON_ROOT)/src/commands/%.json,$(filter $(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md),$(commands)))
 
 $(BUILD_DIR)/.commands-per-group.json: $(VALKEY_ROOT)/src/commands/. utils/build-command-groups.py | $(BUILD_DIR)
 	utils/build-command-groups.py $(json_for_documented_commands) > $@~~
@@ -175,11 +184,14 @@ $(MAN_DIR)/man1/valkey-%.1.gz: topics/%.md $(man_scripts)
 	utils/preprocess-markdown.py --man --page-type program \
 	 --version $(VERSION) --date $(DATE) \$< \
 	 | utils/links-to-man.py - | $(to_man) > $@
-$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(VALKEY_ROOT)/src/commands/%.json $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
+$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
+	$(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_JSON_ROOT))
+	$(eval FINAL_ROOT := $(firstword $(foreach root,$(VALKEY_ROOTS),$(if $(wildcard $(root)/src/commands/$*.json),$(root)))))
+	$(if $(FINAL_ROOT),,$(eval FINAL_ROOT := $(lastword $(VALKEY_ROOTS))))
 	utils/preprocess-markdown.py --man --page-type command \
 	 --version $(VERSION) --date $(DATE) \
 	 --commands-per-group-json $(BUILD_DIR)/.commands-per-group.json \
-	 --valkey-root $(VALKEY_ROOT) $< \
+	 --valkey-root $(FINAL_ROOT) $< \
 	 | utils/links-to-man.py - | $(to_man) > $@
 $(MAN_DIR)/man5/%.5.gz: topics/%.md $(man_scripts)
 	utils/preprocess-markdown.py --man --page-type config \

README.md

@@ -8,10 +8,11 @@ for generating content for the website and man pages.
 This repo comes with a Makefile to build and install man pages.
 
     make VALKEY_ROOT=path/to/valkey
+    VALKEY_JSON_ROOT=path/to/valkey-json
     sudo make install INSTALL_MAN_DIR=/usr/local/share/man
 
 Prerequisites: GNU Make, Python 3, Python 3 YAML (pyyaml), Pandoc.
-Additionally, the scripts need access to the valkey code repo,
+Additionally, the scripts need access to the valkey and valkey-json code repos,
 where metadata files about the commands are stored.
 
 The pages are generated under `_build/man/` by default. The default install

commands/json.arrappend.md

@@ -0,0 +1,50 @@
+## Syntax
+
+```bash
+JSON.ARRAPPEND <key> <path> <json> [json ...]
+```
+
+* key - required, Redis key of document type
+* path - required, a JSON path
+* json - required, JSON value to be appended to the array
+
+## Return
+
+* If the path is enhanced syntax:
+    * Array of integers, representing the new length of the array at each path.
+    * If a value at the path is not an array, its corresponding return value is null.
+    * SYNTAXERR error if one of the input json arguments is not a valid JSON string.
+    * NONEXISTENT error if the path does not exist.
+
+* If the path is restricted syntax:
+    * Integer, the array's new length.
+    * If multiple array values are selected, the command returns the new length of the last updated array.
+    * WRONGTYPE error if the value at the path is not an array.
+    * SYNTAXERR error if one of the input json arguments is not a valid JSON string.
+    * NONEXISTENT error if the path does not exist.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRAPPEND  k1 $[*] '"c"'
+1) (integer) 1
+2) (integer) 2
+3) (integer) 3
+127.0.0.1:6379> JSON.GET k1
+"[[\"c\"],[\"a\",\"c\"],[\"a\",\"b\",\"c\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRAPPEND  k1 [-1] '"c"'
+(integer) 3
+127.0.0.1:6379> JSON.GET k1
+"[[],[\"a\"],[\"a\",\"b\",\"c\"]]"
+```

commands/json.arrindex.md

@@ -0,0 +1,46 @@
+## Syntax
+
+```bash
+JSON.ARRINDEX <key> <path> <json-scalar> [start [end]]
+```
+
+* key - required, Redis key of document type.
+* path - required, a JSON path.
+* json-scalar - required, scalar value to search for. JSON scalar refers to values that are not objects or arrays.
+  i.e., String, number, boolean and null are scalar values.
+* start - optional, start index, inclusive. Defaults to 0 if not provided.
+* end - optional, end index, exclusive. Defaults to 0 if not provided, which means the last element is included.
+  0 or -1 means the last element is included.
+
+## Return
+
+* If the path is enhanced syntax:
+    * Array of integers. Each value is the index of the matching element in the array at the path. The value is -1 if not found.
+    * If a value is not an array, its corresponding return value is null.
+
+* If the path is restricted syntax:
+    * Integer, the index of matching element, or -1 if not found.
+    * WRONGTYPE error if the value at the path is not an array.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRINDEX k1 $[*] '"b"'
+1) (integer) -1
+2) (integer) -1
+3) (integer) 1
+4) (integer) 1
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '{"children": ["John", "Jack", "Tom", "Bob", "Mike"]}'
+OK
+127.0.0.1:6379> JSON.ARRINDEX k1 .children '"Tom"'
+(integer) 2
+```

commands/json.arrinsert.md

@@ -0,0 +1,49 @@
+## Syntax
+
+```bash
+JSON.ARRINSERT <key> <path> <index> <json> [json ...]
+```
+
+* key - required, Redis key of document type
+* path - required, a JSON path
+* index - required, array index before which values are inserted.
+* json - required, JSON value to be appended to the array
+
+## Return
+
+* If the path is restricted syntax:
+    * Array of integers, representing the new length of the array at each path.
+    * If a value is an empty array, its corresponding return value is null.
+    * If a value is not an array, its corresponding return value is null.
+    * OUTOFBOUNDARIES error if the index argument is out of bounds.
+
+* If the path is restricted syntax:
+    * Integer, the new length of the array.
+    * WRONGTYPE error if the value at the path is not an array.
+    * OUTOFBOUNDARIES error if the index argument is out of bounds.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRINSERT k1 $[*] 0 '"c"'
+1) (integer) 1
+2) (integer) 2
+3) (integer) 3
+127.0.0.1:6379> JSON.GET k1
+"[[\"c\"],[\"c\",\"a\"],[\"c\",\"a\",\"b\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRINSERT k1 . 0 '"c"'
+(integer) 4
+127.0.0.1:6379> JSON.GET k1
+"[\"c\",[],[\"a\"],[\"a\",\"b\"]]"
+```

commands/json.arrlen.md

@@ -0,0 +1,65 @@
+## Syntax
+
+```bash
+JSON.ARRLEN <key> [path]
+```
+
+* key - required, Redis key of document type
+* path - optional, a JSON path. Defaults to the root path if not provided
+
+## Return
+
+* If the path is enhanced syntax:
+    * Array of integers, representing the array length at each path.
+    * If a value is not an array, its corresponding return value is null.
+    * Null if the document key does not exist.
+
+* If the path is restricted syntax:
+    * Integer, array length.
+    * If multiple objects are selected, the command returns the first array's length.
+    * WRONGTYPE error if the value at the path is not an array.
+    * NONEXISTENT error if the path does not exist.
+    * Null if the document key does not exist.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], [\"a\"], [\"a\", \"b\"], [\"a\", \"b\", \"c\"]]'
+(error) SYNTAXERR Failed to parse JSON string due to syntax error
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k1 $[*]
+1) (integer) 0
+2) (integer) 1
+3) (integer) 2
+4) (integer) 3
+
+127.0.0.1:6379> JSON.SET k2 . '[[], "a", ["a", "b"], ["a", "b", "c"], 4]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k2 $[*]
+1) (integer) 0
+2) (nil)
+3) (integer) 2
+4) (integer) 3
+5) (nil)
+```
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k1 [*]
+(integer) 0
+127.0.0.1:6379> JSON.ARRLEN k1 $[3]
+1) (integer) 3
+
+127.0.0.1:6379> JSON.SET k2 . '[[], "a", ["a", "b"], ["a", "b", "c"], 4]'
+OK
+127.0.0.1:6379> JSON.ARRLEN k2 [*]
+(integer) 0
+127.0.0.1:6379> JSON.ARRLEN k2 $[1]
+1) (nil)
+127.0.0.1:6379> JSON.ARRLEN k2 $[2]
+1) (integer) 2
+```

commands/json.arrpop.md

@@ -0,0 +1,57 @@
+## Syntax
+
+```bash
+JSON.ARRPOP <key> [path [index]]
+```
+
+* key - required, Redis key of document type
+* path - optional, a JSON path. Defaults to the root path if not provided
+* index - optional, position in the array to start popping from.
+    * Defaults -1 if not provided, which means the last element.
+    * Negative value means position from the last element.
+    * Out of boundary indexes are rounded to their respective array boundaries.
+
+## Return
+
+* If the path is enhanced syntax:
+    * Array of bulk strings, representing popped values at each path.
+    * If a value is an empty array, its corresponding return value is null.
+    * If a value is not an array, its corresponding return value is null.
+
+* If the path is restricted syntax:
+    * Bulk string, representing the popped JSON value
+    * Null if the array is empty.
+    * WRONGTYPE error if the value at the path is not an array.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRPOP k1 $[*]
+1) (nil)
+2) "\"a\""
+3) "\"b\""
+127.0.0.1:6379> JSON.GET k1
+"[[],[],[\"a\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRPOP k1
+"[\"a\",\"b\"]"
+127.0.0.1:6379> JSON.GET k1
+"[[],[\"a\"]]"
+
+127.0.0.1:6379> JSON.SET k2 . '[[], ["a"], ["a", "b"]]'
+OK
+127.0.0.1:6379> JSON.ARRPOP k2 . 0
+"[]"
+127.0.0.1:6379> JSON.GET k2
+"[[\"a\"],[\"a\",\"b\"]]"
+```

commands/json.arrtrim.md

@@ -0,0 +1,51 @@
+## Syntax
+
+```bash
+JSON.ARRTRIM <key> <path> <start> <end>
+```
+
+* key - required, Redis key of document type.
+* path - required, a JSON path.
+* start - required, start index, inclusive.
+* end - required, end index, inclusive.
+
+## Return
+
+* If the path is restricted syntax:
+    * Array of integers, representing the new length of the array at each path.
+    * If a value is an empty array, its corresponding return value is null.
+    * If a value is not an array, its corresponding return value is null.
+    * OUTOFBOUNDARIES error if an index argument is out of bounds.
+
+* If the path is restricted syntax:
+    * Integer, the new length of the array.
+    * Null if the array is empty.
+    * WRONGTYPE error if the value at the path is not an array.
+    * OUTOFBOUNDARIES error if an index argument is out of bounds.
+
+## Examples
+
+Enhanced path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '[[], ["a"], ["a", "b"], ["a", "b", "c"]]'
+OK
+127.0.0.1:6379> JSON.ARRTRIM k1 $[*] 0 1
+1) (integer) 0
+2) (integer) 1
+3) (integer) 2
+4) (integer) 2
+   127.0.0.1:6379> JSON.GET k1
+   "[[],[\"a\"],[\"a\",\"b\"],[\"a\",\"b\"]]"
+```
+
+Restricted path syntax:
+
+```bash
+127.0.0.1:6379> JSON.SET k1 . '{"children": ["John", "Jack", "Tom", "Bob", "Mike"]}'
+OK
+127.0.0.1:6379> JSON.ARRTRIM k1 .children 0 1
+(integer) 2
+127.0.0.1:6379> JSON.GET k1 .children
+"[\"John\",\"Jack\"]"
+```