fast-xml 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b75570b8870b00aff82edced0c1edb3965372998
-  data.tar.gz: 8b2f05fef2d9f371de80c9a23ded894ea686ff67
+  metadata.gz: 3bfc552fd27d382d26a930254300930396aed5da
+  data.tar.gz: f960e2a0cd0b2c38ad983ca497a1ef0664422929
 SHA512:
-  metadata.gz: faa6545061a4db90b9789ca08cbeb76b75d81528362b14d204f49c54f959f07abf443026710274b1d1089d491fda166cc3c979f849b87b0c52f8a0031bd67b74
-  data.tar.gz: 94c4368c92b886c39fc54316ffde0175a6fe7f33c2c7836cb9b3406750552e85a6955fcfd5106eb481782689848febc197dbd3e77b4fb753eb791c7601a9936f
+  metadata.gz: 958ee82a61a7d887f72dc89db46cc928a322012406ed816b368a03a0f35106ca6b6104e482d4deaa214ce66f7c471d4b15d267d03957b2da083693056309ac5a
+  data.tar.gz: 3629dd0432f31eb23ef46fed569a942cf0f01749c33a2684109aa677d56442110d46264aac0bfa0250fdc63113eea3f95c6bd626a5cefd3c5b66b5afa734176f

data/README.md

@@ -26,10 +26,11 @@ See [CHANGELOG.md](CHANGELOG.md)
 
 ## Usage
 
+### Convert hash toXML
+
 ```ruby
 require 'fastxml'
 
-# convert hash to XML
 FastXML.hash2xml({ tag1: { tag2: 'content' } }, indent: 2)
 # =>
 # <?xml version="1.0" encoding="utf-8"?>
@@ -60,83 +61,191 @@ fh.string
 #   <enumerator>1</enumerator>
 #   <enumerator>2</enumerator>
 # </root>
+```
 
+### Convert XML to hash
+
+```ruby
+FastXML.xml2hash('<root><a>aaa</a><a>aaa2</a><b attr="bbb">bbb2</b></root>')
+# => {"a"=>["aaa", "aaa2"], "b"=>{"attr"=>"bbb", "content"=>"bbb2"}}
+
+# use filter
+FastXML.xml2hash('<root><a>aaa</a><a>aaa2</a><b>bbb</b></root>', filter: '/root/a') do |node|
+  p node
+end
+# =>
+# {"a"=>"aaa"}
+# {"a"=>"aaa2"}
 ```
 
 ## Options
 
 The following options are available to pass to FastXML.hash2xml(hash, options = {}).
 
-* **:root** => 'root'
+* **:root => 'root' # hash2xml**
   * Root node name.
 
-* **:version** => '1.0'
+* **:version => '1.0' # hash2xml**
   * XML document version
 
-* **:encoding** => 'utf-8'
+* **:encoding => 'utf-8' # hash2xml + xml2hash**
   * XML input/output encoding
 
-* **:indent** => 0
-  * if indent great than "0", XML output should be indented according to
+* **:indent => 0 # hash2xml**
+  * if indent great than **0**, XML output should be indented according to
     its hierarchic structure. This value determines the number of
     spaces.
 
-  * if indent is "0", XML output will all be on one line.
+  * if indent is **0**, XML output will all be on one line.
 
-* **:output** => nil
+* **:output => nil # hash2xml**
   * XML output method
 
-  * if output is nil, XML document dumped into string.
+  * if output is **nil**, XML document dumped into string.
 
   * if output is filehandle, XML document writes directly to a filehandle or a
     stream.
 
-* **:canonical** => false
-  * if canonical is "true", converter will be write hashes sorted by key.
+* **:canonical => false # hash2xml**
+  * if canonical is **true**, the converter will be write hashes sorted by key.
+
+  * if canonical is **false**, the order of the element will be pseudo-randomly.
+
+* **:use_attr => false # hash2xml**
+  * if use_attr is **true**, the converter will be use the attributes.
+
+  * if use_attr is **fale**, the converter will be use tags only.
+
+* **:content => 'content' # hash2xml + xml2hash**
+  * The key name for the text content.
+
+* **:force_array => nil # xml2hash**
+  * When this option is **true**, the converter will be to force nested elements
+    to be represented as arrays even when there is only one.
+
+    ```FastXML.xml2hash('<root><a>aaa</a></root>', force_array: true)```
+
+    will be converted to:
+
+    ```{ "a" => ["aaa"] }```
+
+    instead of:
+
+    ```{ "a" => "aaa" }```
+
+  * When this option is an array, this allows to specify a list of element
+    names which should always be forced into an array representation,
+    rather than the 'all or nothing' approach above.
+
+    ```FastXML.xml2hash('<root><a>aaa</a><b>bbb</b></root>', force_array: ['a'])```
+
+    will be converted to:
+
+    ```{ "a" => ["aaa"], "b" => "bbb" }```
+
+    ```FastXML.xml2hash('<root><a>aaa</a><a2>aaa</a2><b>bbb</b></root>', force_array: [/^a/])```
+
+    will be converted to:
+
+    ```{ "a" => ["aaa"], "a2" => ["aaa"], "b" => "bbb" }```
+
+* **:force_content => false # xml2hash**
+  * When this options is **true**, this allows you to force text content to always
+    convert to a hash value.
+
+    ```FastXML.xml2hash('<root><a>value</a></root>', force_content: true)```
 
-  * if canonical is "false", order of the element will be pseudo-randomly.
+    will be converted to:
 
-* **:use_attr** => false
-  * if use_attr is "true", converter will be use the attributes.
+    ```{ "a" => { "content" => "value" } }```
 
-  * if use_attr is "fale", converter will be use tags only.
+    instead of:
 
-* **:content** => nil
-  * if defined that the key name for the text content(used only if
-    use_attr = true).
+    ```{ "a" => "value" }```
 
-* **:force_array** => nil
-  * This option is similar to "ForceArray" from [XMl::Simple module]:
-    (https://metacpan.org/pod/XML::Simple#ForceArray-1-in---important).
+* **:merge_text => false # xml2hash**
+  * Setting this option to **true** will cause merge adjacent text nodes.
 
-* **:force_content** => nil
-  * This option is similar to "ForceContent" from [XMl::Simple module]:
-    (https://metacpan.org/pod/XML::Simple#ForceContent-1-in---seldom-used).
+    ```FastXML.xml2hash('<root>value1<!-- comment -->value2</root>', merge_text: true)```
 
-* **:merge_text** => false
-  * Setting this option to "true" will cause merge adjacent text nodes.
+    will be converted to:
 
-* **:xml_decl** => true
-  * if xml_decl is "true", output will start with the XML declaration
-    '<?xml version="1.0" encoding="utf-8"?>'.
+    ```"value1value2"```
 
-  * if xml_decl is "false", XML declaration will not be output.
+    instead of:
 
-* **:trim** => false
+    ```["value1", "value2"]```
+
+* **:xml_decl => true # hash2xml**
+  * if xml_decl is **true**, output will start with the XML declaration
+    ```<?xml version="1.0" encoding="utf-8"?>```
+
+  * if xml_decl is **false**, XML declaration will not be output.
+
+* **:trim => false # hash2xml + xml2hash**
   * Trim leading and trailing whitespace from text nodes.
 
-* **:utf8** => true
-  * Turn on utf8 flag for strings if enabled.
+* **:utf8 => true # hash2xml + xml2hash**
+  * Turn on utf8 flag for strings if is **true**.
 
-* **:max_depth** => 1024
+* **:max_depth => 1024 # xml2hash**
   * Maximum recursion depth.
 
-* **:buf_size** => 4096
+* **:buf_size => 4096 # hash2xml + xml2hash**
   * Buffer size for reading end encoding data.
 
-* **:keep_root** => false
+* **:keep_root => false # xml2hash**
   * Keep root element.
 
+    ```FastXML.xml2hash('<root>value1</root>', keep_root: true)```
+
+    will be converted to:
+
+    ```{ "root" => "value1" }```
+
+    instead of:
+
+    ```"value1"```
+
+* **:filter => nil # xml2hash**
+  * Filter nodes matched by pattern and return an array of nodes.
+
+    ```FastXML.xml2hash('<root><a>aaa</a><a>aaa2</a><b>bbb</b></root>', filter: '/root/a')```
+
+    will be converted to:
+
+    ```[{ "a" => "aaa" }, { "a" => "aaa2" }]```
+
+    ```FastXML.xml2hash('<root><a>aaa</a><a>aaa2</a><b>bbb</b></root>', filter: /a|b/)```
+
+    will be converted to:
+
+    ```[{ "a" => "aaa" }, { "a" => "aaa2" }, { "b" => "bbb" }]```
+
+    ```FastXML.xml2hash('<root><a>aaa</a><a>aaa2</a><b>bbb</b></root>', filter: ['/root/a', '/root/b'])```
+
+    will be converted to:
+
+    ```[{ "a" => "aaa" }, { "a" => "aaa2" }, { "b" => "bbb" }]```
+
+  * You can pass a block as parameter.
+
+    ```
+    FastXML.xml2hash('<root><a>aaa</a><a>aaa2</a><b>bbb</b></root>', filter: '/root/a') do |node|
+      p node
+    end
+    ```
+
+    will be printed:
+
+    ```
+    {"a"=>"aaa"}
+    {"a"=>"aaa2"}
+    ```
+
+    It may be used to parse large XML because does not require a lot of
+    memory.
+
 ## Configuration
 ```
   FastXML.configure do |config|
@@ -161,4 +270,3 @@ fastxml                  0.010000   0.000000   0.010000 (  0.018434)
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/ext/fastxml/ccan/build_assert/build_assert.h

@@ -0,0 +1,40 @@
+/* CC0 (Public domain) - see ccan/licenses/CC0 file for details */
+#ifndef CCAN_BUILD_ASSERT_H
+#define CCAN_BUILD_ASSERT_H
+
+/**
+ * BUILD_ASSERT - assert a build-time dependency.
+ * @cond: the compile-time condition which must be true.
+ *
+ * Your compile will fail if the condition isn't true, or can't be evaluated
+ * by the compiler.  This can only be used within a function.
+ *
+ * Example:
+ *	#include <stddef.h>
+ *	...
+ *	static char *foo_to_char(struct foo *foo)
+ *	{
+ *		// This code needs string to be at start of foo.
+ *		BUILD_ASSERT(offsetof(struct foo, string) == 0);
+ *		return (char *)foo;
+ *	}
+ */
+#define BUILD_ASSERT(cond) \
+	do { (void) sizeof(char [1 - 2*!(cond)]); } while(0)
+
+/**
+ * BUILD_ASSERT_OR_ZERO - assert a build-time dependency, as an expression.
+ * @cond: the compile-time condition which must be true.
+ *
+ * Your compile will fail if the condition isn't true, or can't be evaluated
+ * by the compiler.  This can be used in an expression: its value is "0".
+ *
+ * Example:
+ *	#define foo_to_char(foo)					\
+ *		 ((char *)(foo)						\
+ *		  + BUILD_ASSERT_OR_ZERO(offsetof(struct foo, string) == 0))
+ */
+#define BUILD_ASSERT_OR_ZERO(cond) \
+	(sizeof(char [1 - 2*!(cond)]) - 1)
+
+#endif /* CCAN_BUILD_ASSERT_H */

data/ext/fastxml/ccan/check_type/check_type.h

@@ -0,0 +1,63 @@
+/* CC0 (Public domain) - see ccan/licenses/CC0 file for details */
+#ifndef CCAN_CHECK_TYPE_H
+#define CCAN_CHECK_TYPE_H
+
+/**
+ * check_type - issue a warning or build failure if type is not correct.
+ * @expr: the expression whose type we should check (not evaluated).
+ * @type: the exact type we expect the expression to be.
+ *
+ * This macro is usually used within other macros to try to ensure that a macro
+ * argument is of the expected type.  No type promotion of the expression is
+ * done: an unsigned int is not the same as an int!
+ *
+ * check_type() always evaluates to 0.
+ *
+ * If your compiler does not support typeof, then the best we can do is fail
+ * to compile if the sizes of the types are unequal (a less complete check).
+ *
+ * Example:
+ *	// They should always pass a 64-bit value to _set_some_value!
+ *	#define set_some_value(expr)			\
+ *		_set_some_value((check_type((expr), uint64_t), (expr)))
+ */
+
+/**
+ * check_types_match - issue a warning or build failure if types are not same.
+ * @expr1: the first expression (not evaluated).
+ * @expr2: the second expression (not evaluated).
+ *
+ * This macro is usually used within other macros to try to ensure that
+ * arguments are of identical types.  No type promotion of the expressions is
+ * done: an unsigned int is not the same as an int!
+ *
+ * check_types_match() always evaluates to 0.
+ *
+ * If your compiler does not support typeof, then the best we can do is fail
+ * to compile if the sizes of the types are unequal (a less complete check).
+ *
+ * Example:
+ *	// Do subtraction to get to enclosing type, but make sure that
+ *	// pointer is of correct type for that member.
+ *	#define container_of(mbr_ptr, encl_type, mbr)			\
+ *		(check_types_match((mbr_ptr), &((encl_type *)0)->mbr),	\
+ *		 ((encl_type *)						\
+ *		  ((char *)(mbr_ptr) - offsetof(enclosing_type, mbr))))
+ */
+#if HAVE_TYPEOF
+#define check_type(expr, type)			\
+	((typeof(expr) *)0 != (type *)0)
+
+#define check_types_match(expr1, expr2)		\
+	((typeof(expr1) *)0 != (typeof(expr2) *)0)
+#else
+#include "ccan/build_assert/build_assert.h"
+/* Without typeof, we can only test the sizes. */
+#define check_type(expr, type)					\
+	BUILD_ASSERT_OR_ZERO(sizeof(expr) == sizeof(type))
+
+#define check_types_match(expr1, expr2)				\
+	BUILD_ASSERT_OR_ZERO(sizeof(expr1) == sizeof(expr2))
+#endif /* HAVE_TYPEOF */
+
+#endif /* CCAN_CHECK_TYPE_H */

data/ext/fastxml/ccan/container_of/container_of.h

@@ -0,0 +1,142 @@
+/* CC0 (Public domain) - see ccan/licenses/CC0 file for details */
+#ifndef CCAN_CONTAINER_OF_H
+#define CCAN_CONTAINER_OF_H
+#include "ccan/check_type/check_type.h"
+
+/**
+ * container_of - get pointer to enclosing structure
+ * @member_ptr: pointer to the structure member
+ * @containing_type: the type this member is within
+ * @member: the name of this member within the structure.
+ *
+ * Given a pointer to a member of a structure, this macro does pointer
+ * subtraction to return the pointer to the enclosing type.
+ *
+ * Example:
+ *	struct foo {
+ *		int fielda, fieldb;
+ *		// ...
+ *	};
+ *	struct info {
+ *		int some_other_field;
+ *		struct foo my_foo;
+ *	};
+ *
+ *	static struct info *foo_to_info(struct foo *foo)
+ *	{
+ *		return container_of(foo, struct info, my_foo);
+ *	}
+ */
+#define container_of(member_ptr, containing_type, member)		\
+	 ((containing_type *)						\
+	  ((char *)(member_ptr)						\
+	   - container_off(containing_type, member))			\
+	  + check_types_match(*(member_ptr), ((containing_type *)0)->member))
+
+
+/**
+ * container_of_or_null - get pointer to enclosing structure, or NULL
+ * @member_ptr: pointer to the structure member
+ * @containing_type: the type this member is within
+ * @member: the name of this member within the structure.
+ *
+ * Given a pointer to a member of a structure, this macro does pointer
+ * subtraction to return the pointer to the enclosing type, unless it
+ * is given NULL, in which case it also returns NULL.
+ *
+ * Example:
+ *	struct foo {
+ *		int fielda, fieldb;
+ *		// ...
+ *	};
+ *	struct info {
+ *		int some_other_field;
+ *		struct foo my_foo;
+ *	};
+ *
+ *	static struct info *foo_to_info_allowing_null(struct foo *foo)
+ *	{
+ *		return container_of_or_null(foo, struct info, my_foo);
+ *	}
+ */
+static inline char *container_of_or_null_(void *member_ptr, size_t offset)
+{
+	return member_ptr ? (char *)member_ptr - offset : NULL;
+}
+#define container_of_or_null(member_ptr, containing_type, member)	\
+	((containing_type *)						\
+	 container_of_or_null_(member_ptr,				\
+			       container_off(containing_type, member))	\
+	 + check_types_match(*(member_ptr), ((containing_type *)0)->member))
+
+/**
+ * container_off - get offset to enclosing structure
+ * @containing_type: the type this member is within
+ * @member: the name of this member within the structure.
+ *
+ * Given a pointer to a member of a structure, this macro does
+ * typechecking and figures out the offset to the enclosing type.
+ *
+ * Example:
+ *	struct foo {
+ *		int fielda, fieldb;
+ *		// ...
+ *	};
+ *	struct info {
+ *		int some_other_field;
+ *		struct foo my_foo;
+ *	};
+ *
+ *	static struct info *foo_to_info(struct foo *foo)
+ *	{
+ *		size_t off = container_off(struct info, my_foo);
+ *		return (void *)((char *)foo - off);
+ *	}
+ */
+#define container_off(containing_type, member)	\
+	offsetof(containing_type, member)
+
+/**
+ * container_of_var - get pointer to enclosing structure using a variable
+ * @member_ptr: pointer to the structure member
+ * @container_var: a pointer of same type as this member's container
+ * @member: the name of this member within the structure.
+ *
+ * Given a pointer to a member of a structure, this macro does pointer
+ * subtraction to return the pointer to the enclosing type.
+ *
+ * Example:
+ *	static struct info *foo_to_i(struct foo *foo)
+ *	{
+ *		struct info *i = container_of_var(foo, i, my_foo);
+ *		return i;
+ *	}
+ */
+#if HAVE_TYPEOF
+#define container_of_var(member_ptr, container_var, member) \
+	container_of(member_ptr, typeof(*container_var), member)
+#else
+#define container_of_var(member_ptr, container_var, member)	\
+	((void *)((char *)(member_ptr)	-			\
+		  container_off_var(container_var, member)))
+#endif
+
+/**
+ * container_off_var - get offset of a field in enclosing structure
+ * @container_var: a pointer to a container structure
+ * @member: the name of a member within the structure.
+ *
+ * Given (any) pointer to a structure and a its member name, this
+ * macro does pointer subtraction to return offset of member in a
+ * structure memory layout.
+ *
+ */
+#if HAVE_TYPEOF
+#define container_off_var(var, member)		\
+	container_off(typeof(*var), member)
+#else
+#define container_off_var(var, member)			\
+	((const char *)&(var)->member - (const char *)(var))
+#endif
+
+#endif /* CCAN_CONTAINER_OF_H */