{"id":13484124,"url":"https://github.com/ohler55/ox","last_synced_at":"2025-04-23T20:51:43.580Z","repository":{"id":44566758,"uuid":"1345214","full_name":"ohler55/ox","owner":"ohler55","description":"Ruby Optimized XML Parser","archived":false,"fork":false,"pushed_at":"2025-03-25T01:26:38.000Z","size":2526,"stargazers_count":909,"open_issues_count":3,"forks_count":76,"subscribers_count":24,"default_branch":"develop","last_synced_at":"2025-04-08T23:15:10.209Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.ohler.com/ox","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohler55.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ohler55"]}},"created_at":"2011-02-09T05:56:41.000Z","updated_at":"2025-03-25T01:26:39.000Z","dependencies_parsed_at":"2024-03-21T15:29:52.191Z","dependency_job_id":"cd6f68ab-00b5-4ab8-8f2f-eeacce3288f7","html_url":"https://github.com/ohler55/ox","commit_stats":{"total_commits":693,"total_committers":51,"mean_commits":"13.588235294117647","dds":"0.46031746031746035","last_synced_commit":"cd8511588e0bfdc867e8d5249950138da35fa012"},"previous_names":[],"tags_count":110,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohler55%2Fox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohler55%2Fox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohler55%2Fox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohler55%2Fox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohler55","download_url":"https://codeload.github.com/ohler55/ox/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250514756,"owners_count":21443208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:19.657Z","updated_at":"2025-04-23T20:51:43.520Z","avatar_url":"https://github.com/ohler55.png","language":"C","readme":"# Ox gem\nA fast XML parser and Object marshaller as a Ruby gem.\n\n[![CI](https://github.com/ohler55/ox/actions/workflows/CI.yml/badge.svg)](https://github.com/ohler55/ox/actions/workflows/CI.yml)\n\n## Installation\n    gem install ox\n\n## Documentation\n\n*Documentation*: http://www.ohler.com/ox\n\n## Source\n\n*GitHub* *repo*: https://github.com/ohler55/ox\n\n*RubyGems* *repo*: https://rubygems.org/gems/ox\n\n## Support\n\n[Get supported Ox with a Tidelift Subscription.](https://tidelift.com/subscription/pkg/rubygems-ox?utm_source=rubygems-ox\u0026utm_medium=referral\u0026utm_campaign=readme) Security updates are [supported](https://tidelift.com/security).\n\n## Links of Interest\n\n[Ruby XML Gem Comparison](http://www.ohler.com/dev/xml_with_ruby/xml_with_ruby.html) for a performance comparison between Ox, Nokogiri, and LibXML.\n\n[Fast Ruby XML Serialization](http://www.ohler.com/dev/ruby_object_xml_serialization/ruby_object_xml_serialization.html) to see how Ox can be used as a faster replacement for Marshal.\n\n*Fast JSON parser and marshaller on RubyGems*: https://rubygems.org/gems/oj\n\n*Fast JSON parser and marshaller on GitHub*: https://github.com/ohler55/oj\n\n## Release Notes\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n## Description\n\nOptimized XML (Ox), as the name implies was written to provide speed optimized\nXML and now HTML handling. It was designed to be an alternative to Nokogiri and other Ruby\nXML parsers in generic XML parsing and as an alternative to Marshal for Object\nserialization.\n\nUnlike some other Ruby XML parsers, Ox is self contained. Ox uses nothing\nother than standard C libraries so version issues with libXml are not an\nissue.\n\nMarshal uses a binary format for serializing Objects. That binary format\nchanges with releases making Marshal dumped Object incompatible between some\nversions. The use of a binary format make debugging message streams or file\ncontents next to impossible unless the same version of Ruby and only Ruby is\nused for inspecting the serialize Object. Ox on the other hand uses human\nreadable XML. Ox also includes options that allow strict, tolerant, or a mode\nthat automatically defines missing classes.\n\nIt is possible to write an XML serialization gem with Nokogiri or other XML\nparsers but writing such a package in Ruby results in a module significantly\nslower than Marshal. This is what triggered the start of Ox development.\n\nOx handles XML documents in three ways. It is a generic XML parser and writer,\na fast Object / XML marshaller, and a stream SAX parser. Ox was written for\nspeed as a replacement for Nokogiri, Ruby LibXML, and for Marshal.\n\nAs an XML parser it is 2 or more times faster than Nokogiri and as a generic\nXML writer it is as much as 20 times faster than Nokogiri. Of course different\nfiles may result in slightly different times.\n\nAs an Object serializer Ox is up to 6 times faster than the standard Ruby\nMarshal.dump() and up to 3 times faster than Marshal.load().\n\nThe SAX like stream parser is 40 times faster than Nokogiri and more than 13\ntimes faster than LibXML when validating a file with minimal Ruby\ncallbacks. Unlike Nokogiri and LibXML, Ox can be tuned to use only the SAX\ncallbacks that are of interest to the caller. (See the perf_sax.rb file for an\nexample.)\n\nOx is compatible with Ruby 2.3, 2.4, 2.5, 2.6, 2.7, 3.0.\n\n### Object Dump Sample:\n\n```ruby\nrequire 'ox'\n\nclass Sample\n  attr_accessor :a, :b, :c\n\n  def initialize(a, b, c)\n    @a = a\n    @b = b\n    @c = c\n  end\nend\n\n# Create Object\nobj = Sample.new(1, \"bee\", ['x', :y, 7.0])\n# Now dump the Object to an XML String.\nxml = Ox.dump(obj)\n# Convert the object back into a Sample Object.\nobj2 = Ox.parse_obj(xml)\n```\n\n### Generic XML Writing and Parsing:\n\n```ruby\nrequire 'ox'\n\ndoc = Ox::Document.new\n\ninstruct = Ox::Instruct.new(:xml)\ninstruct[:version] = '1.0'\ninstruct[:encoding] = 'UTF-8'\ninstruct[:standalone] = 'yes'\ndoc \u003c\u003c instruct\n\ntop = Ox::Element.new('top')\ntop[:name] = 'sample'\ndoc \u003c\u003c top\n\nmid = Ox::Element.new('middle')\nmid[:name] = 'second'\ntop \u003c\u003c mid\n\nbot = Ox::Element.new('bottom')\nbot[:name] = 'third'\nbot \u003c\u003c 'text at bottom'\nmid \u003c\u003c bot\n\nother_elements = Ox::Element.new('otherElements')\nother_elements \u003c\u003c Ox::CData.new('\u003csender\u003eJohn Smith\u003c/sender\u003e')\nother_elements \u003c\u003c Ox::Comment.new('Director\\'s commentary')\n# other_elements \u003c\u003c Ox::DocType.new('content')\nother_elements \u003c\u003c Ox::Raw.new('\u003cwarning\u003eBe carefull with this! Direct inject into XML!\u003c/warning\u003e')\ntop \u003c\u003c other_elements\n\n\nxml = Ox.dump(doc)\n\n# xml =\n# \u003c?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?\u003e\n# \u003ctop name=\"sample\"\u003e\n#   \u003cmiddle name=\"second\"\u003e\n#     \u003cbottom name=\"third\"\u003etext at bottom\u003c/bottom\u003e\n#   \u003c/middle\u003e\n#   \u003cotherElements\u003e\n#     \u003c![CDATA[\u003csender\u003eJohn Smith\u003c/sender\u003e]]\u003e\n#     \u003c!-- Director's commentary --\u003e\n#     \u003cwarning\u003eBe carefull with this! Direct inject into XML!\u003c/warning\u003e\n#   \u003c/otherElements\u003e\n# \u003c/top\u003e\n```\n\n### HTML Parsing:\n\nOx can be used to parse HTML with a few options changes. HTML is often loose in\nregard to conformance. For HTML parsing try these options.\n\n```ruby\nOx.default_options = {\n    mode:   :generic,\n    effort: :tolerant,\n    smart:  true\n}\n```\n\n### SAX XML Parsing:\n\n```ruby\nrequire 'stringio'\nrequire 'ox'\n\nclass Sample \u003c ::Ox::Sax\n  def start_element(name); puts \"start: #{name}\";        end\n  def end_element(name);   puts \"end: #{name}\";          end\n  def attr(name, value);   puts \"  #{name} =\u003e #{value}\"; end\n  def text(value);         puts \"text #{value}\";         end\nend\n\nio = StringIO.new(%{\n\u003ctop name=\"sample\"\u003e\n  \u003cmiddle name=\"second\"\u003e\n    \u003cbottom name=\"third\"/\u003e\n  \u003c/middle\u003e\n\u003c/top\u003e\n})\n\nhandler = Sample.new()\nOx.sax_parse(handler, io)\n# outputs\n# start: top\n#   name =\u003e sample\n# start: middle\n#   name =\u003e second\n# start: bottom\n#   name =\u003e third\n# end: bottom\n# end: middle\n# end: top\n```\n\n### Yielding results immediately while SAX XML Parsing:\n\n```ruby\nrequire 'stringio'\nrequire 'ox'\n\nclass Yielder \u003c ::Ox::Sax\n  def initialize(block); @yield_to = block; end\n  def start_element(name); @yield_to.call(name); end\nend\n\nio = StringIO.new(%{\n\u003ctop name=\"sample\"\u003e\n  \u003cmiddle name=\"second\"\u003e\n    \u003cbottom name=\"third\"/\u003e\n  \u003c/middle\u003e\n\u003c/top\u003e\n})\n\nproc = Proc.new { |name| puts name }\nhandler = Yielder.new(proc)\nputs \"before parse\"\nOx.sax_parse(handler, io)\nputs \"after parse\"\n# outputs\n# before parse\n# top\n# middle\n# bottom\n# after parse\n```\n\n### Parsing XML into a Hash (fast)\n\n```ruby\nrequire 'ox'\n\nxml = %{\n\u003ctop name=\"sample\"\u003e\n  \u003cmiddle name=\"second\"\u003e\n    \u003cbottom name=\"third\"\u003eRock bottom\u003c/bottom\u003e\n  \u003c/middle\u003e\n\u003c/top\u003e\n}\n\nputs Ox.load(xml, mode: :hash)\nputs Ox.load(xml, mode: :hash_no_attrs)\n\n#{:top=\u003e[{:name=\u003e\"sample\"}, {:middle=\u003e[{:name=\u003e\"second\"}, {:bottom=\u003e[{:name=\u003e\"third\"}, \"Rock bottom\"]}]}]}\n#{:top=\u003e{:middle=\u003e{:bottom=\u003e\"Rock bottom\"}}}\n```\n\n### Object XML format\n\nThe XML format used for Object encoding follows the structure of the\nObject. Each XML element is encoded so that the XML element name is a type\nindicator. Attributes of the element provide additional information such as\nthe Class if relevant, the Object attribute name, and Object ID if\nnecessary.\n\nThe type indicator map is:\n\n- **a** =\u003e `Array`\n- **b** =\u003e `Base64` - only for legacy loads\n- **c** =\u003e `Class`\n- **f** =\u003e `Float`\n- **g** =\u003e `Regexp`\n- **h** =\u003e `Hash`\n- **i** =\u003e `Fixnum`\n- **j** =\u003e `Bignum`\n- **l** =\u003e `Rational`\n- **m** =\u003e `Symbol`\n- **n** =\u003e `FalseClass`\n- **o** =\u003e `Object`\n- **p** =\u003e `Ref`\n- **r** =\u003e `Range`\n- **s** =\u003e `String`\n- **t** =\u003e `Time`\n- **u** =\u003e `Struct`\n- **v** =\u003e `Complex`\n- **x** =\u003e `Raw`\n- **y** =\u003e `TrueClass`\n- **z** =\u003e `NilClass`\n\nIf the type is an Object, type 'o' then an attribute named 'c' should be set\nwith the full Class name including the Module names. If the XML element\nrepresents an Object then a sub-elements is included for each attribute of\nthe Object. An XML element attribute 'a' is set with a value that is the\nname of the Ruby Object attribute. In all cases, except for the Exception\nattribute hack the attribute names begin with an @ character. (Exception are\nstrange in that the attributes of the Exception Class are not named with a @\nsuffix. A hack since it has to be done in C and can not be done through the\ninterpreter.)\n\nValues are encoded as the text portion of an element or in the sub-elements\nof the principle. For example, a Fixnum is encoded as:\n```xml\n\u003ci\u003e123\u003c/i\u003e\n```\nAn Array has sub-elements and is encoded similar to this example.\n```xml\n\u003ca\u003e\n  \u003ci\u003e1\u003c/i\u003e\n  \u003cs\u003eabc\u003c/s\u003e\n\u003c/a\u003e\n```\nA Hash is encoded with an even number of elements where the first element is\nthe key and the second is the value. This is repeated for each entry in the\nHash. An example is of { 1 =\u003e 'one', 2 =\u003e 'two' } encoding is:\n```xml\n\u003ch\u003e\n  \u003ci\u003e1\u003c/i\u003e\n  \u003cs\u003eone\u003c/s\u003e\n  \u003ci\u003e2\u003c/i\u003e\n  \u003cs\u003etwo\u003c/s\u003e\n\u003c/h\u003e\n```\n\nOx supports circular references where attributes of one Object can refer to\nan Object that refers back to the first Object. When this option is used an\nObject ID is added to each XML Object element as the value of the 'a'\nattribute.\n\n## Contributors\n\n### Code Contributors\n\nThis project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].\n\u003ca href=\"https://github.com/ohler55/ox/graphs/contributors\"\u003e\u003cimg src=\"https://opencollective.com/ohler/contributors.svg?width=890\u0026button=false\" /\u003e\u003c/a\u003e\n\n### Financial Contributors\n\nBecome a financial contributor and help us sustain our community. [[Contribute](https://opencollective.com/ohler/contribute)]\n\n#### Individuals\n\n\u003ca href=\"https://opencollective.com/ohler\"\u003e\u003cimg src=\"https://opencollective.com/ohler/individuals.svg?width=890\"\u003e\u003c/a\u003e\n\n#### Organizations\n\nSupport this project with your organization. Your logo will show up here with a link to your website. [[Contribute](https://opencollective.com/ohler/contribute)]\n\n\u003ca href=\"https://opencollective.com/ohler/organization/0/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/0/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/1/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/1/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/2/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/2/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/3/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/3/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/4/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/4/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/5/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/5/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/6/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/6/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/7/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/7/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/8/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/8/avatar.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://opencollective.com/ohler/organization/9/website\"\u003e\u003cimg src=\"https://opencollective.com/ohler/organization/9/avatar.svg\"\u003e\u003c/a\u003e\n","funding_links":["https://github.com/sponsors/ohler55","https://tidelift.com/subscription/pkg/rubygems-ox?utm_source=rubygems-ox\u0026utm_medium=referral\u0026utm_campaign=readme","https://tidelift.com/security","https://opencollective.com/ohler/contribute","https://opencollective.com/ohler","https://opencollective.com/ohler/organization/0/website","https://opencollective.com/ohler/organization/1/website","https://opencollective.com/ohler/organization/2/website","https://opencollective.com/ohler/organization/3/website","https://opencollective.com/ohler/organization/4/website","https://opencollective.com/ohler/organization/5/website","https://opencollective.com/ohler/organization/6/website","https://opencollective.com/ohler/organization/7/website","https://opencollective.com/ohler/organization/8/website","https://opencollective.com/ohler/organization/9/website"],"categories":["HTML/XML Parsing","C","Input and Output"],"sub_categories":["General formats"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohler55%2Fox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohler55%2Fox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohler55%2Fox/lists"}