PengZheng commented on code in PR #743:
URL: https://github.com/apache/celix/pull/743#discussion_r1577598742
##########
libs/utils/include/celix_properties.h:
##########
@@ -936,6 +936,348 @@ CELIX_UTILS_EXPORT bool
celix_propertiesIterator_equals(const celix_properties_i
!celix_propertiesIterator_isEnd(&(iterName));
\
celix_propertiesIterator_next(&(iterName)))
+/**
+ * @brief Flag to indicate that the encoded output should be pretty; e.g.
encoded with additional whitespaces,
+ * newlines and indentation.
+ *
+ * If this flag is not set, the encoded output will compact; e.g. without
additional whitespaces, newlines and
+ * indentation.
+ */
+#define CELIX_PROPERTIES_ENCODE_PRETTY 0x01
+
+/**
+ * @brief Flag to indicate that the encoded output should be flat; e.g. all
properties entries are written as top level
+ * field entries.
+ *
+ * E.g:
+ * @code{.c}
+ * celix_properties_t* properties = celix_properties_create();
+ * celix_properties_setString(properties, "key/with/slash", "value1");
+ * celix_properties_setString(properties, "key", "value2");
+ * char* json;
+ * celix_properties_saveToString(properties, CELIX_PROPERTIES_ENCODE_FLAT,
&json);
+ * // json will be: {"key/with/slash": "value1", "key": "value2"}
+ * @endcode
+ *
+ * Note that encoding with a flat encoding style, all properties keys are
unique JSON keys and can be written.
+ *
+ * If no encoding style flag is set, the encoded output will use the default
encoding style.
+ */
+#define CELIX_PROPERTIES_ENCODE_FLAT_STYLE 0x02
+
+/**
+ * @brief Flag to indicate that the encoded output should be nested; e.g.
properties entries are split on '/' and nested
+ * in JSON objects.
+ *
+ * E.g:
+ * @code{.c}
+ * celix_properties_t* properties = celix_properties_create();
+ * celix_properties_setString(properties, "key/with/slash", "value1");
+ * celix_properties_setString(properties, "key", "value2");
+ * char* json;
+ * celix_properties_saveToString(properties, CELIX_PROPERTIES_ENCODE_NESTED,
&json);
+ * // json will be: {"key":{"with":{"slash": "value1"}}}
+ * // or
+ * // json will be: {"key": "value2"}
+ * @endcode
+ *
+ * Note that encoding with a nested encoding style, it properties key can
collide resulting in missing properties
+ * entries or (if CELIX_PROPERTIES_ENCODE_ERROR_ON_COLLISIONS is set) an error.
+ *
+ * If no encoding style flag is set, the encoded output will use the default
encoding style.
+ */
+#define CELIX_PROPERTIES_ENCODE_NESTED_STYLE 0x04
+
+/**
+ * @brief Flag to indicate that the encoding should fail if the JSON
representation will contain colliding keys.
+ *
+ * Note that colliding keys can only occur when using the nested encoding
style.
+ *
+ * E.g. the following will lead to an error:
+ * @code{.c}
+ * celix_properties_t* properties = celix_properties_create();
+ * celix_properties_setString(properties, "key/with/slash", "value1");
+ * celix_properties_setString(properties, "key", "value2"); //collision
+ * char* json;
+ * celix_status_t status = celix_properties_saveToString(properties,
CELIX_PROPERTIES_ENCODE_NESTED, &json);
+ * // status will be CELIX_ILLEGAL_ARGUMENT and a error message will be logged
to celix_err
+ * @endcode
+ *
+ * If this flag is set, the encoding will fail if the JSON representation will
contain colliding keys and if this flag
+ * is not set, the encoding will not fail and the colliding keys will be
ignored.
+ */
+#define CELIX_PROPERTIES_ENCODE_ERROR_ON_COLLISIONS 0x10
+
+/**
+ * @brief Flag to indicate that the encoding should fail if the JSON
representation will contain empty arrays.
+ *
+ * Although empty arrays are valid in JSON, they cannot be decoded to a valid
properties array entry and as such
+ * empty arrays properties entries are not encoded.
+ *
+ * If this flag is set, the encoding will fail if the JSON representation will
contain empty arrays and if this flag
+ * is not set, the encoding will not fail and the empty arrays will be ignored.
+ */
+#define CELIX_PROPERTIES_ENCODE_ERROR_ON_EMPTY_ARRAYS 0x20
+
+/**
+ * @brief Flag to indicate that the encoding should fail if the JSON
representation will contain NaN or Inf values.
+ *
+ * NaN, Inf and -Inf are not valid JSON values and as such properties entries
with these values are not encoded.
+ *
+ * If this flag is set, the encoding will fail if the JSON representation will
contain NaN or Inf values and if this
+ * flag is not set, the encoding will not fail and the NaN and Inf entries
will be ignored.
+ */
+#define CELIX_PROPERTIES_ENCODE_ERROR_ON_NAN_INF 0x40
+
+/**
+ * @brief Flag to indicate that all encode "error on" flags should be set.
+ */
+#define CELIX_PROPERTIES_ENCODE_STRICT
\
+ (CELIX_PROPERTIES_ENCODE_ERROR_ON_COLLISIONS |
CELIX_PROPERTIES_ENCODE_ERROR_ON_EMPTY_ARRAYS)
+
+/**
+ * @brief Save (encode) as a JSON representation to a stream.
+ *
+ * The stream is expected to be a valid stream and is not reset or closed by
this function.
+ *
+ * Properties are encoded as a JSON object.
+ *
+ * If no encoding style flag is set of when the
CELIX_PROPERTIES_ENCODE_FLAT_STYLE flag is set, properties
+ * entries are written as top level field entries.
+ *
+ * If the CELIX_PROPERTIES_ENCODE_NESTED_STYLE flag is set, properties entry
keys are split on '/' and nested in
+ * JSON objects. This leads to a more natural JSON representation, but if
there are colliding properties keys (e.g.
+ * `{"key": "value1", "key/with/slash": "value2"}`), not all properties
entries will be written.
+ *
+ * With all encoding styles, the empty array properties entries are ignored,
because they cannot be decoded to a valid
+ * properties array entry.
+ *
+ * Properties type entries are encoded as follows:
+ * - CELIX_PROPERTIES_TYPE_STRING: The value is encoded as a JSON string.
+ * - CELIX_PROPERTIES_TYPE_LONG: The value is encoded as a JSON number.
+ * - CELIX_PROPERTIES_TYPE_DOUBLE: The value is encoded as a JSON number.
+ * - CELIX_PROPERTIES_TYPE_BOOL: The value is encoded as a JSON boolean.
+ * - CELIX_PROPERTIES_TYPE_ARRAY: The value is encoded as a JSON array, with
each element encoded according to its type.
+ * - CELIX_PROPERTIES_TYPE_VERSION: The value is encoded as a JSON string with
a "version<" prefix and a ">" suffix
+ * (e.g. "version<1.2.3>").
+ *
+ * For a overview of the possible encode flags, see the
CELIX_PROPERTIES_ENCODE_* flags documentation.
+ * The default encoding style is a compact and flat JSON representation.
+ *
+ * @param properties The properties object to encode.
+ * @param stream The stream to write the JSON representation of the properties
object to.
+ * @param encodeFlags The flags to use when encoding the input string.
+ * @return CELIX_SUCCESS if the operation was successful,
CELIX_ILLEGAL_ARGUMENT if the provided properties cannot be
+ * encoded to a JSON representation and ENOMEM if there was not enough memory.
+ */
+CELIX_UTILS_EXPORT celix_status_t celix_properties_saveToStream(const
celix_properties_t* properties,
+ FILE* stream,
+ int
encodeFlags);
+
+/**
+ * @brief Save (encode) properties as a JSON representation to a file.
+ *
+ * For more information how a properties object is encoded to JSON, see the
celix_properties_loadFromStream
+ *
+ * For a overview of the possible encode flags, see the
CELIX_PROPERTIES_ENCODE_* flags documentation.
+ * The default encoding style is a compact and flat JSON representation.
+ *
+ * @param[in] properties The properties object to encode.
+ * @param[in] filename The file to write the JSON representation of the
properties object to.
+ * @param[in] encodeFlags The flags to use when encoding the input string.
Review Comment:
```suggestion
* @param[in] encodeFlags The flags to use when encoding the input
properties.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscr...@celix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
