diff options
Diffstat (limited to 'branch-master/logging-api.html')
| -rw-r--r-- | branch-master/logging-api.html | 394 |
1 files changed, 394 insertions, 0 deletions
diff --git a/branch-master/logging-api.html b/branch-master/logging-api.html new file mode 100644 index 00000000..19d4d1d6 --- /dev/null +++ b/branch-master/logging-api.html @@ -0,0 +1,394 @@ +<html> + <head> + <title>logging - clojure-contrib next API documentation</title> + <link href="../static/favicon.png" rel="icon" /> + <link href="../static/favicon.png" rel="shortcut icon" /> + <link media="all" type="text/css" href="../static/clojure.css" rel="stylesheet" /> + <link media="all" type="text/css" href="../static/wiki.css" rel="stylesheet" /> + <link media="all" type="text/css" href="../static/internal.css" rel="stylesheet" /> + <!-- TODO: are we using these (from clojure.org)? If so, add the files --> + <script src="file/view/code_highlighter.js" type="text/javascript"></script> + <script src="file/view/clojure.js" type="text/javascript"></script> + <style>.menuWrapper{height: 36px;}</style> + <!--[if lte IE 6]> + <link rel="stylesheet" href="http://www.wikispaces.com/_/2009051601/s/internal_ie.css" type="text/css" /> + <![endif]--> + </head> +<!-- +This document was auto-generated from the source by the clojure autodoc system. +To report errors or ask questions about the overall documentation structure, formatting, +etc., contact Tom Faulhaber (google mail name: tomfaulhaber). +For errors in the documentation of a particular namespace, contact the author of that +namespace. +--> + <body> + <div id="AllContentContainer"> + <div id="Header"> + <a id="Logo" href="index.html"><img alt="Clojure" height="100" width="100" src="../static/clojure-icon.gif" /></a> + <h1><a title="page header title" id="page-header" href="index.html">Clojure-contrib API Reference</a></h1> + </div> + <div id="leftcolumn"><div style="text-align: center;"></div> +<div class="menu"> + <div class="WikiCustomNav WikiElement wiki"> + <span class="toc-header"><span id="project-name">clojure-contrib</span> <span id="version">next</span> API</span><br /> + <ul> + <li><a class="wiki_link" href="index.html">Overview</a></li> + <li><a class="wiki_link" href="api-index.html">API Index</a></li> + </ul> + <span class="toc-header">Namespaces</span> + <ul id="left-sidebar-list"> + <li><a href="accumulators-api.html" class="wiki_link">accumulators</a></li><li><a href="agent-utils-api.html" class="wiki_link">agent-utils</a></li><li><a href="apply-macro-api.html" class="wiki_link">apply-macro</a></li><li><a href="base64-api.html" class="wiki_link">base64</a></li><li><a href="classpath-api.html" class="wiki_link">classpath</a></li><li><a href="combinatorics-api.html" class="wiki_link">combinatorics</a></li><li><a href="command-line-api.html" class="wiki_link">command-line</a></li><li><a href="complex-numbers-api.html" class="wiki_link">complex-numbers</a></li><li><a href="cond-api.html" class="wiki_link">cond</a></li><li><a href="condition-api.html" class="wiki_link">condition</a></li><li><a href="core-api.html" class="wiki_link">core</a></li><li><a href="dataflow-api.html" class="wiki_link">dataflow</a></li><li><a href="datalog-api.html" class="wiki_link">datalog</a></li><li><a href="def-api.html" class="wiki_link">def</a></li><li><a href="duck-streams-api.html" class="wiki_link">duck-streams</a></li><li><a href="error-kit-api.html" class="wiki_link">error-kit</a></li><li><a href="except-api.html" class="wiki_link">except</a></li><li><a href="fcase-api.html" class="wiki_link">fcase</a></li><li><a href="find-namespaces-api.html" class="wiki_link">find-namespaces</a></li><li><a href="fnmap-api.html" class="wiki_link">fnmap</a></li><li><a href="gen-html-docs-api.html" class="wiki_link">gen-html-docs</a></li><li><a href="generic.arithmetic-api.html" class="wiki_link">generic.arithmetic</a></li><li><a href="generic.collection-api.html" class="wiki_link">generic.collection</a></li><li><a href="generic.comparison-api.html" class="wiki_link">generic.comparison</a></li><li><a href="generic.functor-api.html" class="wiki_link">generic.functor</a></li><li><a href="generic.math-functions-api.html" class="wiki_link">generic.math-functions</a></li><li><a href="graph-api.html" class="wiki_link">graph</a></li><li><a href="greatest-least-api.html" class="wiki_link">greatest-least</a></li><li><a href="http.agent-api.html" class="wiki_link">http.agent</a></li><li><a href="http.connection-api.html" class="wiki_link">http.connection</a></li><li><a href="import-static-api.html" class="wiki_link">import-static</a></li><li><a href="io-api.html" class="wiki_link">io</a></li><li><a href="jar-api.html" class="wiki_link">jar</a></li><li><a href="java-utils-api.html" class="wiki_link">java-utils</a></li><li><a href="javadoc.browse-api.html" class="wiki_link">javadoc.browse</a></li><li><a href="jmx-api.html" class="wiki_link">jmx</a></li><li><a href="json-api.html" class="wiki_link">json</a></li><li><a href="lazy-seqs-api.html" class="wiki_link">lazy-seqs</a></li><li><a href="lazy-xml-api.html" class="wiki_link">lazy-xml</a></li><li><a href="logging-api.html" class="wiki_link">logging</a></li><li><a href="macro-utils-api.html" class="wiki_link">macro-utils</a></li><li><a href="macros-api.html" class="wiki_link">macros</a></li><li><a href="map-utils-api.html" class="wiki_link">map-utils</a></li><li><a href="math-api.html" class="wiki_link">math</a></li><li><a href="miglayout-api.html" class="wiki_link">miglayout</a></li><li><a href="mmap-api.html" class="wiki_link">mmap</a></li><li><a href="mock-api.html" class="wiki_link">mock</a></li><li><a href="monadic-io-streams-api.html" class="wiki_link">monadic-io-streams</a></li><li><a href="monads-api.html" class="wiki_link">monads</a></li><li><a href="ns-utils-api.html" class="wiki_link">ns-utils</a></li><li><a href="pprint-api.html" class="wiki_link">pprint</a></li><li><a href="priority-map-api.html" class="wiki_link">priority-map</a></li><li><a href="probabilities.finite-distributions-api.html" class="wiki_link">probabilities.finite-distributions</a></li><li><a href="probabilities.monte-carlo-api.html" class="wiki_link">probabilities.monte-carlo</a></li><li><a href="probabilities.random-numbers-api.html" class="wiki_link">probabilities.random-numbers</a></li><li><a href="profile-api.html" class="wiki_link">profile</a></li><li><a href="properties-api.html" class="wiki_link">properties</a></li><li><a href="prxml-api.html" class="wiki_link">prxml</a></li><li><a href="reflect-api.html" class="wiki_link">reflect</a></li><li><a href="repl-ln-api.html" class="wiki_link">repl-ln</a></li><li><a href="repl-utils-api.html" class="wiki_link">repl-utils</a></li><li><a href="seq-api.html" class="wiki_link">seq</a></li><li><a href="seq-utils-api.html" class="wiki_link">seq-utils</a></li><li><a href="server-socket-api.html" class="wiki_link">server-socket</a></li><li><a href="set-api.html" class="wiki_link">set</a></li><li><a href="shell-api.html" class="wiki_link">shell</a></li><li><a href="shell-out-api.html" class="wiki_link">shell-out</a></li><li><a href="singleton-api.html" class="wiki_link">singleton</a></li><li><a href="sql-api.html" class="wiki_link">sql</a></li><li><a href="str-utils-api.html" class="wiki_link">str-utils</a></li><li><a href="str-utils2-api.html" class="wiki_link">str-utils2</a></li><li><a href="stream-utils-api.html" class="wiki_link">stream-utils</a></li><li><a href="string-api.html" class="wiki_link">string</a></li><li><a href="strint-api.html" class="wiki_link">strint</a></li><li><a href="swing-utils-api.html" class="wiki_link">swing-utils</a></li><li><a href="test-is-api.html" class="wiki_link">test-is</a></li><li><a href="trace-api.html" class="wiki_link">trace</a></li><li><a href="types-api.html" class="wiki_link">types</a></li><li><a href="with-ns-api.html" class="wiki_link">with-ns</a></li><li><a href="zip-filter-api.html" class="wiki_link">zip-filter</a></li> + </ul> + <div class="BranchTOC"> + <span class="toc-header">Other Versions</span> + <ul id="left-sidebar-branch-list"> + <li><a href="../index.html" class="wiki_link">v1.2 (beta 1)</a></li><li><a href="../branch-1.1.x/index.html" class="wiki_link">v1.1 (stable)</a></li> + </ul> + </div> + <a href="http://clojure.org" class="wiki_link">Clojure Home</a> + </div> +</div> +</div> + <div id="rightcolumn"> + <div id="Content"> + <div class="contentBox"><div class="innerContentBox"> + <div id="content_view" class="wiki wikiPage"> + <div id="right-sidebar"><div id="toc"> + <h1 class="nopad">Table of Contents</h1> + <div style="margin-left: 1em;" class="toc-section"> + <a href="#toc0">Overview</a> + <div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/*allow-direct-logging*">*allow-direct-logging*</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/*impl-name*">*impl-name*</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/*logging-agent*">*logging-agent*</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/debug">debug</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/enabled?">enabled?</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/error">error</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/fatal">fatal</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/impl-enabled?">impl-enabled?</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/impl-get-log">impl-get-log</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/impl-write!">impl-write!</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/info">info</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/log">log</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/log-capture!">log-capture!</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/log-stream">log-stream</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/log-uncapture!">log-uncapture!</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/spy">spy</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/trace">trace</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/warn">warn</a> + </div><div style="margin-left: 1em;" class="toc-entry"> + <a href="#clojure.contrib.logging/with-logs">with-logs</a> + </div> + <br /> + </div> +</div> +</div> + <div id="content-tag"><h1 id="overview">API for <span id="namespace-name">logging</span> + - <span id="header-project">clojure-contrib</span> <span id="header-version">next</span> (<span id="header-status">in development</span>) + </h1> +<span id="author-line">by <span id="author-name">Alex Taggart, Timothy Pratley</span><br /></span> +<br />Usage: +<pre> +(ns your-namespace + (:require <span id="long-name">clojure.contrib.logging</span>)) +</pre><pre> +</pre><h2>Overview</h2> +<pre id="namespace-docstr">Logging macros which delegate to a specific logging implementation. At +runtime a specific implementation is selected from, in order, Apache +commons-logging, log4j, and finally java.util.logging. + +Logging levels are specified by clojure keywords corresponding to the +values used in log4j and commons-logging: + :trace, :debug, :info, :warn, :error, :fatal + +Logging occurs with the log macro, or the level-specific convenience macros, +which write either directly or via an agent. For performance reasons, direct +logging is enabled by default, but setting the *allow-direct-logging* boolean +atom to false will disable it. If logging is invoked within a transaction it +will always use an agent. + +The log macros will not evaluate their 'message' unless the specific logging +level is in effect. Alternately, you can use the spy macro when you have code +that needs to be evaluated, and also want to output the code and its result to +the debug log. + +Unless otherwise specified, the current namespace (as identified by *ns*) will +be used as the log-ns (similar to how the java class name is usually used). +Note: your log configuration should display the name that was passed to the +logging implementation, and not perform stack-inspection, otherwise you'll see +something like "fn__72$impl_write_BANG__39__auto____81" in your logs. + +Use the enabled? macro to write conditional code against the logging level +(beyond simply whether or not to call log, which is handled automatically). + +You can redirect all java writes of System.out and System.err to the log +system by calling log-capture!. To rebind *out* and *err* to the log system +invoke with-logs. In both cases a log-ns (e.g., "com.example.captured") +needs to be specified to namespace the output.</pre> + + +<br /> +<h2>Public Variables and Functions</h2> +<div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/*allow-direct-logging*">*allow-direct-logging*</h2> + <span id="var-type">var</span><br /> + <pre id="var-usage"></pre> + <pre id="var-docstr">A boolean indicating whether direct logging (as opposed to via an agent) is +allowed when not operating from within a transaction. Defaults to true.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L202" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/*impl-name*">*impl-name*</h2> + <span id="var-type">var</span><br /> + <pre id="var-usage"></pre> + <pre id="var-docstr">The name of the logging implementation used.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L188" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/*logging-agent*">*logging-agent*</h2> + <span id="var-type">var</span><br /> + <pre id="var-usage"></pre> + <pre id="var-docstr">The default agent used for performing logging durng a transaction or when +direct logging is disabled.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L196" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/debug">debug</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (debug message) + (debug message throwable) +</pre> + <pre id="var-docstr">Logs a message at the debug level.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L310" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/enabled?">enabled?</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (enabled? level) + (enabled? level log-ns) +</pre> + <pre id="var-docstr">Returns true if the specific logging level is enabled. Use of this function +should only be necessary if one needs to execute alternate code paths beyond +whether the log should be written to.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L226" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/error">error</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (error message) + (error message throwable) +</pre> + <pre id="var-docstr">Logs a message at the error level.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L331" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/fatal">fatal</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (fatal message) + (fatal message throwable) +</pre> + <pre id="var-docstr">Logs a message at the fatal level.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L338" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/impl-enabled?">impl-enabled?</h2> + <span id="var-type">var</span><br /> + <pre id="var-usage"></pre> + <pre id="var-docstr">Implementation-specific check if a particular level is enabled. End-users +should not need to call this.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L188" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/impl-get-log">impl-get-log</h2> + <span id="var-type">var</span><br /> + <pre id="var-usage"></pre> + <pre id="var-docstr">Returns an implementation-specific log by string namespace. End-users should +not need to call this.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L188" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/impl-write!">impl-write!</h2> + <span id="var-type">var</span><br /> + <pre id="var-usage"></pre> + <pre id="var-docstr">Implementation-specific write of a log message. End-users should not need to +call this.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L188" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/info">info</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (info message) + (info message throwable) +</pre> + <pre id="var-docstr">Logs a message at the info level.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L317" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/log">log</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (log level message) + (log level message throwable) + (log level message throwable log-ns) +</pre> + <pre id="var-docstr">Logs a message, either directly or via an agent. Also see the level-specific +convenience macros.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L208" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/log-capture!">log-capture!</h2> + <span id="var-type">function</span><br /> + <pre id="var-usage">Usage: (log-capture! log-ns) +</pre> + <pre id="var-docstr">Captures System.out and System.err, redirecting all writes of those streams +to :info and :error logging, respectively. The specified log-ns value will +be used to namespace all redirected logging. NOTE: this will not redirect +output of *out* or *err*; for that, use with-logs.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L265" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/log-stream">log-stream</h2> + <span id="var-type">function</span><br /> + <pre id="var-usage">Usage: (log-stream level log-ns) +</pre> + <pre id="var-docstr">Creates a PrintStream that will output to the log. End-users should not need +to invoke this.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L243" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/log-uncapture!">log-uncapture!</h2> + <span id="var-type">function</span><br /> + <pre id="var-usage">Usage: (log-uncapture!) +</pre> + <pre id="var-docstr">Restores System.out and System.err to their original values.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L281" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/spy">spy</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (spy expr) +</pre> + <pre id="var-docstr">Evaluates expr and outputs the form and its result to the debug log; returns +the result of expr.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L236" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/trace">trace</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (trace message) + (trace message throwable) +</pre> + <pre id="var-docstr">Logs a message at the trace level.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L303" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/warn">warn</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (warn message) + (warn message throwable) +</pre> + <pre id="var-docstr">Logs a message at the warn level.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L324" id="var-source">Source</a> +</div><div id="var-entry"> + <br /> + <hr /> + <h2 id="clojure.contrib.logging/with-logs">with-logs</h2> + <span id="var-type">macro</span><br /> + <pre id="var-usage">Usage: (with-logs log-ns & body) +</pre> + <pre id="var-docstr">Evaluates exprs in a context in which *out* and *err* are bound to :info and +:error logging, respectively. The specified log-ns value will be used to +namespace all redirected logging.</pre> + + + <a href="http://github.com/richhickey/clojure-contrib/blob/7188a51605136f36524e4091fe806859114d6056/src/main/clojure/clojure/contrib/logging.clj#L291" id="var-source">Source</a> +</div> + + +</div> + </div> + </div> + </div> + </div> + <div id="foot"> + <div style="text-align: center;" id="copyright">Copyright 2007-2009 by Rich Hickey and the various contributors</div> + </div> + </div> + <div id="DesignedBy">Logo & site design by <a title="Visit Tom Hickey's website." href="http://www.tomhickey.com">Tom Hickey</a>.<br /> + Clojure auto-documentation system by Tom Faulhaber.</div> + </div> + <!-- /AllContentContainer --> + </body> + +</html>
\ No newline at end of file |