external/lift.darcs/website/source/overview.md

   1 {include header.md}
   2 {set-property title Log5 - overview}
   3
   4 ### Overview
   5
   6 the bird's eye view looks like this: You define *categories* for your application. These might look like
   7
   8     (defcategory motion)
   9
  10     (defcategory energy)
  11
  12     (defcategory physics (or energy motion))
  13
  14     (defcategory planner)
  15
  16 and so forth. Categories are sort of like Lisp `*features*` with names. They can be simple (like `motion`) or boolean combinations (like `physics`). When you write a typical log *message*, you use a combination of categories to describe it:
  17
  18     (log-for (and physics (not file-system) trace)
  19              "starting widget simulation")
  20
  21 or
  22
  23     (log-for (or planner motion) "Planning path for agent ~a" (name agent))
  24
  25 You start a *sender* using `start-sender` (surprise!). You specify what kind of sender it is (e.g., a stream sender or a database sender or an HTML sender or whatever) and pass along whatever arguments are needed to create it. You also specify the categories and the *outputs* the sender will send. Categories were discussed above; a sender's outputs are a list of named properties defined with defoutput. For example:
  26
  27     (defoutput time (get-universal-time))
  28
  29     (defoutput virtual-memory (os-get-virtual-memory))
  30
  31     (defoutput current-database (name *db*)))
  32
  33 Outputs can compute anything that makes sense for your program (though they ought to compute it quickly if you don't want logging to kill performance!). Some outputs are special and predefined. For example, the output `message` refers to the string created by the log message statement (e.g., the `log-for` examples above). The output `context` refers to the current *context* (the last of our five players).
  34
  35 The context is a carry-all you can use to specify whatever important is happening in the global environment. If you're writing a web-application; the context might track the current session ID; A planner might track the current agent and so forth. Information from the context is added to the end of each log message sent and so functions as a variable portion in contrast to the fixed structure of the sender's output.
  36
  37 {include footer.md}