{"id":20481886,"url":"https://github.com/typeable/xml-isogen","last_synced_at":"2025-04-13T14:11:14.952Z","repository":{"id":13565917,"uuid":"74341846","full_name":"typeable/xml-isogen","owner":"typeable","description":"TemplateHaskell generators for XML-isomorphic data types, instances for parsing and rendering. A convenient DSL to define types.","archived":false,"fork":false,"pushed_at":"2023-04-19T08:42:01.000Z","size":67,"stargazers_count":10,"open_issues_count":2,"forks_count":6,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-11T21:41:33.981Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Haskell","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/typeable.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-21T08:23:42.000Z","updated_at":"2022-05-18T18:22:59.000Z","dependencies_parsed_at":"2022-09-01T00:31:19.434Z","dependency_job_id":null,"html_url":"https://github.com/typeable/xml-isogen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typeable%2Fxml-isogen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typeable%2Fxml-isogen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typeable%2Fxml-isogen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typeable%2Fxml-isogen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typeable","download_url":"https://codeload.github.com/typeable/xml-isogen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724629,"owners_count":21151561,"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-11-15T16:10:09.930Z","updated_at":"2025-04-13T14:11:14.925Z","avatar_url":"https://github.com/typeable.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xml-isogen\n\n[![Build Status](https://travis-ci.org/typeable/xml-isogen.svg?branch=master)](https://travis-ci.org/typeable/xml-isogen)\n\nTemplateHaskell generators for XML-isomorphic data types, including\ninstances for parsing and rendering. A convenient DSL to define those\ntypes.\n\nEssentially it's a haskell DSL which allows its users to generate XML parsers and generators for haskell datatypes.\nSee also [xsd-isogen](https://github.com/typeable/xsd-isogen)\n\n## Tutorial\n\nLets go through series of examples. First things first:\n\n```haskell\n{-# LANGUAGE TemplateHaskell #-}\n{-# LANGUAGE OverloadedStrings #-}\n{-# LANGUAGE DeriveGeneric #-}\n\nmodule Tutorial\nwhere\n\nimport Prelude hiding ((^))\nimport Control.DeepSeq      -- from deepseq\nimport Data.Text\nimport Data.THGen.XML       -- from xml-isogen\nimport Text.XML.Writer      -- from xml-conduit-writer\nimport Text.XML.DOM.Parser  -- from dom-parser\n```\n\n### Records\n\nLets say we want to parse and/or generate an XML file of the following form:\n\n```XML\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cperson\u003e\n    \u003cname\u003e\n        John\n    \u003c/name\u003e\n    \u003cemail\u003e\n        john@example.com\n    \u003c/email\u003e\n\u003c/person\u003e\n```\n\nPerson has a name and an email, and email could be omitted. With `xml-isogen` it's\nenough to write the following definition:\n\n```haskell\n\"Person\" =:= record ParserAndGenerator\n  ! \"name\" [t|Text|]\n  ? \"email\" [t|Text|]\n```\n\nAt this point you can load the module into `ghci` and check what was generated for us\nso far:\n\n```\n*Tutorial\u003e :browse\ndata XmlPerson\n  = XmlPerson {_xpName :: !Text, _xpEmail :: !(Maybe Text)}\nxpEmail ::\n  lens-4.18.1:Control.Lens.Type.Lens' XmlPerson (Maybe Text)\nxpName :: lens-4.18.1:Control.Lens.Type.Lens' XmlPerson Text\n```\n\nWe have a data type `XmlPerson` with two fields and two lenses. Note that the\nfields have a prefix built of an underscore and all upper case characters\nand digits of the type name.\n\n\nLets take a closer look at `XmlPerson`:\n\n```\n*Tutorial\u003e :i XmlPerson\ndata XmlPerson\n  = XmlPerson {_xpName :: !Text, _xpEmail :: !(Maybe Text)}\n      -- Defined at Tutorial.hs:13:1\ninstance Show XmlPerson -- Defined at Tutorial.hs:13:1\ninstance Eq XmlPerson -- Defined at Tutorial.hs:13:1\ninstance FromDom XmlPerson -- Defined at Tutorial.hs:13:1\ninstance ToXML XmlPerson -- Defined at Tutorial.hs:13:1\n\n```\n\nWe have\n[FromDom](https://hackage.haskell.org/package/dom-parser-3.1.0/docs/Text-XML-DOM-Parser-FromDom.html#t:FromDom)\nand\n[ToXML](https://hackage.haskell.org/package/xml-conduit-writer-0.1.1.2/docs/Text-XML-Writer.html#t:ToXML)\ninstance generated for us. That's because\nwe instructed `xml-isogen` to generate them using the `ParserAndGenerator` noun. You can specify\nalso `Parser` or `Generator` if you want only one of them.\n\nThe `_xpEmail` field is optional; that's because we prefixed it with `?` modifier.\nHere is the list of possible modifiers that affect types:\n\nModifier | Description | Generated Type\n--- | --- | ---\n`!` | required | `a`\n`?` | optional | `Maybe a`\n`*` | repeated | `[a]`\n`+` | nonempty | `NonEmpty a`\n\n### Supported types\n\nFields in a record may have any types as long as they are instances of `Eq`, `Show`,\n`NFData`, `FromDom` (for the parser) and `ToXml` (for the generator). Remember\nthough that TemplateHaskell requires types to be available before they are used\nin a splice.\n\nYou can omit field types altogether, in that case the type will be assumed to be a\ncapitalized field name with an `Xml` prefix.\nIt's your responsibility to make sure that type exists.\nExample:\n\n```haskell\nnewtype XmlEmail = XmlEmail Text\n  deriving (Eq, Show, NFData, ToXML)\n\ninstance FromDom XmlEmail where\n  fromDom = XmlEmail \u003c$\u003e fromDom\n\n\"Example1\" =:= record Parser\n  ! \"email\"  -- will have type XmlEmail\n```\n\n### Enumerations\n\nOften XML element can contain only limited number of possible values. Lets define\na type `Status` that can have only values `Active`, `Pending` or `Deleted`:\n\n```haskell\n\"Status\" =:= enum ParserAndGenerator\n  \u0026 \"Active\"\n  \u0026 \"Pending\"\n  \u0026 \"Deleted\"\n```\n\nThis definition will generate the following type for us:\n\n```haskell\ndata XmlStatus\n  = XmlStatusActive\n  | XmlStatusPending\n  | XmlStatusDeleted\n  | UnknownXmlStatus !String\n```\n\nIt has all the necessary instances, so you can use it as a type for a field.\n\n### Append content\n\nSometimes the XML you are dealing with contains a mix of elements and immediate\ncontent. Something like the following:\n\n```XML\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cexample\u003e\n    \u003cfield1\u003e\n        I am\n    \u003c/field1\u003e\n    totally\n    \u003cfield2\u003e\n        weird\n    \u003c/field2\u003e\n\u003c/example\u003e\n```\n\nYou can model this with an \"append content\" modifier `^`. It will instruct\n`xml-isogen` to append content of the field as it is, without wrapping it\ninto an XML element. For our case it may look like this:\n\n```haskell\n\"Example2\" =:= record ParserAndGenerator\n  ! \"field1\" [t|Text|]\n  ^ \"mixed\" [t|Text|]\n  ! \"field2\" [t|Text|]\n```\n\nAfter parsing the XML above, we'll get the following:\n\n```haskell\nXmlExample2 {_xe2Field1 = \"I am\", _xe2Mixed = \"totally\", _xe2Field2 = \"weird\"}\n```\n\n### Attributes\n\n`xml-isogen` also supports XML attributes using `!%` and `?%` modifiers:\n\n```haskell\n\"Example3\" =:= record ParserAndGenerator\n  ! \"field1\" [t|Text|]\n  !% \"attribute1\" [t|Text|]\n  ?% \"attribute2\" [t|Text|]\n\n\"Body\" =:= record ParserAndGenerator\n  ! \"root\" [t|XmlExample3|]\n```\n\nThe following two types will be generated:\n\n```haskell\ndata XmlExample3\n  = XmlExample3 {_xe3Field1 :: !Text,\n                 _xe3Attribute1 :: !Text,\n                 _xe3Attribute2 :: !(Maybe Text)}\n\nnewtype XmlBody = XmlBody {_xbRoot :: XmlExample3}\n```\n\nThe `_xe3Attribute2` is optional because we used `?%` modifier. Attributes will be\nattached to parent XML element. Here is an example of the generated XML file:\n\n```XML\n\u003croot attribute1=\"world\"\u003e\n    \u003cfield1\u003e\n\thello\n    \u003c/field1\u003e\n\u003c/root\u003e\n```\n\nNote that attributes are attached to the parent XML element, that's why we needed\n`XmlBody` type here.\n\nAnd here is what you get after parsing the XML:\n\n```haskell\nXmlExample3 {_xe3Field1 = \"hello\", _xe3Attribute1 = \"world\", _xe3Attribute2 = Nothing}\n```\n\n### Namespaces\n\nOften XSD schema requires XML elements to be qualified with a namespace. To instruct\n`xml-isogen` to qualify fields, specify namespace is a curly brackets:\n\n```haskell\n\"Example4\" =:= record ParserAndGenerator\n  ! \"field1\" [t|Text|]\n  ! \"{http://example.com/1}field2\" [t|Text|]\n  ! \"{http://example.com/2}field3\" [t|Text|]\n```\n\nHere is the generated XML:\n\n```XML\n\u003cfield1\u003e\n    hello\n\u003c/field1\u003e\n\u003cfield2 xmlns=\"http://example.com/1\"\u003e\n    world\n\u003c/field2\u003e\n\u003cfield3 xmlns=\"http://example.com/2\"\u003e\n    !\n\u003c/field3\u003e\n```\n\n### Nillable types\n\nSometimes optional element in XML are encoded using `nil=\"true\"` attribute instead of\nomitting the element. (The `nil` attribute comes from `http://www.w3.org/2001/XMLSchema-instance` namespace). With `xml-isogen` you handle it using the `Nillable` type:\n\n```haskell\n\"Example5\" =:= record ParserAndGenerator\n  ! \"field\" [t|Nillable Text|]\n```\n\nIf the field contains the value `Nothing`, like this\n\n```haskell\nXmlExample5 { _xe5Field = Nillable Nothing}\n```\n\nthen the following XML will be generated:\n\n```XML\n\u003cfield\n  xmlns:ns=\"http://www.w3.org/2001/XMLSchema-instance\"\n  ns:nil=\"true\"\n/\u003e\n```\n\n## Development\n\nTo start working with `xml-isogen` using nix use:\n\n```\nnix-shell --packages cabal2nix --run \"cabal2nix .\" \u003e default.nix\nnix-shell\ncabal v2-build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypeable%2Fxml-isogen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypeable%2Fxml-isogen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypeable%2Fxml-isogen/lists"}