gered/clj-metasearch
Archived
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

update README.md

Browse source
This commit is contained in:
Gered 2014-04-09 09:42:14 -04:00
parent 9863a8708e
commit 9d8f91cdb8
1 changed files with 19 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
README.md
View file

@ -12,7 +12,7 @@ Finding Clojure Vars is fairly simple.
(use 'clj-metasearch.core)
(find-vars #(= (:name %) 'pprint))
=> ({:ns clojure.pprint, :var (var clojure.pprint/pprint)})
=> ((var clojure.pprint/pprint))
```
`find-vars` takes a predicate which will be run on the metadata for each Var being checked.
@ -22,7 +22,6 @@ We can get the value of Vars we find by using `var-get` and then begin using the
```clojure
(let [println-fn (-> (find-vars #(= (:name %) 'println))
(first)
:var
(var-get))]
(println-fn "Hello world!"))
Hello world!
@ -37,21 +36,21 @@ as a symbol to the predicate).
```clojure
; no namespace filtering. all namespaces are checked
(find-vars #(= (:name %) 'find-namespaces))
=> ({:ns clj-metasearch.core, :var (var clj-metasearch.core/find-namespaces)}
{:ns clojure.tools.namespace.find, :var (var clojure.tools.namespace.find/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))
=> ({:ns clojure.tools.namespace.find, :var (var clojure.tools.namespace.find/find-namespaces)})
=> ((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` takes an additional optional argument `:require-all-namespaces?` that allows you to change this
`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
@ -61,13 +60,26 @@ behaviour. Passing `true` will cause each namespace being checked to first be lo
(find-vars
#(= (:name %) 'parse)
:require-all-namespaces? true)
=> ({:ns clojure.xml, :var (var clojure.xml/parse)})
=> ((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.