grimoire.api — org.clojure-grimoire/lib-grimoire 0.10.10

This namespace serves to implement an abstraction layer for looking up examples, symbols, namespaces and artifacts as values without regard to the implementation of the datastore. Ports of Grimoire to different datastores should only need to extend the multimethods in this namespace.

API Contract assumptions:

• Everything has metadata, even if it's nil. If metadata for a Thing cannot be found, then the Thing itself is not in the datastore.

-compare-to-version clj

-list-artifacts clj multimethod

Implementation extension point of clj::grimoire.api/list-artifacts. Listing APIs must extend this multimethod.

λ [config Group] → (Either (Succeed (Seq Artifact)) (Failure String))

-list-defs clj multimethod

Implementation extension point of clj::grimoire.api/list-defs. Listing APIs must extend this multimethod.

λ [config Ns] → (Either (Succeed (Seq Def)) (Failure String))

-list-examples clj multimethod

Implementation extension point of clj::grimoire.api/list-examples. Listing APIs must extend this multimethod.

λ [config Thing] → (Either (Succeed (Seq Example)) (Failure String))

-list-groups clj multimethod

Implementation extension point of clj::grimoire.api/list-groups. Listing APIs must extend this multimethod.

λ [config] → (Either (Succeed (Seq Group)) (Failure String))

-list-namespaces clj multimethod

Implementation extension point of clj::grimoire.api/list-namespaces. Listing APIs must extend this multimethod.

λ [config Platform] → (Either (Succeed (Seq Ns)) (Failure String))

-list-notes clj multimethod

Implementation extension point of clj::grimoire.api/list-notes. Listing APIs must extend this multimethod.

λ [config Thing] → (Either (Succeed (Seq Note)) (Failure String))

-list-platforms clj multimethod

Implementation extension point of clj::grimoire.api/list-platforms. Listing APIs must extend this multimethod.

λ [config Version] → (Either (Succeed (Seq Platform)) (Failure String))

-list-related clj multimethod

Implementation extension point of clj::grimoire.api/list-related. Listing APIs must extend this multimethod.

λ [config Thing] → (Either (Succeed (Seq Thing)) (Failure String))

-list-versions clj multimethod

Implementation extension point of clj::grimoire.api/list-versions. Listing APIs must extend this multimethod.

λ [config Artifact] → (Either (Succeed (Seq Version)) (Failure String))

-read-example clj multimethod

Implementation extension point of clj::grimoire.api/read-example. Listing APIs must extend this multimethod.

λ [config Artifact] → (Either (Succeed String) (Failure String))

-read-meta clj multimethod

Implementation extension point of clj::grimoire.api/read-meta. Listing APIs must extend this multimethod.

λ [config Thing] → (Either (Succeed Map) (Failure String))

-read-note clj multimethod

Implementation extension point of clj::grimoire.api/read-note. Listing APIs must extend this multimethod.

λ [config Note] → (Either (Succeed String) (Failure String))

-search clj multimethod

Implementation extension point of clj::grimoire.api/search. Listing APIs may implement this multimethod, however a default implementation in terms of the various listing operations and clj::clojure.core/for is provided.

λ [config Pattern] → (Either (Succeed (Seq Thing)) (Failure String))

-thing->prior-versions clj multimethod

Implementation extension point of clj::grimoire.api/thing->prior-versions. Listing APIs may implement this multimethod, however a default implementation in terms of the various listing operations.

λ [config Thing] → (Either (Succeed (Seq Thing)) (Failure String))

-write-example clj multimethod

-write-meta clj multimethod

-write-note clj multimethod

-write-related clj multimethod

dispatch clj

(dispatch config & more)

Common dispatch function for all the API multimethods.

list-artifacts clj

(list-artifacts config group-thing)

Succeeds with a result Seq[Artifact] representing all Maven artifacts in the queried datastore that belong to the specified Group. Will Succeed with an empty result if there are no known artifacts.

Fails if the group is unknown or if another Failure is encountered.

list-defs clj

(list-defs config namespace-thing)

Succeeds with a result Seq[Def] representing all Clojure defs in the specified Namespace. Could succeed with an empty result.

Fails if the specified Namespace does not exist or if another failure is encountered.

list-examples clj

(list-examples config def-thing)

Succeeds with a result Seq[Example] encoding for all examples on prior or equal versions of the given thing sorted in decending version order.

Will Fail if the given Def does not exist, or if a nested Failure is encountered.

Note that future versions of this API may extend examples to Namespaces and Versions.

list-groups clj

(list-groups config)

Succeeds with a result Seq[Group] representing all Maven groups in the queried datastore. Will succeed with an empty result if there are no known groups.

Fails if the datstore isn't correctly configured or missing.

list-namespaces clj

(list-namespaces config platform-thing)

Succeeds with a result Seq[Namespace] representing all Clojure namespaces in the specified Version. Could succeed with an empty result.

Fails if the specified Platform does not exist or if another Failure is encountered.

list-notes clj

(list-notes config thing)

Succeeds with a result Seq[Note] representing all the Notes known on equal or prior versions of the given Thing.

Fails if the specified Thing does not exist, or if a nested Failure is encountered.

list-platforms clj

(list-platforms config version-thing)

Succeeds with a result Seq[Platform] representing all Clojure dialects of the specified Artifact in the specified datastore. Could succeed with an empty result if there is no documentation for any known dialect.

Fails if the specified Version does not exist or if another Failure is encountered.

list-related clj

(list-related config thing)

Succeeds with a result Seq[Def] being the sequence of Things "related" according to the documentation writer to the Thing for which related entities was requested.

Fails if the given Thing does not exist, or if a nested Failure is encountered.

As of 0.6.X, this operation is only defined over Defs, however future versions of this API may extend this operation to other types.

list-versions clj

(list-versions config artifact-thing)

Succeeds with a result Seq[Version] representing all Maven versions in the queried datastore of the specified Artifact in decending version order. Could succeed with an empty result if there are no known versions.

Fails if the specified Artifact does not exist or if another Failure is encountered.

read-example clj

(read-example config example-thing)

Succeeds with a result String being the text of an example read as identified by a given examples handle.

Will Fail if the given Example Thing does not exist, or if a nested Failure is encountered.

Note that future versions of this API may extend examples to Namespaces and Versions.

read-meta clj

(read-meta config thing)

Succeeds returning a Map being the metadata for the specified Thing. No backtracking is done to find metadata on prior Versions of the given Thing.

Fails if the given Thing does not exist.

Note that per the API contract, failure to find a metadata descriptor for a Thing is equivalent to its absence even if other data bout the Thing could be found.

read-note clj

(read-note config note-thing)

Succeeds with a result String being the text of notes read as identified by a given notes handle.

Will Fail if the given Notes Thing does not exist, or if a nested Failure is encountered.

read-notes clj

(read-notes config thing)

Succeeds with a result Seq[Version, string], being the zip of list-notes with read-note for each listed note.

Fails if a nested Failure is encountered.

Legacy from the 0.7.X and earlier API. Note that this function does not return the Note instances themselves, only the versions each read note is attached to.

resolve-short-string clj

(resolve-short-string config s)

Succeeds with a result Thing, mapping a short string as generated by clj::grimoire.things/thing->short-string back to a thing via clj::grimoire.api/search.

search clj

(search config pattern)

Succeeds with a result Seq[Thing], being a list of all the Things in the given datastore which match the given search structure.

Search patterns are vectors of the form [<type> &parts] where a type is one of the Thing keywords, and &parts is a sequence terms being either sets of strings, strings, regexes, functions, nil or the keyword :any.

• nil as a term matches any Thing
• :any as a term matches any Thing
• Sets as a term match Thing with its Name in the set
• Strings as a term match any Thing with an equal Name
• Regexps as a Term match any Thing with a matching Name
• Fns as a term match any Thing such that (f T) is truthy
• :latest is a speciao Version which matches only the latest one

Examples:

[:def :any :any :any :any "clojure.core" "concat"]

Will match all instances of Defs named "clojure.core/concat" on all platforms in all versions in all artifacts in all groups.

[:ns :any "clojure" :any :any "clojure.set"]

Will match all instances of Nss named "clojure.set" in all artifacts named "clojure" in all versions, platforms and groups.

[:ns #"org.*" :any :any :any :any]

Will match all instances of Ns in any platform of any version of any artifact in a Maven group matching the regex #"org.*"

thing->prior-versions clj

(thing->prior-versions config thing)

Succeeds with a result Seq[Thing] representing the argument Thing at earlier or equal versions sorted in decending order. Note that this op only supports Versions, Namespaces and Defs. Artifacts and Groups do not have versions, and will give Failures. The Version component of a Note or an Example is naming, and versions of these Things are not guranteed to be interchangable. Trying to get a prior version with a

Fails if a nested Failure is encountered.

write-example clj

(write-example config example data)

Writes an example into the datastore specified by the config at the path represented by thing. Note that thing need not be a def.

write-meta clj

(write-meta config thing data)

Writes a map, being documentation data, into the datastore as specified by config at the def denoted by thing. Note that non-readable structures such as Namespaces must be stringified or removed by users. This function provides no sanitization.

Expected keys for symbols:

• :ns -> string naming the namespace, namespace itself, or a symbol
• :name -> string naming the symbol (unmunged), or a symbol
• :doc -> documentation string
• :arglists -> list of argument vectors
• :src -> string of source code
• :added -> string being a SemVer version
• :column -> integer being colunm number
• :line -> integer being line number
• :file -> string being file name
• :target -> string being symbol name for implementing macro. only for {:type :sentinel}
• :type -> one of #{:macro :fn :var :special :sentinel}

Expected keys for namespaces:

• :doc -> documentation string

write-note clj

(write-note config thing data)

Writes a string into the datastore specified by the config and the Thing to which the resulting Note will be attached. Returns no meaningful value.

write-related clj

(write-related config thing related-things)

Writes a sequence of things representing defs into the datastore's related file as specified by the target thing.