break docs into pieces

Author: sbcgua

docsite/blog/2022-07-23 - json alternative to maintenance views in abap/index.md

@@ -34,7 +34,7 @@ Example of json config
 
 As you can see the content is freely editable JSON text.
 
-Finally, accessing the config parameters is done with a help of [ajson package](https://github.com/sbcgua/ajson). I wrote about it before - [AJSON – yet another abap json parser and serializer](/posts/2020-08-14---ajson---yet-another-abap-json-parser-and-serializer/). Since the original blog post, the library has matured and we use it in several productive tools which exchange the data with external APIs and web services. The tool is designed to be convenient for a developer, so the accessing code looks, for example, as follows:
+Finally, accessing the config parameters is done with a help of [ajson package](https://github.com/sbcgua/ajson). I wrote about it before - [AJSON – yet another abap json parser and serializer](/blog/ajson-yet-another-abap-json-parser-and-serializer/). Since the original blog post, the library has matured and we use it in several productive tools which exchange the data with external APIs and web services. The tool is designed to be convenient for a developer, so the accessing code looks, for example, as follows:
 
 ```abap
 data lo_json_settings type ref to zif_ajson.

docsite/docs/01-intro.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 10
+---
+
+# Introduction
+
+AJson is a json parser/serializer for ABAP designed with the convenience for developer in mind. It works with abap release 7.02 or higher.
+
+## Features
+
+- Parse json content into a flexible form, not fixed to any predefined data structure, allowing to modify the parsed data, selectively access its parts and slice subsections of it
+  - slicing can be particularly useful for REST header separation e.g. `{ "success": 1, "error": "", "payload": {...} }` where 1st level attrs are processed in one layer of your application and payload in another (and can differ from request to request)
+- Allows conversion to fixed abap structures/tables (`to_abap`)
+- Convenient interface to manipulate the data - `set( value )`, `set( structure )`, `set( table )`, `set( another_instance_of_ajson )`, also typed e.g. `set_date`
+  - also `setx` for text-based value setting like `setx( '/a/b:123' )` (useful e.g. for constants in APIs or in unit-tests)
+- Seralization to string
+- Freezing (read only) instance content
+- Filtering - create a json skipping empty values, predefined paths, or your custom filter.
+- Mapping - rule-based changing node names (e.g. snake case to camel case, upper/lower case)
+- Utility to calculate difference between 2 jsons
+- Supports: timestamps, reference initialization
+
+## Example of usage
+
+```abap
+data r type ref to zif_ajson.
+data fragment type ref to zif_ajson.
+
+r = zcl_ajson=>parse( '{"success": 1, "error": "", "payload": {"text": "hello"}}' ).
+
+r->get( '/success' ).              " returns "1"
+r->get_integer( '/success' ).      " returns 1 (number)
+r->get_boolean( '/success' ).      " returns "X" (abap_true - because not empty)
+r->get( '/payload/text' ).         " returns "hello"
+
+r->members( '/' ).                 " returns table of "success", "error", "payload"
+
+fragment = r->slice( '/payload' ).
+fragment->get( '/text' ).          " returns "hello" (the root has changed)
+
+fragment->set(
+  iv_path = '/text'
+  iv_val  = 'new text' ).
+fragment->stringify( ).            " {"text":"new text"}
+```
+
+See more examples and usages in the further docs.

docsite/docs/10-intro.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 20
 ---
 
 # Installation

docsite/docs/02-installation.md docsite/docs/20-installation.mddocsite/docs/02-installation.md renamed to docsite/docs/20-installation.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 30
+---
+
+# Instantiating and basics
+
+- To **parse** existing json data - call `zcl_ajson=>parse( lv_json_string )`
+- To create a new **empty** json instance (to set values and serialize) - call `zcl_ajson=>new( )` or `new zcl_ajson( )` in newer abap syntax
+- You can **clone** an ajson instance to get a new independent copy with `lo_orig_json->clone( )`
+
+## Basics
+
+- All functional methods and types are defined in `zif_ajson` interface.
+  - Methods have aliases in the `zcl_ajson` class, however please restrain from using them directly as they may be *deprecated* in future.
+- Json attributes are addressed by path in form `/obj1/obj2/value` of e.g. `->get( '/a/b/c' )` addresses `{ "a": { "b": { "c": "this value !" } } }`
+- Array items addressed with index starting from 1: `/tab/2/val` -> `{ "tab": [ {...}, { "val": "this value !" } ] }`
+
+## Support for '/' in attribute names
+
+*TBD*
+
+## Chaining
+
+- `Set` (and some other) methods also return `me` to support chaining: `li_json->set(...)->set(...)->touch_array(...)->push(...)`.
+
+## Mapping and filtering libraries
+
+- Mapping and formatting are enabled by interface `zif_ajson_mapping`. Predefined patterns for field mapping (ABAP ⇆ JSON), Camel Case, UPPER/lower case can be found in class `zcl_ajson_mapping`
+- Predefined filters are available in `zcl_ajson_filter_lib` class
+
+## Creating from (deprecated?)
+
+```abap
+  lo_new_json = zcl_ajson=>create_from(
+    ii_source_json = lo_orig_json ).
+```

docsite/docs/30-basics.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 40
+---
+
+# Reading JSON values
+
+The methods of interface allows accessing attributes and converting to abap structure.
+
+Examples below assume original json was:
+
+```json
+{
+  "success": 1,
+  "error": "",
+  "payload": {
+    "text": "hello",
+    "num": 123,
+    "bool": true,
+    "false": false,
+    "null": null,
+    "date": "2020-07-28",
+    "table": [
+      "abc",
+      "def"
+    ]
+  }
+}
+```
+
+#### Individual value reading
+
+```abap
+data r type ref to zif_ajson.
+r = zcl_ajson=>parse( lv_json_string_from_above ).
+
+r->is_empty( ).                     " returns abap_false
+r->exists( '/success' ).            " returns abap_true
+
+r->get( '/success' ).               " returns "1"
+r->get_integer( '/success' ).       " returns 1 (number)
+r->get_boolean( '/success' ).       " returns "X" (abap_true - because not empty)
+
+r->get( '/payload/bool' ).          " returns "true"
+r->get_boolean( '/payload/bool' ).  " returns "X" (abap_true)
+
+r->get( '/payload/false' ).         " returns "false"
+r->get_boolean( '/payload/false' ). " returns "" (abap_false)
+
+r->get( '/payload/null' ).          " returns "null"
+r->get_string( '/payload/null' ).   " returns "" (empty string)
+
+r->get( '/payload/date' ).          " returns "2020-07-28"
+r->get_date( '/payload/date' ).     " returns "20200728" (type d)
+
+r->members( '/' ).                  " returns table of "success", "error", "payload"
+```
+
+#### Segment slicing
+
+```abap
+" Slice returns zif_ajson instance but "payload" becomes root
+" Useful to process API responses with unified wrappers
+data payload type ref to zif_ajson.
+payload = r->slice( '/payload' ). 
+```
+
+#### Getting node type
+
+In some case you might want to know node type prior to accessing it first. Type can be 'str', 'num', 'null', 'bool', 'object', 'array'.
+
+```abap
+r->get_node_type( '/payload/false' ).         " returns "bool"
+r->get_node_type( '/payload/text' ).          " returns "str"
+```
+
+#### Converting to abap structure
+
+```abap
+data:
+  begin of ls_payload,
+    text type string,
+    num type i,
+    bool type abap_bool,
+    false type abap_bool,
+    null type string,
+    table type string_table, " Array !
+  end of ls_payload.
+
+payload->to_abap( importing ev_container = ls_payload ).
+```
+
+`to_abap` supports transferring "corresponding only" fields.
+
+```abap
+payload->to_abap( 
+  exporting iv_corresponding = abap_true
+  importing ev_container     = ls_payload ).
+
+" Or via an instance flag (persists after setting!)
+payload->to_abap_corresponding_only( )->to_abap( importing ev_container = ls_payload ).
+```