Raise an error if un implemented append function called.

[postgresql/pg_jsonb_opx] / README.md

diff --git a/README.md b/README.md
index 7933507de7c41d40450f403f6a8087ed5b7b8621..0eb0228397657205a3d08f5d7175aa0a25474438 100755 (executable)
--- a/README.md
+++ b/README.md
@@ -1,123 +1,49 @@
 jsonb_opx
 =========
 
-Missing operators for jsonb in PostgreSQL 9.4, this may contain some errors and bad form so please test that it suits your requirements before using in any production scenario.
+Missing operators for jsonb in PostgreSQL 9.4, this may contain some errors and bad form as it's primarily just experimentation (i'm not a frequent C programmer; but everyone has to start somewhere right?).  Please test that it suits your requirements before using in any production scenario.
 
 Provides
 --------
 
+The following behave like **hstore 1.x operators**; i.e. without nested jsonb traversal
+
 * deletion using **-** operator
   * jsonb_delete(jsonb, text)
+  * jsonb_delete(jsonb, numeric)
+  * jsonb_delete(jsonb, boolean)
   * jsonb_delete(jsonb, text[])
+  * jsonb_delete(jsonb, numeric[])
+  * jsonb_delete(jsonb, boolean[])
   * jsonb_delete(jsonb, jsonb)
 * concatenation using **||** operator
   * jsonb_concat(jsonb, jsonb)
+* replacement using **#=** operator
+  * jsonb_replace(jsonb, jsonb)
 
-More detail
------------
-* delete operator **"-"** provided by functions *jsonb_delete(jsonb, text) jsonb_delete(jsonb, text[]) and jsonb_delete(jsonb, jsonb)*
-    Provides:
-        jsonb - text
-        jsonb - text[]
-        jsonb - jsonb
-
-    Note: When using text type operators on jsonb arrays only elements of type text will be deleted. E.g.
+All of the above are provided with the standard extension and can be installed via CREATE EXTENSION E.g:
 
 ```sql
-TEST=# SELECT '[1, "1", "2", 2]'::jsonb - '2'::text;
-  ?column?   
--------------
- [1, "1", 2]
-(1 row)
+CREATE EXTENSION jsonb_opx;
+``` 
 
-TEST=# SELECT '[1, "1", "2", 2]'::jsonb - '"2"'::text;
-     ?column?     
-------------------
- [1, "1", "2", 2]
-(1 row)
+The following are intended to behave like **hstore 2.0 operators**;  i.e. recurse into nested jsonb path.
 
-TEST=# SELECT '[1, "1", "2", 2]'::jsonb - array['2']::text[];
-  ?column?   
--------------
- [1, "1", 2]
-(1 row)
+> As of 26/02/2015 there appears to be an effort discussed on pgsql-hackers for this type of path manipulation named <a href="http://github.com/erthalion/jsonbx" target="_blank">jsonbx</a> that appears to be much further ahead than my effort below.
 
-TEST=# SELECT '[1, "1", "2", 2]'::jsonb - array['"2"']::text[];
-     ?column?     
-------------------
- [1, "1", "2", 2]
-(1 row)
+* deletion at chained path using **#-** operator
+  * jsonb_delete_path(jsonb, text[])
+* replacement at chained path using function (no operator)
+  * jsonb_replace_path(jsonb, text[], jsonb)
 
-```
+To install this extra functionality specify version 1.1 when using CREATE EXTENSION E.g:
 
-    More. E.g.
- 
 ```sql
-TEST=# SELECT '{"a": 1, "b": 2, "c": 3}'::jsonb - 'b'::text;
-     ?column?     
-------------------
- {"a": 1, "c": 3}
-(1 row)
-
-TEST=# SELECT '{"a": 1, "b": 2, "c": 3}'::jsonb - ARRAY['a','b'];
- ?column? 
-----------
- {"c": 3}
-(1 row)
-
-TEST=# SELECT '{"a": 1, "b": 2, "c": 3}'::jsonb - '{"a": 4, "b": 2}'::jsonb;
-     ?column?     
-------------------
- {"a": 1, "c": 3}
-(1 row)
-
-TEST=# SELECT '{"a": 1, "b": 2, "c": 3, "d": {"a": 4}}'::jsonb - '{"d": {"a": 4}, "b": 2}'::jsonb;
-     ?column?     
-------------------
- {"a": 1, "c": 3}
-(1 row)
-
-TEST=# SELECT '{"a": 4, "b": 2, "c": 3, "d": {"a": 4}}'::jsonb - '{"a": 4, "b": 2}'::jsonb;
-        ?column?         
--------------------------
- {"c": 3, "d": {"a": 4}}
-(1 row)
+CREATE EXTENSION jsonb_opx VERSION '1.1';
 ```
-    
-* concatenation operator  **"||"** provided by function *jsonb_concat(jsonb, jsonb)*
-    Provides:
-         jsonb || jsonb
 
-    E.g.
+Or if you have version 1.0 already installed, use ALTER EXTENSION E.g:
 
 ```sql
-TEST=#  SELECT '{"a": 1, "b": 2, "c": 3}'::jsonb || '{"a": 4, "b": 2, "d": 4}'::jsonb;
-             ?column?             
-----------------------------------
- {"a": 4, "b": 2, "c": 3, "d": 4}
-(1 row)
-
-TEST=#  SELECT '["a", "b"]'::jsonb || '["c"]'::jsonb;
-    ?column?     
------------------
- ["a", "b", "c"]
-(1 row)
-
-TEST=#  SELECT '[1,2,3]'::jsonb || '[3,4,5]'::jsonb;
-      ?column?      
---------------------
- [1, 2, 3, 3, 4, 5]
-(1 row)
-
-TEST=#  SELECT '{"a": 1, "b": 2, "c": 3}'::jsonb || '[1,2,3]'::jsonb;
-              ?column?               
--------------------------------------
- [{"a": 1, "b": 2, "c": 3}, 1, 2, 3]
-(1 row)
-
-TEST=#  SELECT '{"a": 1, "b": 2, "c": 3}'::jsonb || '[1,2,3]'::jsonb || '"a"'::jsonb;
-                 ?column?                 
-------------------------------------------
- [{"a": 1, "b": 2, "c": 3}, 1, 2, 3, "a"]
-(1 row)
+ALTER EXTENSION jsonb_opx UPDATE TO '1.1';
 ```