{"id":13484128,"url":"https://github.com/Empact/roxml","last_synced_at":"2025-03-27T15:31:06.739Z","repository":{"id":426329,"uuid":"46439","full_name":"Empact/roxml","owner":"Empact","description":"ROXML is a module for binding Ruby classes to XML. It supports custom mapping and bidirectional marshalling between Ruby and XML using annotation-style class methods, via Nokogiri or LibXML.","archived":false,"fork":false,"pushed_at":"2024-05-22T18:35:01.000Z","size":1219,"stargazers_count":222,"open_issues_count":14,"forks_count":176,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-05-22T19:00:01.262Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://roxml.rubyforge.org/","language":"Ruby","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/Empact.png","metadata":{"files":{"readme":"README.rdoc","changelog":"History.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2008-08-26T23:34:54.000Z","updated_at":"2024-06-18T12:35:02.071Z","dependencies_parsed_at":"2024-06-18T12:34:59.670Z","dependency_job_id":"74e4ee3f-1bfa-44c0-b954-67ec494d3ed7","html_url":"https://github.com/Empact/roxml","commit_stats":{"total_commits":671,"total_committers":30,"mean_commits":"22.366666666666667","dds":0.1296572280178837,"last_synced_commit":"b39ca632dc01aa4e41567d09814243c694886e54"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Empact%2Froxml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Empact%2Froxml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Empact%2Froxml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Empact%2Froxml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Empact","download_url":"https://codeload.github.com/Empact/roxml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245871804,"owners_count":20686264,"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.686Z","updated_at":"2025-03-27T15:31:06.253Z","avatar_url":"https://github.com/Empact.png","language":"Ruby","readme":"ROXML Ruby Object to XML mapping library.\n\nFor more information visit:\n\n    http://rdoc.info/projects/Empact/roxml\n    http://empact.github.com/roxml/\n\nPlease submit bugs here:\n\n    http://github.com/Empact/roxml/issues\n\n=Quick Start Guide\n\nThis is a short usage example. See ROXML::ClassMethods::Declarations and packaged test cases for more information.\n\n==Basic Mapping\n\nConsider an XML document representing a Library containing a number of Books. You\ncan map this structure to Ruby classes that provide addition useful behavior. With\nROXML, you can annotate the Ruby classes as follows:\n\n  class Book\n    include ROXML\n\n    xml_accessor :isbn, :from =\u003e \"@ISBN\" # attribute with name 'ISBN'\n    xml_accessor :title\n    xml_accessor :description, :cdata =\u003e true  # text node with cdata protection\n    xml_accessor :author\n  end\n\n  class Library\n    include ROXML\n\n    xml_accessor :name, :from =\u003e \"NAME\", :cdata =\u003e true\n    xml_accessor :books, :as =\u003e [Book] # by default roxml searches for books for in \u003cbook\u003e child nodes, then, if none are present, in ./books/book children\n  end\n\nTo create a library and put a number of books in it we could run the following code:\n\n  book = Book.new\n  book.isbn = \"0201710897\"\n  book.title = \"The PickAxe\"\n  book.description = \"Best Ruby book out there!\"\n  book.author = \"David Thomas, Andrew Hunt, Dave Thomas\"\n\n  lib = Library.new\n  lib.name = \"Favorite Books\"\n  lib.books = [book]\n\nTo save this information to an XML file:\n\n  doc = Nokogiri::XML::Document.new\n  doc.root = lib.to_xml\n  open(\"library.xml\", 'w') do |file|\n    file \u003c\u003c doc.serialize\n  end\n\nor\n\n  doc = LibXML::XML::Document.new\n  doc.root = lib.to_xml\n  doc.save(\"library.xml\")\n\nTo later populate the library object from the XML file:\n\n  lib = Library.from_xml(File.read(\"library.xml\"))\n\nSimilarly, to do a one-to-one mapping between XML objects, such as book and publisher,\nyou would add a reference to another ROXML class. For example:\n\n  \u003cbook isbn=\"0974514055\"\u003e\n    \u003ctitle\u003eProgramming Ruby - 2nd Edition\u003c/title\u003e\n    \u003cdescription\u003eSecond edition of the great book.\u003c/description\u003e\n    \u003cpublisher\u003e\n      \u003cname\u003ePragmatic Bookshelf\u003c/name\u003e\n    \u003c/publisher\u003e\n  \u003c/book\u003e\n\ncan be mapped using the following code:\n\n  class Publisher\n    include ROXML\n\n    xml_accessor :name\n\n    # other important functionality\n  end\n\n  class BookWithPublisher\n    include ROXML\n\n    xml_name 'book'\n    xml_reader :publisher, :as =\u003e Publisher\n\n    #  or, alternatively, if no class is needed to hang functionality on:\n    # xml_reader :publisher, :from =\u003e 'name', :in =\u003e 'publisher'\n  end\n\nNote: In the above example, _xml_name_ annotation tells ROXML to set the element\nname to \"book\" for mapping to XML. The default is XML element name is the class name in lowercase; \"bookwithpublisher\"\nin this case.\n\n=== Namespace Support\n\nNamespaced nodes are supported via the xml_namespace and xml_namespaces declarations and the :from and :namespace attr options.  See spec/xml/namespace_spec.rb for usage.\n\nNote that ROXML does not currently support outputting namespaced nodes.  This is planned for a future version.\n\n== Manipulation\n\nExtending the above examples, say you want to parse a book's page count and have it available as an Integer.\nIn such a case, you can extend any object with a block to manipulate it's value at parse time.  For example:\n\n  class Dog\n    include ROXML\n\n    xml_reader(:age, :from =\u003e '@human_years', :as =\u003e Integer) {|years| years * 7 }\n  end\n\nThe result of the block above is stored, rather than the actual value parsed from the document.\n\n== Construction\n\nObject life-cycle is as follows: .from_xml is called with a first argument representing the xml\nin file, string, or path form, and with optional initialization_args following.\n\nFirt .new and thus #initialize, is called with those same initialization_args, or no args if none\nare present.  Then the object is populated with the attribute values from xml.  Then the\n#after_parse callback is called, with no arguments.\n\nIn #after_parse you can ensure that your object initialization is complete, including initialization which\nrequires more than one variable in concert.\n\nE.g.:\n\n  class Measurement\n    include ROXML\n\n    xml_reader :units, :from =\u003e :attr\n    xml_reader :value, :from =\u003e :content\n\n    def initialize(value = 0, units = 'meters')\n      to_metric\n    end\n\n  private\n    def after_parse\n      # xml attributes of self are already valid\n      to_metric\n    end\n\n    def to_metric\n      # translate units \u0026 value into metric, for example\n    end\n  end\n\nOne important use of this approach is to make ROXML object which may or may not include an xml backing,\nwhich may be used via _new_ construction as well as _from_xml_ construction.\n\n== Selecting a parser\n\nBy default, ROXML will use Nokogiri if it is available, followed by LibXML.  If you'd like to\nexplicitly require one or the other, you may do the following:\n\n  module ROXML\n    XML_PARSER = 'nokogiri' # or 'libxml'\n  end\n  require 'roxml'\n\nFor more information on available annotations, see ROXML::ClassMethods::Declarations\n\n== Note on Patches/Pull Requests\n\n* Fork the project.\n* Make your feature addition or bug fix.\n* Add specs for it. This is important so I don't break it in a\n  future version unintentionally.\n* Commit, do not mess with rakefile, version, or history.\n  (if you want to have your own version, that is fine but\n   bump version in a commit by itself I can ignore when I pull)\n* Send me a pull request. Bonus points for topic branches.\n\n== Copyright\n\nCopyright (c) 2004-2024 Ben Woosley, Zak Mandhro and Anders Engstrom. See LICENSE for details.\n","funding_links":[],"categories":["HTML/XML Parsing"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEmpact%2Froxml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEmpact%2Froxml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEmpact%2Froxml/lists"}