Replace getters for reference to node values (#481)

* implemented as_xxx() in basic_node template class to replace get_value_ref() * replaced internal get_value_ref() calls with as_xxx() * added test cases for as_xxx() functions * added api references & examples for the new as_xxx() functions * improved migration guide from get_value_ref
fktn-k · Feb 5, 2025 · 06dec7b · 06dec7b
1 parent f8a276d
commit 06dec7b
Show file tree

Hide file tree

Showing 49 changed files with 1,385 additions and 628 deletions.
diff --git a/README.md b/README.md
@@ -36,10 +36,9 @@ works on:
     auto node = fkyaml::node::deserialize(yaml);
 
     // 2. Modify it.
-    //    `fkyaml::node::sequence_type` is `std::vector<fkyaml::node>`.
+    //    as_seq() returns a `std::vector<fkyaml::node>&` object.
     node["maintainer"] = "fktn-k";
-    node.at("works on").get_value_ref<fkyaml::node::sequence_type&>()
-                       .emplace_back("Windows");
+    node.at("works on").as_seq().emplace_back("Windows");
 
     // 3. serialize the modified document to a YAML string and save it.
     std::ofstream ofs("out.yaml");
@@ -106,7 +105,7 @@ See the [supported compilers](#supported-compilers) section for more details.
     * YAML syntax
         * Support scalars, sequences, mappings in both block and flow styles.
             * Sequences and mappings are accepted as mapping keys in de/serialization. Such a key can also be passed to query a mapping value like [`operator[]`](https://fktn-k.github.io/fkYAML/api/basic_node/operator[]/) or [`at`](https://fktn-k.github.io/fkYAML/api/basic_node/at/).
-            * Values can be referenced by [`get_value_ref`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value_ref/) or converted to arbitrary types by [`get_value`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value/) or [`get_value_inplace`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value_inplace/).
+            * Node values can be referenced by using [`as_seq`](https://fktn-k.github.io/fkYAML/api/basic_node/as_seq/) or [`as_map`](https://fktn-k.github.io/fkYAML/api/basic_node/as_map/), or converted to arbitrary types by [`get_value`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value/) or [`get_value_inplace`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value_inplace/).
             * Empty mapping keys like `: value` or `- : value` are NOT supported.
         * Support `%TAG` and `%YAML` directives
             * `%YAML` directives have no effect and YAML 1.2 is always assumed.

diff --git a/docs/docs/api/basic_node/as_bool.md b/docs/docs/api/basic_node/as_bool.md
@@ -0,0 +1,32 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::basic_node::</small>as_bool
+
+```cpp
+boolean_type& as_bool();
+const boolean_type& as_bool() const;
+```
+
+Returns (const) reference to the boolean node value.  
+If the current node value is not a boolean, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
+
+## **Return Value**
+
+(const) reference to the boolean node value.  
+
+## **Examples**
+
+??? Example
+
+    ```cpp
+    --8<-- "apis/basic_node/as_bool.cpp:9"
+    ```
+
+    output:
+    ```bash
+    --8<-- "apis/basic_node/as_bool.output"
+    ```
+
+## **See Also**
+
+* [node_type](../node_type.md)
diff --git a/docs/docs/api/basic_node/as_float.md b/docs/docs/api/basic_node/as_float.md
@@ -0,0 +1,32 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::basic_node::</small>as_float
+
+```cpp
+float_number_type& as_float();
+const float_number_type& as_float() const;
+```
+
+Returns (const) reference to the float node value.  
+If the current node value is not a floating point value, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
+
+## **Return Value**
+
+(const) reference to the float node value.  
+
+## **Examples**
+
+??? Example
+
+    ```cpp
+    --8<-- "apis/basic_node/as_float.cpp:9"
+    ```
+
+    output:
+    ```bash
+    --8<-- "apis/basic_node/as_float.output"
+    ```
+
+## **See Also**
+
+* [node_type](../node_type.md)
diff --git a/docs/docs/api/basic_node/as_int.md b/docs/docs/api/basic_node/as_int.md
@@ -0,0 +1,32 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::basic_node::</small>as_int
+
+```cpp
+integer_type& as_int();
+const integer_type& as_int() const;
+```
+
+Returns (const) reference to the integer node value.  
+If the current node value is not an integer, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
+
+## **Return Value**
+
+(const) reference to the integer node value.  
+
+## **Examples**
+
+??? Example
+
+    ```cpp
+    --8<-- "apis/basic_node/as_int.cpp:9"
+    ```
+
+    output:
+    ```bash
+    --8<-- "apis/basic_node/as_int.output"
+    ```
+
+## **See Also**
+
+* [node_type](../node_type.md)
diff --git a/docs/docs/api/basic_node/as_map.md b/docs/docs/api/basic_node/as_map.md
@@ -0,0 +1,32 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::basic_node::</small>as_map
+
+```cpp
+mapping_type& as_map();
+const mapping_type& as_map() const;
+```
+
+Returns (const) reference to the mapping node value.  
+If the current node value is not a mapping, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
+
+## **Return Value**
+
+(const) reference to the mapping node value.  
+
+## **Examples**
+
+??? Example
+
+    ```cpp
+    --8<-- "apis/basic_node/as_map.cpp:9"
+    ```
+
+    output:
+    ```bash
+    --8<-- "apis/basic_node/as_map.output"
+    ```
+
+## **See Also**
+
+* [node_type](../node_type.md)
diff --git a/docs/docs/api/basic_node/as_seq.md b/docs/docs/api/basic_node/as_seq.md
@@ -0,0 +1,32 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::basic_node::</small>as_seq
+
+```cpp
+sequence_type& as_seq();
+const sequence_type& as_seq() const;
+```
+
+Returns (const) reference to the sequence node value.  
+If the current node value is not an sequence, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
+
+## **Return Value**
+
+(const) reference to the sequence node value.  
+
+## **Examples**
+
+??? Example
+
+    ```cpp
+    --8<-- "apis/basic_node/as_seq.cpp:9"
+    ```
+
+    output:
+    ```bash
+    --8<-- "apis/basic_node/as_seq.output"
+    ```
+
+## **See Also**
+
+* [node_type](../node_type.md)
diff --git a/docs/docs/api/basic_node/as_str.md b/docs/docs/api/basic_node/as_str.md
@@ -0,0 +1,32 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::basic_node::</small>as_str
+
+```cpp
+string_type& as_str();
+const string_type& as_str() const;
+```
+
+Returns (const) reference to the string node value.  
+If the current node value is not an string, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
+
+## **Return Value**
+
+(const) reference to the string node value.  
+
+## **Examples**
+
+??? Example
+
+    ```cpp
+    --8<-- "apis/basic_node/as_str.cpp:9"
+    ```
+
+    output:
+    ```bash
+    --8<-- "apis/basic_node/as_str.output"
+    ```
+
+## **See Also**
+
+* [node_type](../node_type.md)
diff --git a/docs/docs/api/basic_node/get_value.md b/docs/docs/api/basic_node/get_value.md
@@ -30,7 +30,13 @@ This function converts a [`fkyaml::basic_node`](./index.md) to either
    ```
 
 Actual conversions rely on the [`node_value_converter`](../node_value_converter/index.md)::[`from_node`](../node_value_converter/from_node.md) function.  
-This API makes a copy of the value, and if the copying costs too much, or if you need an address of the original value, then you should call [`get_value_ref`](get_value_ref.md) instead.  
+This API makes a copy of the value, and if the copying costs too much, or if you need an address of the original value, then you should call one of the following functions instead.
+* [`as_seq`](as_seq.md)
+* [`as_map`](as_map.md)
+* [`as_bool`](as_bool.md)
+* [`as_int`](as_int.md)
+* [`as_float`](as_float.md)
+* [`as_str`](as_str.md)
 
 ??? Note "Convert from a Sequence Node"
 
@@ -135,5 +141,10 @@ A compatible native data value converted from the [basic_node](./index.md) objec
 
 * [basic_node](index.md)
 * [get_value_inplace](get_value_inplace.md)
-* [get_value_ref](get_value_ref.md)
+* [as_seq](as_seq.md)
+* [as_map](as_map.md)
+* [as_bool](as_bool.md)
+* [as_int](as_int.md)
+* [as_float](as_float.md)
+* [as_str](as_str.md)
 * [node_value_converter::from_node](../node_value_converter/from_node.md)
diff --git a/docs/docs/api/basic_node/get_value_inplace.md b/docs/docs/api/basic_node/get_value_inplace.md
@@ -67,5 +67,10 @@ See the notes there for details.
 
 * [basic_node](index.md)
 * [get_value](get_value.md)
-* [get_value_ref](get_value_ref.md)
+* [as_seq](as_seq.md)
+* [as_map](as_map.md)
+* [as_bool](as_bool.md)
+* [as_int](as_int.md)
+* [as_float](as_float.md)
+* [as_str](as_str.md)
 * [node_value_converter::from_node](../node_value_converter/from_node.md)
diff --git a/docs/docs/api/basic_node/get_value_ref.md b/docs/docs/api/basic_node/get_value_ref.md
@@ -10,6 +10,28 @@ template <typename ReferenceType>
 ReferenceType get_value_ref() const;
 ```
 
+!!! warning "Deprecation"
+
+    This function has been deprecated in version 0.4.3 and replaced with the following functions since it offers too verbose interface and that may confuse library users, given that only non-/const reference types to [`sequence_type`](sequence_type.md), [`mapping_type`](mapping_type.md), [`boolean_type`](boolean_type.md), [`integer_type`](integer_type.md), [`float_number_type`](float_number_type.md) and [`string_type`](string_type.md) are accepted and that violating the limitation is not clear from error messages during compilation.  
+
+    * [as_seq](as_seq.md)
+    * [as_map](as_map.md)
+    * [as_bool](as_bool.md)
+    * [as_int](as_int.md)
+    * [as_float](as_float.md)
+    * [as_str](as_str.md)
+
+    It will be removed in a future version. Please replace usages according to the following table.  
+
+    | from                                                                             | to         |
+    | -------------------------------------------------------------------------------- | ---------- |
+    | get_value_ref<sequence_type&>(),<br>get_value_ref<const sequence_type&>()         | as_seq()   |
+    | get_value_ref<mapping_type&>(),<br>get_value_ref<const mapping_type&>()           | as_map()   |
+    | get_value_ref<boolean_type&>(),<br>get_value_ref<const boolean_type&>()           | as_bool()  |
+    | get_value_ref<integer_type&>(),<br>get_value_ref<const integer_type&>()           | as_int()   |
+    | get_value_ref<float_number_type&>(),<br>get_value_ref<const float_number_type&>() | as_float() |
+    | get_value_ref<string_type&>(),<br>get_value_ref<const string_type&>()             | as_str()   |
+
 Explicit reference access to the internally stored YAML node value.  
 If the requested reference type does not match the current node value, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
 
@@ -50,3 +72,9 @@ Reference to the internally stored YAML node value.
 ## **See Also**
 
 * [basic_node](index.md)
+* [as_seq](as_seq.md)
+* [as_map](as_map.md)
+* [as_bool](as_bool.md)
+* [as_int](as_int.md)
+* [as_float](as_float.md)
+* [as_str](as_str.md)
diff --git a/docs/docs/api/basic_node/index.md b/docs/docs/api/basic_node/index.md
@@ -106,7 +106,13 @@ This class provides features to handle YAML nodes.
 | [operator<<](insertion_operator.md)       |          | serializes a basic_node into an output stream.                          |
 | [get_value](get_value.md)                 |          | converts a basic_node into a target type.                               |
 | [get_value_inplace](get_value_inplace.md) |          | converts a basic_node into a target type and write it to a destination. |
-| [get_value_ref](get_value_ref.md)         |          | converts a basic_node into reference to a target type.                  |
+| [as_seq](as_seq.md)                       |          | get reference to the sequence node value.                               |
+| [as_map](as_map.md)                       |          | get reference to the mapping node value.                                |
+| [as_bool](as_bool.md)                     |          | get reference to the boolean node value.                                |
+| [as_int](as_int.md)                       |          | get reference to the integer node value.                                |
+| [as_float](as_float.md)                   |          | get reference to the float node value.                                  |
+| [as_str](as_str.md)                       |          | get reference to the string node value.                                 |
+| [get_value_ref](get_value_ref.md)         |          | **(DEPRECATED)** converts a basic_node into reference to a target type. |
 
 ### Iterators
 | Name                      | Description                                                                                                |

diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -36,10 +36,9 @@ works on:
     auto node = fkyaml::node::deserialize(yaml);
 
     // 2. Modify it.
-    //    `fkyaml::node::sequence_type` is `std::vector<fkyaml::node>`.
+    //    as_seq() returns a `std::vector<fkyaml::node>&` object.
     node["maintainer"] = "fktn-k";
-    node.at("works on").get_value_ref<fkyaml::node::sequence_type&>()
-                       .emplace_back("Windows");
+    node.at("works on").as_seq().emplace_back("Windows");
 
     // 3. serialize the modified document to a YAML string and save it.
     std::ofstream ofs("out.yaml");
@@ -106,7 +105,7 @@ See the [supported compilers](#supported-compilers) section for more details.
     * YAML syntax
         * Support scalars, sequences, mappings in both block and flow styles.
             * Sequences and mappings are accepted as mapping keys in de/serialization. Such a key can also be passed to query a mapping value like [`operator[]`](https://fktn-k.github.io/fkYAML/api/basic_node/operator[]/) or [`at`](https://fktn-k.github.io/fkYAML/api/basic_node/at/).
-            * Values can be referenced by [`get_value_ref`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value_ref/) or converted to arbitrary types by [`get_value`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value/) or [`get_value_inplace`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value_inplace/).
+            * Node values can be referenced by using [`as_seq`](https://fktn-k.github.io/fkYAML/api/basic_node/as_seq/) or [`as_map`](https://fktn-k.github.io/fkYAML/api/basic_node/as_map/), or converted to arbitrary types by [`get_value`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value/) or [`get_value_inplace`](https://fktn-k.github.io/fkYAML/api/basic_node/get_value_inplace/).
             * Empty mapping keys like `: value` or `- : value` are NOT supported.
         * Support `%TAG` and `%YAML` directives
             * `%YAML` directives have no effect and YAML 1.2 is always assumed.

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -109,8 +109,6 @@ nav:
       - 'iterator, const_iterator': api/basic_node/iterator.md
       - 'reverse_iterator, const_reverse_iterator': api/basic_node/reverse_iterator.md
       - value_converter_type: api/basic_node/value_converter_type.md
-      - node_t: api/basic_node/node_t.md
-      - yaml_version_t: api/basic_node/yaml_version_t.md
       - 'map_range, const_map_range': api/basic_node/map_range.md
     - (constructor): api/basic_node/constructor.md
     - (destructor): api/basic_node/destructor.md
@@ -126,6 +124,12 @@ nav:
     - add_anchor_name: api/basic_node/add_anchor_name.md
     - add_tag_name: api/basic_node/add_tag_name.md
     - alias_of: api/basic_node/alias_of.md
+    - as_bool: api/basic_node/as_bool.md
+    - as_float: api/basic_node/as_float.md
+    - as_int: api/basic_node/as_int.md
+    - as_map: api/basic_node/as_map.md
+    - as_seq: api/basic_node/as_seq.md
+    - as_str: api/basic_node/as_str.md
     - at: api/basic_node/at.md
     - 'begin, cbegin': api/basic_node/begin.md
     - contains: api/basic_node/contains.md
@@ -138,8 +142,6 @@ nav:
     - get_type: api/basic_node/get_type.md
     - get_value: api/basic_node/get_value.md
     - get_value_inplace: api/basic_node/get_value_inplace.md
-    - get_value_ref: api/basic_node/get_value_ref.md
-    - get_yaml_version: api/basic_node/get_yaml_version.md
     - get_yaml_version_type: api/basic_node/get_yaml_version_type.md
     - has_anchor_name: api/basic_node/has_anchor_name.md
     - has_tag_name: api/basic_node/has_tag_name.md
@@ -161,11 +163,16 @@ nav:
     - sequence: api/basic_node/sequence.md
     - serialize: api/basic_node/serialize.md
     - serialize_docs: api/basic_node/serialize_docs.md
-    - set_yaml_version: api/basic_node/set_yaml_version.md
     - set_yaml_version_type: api/basic_node/set_yaml_version_type.md
     - size: api/basic_node/size.md
     - swap: api/basic_node/swap.md
-    - type: api/basic_node/type.md
+    - deprecated:
+      - node_t: api/basic_node/node_t.md
+      - yaml_version_t: api/basic_node/yaml_version_t.md
+      - get_value_ref: api/basic_node/get_value_ref.md
+      - get_yaml_version: api/basic_node/get_yaml_version.md
+      - set_yaml_version: api/basic_node/set_yaml_version.md
+      - type: api/basic_node/type.md
   - exception:
     - exception: api/exception/index.md
     - (constructor): api/exception/constructor.md

diff --git a/examples/apis/basic_node/alias_of.cpp b/examples/apis/basic_node/alias_of.cpp
@@ -20,7 +20,7 @@ int main() {
     fkyaml::node alias_node = fkyaml::node::alias_of(anchor_node);
 
     // print the value in the alias node.
-    std::cout << alias_node.get_value_ref<fkyaml::node::string_type&>() << std::endl;
+    std::cout << alias_node.as_str() << std::endl;
 
     return 0;
 }