86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# clj-metasearch
|
|
|
|
Helper functions for searching through Clojure namespaces for Vars containing specific bits of metadata.
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
Finding Clojure Vars is fairly simple.
|
|
|
|
```clojure
|
|
(use 'clj-metasearch.core)
|
|
|
|
(find-vars #(= (:name %) 'pprint))
|
|
=> ((var clojure.pprint/pprint))
|
|
```
|
|
|
|
`find-vars` takes a predicate which will be run on the metadata for each Var being checked.
|
|
|
|
We can get the value of Vars we find by using `var-get` and then begin using the value right away. For example:
|
|
|
|
```clojure
|
|
(let [println-fn (-> (find-vars #(= (:name %) 'println))
|
|
(first)
|
|
(var-get))]
|
|
(println-fn "Hello world!"))
|
|
Hello world!
|
|
=> nil
|
|
```
|
|
|
|
By default `find-vars` will search all Clojure namespaces it can find in the current classpath. We can filter
|
|
which Clojure namespaces are checked by supplying an additional predicate to `find-vars` under the
|
|
`:namespace-pred` argument. This predicate will be run on each namespace found (the namespace will be passed
|
|
as a symbol to the predicate).
|
|
|
|
```clojure
|
|
; no namespace filtering. all namespaces are checked
|
|
(find-vars #(= (:name %) 'find-namespaces))
|
|
=> ((var clj-metasearch.core/find-namespaces)
|
|
(var clojure.tools.namespace.find/find-namespaces))
|
|
|
|
; using namespace filtering
|
|
(find-vars
|
|
#(= (:name %) 'find-namespaces)
|
|
:namespace-pred #(not= % 'clj-metasearch.core))
|
|
=> ((var clojure.tools.namespace.find/find-namespaces))
|
|
```
|
|
|
|
By default, to help avoid loading a bunch of libraries the first time `find-vars` is called namespaces are not
|
|
automatically loaded before being checked. Thusly, you will only be able to find Vars in namespaces that are
|
|
currently loaded.
|
|
|
|
`find-vars` accepts an option, `:require-all-namespaces?`, that allows you to change this
|
|
behaviour. Passing `true` will cause each namespace being checked to first be loaded via `require`.
|
|
|
|
```clojure
|
|
(find-vars #(= (:name %) 'parse))
|
|
=> ()
|
|
|
|
(find-vars
|
|
#(= (:name %) 'parse)
|
|
:require-all-namespaces? true)
|
|
=> ((var clojure.xml/parse))
|
|
```
|
|
|
|
When you use `true` for `:require-all-namespaces?`, it would normally be a good idea to supply a namespace
|
|
predicate via `:namespace-pred` if at all possible to avoid unnecessarily loading a whole bunch of extra
|
|
namespaces.
|
|
|
|
### Exceptions
|
|
|
|
By default `find-vars` suppresses any exceptions encountered while it searches through namespaces (including
|
|
any exceptions that might occur when loading new namespaces when `:require-all-namespaces?` is set). This
|
|
can be helpful, but sometimes it might be useful to know why something you might have been expecting to
|
|
find doesn't get returned by `find-vars`.
|
|
|
|
We can turn off exception suppression by using either the `throw-exceptions?` option or the
|
|
`throw-compiler-exceptions?` option in calls to `find-vars`. Setting `throw-exceptions?` to true will not
|
|
suppress any exceptions that are encountered, while setting `throw-compiler-exceptions?` to true will
|
|
suppress all exceptions except for `clojure.lang.Compiler.CompilerException` exceptions. This option can
|
|
be useful to catch any syntax or other errors in your own code.
|
|
|
|
## License
|
|
|
|
Distributed under the the MIT License. See LICENSE for more details.
|