|
| 1 | +# lambdaisland/xml-select |
| 2 | + |
| 3 | +<!-- badges --> |
| 4 | +[](https://cljdoc.org/d/com.lambdaisland/xml-select) [](https://clojars.org/com.lambdaisland/xml-select) |
| 5 | +<!-- /badges --> |
| 6 | + |
| 7 | +XPath-style selectors in Clojure |
| 8 | + |
| 9 | +A single `select` function to conveniently search in `clojure.data.xml` style |
| 10 | +data structures. |
| 11 | + |
| 12 | +## Features |
| 13 | + |
| 14 | +```clj |
| 15 | +(require '[lambdaisland.xml-select :as xs]) |
| 16 | + |
| 17 | +(def doc |
| 18 | + {:tag :Movies |
| 19 | + :content |
| 20 | + [{:tag :Movie |
| 21 | + :attrs {:rating "R"} |
| 22 | + :content |
| 23 | + [{:tag :Title :attrs {:runtime "177"} :content ["The Godfather"]} |
| 24 | + {:tag :Genre :content ["Crime Drama"]} |
| 25 | + {:tag :Director |
| 26 | + :content |
| 27 | + [{:tag :Name |
| 28 | + :content |
| 29 | + [{:tag :First :content ["Francis Ford"]} |
| 30 | + {:tag :Last :content ["Coppola"]}]}]} |
| 31 | + {:tag :Studio :content ["Paramount Pictures"]} |
| 32 | + {:tag :Year :content ["1972"]}]} |
| 33 | + {:tag :Movie |
| 34 | + :attrs {:rating "R"} |
| 35 | + :content |
| 36 | + [{:tag :Title |
| 37 | + :attrs {:runtime "142"} |
| 38 | + :content ["The Shwashank Redemption"]} |
| 39 | + {:tag :Genre :content ["Drama"]} |
| 40 | + {:tag :Director |
| 41 | + :content |
| 42 | + [{:tag :Name |
| 43 | + :attrs {:highratedmovie "The Mist"} |
| 44 | + :content |
| 45 | + [{:tag :First :content ["Frank"]} |
| 46 | + {:tag :Last :content ["Darabont"]}]}]} |
| 47 | + {:tag :Studio :content ["Columbia Pictures"]} |
| 48 | + {:tag :Year :content ["1994"]}]}]}) |
| 49 | + |
| 50 | +;; Select by tag |
| 51 | +(xs/select [:Year] doc) |
| 52 | +;; => ({:tag :Year, :content ["1972"]} {:tag :Year, :content ["1994"]}) |
| 53 | + |
| 54 | +;; Descendants |
| 55 | +(xs/select [:Movies :Title] doc) |
| 56 | +;; => ({:tag :Title, :attrs {:runtime "177"}, :content ["The Godfather"]} |
| 57 | +;; {:tag :Title, :attrs {:runtime "142"}, :content ["The Shwashank Redemption"]}) |
| 58 | + |
| 59 | + |
| 60 | +;; Direct Descendant |
| 61 | +(xs/select [:Movie :> :Title] doc) |
| 62 | + |
| 63 | +;; Arbitary function |
| 64 | +(xs/select [:Movies :> #(= {:rating "R"} (:attrs %))] doc) |
| 65 | + |
| 66 | +;; Attribute |
| 67 | +(xs/select [{:runtime "142"}] doc) |
| 68 | +;; => ({:tag :Title, :attrs {:runtime "142"}, :content ["The Shwashank Redemption"]}) |
| 69 | + |
| 70 | +;; Can take a regex |
| 71 | +(xs/select [{:runtime #"\d{3}"}] doc) |
| 72 | +;; => ({:tag :Title, :attrs {:runtime "177"}, :content ["The Godfather"]} |
| 73 | +;; {:tag :Title, :attrs {:runtime "142"}, :content ["The Shwashank Redemption"]}) |
| 74 | + |
| 75 | +;; Can take a function |
| 76 | +(xs/select [{:runtime #(< 150 (parse-long %) 180)}] doc) |
| 77 | +;; => ({:tag :Title, :attrs {:runtime "177"}, :content ["The Godfather"]}) |
| 78 | + |
| 79 | +;; Vector to combine multiple predicates |
| 80 | +(xs/select [:Movie [:Title {:runtime "177"}]] doc) |
| 81 | +;; => ({:tag :Title, :attrs {:runtime "177"}, :content ["The Godfather"]}) |
| 82 | + |
| 83 | +;; String matches a text node, or the combined string value of all descendant text nodes |
| 84 | +(xs/select ["Coppola"] doc) |
| 85 | +;; => ({:tag :Last, :content ["Coppola"]} "Coppola") |
| 86 | + |
| 87 | + |
| 88 | +;; Compose to have "having" semantics, e.g. the year of all movies with genre "Crime drama" |
| 89 | +(xs/select [:Movies :> #(xs/select [:Genre "Crime Drama"] %) :Year] doc) |
| 90 | +;; => ({:tag :Movie, |
| 91 | +;; :attrs {:rating "R"}, |
| 92 | +;; :content |
| 93 | +;; [{:tag :Title, :attrs {:runtime "177"}, :content ["The Godfather"]} |
| 94 | +;; {:tag :Genre, :content ["Crime Drama"]} |
| 95 | +;; {:tag :Director, |
| 96 | +;; :content |
| 97 | +;; [{:tag :Name, |
| 98 | +;; :content |
| 99 | +;; [{:tag :First, :content ["Francis Ford"]} |
| 100 | +;; {:tag :Last, :content ["Coppola"]}]}]} |
| 101 | +;; {:tag :Studio, :content ["Paramount Pictures"]} |
| 102 | +;; {:tag :Year, :content ["1972"]}]}) |
| 103 | +``` |
| 104 | + |
| 105 | +<!-- installation --> |
| 106 | +## Installation |
| 107 | + |
| 108 | +To use the latest release, add the following to your `deps.edn` ([Clojure CLI](https://clojure.org/guides/deps_and_cli)) |
| 109 | + |
| 110 | +``` |
| 111 | +com.lambdaisland/xml-select {:mvn/version "0.0.0"} |
| 112 | +``` |
| 113 | + |
| 114 | +or add the following to your `project.clj` ([Leiningen](https://leiningen.org/)) |
| 115 | + |
| 116 | +``` |
| 117 | +[com.lambdaisland/xml-select "0.0.0"] |
| 118 | +``` |
| 119 | +<!-- /installation --> |
| 120 | + |
| 121 | +## Rationale |
| 122 | + |
| 123 | +## Usage |
| 124 | + |
| 125 | +<!-- opencollective --> |
| 126 | +## Lambda Island Open Source |
| 127 | + |
| 128 | +Thank you! xml-select is made possible thanks to our generous backers. [Become a |
| 129 | +backer on OpenCollective](https://opencollective.com/lambda-island) so that we |
| 130 | +can continue to make xml-select better. |
| 131 | + |
| 132 | +<a href="https://opencollective.com/lambda-island"> |
| 133 | +<img src="https://opencollective.com/lambda-island/organizations.svg?avatarHeight=46&width=800&button=false"> |
| 134 | +<img src="https://opencollective.com/lambda-island/individuals.svg?avatarHeight=46&width=800&button=false"> |
| 135 | +</a> |
| 136 | +<img align="left" src="https://github.com/lambdaisland/open-source/raw/master/artwork/lighthouse_readme.png"> |
| 137 | + |
| 138 | + |
| 139 | + |
| 140 | +xml-select is part of a growing collection of quality Clojure libraries created and maintained |
| 141 | +by the fine folks at [Gaiwan](https://gaiwan.co). |
| 142 | + |
| 143 | +Pay it forward by [becoming a backer on our OpenCollective](http://opencollective.com/lambda-island), |
| 144 | +so that we continue to enjoy a thriving Clojure ecosystem. |
| 145 | + |
| 146 | +You can find an overview of all our different projects at [lambdaisland/open-source](https://github.com/lambdaisland/open-source). |
| 147 | + |
| 148 | + |
| 149 | + |
| 150 | + |
| 151 | +<!-- /opencollective --> |
| 152 | + |
| 153 | +<!-- contributing --> |
| 154 | +## Contributing |
| 155 | + |
| 156 | +We warmly welcome patches to xml-select. Please keep in mind the following: |
| 157 | + |
| 158 | +- adhere to the [LambdaIsland Clojure Style Guide](https://nextjournal.com/lambdaisland/clojure-style-guide) |
| 159 | +- write patches that solve a problem |
| 160 | +- start by stating the problem, then supply a minimal solution `*` |
| 161 | +- by contributing you agree to license your contributions as MPL 2.0 |
| 162 | +- don't break the contract with downstream consumers `**` |
| 163 | +- don't break the tests |
| 164 | + |
| 165 | +We would very much appreciate it if you also |
| 166 | + |
| 167 | +- update the CHANGELOG and README |
| 168 | +- add tests for new functionality |
| 169 | + |
| 170 | +We recommend opening an issue first, before opening a pull request. That way we |
| 171 | +can make sure we agree what the problem is, and discuss how best to solve it. |
| 172 | +This is especially true if you add new dependencies, or significantly increase |
| 173 | +the API surface. In cases like these we need to decide if these changes are in |
| 174 | +line with the project's goals. |
| 175 | + |
| 176 | +`*` This goes for features too, a feature needs to solve a problem. State the problem it solves first, only then move on to solving it. |
| 177 | + |
| 178 | +`**` Projects that have a version that starts with `0.` may still see breaking changes, although we also consider the level of community adoption. The more widespread a project is, the less likely we're willing to introduce breakage. See [LambdaIsland-flavored Versioning](https://github.com/lambdaisland/open-source#lambdaisland-flavored-versioning) for more info. |
| 179 | +<!-- /contributing --> |
| 180 | + |
| 181 | +<!-- license --> |
| 182 | +## License |
| 183 | + |
| 184 | +Copyright © 2024 Arne Brasseur and Contributors |
| 185 | + |
| 186 | +Licensed under the term of the Mozilla Public License 2.0, see LICENSE. |
| 187 | +<!-- /license --> |
0 commit comments