Merge pull request #201 from fktn-k/feature/195_basic_node_operators_…

…with_iostreams #195 Implement insertion/extraction operators for basic_node template class
fktn-k · Nov 8, 2023 · 7df5b59 · 7df5b59
2 parents e1551b9 + 48657ad
commit 7df5b59
Show file tree

Hide file tree

Showing 23 changed files with 281 additions and 42 deletions.
diff --git a/docs/mkdocs/docs/api/basic_node/begin.md b/docs/mkdocs/docs/api/basic_node/begin.md
@@ -28,7 +28,7 @@ An iterator to the first element of a container node value (either sequence or m
         fkyaml::node n = {"foo", "bar"};
         // get an iterator to the first element.
         fkyaml::node::iterator it = n.begin();
-        std::cout << fkyaml::node::serialize(*it) << std::endl;
+        std::cout << *it << std::endl;
         return 0;
     }
     ```

diff --git a/docs/mkdocs/docs/api/basic_node/const_iterator.md b/docs/mkdocs/docs/api/basic_node/const_iterator.md
@@ -22,7 +22,7 @@ This iterator type is commonly used for sequence and mapping container values.
         const fkyaml::node sequence_node = {1, 2, 3};
         // get an iterator to the first sequence element.
         fkyaml::node::const_iterator it = sequence_node.begin();
-        std::cout << fkyaml::node::serialize(*it) << std::endl;
+        std::cout << *it << std::endl;
         return 0;
     };
     ```

diff --git a/docs/mkdocs/docs/api/basic_node/constructor.md b/docs/mkdocs/docs/api/basic_node/constructor.md
@@ -48,7 +48,7 @@ The resulting basic_node has the [`node_t::NULL_OBJECT`](node_t.md) type.
     int main()
     {
         fkyaml::node n;
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -80,7 +80,7 @@ The resulting basic_node has a default value for the given type.
     int main()
     {
         fkyaml::node n(fkyaml::node::node_t::INTEGER);
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -113,7 +113,7 @@ The resulting basic_node has the same type and value as `rhs`.
     {
         fkyaml::node n(fkyaml::node::node_t::BOOLEAN);
         fkyaml::node n2(n);
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -147,7 +147,7 @@ The value of the argument `rhs` after calling this move constructor, will be the
     {
         fkyaml::node n(fkyaml::node::node_t::BOOLEAN);
         fkyaml::node n2(n);
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -195,7 +195,7 @@ The resulting basic_node has the value of `val` and the type which is associated
     {
         double pi = 3.141592;
         fkyaml::node n = pi;
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -241,7 +241,7 @@ The resulting basic_node has the value of the referenced basic_node by `node_ref
     int main()
     {
         fkyaml::node n({true, false});
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -276,10 +276,10 @@ If `init` contains a sequence of basic_node objects in which the number of basic
     int main()
     {
         fkyaml::node n = {true, false};
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
 
         fkyaml::node n2 = {"foo", 1024};
-        std::cout << fkyaml::node::serialize(n2) << std::endl;
+        std::cout << n2 << std::endl;
         return 0;
     }
     ```
@@ -297,3 +297,4 @@ If `init` contains a sequence of basic_node objects in which the number of basic
 ## **See Also**
 
 * [basic_node](index.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/end.md b/docs/mkdocs/docs/api/basic_node/end.md
@@ -30,7 +30,7 @@ An iterator to the past-the-last element of a container node value (either seque
         fkyaml::node::iterator it = n.end();
         // decrement the iterator to point to the last element.
         --it;
-        std::cout << fkyaml::node::serialize(*it) << std::endl;
+        std::cout << *it << std::endl;
         return 0;
     }
     ```
@@ -46,4 +46,5 @@ An iterator to the past-the-last element of a container node value (either seque
 * [node](node.md)
 * [iterator](iterator.md)  
 * [const_iterator](const_iterator.md)
-* [begin](begin.md)
+* [begin](begin.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/extraction_operator.md b/docs/mkdocs/docs/api/basic_node/extraction_operator.md
@@ -0,0 +1,62 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::</small>operator>>
+
+```cpp
+inline std::istream& operator>>(std::istream& is, basic_node& n);
+```
+
+Insertion operator for basic_node template class.  
+Deserializes an input stream into a [`basic_node`](index.md).  
+This API is a wrapper of [`basic_node::deserialize()`](deserialize.md) function for input streams to simplify the implementation in the user's code.  
+
+## **Parameters**
+
+***`is`*** [in]
+:   An input stream object.
+
+***`n`*** [in]
+:   A basic_node object.
+
+## **Return Value**
+
+Reference to the input stream object `is`.  
+
+???+ Example
+
+    ```yaml title="input.yaml"
+    foo: true
+    bar: 123
+    baz: 3.14
+    ```
+
+    ```cpp
+    #include <fstream>
+    #include <iostream>
+    #include <fkYAML/node.hpp>
+
+    int main()
+    {
+        std::ifstream ifs("input.yaml");
+        fkyaml::node n;
+        ifs >> n;
+
+        // print the deserialization result.
+        std::cout << n << std::endl;
+
+        return 0;
+    }
+    ```
+
+    ```yaml
+    foo: true
+    bar: 123
+    baz: 3.14
+    ```
+
+### **See Also**
+
+* [basic_node](index.md)
+* [deserialize](deserialize.md)
+* [serialize](serialize.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/index.md b/docs/mkdocs/docs/api/basic_node/index.md
@@ -74,12 +74,14 @@ This class provides features to handle YAML nodes.
 | [is_string](is_string.md)             | checks if a basic_node has a string node value.       |
 
 ### Conversions
-| Name                              |          | Description                                                        |
-| --------------------------------- | -------- | ------------------------------------------------------------------ |
-| [deserialize](deserialize.md)     | (static) | deserializes a YAML formatted string into a basic_node.            |
-| [serialize](serialize.md)         | (static) | serializes a basic_node into a YAML formatted string.              |
-| [get_value](get_value.md)         |          | converts a basic_node into a target native data type.              |
-| [get_value_ref](get_value_ref.md) |          | converts a basic_node into reference to a target native data type. |
+| Name                                 |          | Description                                                        |
+| ------------------------------------ | -------- | ------------------------------------------------------------------ |
+| [deserialize](deserialize.md)        | (static) | deserializes a YAML formatted string into a basic_node.            |
+| [operator>>](extraction_operator.md) |          | deserializes an input stream into a basic_node.                    |
+| [serialize](serialize.md)            | (static) | serializes a basic_node into a YAML formatted string.              |
+| [operator<<](insertion_operator.md)  |          | serializes a basic_node into an output stream.                     |
+| [get_value](get_value.md)            |          | converts a basic_node into a target native data type.              |
+| [get_value_ref](get_value_ref.md)    |          | converts a basic_node into reference to a target native data type. |
 
 ### Iterators
 | Name              | Description                                              |

diff --git a/docs/mkdocs/docs/api/basic_node/insertion_operator.md b/docs/mkdocs/docs/api/basic_node/insertion_operator.md
@@ -0,0 +1,93 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::</small>operator<<
+
+```cpp
+inline std::ostream& operator<<(std::ostream& os, const basic_node& n);
+```
+
+Extraction operator for basic_node template class.  
+Serializes YAML node values into an output stream.  
+This API is a wrapper of [`basic_node::serialize()`](serialize.md) function to simplify the implementation in the user's code.  
+For more detailed descriptions, please visit the reference page for the [`basic_node::serialize()`](serialize.md) function.  
+
+## **Template Parameters**
+
+***SequenceType***
+:   Type for sequence node value containers.
+
+***MappingType***
+:   Type for mapping node value containers.
+
+***BooleanType***
+:   Type for boolean node values.
+
+***IntegerType***
+:   Type for integer node values.
+
+***FloatNumberType***
+:   Type for float number node values.
+
+***StringType***
+:   Type for string node values.
+
+***ConverterType***
+:   Type for converters between nodes and values of native data types.
+
+## **Parameters**
+
+***`os`*** [in]
+:   An output stream object.
+
+***`n`*** [in]
+:   A basic_node object.
+
+## **Return Value**
+
+Reference to the output stream object `os`.  
+
+???+ Example
+
+    ```cpp
+    #include <iostream>
+    #include <fkYAML/node.hpp>
+
+    int main()
+    {
+        // create a basic_node object.
+        fkyaml::node n = {
+            {"foo", true},
+            {"bar", {1, 2, 3}},
+            {"baz", {
+                {"qux", 3.14},
+                {"corge", nullptr}
+            }}
+        };
+
+        // serialize the basic_node object with insertion operator.
+        // this is equivalent with:
+        //   std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
+
+        return 0;
+    }
+    ```
+
+    output:
+    ```yaml
+    foo: true
+    bar:
+      - 1
+      - 2
+      - 3
+    baz:
+      qux: 3.14
+      corge: null
+    ```
+
+### **See Also**
+
+* [basic_node](index.md)
+* [serialize](serialize.md)
+* [deserialize](deserialize.md)
+* [operator>>](extraction_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/iterator.md b/docs/mkdocs/docs/api/basic_node/iterator.md
@@ -22,7 +22,7 @@ This iterator type is commonly used for sequence and mapping container values.
         fkyaml::node sequence_node = {1, 2, 3};
         // get an iterator to the first sequence element.
         fkyaml::node::iterator it = sequence_node.begin();
-        std::cout << fkyaml::node::serialize(*it) << std::endl;
+        std::cout << *it << std::endl;
         return 0;
     };
     ```
@@ -37,3 +37,4 @@ This iterator type is commonly used for sequence and mapping container values.
 * [basic_node](index.md)
 * [begin](begin.md)
 * [const_iterator](const_iterator.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/mapping.md b/docs/mkdocs/docs/api/basic_node/mapping.md
@@ -25,7 +25,7 @@ The resulting basic_node has the [`node_t::MAPPING`](node_t.md) type.
             {"bar", 3.14}
         };
         fkyaml::node n = fkyaml::node::mapping(m);
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -41,3 +41,4 @@ The resulting basic_node has the [`node_t::MAPPING`](node_t.md) type.
 
 * [basic_node](index.md)
 * [node_t](node_t.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/node.md b/docs/mkdocs/docs/api/basic_node/node.md
@@ -31,7 +31,7 @@ This type is the default specialization of the [basic_node](index.md) class whic
         n["qux"]["key"] = {"another", "value"};
 
         // output a YAML formatted string.
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
     };
     ```
 
@@ -51,4 +51,5 @@ This type is the default specialization of the [basic_node](index.md) class whic
 
 ### **See Also**
 
-* [basic_node](index.md)
+* [basic_node](index.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/operator[].md b/docs/mkdocs/docs/api/basic_node/operator[].md
@@ -61,10 +61,10 @@ Reference, or constant reference, to the YAML node at the given index.
         fkyaml::node n = {123, 234, 345, 456};
 
         // print YAML nodes at the following indexes.
-        std::cout << fkyaml::node::serialize(n[0]) << std::endl;
-        std::cout << fkyaml::node::serialize(n[1]) << std::endl;
-        std::cout << fkyaml::node::serialize(n[2]) << std::endl;
-        std::cout << fkyaml::node::serialize(n[3]) << std::endl;
+        std::cout << n[0] << std::endl;
+        std::cout << n[1] << std::endl;
+        std::cout << n[2] << std::endl;
+        std::cout << n[3] << std::endl;
         return 0;
     }
     ```
@@ -123,8 +123,8 @@ Reference, or constant reference, to the YAML node associated with the given key
         fkyaml::node n = {{"foo", true}, {"bar", 123}};
 
         // print YAML nodes associated with the following keys.
-        std::cout << std::boolalpha << fkyaml::node::serialize(n["foo"]) << std::endl;
-        std::cout << fkyaml::node::serialize(n["bar"]) << std::endl;
+        std::cout << std::boolalpha << n["foo"] << std::endl;
+        std::cout << n["bar"] << std::endl;
 
         return 0;
     }
@@ -135,3 +135,4 @@ Reference, or constant reference, to the YAML node associated with the given key
 * [basic_node](index.md)
 * [size](size.md)
 * [contains](contains.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/basic_node/sequence.md b/docs/mkdocs/docs/api/basic_node/sequence.md
@@ -22,7 +22,7 @@ The resulting basic_node has the [`node_t::SEQUENCE`](node_t.md) type.
     {
         fkyaml::node::sequence_type s = {fkyaml::node(true), fkyaml::node(false)};
         fkyaml::node n = fkyaml::node::sequence(s);
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
         return 0;
     }
     ```
@@ -38,3 +38,4 @@ The resulting basic_node has the [`node_t::SEQUENCE`](node_t.md) type.
 
 * [basic_node](index.md)
 * [node_t](node_t.md)
+* [operator<<](insertion_operator.md)
diff --git a/docs/mkdocs/docs/api/node_value_converter/to_node.md b/docs/mkdocs/docs/api/node_value_converter/to_node.md
@@ -67,7 +67,7 @@ This function is usually called by the constructors of the [`basic_node`](../bas
 
         fkyaml::node n = b;
 
-        std::cout << fkyaml::node::serialize(n) << std::endl;
+        std::cout << n << std::endl;
 
         return 0;
     }
@@ -85,3 +85,4 @@ This function is usually called by the constructors of the [`basic_node`](../bas
 * [node](../basic_node/node.md)
 * [basic_node::(constructor)](../basic_node/constructor.md)
 * [basic_node::serialize](../basic_node/serialize.md)
+* [operator<<(basic_node)](../basic_node/insertion_operator.md)