{"id":15540230,"url":"https://github.com/rm-hull/helpmate","last_synced_at":"2025-06-30T15:35:45.742Z","repository":{"id":62434512,"uuid":"70363869","full_name":"rm-hull/helpmate","owner":"rm-hull","description":"A Clojure library for emitting SGML (HTML,SVG,XML,MathML) fragments","archived":false,"fork":false,"pushed_at":"2023-11-29T23:46:42.000Z","size":103,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-25T14:17:15.847Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.destructuring-bind.org/helpmate","language":"Clojure","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/rm-hull.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2016-10-08T23:54:42.000Z","updated_at":"2025-05-12T09:27:40.000Z","dependencies_parsed_at":"2025-03-06T01:32:04.899Z","dependency_job_id":"c29ddff7-04b7-4895-a5ba-90befe0b1c90","html_url":"https://github.com/rm-hull/helpmate","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/rm-hull/helpmate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rm-hull%2Fhelpmate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rm-hull%2Fhelpmate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rm-hull%2Fhelpmate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rm-hull%2Fhelpmate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rm-hull","download_url":"https://codeload.github.com/rm-hull/helpmate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rm-hull%2Fhelpmate/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262043120,"owners_count":23249726,"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-10-02T12:13:18.645Z","updated_at":"2025-06-30T15:35:45.717Z","avatar_url":"https://github.com/rm-hull.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HelpMate\n\n[![Build Status](https://github.com/rm-hull/helpmate/actions/workflows/clojure.yml/badge.svg)](https://github.com/rm-hull/helpmate/actions/workflows/clojure.yml)\n[![Coverage Status](https://coveralls.io/repos/rm-hull/helpmate/badge.svg?branch=main)](https://coveralls.io/r/rm-hull/helpmate?branch=main)\n[![Dependencies Status](https://versions.deps.co/rm-hull/helpmate/status.svg)](https://versions.deps.co/rm-hull/helpmate)\n[![Downloads](https://versions.deps.co/rm-hull/helpmate/downloads.svg)](https://versions.deps.co/rm-hull/helpmate)\n[![Clojars Project](https://img.shields.io/clojars/v/rm-hull/helpmate.svg)](https://clojars.org/rm-hull/helpmate)\n[![Maintenance](https://img.shields.io/maintenance/yes/2023.svg?maxAge=2592000)]()\n\nHelpMate is a Clojure/ClojureScript library for templating/emitting SGML-like\ncontent. It uses S-Expressions to represent elements, and maps to represent an\nelement's attributes. HelpMate is a strained portmanteau of _Helpful HTML\ntemplate_.\n\nAll the current [HTML](https://developer.mozilla.org/en/docs/Web/HTML/Element)\nand [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG/Element) elements\nare represented with doc-strings scraped from Mozilla Developer Network, the\ncontent of which is available under the terms of the [Creative Commons\nAttribution-ShareAlike license](http://creativecommons.org/licenses/by-sa/2.5/)\n(CC-BY-SA), v2.5.\n\nPlanned additional definitions include\n\n- [RDF](https://www.w3.org/TR/rdf-syntax-grammar/)\n- [MathML](https://developer.mozilla.org/en-US/docs/Web/MathML/Element)\n\nCustom elements can be created by way of the `defelem` macro: this allows\narbitrary SGML tags to be represented in regular Clojure code, intersperced\nwith forms like `map` and `for`, making templating much more convenient:\n\n```clojure\n(defelem ul)\n(defelem li)\n\n(ul\n  (for [x (range 1 4)]\n    (li x)))\n; =\u003e \"\u003cul\u003e\u003cli\u003e1\u003c/li\u003e\u003cli\u003e2\u003c/li\u003e\u003cli\u003e3\u003c/li\u003e\u003c/ul\u003e\"\n```\n\n## Install\n\nThere is a version hosted at [Clojars](https://clojars.org/rm-hull/helpmate).\nFor leiningen include a dependency in your `project.clj` file:\n\n```clojure\n[rm-hull/helpmate \"0.1.4\"]\n```\n\n## API Documentation\n\nSee [www.destructuring-bind.org/helpmate](http://www.destructuring-bind.org/helpmate/) for API details.\n\n## Basic Usage\n\nThere is a predefined library of all (current) HTML elements complete with\ndoc-strings:\n\n```clojure\n(use 'helpmate.html)\n\n(div\n  (p \"Hello\"\n     (strong \"world\")))\n;=\u003e \u003cdiv\u003e\u003cp\u003eHello \u003cstrong\u003eworld\u003c/strong\u003e\u003c/p\u003e\u003c/div\u003e\n```\n\nConvention dictates that attributes are specified first, then children. Child elements\nmay be given in SEQable collection, or as varargs, and can be arbitrarily nested; thus,\nthey can be combined into normal Clojure code, as per the opening example.\n\nSome elements have certain behaviour, for example `(div)` expands into `\u003cdiv\u003e\u003c/div\u003e`,\nwhereas `(br)` expands into `\u003cbr\u003e`. Most other empty tags will self-close, eg. `(p)`\nexpands into `\u003cp/\u003e` - these are specified with meta-data when the element was defined.\n\n### Specifying attributes\n\nAttributes can be supplied as a map of key/value pairs:\n\n```clojure\n(a {:id \"puppies\" :class \"flush--right\" :target \"_blank\" :href \"/puppies.html\"}\n  (img {:src \"/img/puppies.png\"}))\n;=\u003e \u003ca id=\"puppies\" class=\"flush--right\" target=\"_blank\" href=\"/puppies.html\"\u003e\u003cimg src=\"/img/puppies.png\"\u003e\u003c/a\u003e\n```\n\nAlternatively, the braces can be omitted, as long as there are pairs of keys\nand values (and in which case, the keys _must_ be Clojure keywords and the\nvalues _must_ be string, number or nil):\n\n```clojure\n(div :id \"main\" :data-target \"#nav\"\n  (h2 :class \"large editable-field inactive\" \"Dashboard\"))\n;=\u003e \u003cdiv id=\"main\" data-target=\"#nav\"\u003e\u003ch2 class=\"large editable-field inactive\"\u003eDashboard\u003c/h2\u003e\u003c/div\u003e\n```\n\n`:id` and `:class` values can be shortened even further, as below, where a\nClojure keyword starting with an octothorpe (`#`) is treated as an id, whereas a\nkeyword starting with dot (`.`) is treated as a class. Keywords with embedded dots\nare treated as multiple classes.\n\n```clojure\n(div :#main :data-target \"#nav\"\n  (h2 :.large.editable-field.inactive \"Dashboard\"))\n;=\u003e \u003cdiv id=\"main\" data-target=\"#nav\"\u003e\u003ch2 class=\"large editable-field inactive\"\u003eDashboard\u003c/h2\u003e\u003c/div\u003e\n```\n\n### Creating custom elements\n\nThe `defelem` macro can be used to create element definitions. The simplest\nform is:\n\n```clojure\n(defelem book)\n(defelem author)\n\n(author :first-name \"Barry\" :surname \"Fungus\"\n  (book :year 1999 \"One hundred ways to kill mice\")\n  (book :year 2012 \"The Dummys guide to Sensible Eating Habits\"))\n```\n\nafter formatting, gives:\n\n```xml\n\u003cauthor first-name=\"Barry\" surname=\"Fungus\"\u003e\n  \u003cbook year=\"1999\"\u003eOne hundred ways to kill mice\u003c/book\u003e\n  \u003cbook year=\"2012\"\u003eThe Dummys guide to Sensible Eating Habits\u003c/book\u003e\n\u003c/author\u003e\n```\n\nOf course, modelling the data structure with elements or attributes is a matter\nof taste; but with HelpMate, you can arbitrarity make that decision.\n\n`defelem` can also take an optional doc-string:\n\n```clojure\n(defelem publisher\n  \"A company or person that prepares and issues books, journals, or music for\n  sale. Valid attributes: name, publisher-code, Valid child elements: author.\")\n\n(clojure.repl/doc publisher)\n;=\u003e -------------------------\n;=\u003e helpmate.html-test/publisher\n;=\u003e  A company or person that prepares and issues books, journals, or music for\n;=\u003e  sale. Valid attributes: name, publisher-code, Valid child elements: author.\n```\n\nMeta-data is also respected, and use of `^:deprecated` is encouraged where\nappropriate (and actively used within the `helpmate.html` namespace). Other\nvalid meta-data flags are:\n\n- `^:non-void` - denotes that the element _must_ have an end-tag, such as\n  `\u003cdiv\u003e` or `\u003cscript\u003e` for example. Non-void tags will never self-close.\n- `^:empty-tag` - signals that the element is expected to have no child\n  elements (and will throw an exception if evaluated with children), such\n  as `\u003cimg\u003e` or `\u003cbr\u003e` elements. An empty tag implies that an element is\n  also void.\n\n### XML Namespaces\n\nNamespaces (both in element and attributes) are supported:\n\n```clojure\n(defelem ^:empty-tag foo:bar)\n\n(foo:bar :xmlns:foo \"http://example.org/rosé\")\n;=\u003e \u003cfoo:bar xmlns:foo=\"http://example.org/rosé\"\u003e\n```\n\n### Examples\n\nUsing the SVG tags from the `helpmate.svg` namespace:\n\n```clojure\n(svg {:viewBox \"0 0 95 50\" :xmlns \"http://www.w3.org/2000/svg\"}\n     (g {:stroke \"green\" :fill \"white\" :stroke-width 5}\n        (circle {:cx 25 :cy 25 :r 15})\n        (circle {:cx 40 :cy 25 :r 15})\n        (circle {:cx 55 :cy 25 :r 15})\n        (circle {:cx 70 :cy 25 :r 15}))))\n```\n\nproduces:\n\n![example-SVG](https://rawgithub.com/rm-hull/helpmate/main/doc/example.svg)\n\nAnd another more substantial example:\n\n```clojure\n(defelem animateMotion)\n(defelem mpath)\n\n(svg :width 120 :height 120 :viewBox \"0 0 120 120\"\n     :xmlns \"http://www.w3.org/2000/svg\" :version \"1.1\"\n     :xmlns:xlink \"http://www.w3.org/1999/xlink\"\n\n     (comment \"Draw the outline of the motion path in grey, along\n              with 2 small circles at key points\")\n\n     (path :d \"M10,110 A120,120 -45 0,1 110 10 A120,120 -45 0,1 10,110\"\n           :stroke \"lightgrey\" :stroke-width \"2\"\n           :fill \"none\" :id \"theMotionPath\")\n     (circle :cx 10 :cy 110 :r 3 :fill \"lightgrey\")\n     (circle :cx 110 :cy 10 :r 3 :fill \"lightgrey\")\n\n     (comment \"Red circle which will be moved along the motion path.\")\n     (circle :cx \"\" :cy \"\" :r 5 :fill \"red\"\n\n             (comment \"Define the motion path animation\")\n             (animateMotion :dur \"6s\" :repeatCount \"indefinite\"\n                            (mpath :xlink:href \"#theMotionPath\")))))\n```\n\n![animate-SVG](https://rawgithub.com/rm-hull/helpmate/main/doc/animate.svg)\n\n## References\n\n- https://developer.mozilla.org/en/docs/Web/HTML/Element\n- https://developer.mozilla.org/en-US/docs/Web/SVG/Element\n\n## Attribution\n\n- Docstring content scraped from Mozilla Developer Network, the\n  content of which is available under the terms of the [Creative Commons\n  Attribution-ShareAlike license](http://creativecommons.org/licenses/by-sa/2.5/) (CC-BY-SA), v2.5.\n- Code examples / inspiration from https://github.com/weavejester/hiccup.\n- SVG examples transcribed from Mozilla Developer Network\n\n## License\n\n### MIT License\n\nCopyright (c) 2016 Richard Hull\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frm-hull%2Fhelpmate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frm-hull%2Fhelpmate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frm-hull%2Fhelpmate/lists"}