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) (use 'clj-metasearch.core)
(find-vars #(= (:name %) 'pprint)) (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. `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 ```clojure
(let [println-fn (-> (find-vars #(= (:name %) 'println)) (let [println-fn (-> (find-vars #(= (:name %) 'println))
(first) (first)
:var
(var-get))] (var-get))]
(println-fn "Hello world!")) (println-fn "Hello world!"))
Hello world! Hello world!
@ -37,21 +36,21 @@ as a symbol to the predicate).
```clojure ```clojure
; no namespace filtering. all namespaces are checked ; no namespace filtering. all namespaces are checked
(find-vars #(= (:name %) 'find-namespaces)) (find-vars #(= (:name %) 'find-namespaces))
=> ({:ns clj-metasearch.core, :var (var clj-metasearch.core/find-namespaces)} => ((var clj-metasearch.core/find-namespaces)
{:ns clojure.tools.namespace.find, :var (var clojure.tools.namespace.find/find-namespaces)}) (var clojure.tools.namespace.find/find-namespaces))
; using namespace filtering ; using namespace filtering
(find-vars (find-vars
#(= (:name %) 'find-namespaces) #(= (:name %) 'find-namespaces)
:namespace-pred #(not= % 'clj-metasearch.core)) :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 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 automatically loaded before being checked. Thusly, you will only be able to find Vars in namespaces that are
currently loaded. 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`. behaviour. Passing `true` will cause each namespace being checked to first be loaded via `require`.
```clojure ```clojure
@ -61,13 +60,26 @@ behaviour. Passing `true` will cause each namespace being checked to first be lo
(find-vars (find-vars
#(= (:name %) 'parse) #(= (:name %) 'parse)
:require-all-namespaces? true) :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 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 predicate via `:namespace-pred` if at all possible to avoid unnecessarily loading a whole bunch of extra
namespaces. 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 ## License
Distributed under the the MIT License. See LICENSE for more details. Distributed under the the MIT License. See LICENSE for more details.