clojure.tools.namespace - tools.namespace 1.4.6-SNAPSHOT API documentation (original) (raw)

Full namespace name: clojure.tools.namespace

Overview

This namespace is DEPRECATED; most functions have been moved to other namespaces

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1

Public Variables and Functions

function

Usage: (clojure-source-file? file)

DEPRECATED; moved to clojure.tools.namespace.file

Returns true if file is a normal file with a .clj or .cljc extension.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (clojure-sources-in-jar jar-file)

DEPRECATED; moved to clojure.tools.namespace.find

Returns a sequence of filenames ending in .clj or .cljc found in the JAR file.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (comment? form)

DEPRECATED; moved to clojure.tools.namespace.parse

Returns true if form is a (comment ...)

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (find-clojure-sources-in-dir dir)

DEPRECATED; moved to clojure.tools.namespace.find

Searches recursively under dir for Clojure source files (.clj, .cljc). Returns a sequence of File objects, in breadth-first sort order.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (find-namespaces-in-dir dir)

DEPRECATED; moved to clojure.tools.namespace.find

Searches dir recursively for (ns ...) declarations in Clojure source files; returns the symbol names of the declared namespaces.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (find-namespaces-in-jarfile jarfile)

DEPRECATED; moved to clojure.tools.namespace.find

Searches the JAR file for Clojure source files containing (ns ...) declarations. Returns a sequence of the symbol names of the declared namespaces.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (find-namespaces-on-classpath)

DEPRECATED; use clojure.tools.namespace.find/find-namespaces and clojure.java.classpath/classpath from http://github.com/clojure/java.classpath

Searches CLASSPATH (both directories and JAR files) for Clojure source files containing (ns ...) declarations. Returns a sequence of the symbol names of the declared namespaces.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (find-ns-decls-in-dir dir)

DEPRECATED; moved to clojure.tools.namespace.find

Searches dir recursively for (ns ...) declarations in Clojure source files; returns the unevaluated ns declarations.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (find-ns-decls-in-jarfile jarfile)

DEPRECATED; moved to clojure.tools.namespace.find

Searches the JAR file for Clojure source files containing (ns ...) declarations; returns the unevaluated ns declarations.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (find-ns-decls-on-classpath)

DEPRECATED; use clojure.tools.namespace.find/find-ns-decls and clojure.java.classpath/classpath from http://github.com/clojure/java.classpath

Searches CLASSPATH (both directories and JAR files) for Clojure source files containing (ns ...) declarations. Returns a sequence of the unevaluated ns declaration forms.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (ns-decl? form)

DEPRECATED; moved to clojure.tools.namespace.parse

Returns true if form is a (ns ...) declaration.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (read-file-ns-decl file)

DEPRECATED; moved to clojure.tools.namespace.file

Attempts to read a (ns ...) declaration from file, and returns the unevaluated form. Returns nil if read fails, or if the first form is not a ns declaration.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

function

Usage: (read-ns-decl rdr)

DEPRECATED; moved to clojure.tools.namespace.parse

Attempts to read a (ns ...) declaration from rdr, and returns the unevaluated form. Returns nil if read fails or if a ns declaration cannot be found. The ns declaration must be the first Clojure form in the file, except for (comment ...) forms.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

read-ns-decl-from-jarfile-entry

function

Usage: (read-ns-decl-from-jarfile-entry jarfile entry-name)

DEPRECATED; moved to clojure.tools.namespace.find

Attempts to read a (ns ...) declaration from the named entry in the JAR file, and returns the unevaluated form. Returns nil if the read fails, or if the first form is not a ns declaration.

Added in tools.namespace version 0.1.0
Deprecated since tools.namespace version 0.2.1
Source

Bidirectional graphs of dependencies and dependent objects.

Protocols

Protocol

Known implementations: MapDependencyGraph

immediate-dependencies

function

Usage: (immediate-dependencies graph node)

Returns the set of immediate dependencies of node.

immediate-dependents

function

Usage: (immediate-dependents graph node)

Returns the set of immediate dependents of node.

nodes

function

Usage: (nodes graph)

Returns the set of all nodes in graph.

transitive-dependencies

function

Usage: (transitive-dependencies graph node)

Returns the set of all things which node depends on, directly or transitively.

transitive-dependencies-set

function

Usage: (transitive-dependencies-set graph node-set)

Returns the set of all things which any node in node-set depends on, directly or transitively.

transitive-dependents

function

Usage: (transitive-dependents graph node)

Returns the set of all things which depend upon node, directly or transitively.

transitive-dependents-set

function

Usage: (transitive-dependents-set graph node-set)

Returns the set of all things which depend upon any node in node-set, directly or transitively.

Protocol

Known implementations: MapDependencyGraph

depend

function

Usage: (depend graph node dep)

Returns a new graph with a dependency from node to dep ("node depends on dep"). Forbids circular dependencies.

remove-all

function

Usage: (remove-all graph node)

Returns a new dependency graph with all references to node removed.

remove-edge

function

Usage: (remove-edge graph node dep)

Returns a new graph with the dependency from node to dep removed.

remove-node

function

Usage: (remove-node graph node)

Removes the node from the dependency graph without removing it as a dependency of other nodes. That is, removes all outgoing edges from node.

Types

record

Fields: [dependencies dependents]
Protocols: DependencyGraph, DependencyGraphUpdate
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

Public Variables and Functions

function

Usage: (->MapDependencyGraph dependencies dependents)

Positional factory function for class clojure.tools.namespace.dependency.MapDependencyGraph.

function

Usage: (dependent? graph x y)

True if y is a dependent of x.

function

Usage: (depends? graph x y)

True if x is directly or transitively dependent on y.

function

Usage: (graph)

Returns a new, empty, dependency graph.

function

Usage: (map->MapDependencyGraph m#)

Factory function for class clojure.tools.namespace.dependency.MapDependencyGraph, taking a map of keywords to field values.

function

Usage: (topo-comparator graph)

Returns a comparator fn which produces a topological sort based on the dependencies in graph. Nodes not present in the graph will sort after nodes in the graph.

function

Usage: (topo-sort graph)

Returns a topologically-sorted list of nodes in graph.

Track namespace dependencies and changes by monitoring file-modification timestamps

Public Variables and Functions

function

Usage: (scan tracker & dirs)

DEPRECATED: replaced by scan-dirs.

Scans directories for Clojure (.clj, .cljc) source files which have changed since the last time 'scan' was run; update the dependency tracker with new/changed/deleted files.

If no dirs given, defaults to all directories on the classpath.

Added in tools.namespace version 0.2.0
Deprecated since tools.namespace version 0.3.0
Source

function

Usage: (scan-all tracker & dirs)

DEPRECATED: replaced by scan-dirs.

Scans directories for all Clojure source files and updates the dependency tracker to reload files. If no dirs given, defaults to all directories on the classpath.

Added in tools.namespace version 0.2.0
Deprecated since tools.namespace version 0.3.0
Source

function

Usage: (scan-dirs tracker) (scan-dirs tracker dirs) (scan-dirs tracker dirs {:keys [platform add-all?], :as options})

Scans directories for files which have changed since the last time 'scan-dirs' or 'scan-files' was run; updates the dependency tracker with new/changed/deleted files.

dirs is the collection of directories to scan, defaults to all directories on Clojure's classpath.

Optional third argument is map of options:

:platform Either clj (default) or cljs, both defined in clojure.tools.namespace.find, controls file extensions and reader options.

:add-all? If true, assumes all extant files are modified regardless of filesystem timestamps.

Added in tools.namespace version 0.3.0
Source

function

Usage: (scan-files tracker files) (scan-files tracker files {:keys [platform add-all?]})

Scans files to find those which have changed since the last time 'scan-files' was run; updates the dependency tracker with new/changed/deleted files.

files is the collection of files to scan.

Optional third argument is map of options:

:platform Either clj (default) or cljs, both defined in clojure.tools.namespace.find, controls reader options for parsing files.

:add-all? If true, assumes all extant files are modified regardless of filesystem timestamps.

Added in tools.namespace version 0.3.0
Source

Read and track namespace information from files

Public Variables and Functions

function

Usage: (add-files tracker files) (add-files tracker files read-opts)

Reads ns declarations from files; returns an updated dependency tracker with those files added. read-opts is passed through to tools.reader.

var

File extensions for Clojure (JVM) files.

Added in tools.namespace version 0.3.0
Source

function

Usage: (clojure-file? file)

Returns true if the java.io.File represents a file which will be read by the Clojure (JVM) compiler.

var

File extensions for ClojureScript files.

Added in tools.namespace version 0.3.0
Source

function

Usage: (clojurescript-file? file)

Returns true if the java.io.File represents a file which will be read by the ClojureScript compiler.

Added in tools.namespace version 0.3.0
Source

function

Usage: (file-with-extension? file extensions)

Returns true if the java.io.File represents a file whose name ends with one of the Strings in extensions.

Added in tools.namespace version 0.3.0
Source

function

Usage: (read-file-ns-decl file) (read-file-ns-decl file read-opts)

Attempts to read a (ns ...) declaration from file, and returns the unevaluated form. Returns nil if ns declaration cannot be found. read-opts is passed through to tools.reader/read.

function

Usage: (remove-files tracker files)

Returns an updated dependency tracker with files removed. The files must have been previously added with add-files.

Search for namespace declarations in directories and JAR files.

Public Variables and Functions

var

Platform definition of file extensions and reader options for Clojure (.clj and .cljc) source files.

Added in tools.namespace version 0.3.0
Source

var

Platform definition of file extensions and reader options for ClojureScript (.cljs and .cljc) source files.

Added in tools.namespace version 0.3.0
Source

function

Usage: (clojure-sources-in-jar jar-file)

DEPRECATED: replaced by sources-in-jar

Returns a sequence of filenames ending in .clj or .cljc found in the JAR file.

Added in tools.namespace version 0.2.0
Deprecated since tools.namespace version 0.3.0
Source

function

Usage: (find-clojure-sources-in-dir dir)

DEPRECATED: replaced by find-sources-in-dir

Searches recursively under dir for Clojure source files (.clj, .cljc). Returns a sequence of File objects, in breadth-first sort order.

Added in tools.namespace version 0.2.0
Deprecated since tools.namespace version 0.3.0
Source

function

Usage: (find-namespaces files) (find-namespaces files platform)

Searches a sequence of java.io.File objects (both directories and JAR files) for platform source files containing (ns...) declarations. Returns a sequence of the symbol names of the declared namespaces. Use with clojure.java.classpath to search Clojure's classpath.

Optional second argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

function

Usage: (find-namespaces-in-dir dir) (find-namespaces-in-dir dir platform)

Searches dir recursively for (ns ...) declarations in Clojure source files; returns the symbol names of the declared namespaces.

Optional second argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

Added in tools.namespace version 0.3.0
Source

function

Usage: (find-namespaces-in-jarfile jarfile) (find-namespaces-in-jarfile jarfile platform)

Searches the JAR file for platform source files containing (ns ...) declarations. Returns a sequence of the symbol names of the declared namespaces.

Optional second argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

function

Usage: (find-ns-decls files) (find-ns-decls files platform)

Searches a sequence of java.io.File objects (both directories and JAR files) for platform source files containing (ns...) declarations. Returns a sequence of the unevaluated ns declaration forms. Use with clojure.java.classpath to search Clojure's classpath.

Optional second argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

function

Usage: (find-ns-decls-in-dir dir) (find-ns-decls-in-dir dir platform)

Searches dir recursively for (ns ...) declarations in Clojure source files; returns the unevaluated ns declarations. The symbol name in the returned ns declaration will contain metadata for the corresponding directory and located file within at keys :dir and :file.

Optional second argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

Added in tools.namespace version 0.2.0
Source

function

Usage: (find-ns-decls-in-jarfile jarfile) (find-ns-decls-in-jarfile jarfile platform)

Searches the JAR file for source files containing (ns ...) declarations; returns the unevaluated ns declarations.

Optional second argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

function

Usage: (find-sources-in-dir dir) (find-sources-in-dir dir platform)

Searches recursively under dir for source files. Returns a sequence of File objects, in breadth-first sort order.

Optional second argument is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

Added in tools.namespace version 0.3.0
Source

read-ns-decl-from-jarfile-entry

function

Usage: (read-ns-decl-from-jarfile-entry jarfile entry-name) (read-ns-decl-from-jarfile-entry jarfile entry-name platform)

Attempts to read a (ns ...) declaration from the named entry in the JAR file, and returns the unevaluated form. Returns nil if read fails due to invalid syntax or if a ns declaration cannot be found. The symbol name in the returned ns declaration will contain metadata for the corresponding jar filename and located file within at keys :jar and :file.

Optional third argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

function

Usage: (sources-in-jar jar-file) (sources-in-jar jar-file platform)

Returns a sequence of source file names found in the JAR file.

Optional second argument platform is either clj (default) or cljs, both defined in clojure.tools.namespace.find.

Added in tools.namespace version 0.3.0
Source

Refactoring tool to move a Clojure namespace from one name/file to another, and update all references to that namespace in your other Clojure source files.

WARNING: This code is ALPHA and subject to change. It also modifies and deletes your source files! Make sure you have a backup or version control.

Public Variables and Functions

function

Usage: (move-ns old-sym new-sym source-path dirs)

ALPHA: subject to change. Moves the .clj source file (found relative to source-path) for the namespace named old-sym to new-sym and replace all occurrences of the old name with the new name in all Clojure source files found in dirs.

This is a purely textual transformation. It does not work on namespaces require'd or use'd from a prefix list.

WARNING: This function modifies and deletes your source files! Make sure you have a backup or version control.

function

Usage: (move-ns-file old-sym new-sym source-path)

ALPHA: subject to change. Moves the .clj source file (found relative to source-path) for the namespace named old-sym to a file for a namespace named new-sym.

WARNING: This function moves and deletes your source files! Make sure you have a backup or version control.

function

Usage: (replace-ns-symbol source old-sym new-sym)

ALPHA: subject to change. Given Clojure source as a string, replaces all occurrences of the namespace name old-sym with new-sym and returns modified source as a string.

Parse Clojure namespace (ns) declarations and extract dependencies.

Public Variables and Functions

var

Map of options for tools.reader/read allowing reader conditionals with the :clj feature enabled.

var

Map of options for tools.reader/read allowing reader conditionals with the :cljs feature enabled.

function

Usage: (comment? form)

Returns true if form is a (comment ...)

function

Usage: (deps-from-ns-decl decl)

Given an (ns...) declaration form (unevaluated), returns a set of symbols naming the dependencies of that namespace. Handles :use and :require clauses but not :load.

function

Usage: (name-from-ns-decl decl)

Given an (ns...) declaration form (unevaluated), returns the name of the namespace as a symbol.

function

Usage: (ns-decl? form)

Returns true if form is a (ns ...) declaration.

function

Usage: (read-ns-decl rdr) (read-ns-decl rdr read-opts)

Attempts to read a (ns ...) declaration from a reader, and returns the unevaluated form. Returns the first top-level ns form found. Returns nil if ns declaration cannot be found. Throws exception on invalid syntax.

Note that read can execute code (controlled by tools.reader/read-eval), and as such should be used only with trusted sources. read-opts is passed through to tools.reader/read, defaults to clj-read-opts

Force reloading namespaces on demand or through a dependency tracker

Public Variables and Functions

function

Usage: (remove-lib lib)

Remove lib's namespace and remove lib from the set of loaded libs.

function

Usage: (track-reload tracker)

Executes all pending unload/reload operations on dependency tracker until either an error is encountered or there are no more pending operations.

function

Usage: (track-reload-one tracker)

Executes the next pending unload/reload operation in the dependency tracker. Returns the updated dependency tracker. If reloading caused an error, it is captured as ::error and the namespace which caused the error is ::error-ns.

REPL utilities for working with namespaces

Public Variables and Functions

function

Usage: (clear)

Clears all state from the namespace/file tracker. This may help repair the namespace tracker when it gets into an inconsistent state, without restarting the Clojure process. The next call to 'refresh' will reload all source files, but may not completely remove stale code from deleted files.

function

Usage: (disable-reload!) (disable-reload! namespace)

Adds metadata to namespace (or ns if unspecified) telling 'refresh' not to load it. Implies disable-unload! also.

Warning: Aliases to reloaded namespaces will break.

function

Usage: (disable-unload!) (disable-unload! namespace)

Adds metadata to namespace (or ns if unspecified) telling 'refresh' not to unload it. The namespace may still be reloaded, it just won't be removed first.

Warning: Aliases to reloaded namespaces will break.

function

Usage: (refresh & options)

Scans source code directories for files which have changed (since the last time this function was run) and reloads them in dependency order. Returns :ok or an error; sets the latest exception to clojure.core/*e (if *e is thread-bound).

The directories to be scanned are controlled by 'set-refresh-dirs'; defaults to all directories on the Java classpath.

Options are key-value pairs. Valid options are:

:after   Namespace-qualified symbol naming a zero-argument
         function to be invoked after a successful refresh. This
         symbol will be resolved *after* all namespaces have
         been reloaded.

function

Usage: (refresh-all & options)

Scans source code directories for all Clojure source files and reloads them in dependency order.

The directories to be scanned are controlled by 'set-refresh-dirs'; defaults to all directories on the Java classpath.

Options are key-value pairs. Valid options are:

:after   Namespace-qualified symbol naming a zero-argument
         function to be invoked after a successful refresh. This
         symbol will be resolved *after* all namespaces have
         been reloaded.

function

Usage: (refresh-scanned & options)

Reloads namespaces in dependency order. Does not scan directories again, expected to be used after 'scan'.

Returns :ok or an error; sets the latest exception to clojure.core/*e (if *e is thread-bound).

The directories to be scanned are controlled by 'set-refresh-dirs'; defaults to all directories on the Java classpath.

Options are key-value pairs. Valid options are:

:after   Namespace-qualified symbol naming a zero-argument
         function to be invoked after a successful refresh. This
         symbol will be resolved *after* all namespaces have
         been reloaded.

function

Usage: (scan) (scan options)

Scans directories for files which have changed since the last time 'scan' or 'refresh' was run; updates the dependency tracker with new/changed/deleted files.

Optional argument is map of options:

:platform  Either clj (default) or cljs, both defined in
           clojure.tools.namespace.find, controls file extensions
           and reader options.

:add-all?  If true, assumes all extant files are modified regardless
           of filesystem timestamps.

Returns map with keys:

::track/unload   list of namespace symbols that will be unloaded
::track/load     list of namespace symbols that will be loaded

function

Usage: (set-refresh-dirs & dirs)

Sets the directories which are scanned by 'refresh'. Supports the same types as clojure.java.io/file.

Dependency tracker which can compute which namespaces need to be reloaded after files have changed. This is the low-level implementation that requires you to find the namespace dependencies yourself: most uses will interact with the wrappers in clojure.tools.namespace.file and clojure.tools.namespace.dir or the public API in clojure.tools.namespace.repl.

Public Variables and Functions

function

Usage: (add tracker depmap)

Returns an updated dependency tracker with new/updated namespaces.

Depmap is a map describing the new or modified namespaces. Keys in the map are namespace names (symbols). Values in the map are sets of symbols naming the direct dependencies of each namespace. For example, assuming these ns declarations:

(ns alpha (:require beta))
(ns beta (:require gamma delta))

the depmap would look like this:

{alpha #{beta}
 beta  #{gamma delta}}

After adding new/updated namespaces, the dependency tracker will have two lists associated with the following keys:

:clojure.tools.namespace.track/unload
    is the list of namespaces that need to be removed

:clojure.tools.namespace.track/load
    is the list of namespaces that need to be reloaded

To reload namespaces in the correct order, first remove/unload all namespaces in the 'unload' list, then (re)load all namespaces in the 'load' list. The clojure.tools.namespace.reload namespace has functions to do this.

function

Usage: (remove tracker names)

Returns an updated dependency tracker from which the namespaces (symbols) have been removed. The ::unload and ::load lists are populated as with 'add'.

function

Usage: (tracker)

Returns a new, empty dependency tracker