org-contrib/org-collector.org

   1 #+TITLE:     org-collector.el --- collect properties into tables
   2 #+OPTIONS:    H:3 num:nil toc:3 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   3 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   4 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   5 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   6 #+AUTHOR:     Eric Schulte
   7 #+EMAIL:      schulte.eric at gmail dot com
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg
  11
  12 * General
  13
  14 =org-collector= collects headline properties into tables with optional
  15 pre-processing.
  16
  17
  18 * How to use it
  19
  20 ** Quick Examples
  21
  22 As a quick demonstration of use of =org-collector= first [[* Loading it][load it]] as
  23 described below.  Then download this @<a
  24 href="http://orgmode.org/worg/sources/org-contrib/org-collector-example.org">example
  25 file@</a>, which contains the following headlines/properties.
  26
  27 [[file:../images/org-collector/dec-spending.png]]
  28
  29 This property information can then be collected into tables.
  30
  31 *** Simple Example
  32
  33 Lets look at the following org-collector block.
  34
  35 : #+BEGIN: propview :id "december" :conds ((string= spendtype "food")) :cols (ITEM amount)
  36 : #+END:
  37
  38 To evaluate this block press =\C-c\C-c= with your cursor on the
  39 =#+BEGIN= line of the block.  Evaluation will result in the following
  40
  41 : #+BEGIN: propview :id "december" :conds ((string= spendtype "food")) :cols (ITEM amount)
  42 : | "ITEM"                           | "amount" |
  43 : |----------------------------------+----------|
  44 : | "Grocery Store [2008-12-01 Mon]" |    56.77 |
  45 : | "Restaurant [2008-12-08 Mon]"    |    30.67 |
  46 : |----------------------------------+----------|
  47 : |                                  |          |
  48 : #+END:
  49
  50 Lets look at the arguments one by one.
  51
  52 - :id "december" ::
  53   The =:id= argument has the effect of limiting the search to headers
  54   under the header with the id of "december".
  55 - :conds ((string= spendtype "food")) ::
  56   The =:conds= argument accepts a list of e-lisp expressions.  Only
  57   headlines which match all of these expressions will be displayed in
  58   the table.  The names of properties of a headline can be used as
  59   variables in the expressions.  This particular expression only
  60   returns true when the =spendtype= property of a headline is equal to "food".
  61 - :cols (ITEM amount) ::
  62   The =:cols= property controls what each row of the table should look
  63   like.  In this case we are showing =ITEM= which shows the actual
  64   text of the headline as well as =amount= which show the value of the
  65   =amount= property of each headline.
  66
  67
  68
  69 *** More Complex Example
  70
  71 This example demonstrates a couple of new headline arguments for
  72 =org-collector=.
  73
  74 : #+BEGIN: propview :cols (ITEM (+ 400 amount)) :scope tree :match "example"
  75 : | "ITEM"                                                                          | "(+ 400 amount)" |
  76 : |---------------------------------------------------------------------------------+------------------|
  77 : | "December Spending                                                   :example:" |                0 |
  78 : | "Week One"                                                                      |                0 |
  79 : | "Grocery Store [2008-12-01 Mon]"                                                |           456.77 |
  80 : | "Athletic club [2008-12-02 Tue]"                                                |            475.0 |
  81 : | "Week Two "                                                                     |                0 |
  82 : | "Restaurant [2008-12-08 Mon]"                                                   |           430.67 |
  83 : |---------------------------------------------------------------------------------+------------------|
  84 : |                                                                                 |                  |
  85 : #+END:
  86
  87 - :cols (ITEM (+ 400 amount)) ::
  88   Notice that the =:cols= list in this example contains an elisp
  89   expression for one of the column values.  It is possible to run
  90   arbitrary elisp over the header properties the results of which will
  91   be used when building the resulting table.
  92 - :scope "tree" :match "example" ::
  93   The =:scope tree= and =:match= header arguments limits the included
  94   headlines to those which have a tag matching "example" or their
  95   descendents.
  96
  97
  98 ** Loading it (No surprises here)
  99 The easiest way is by
 100
 101         M-x customize-apropos org-modules
 102
 103 Check the line for collector.  This will cause it to be loaded every
 104 time you start org-mode.
 105
 106 You'll still have to load it manually the first time.
 107
 108 Of course, you can also just try it out by loading it manually.
 109
 110 If you prefer to manually customize your emacs then make sure that the
 111 path to org's contrib directory is in your load-path and add the
 112 following to your =.emacs=.
 113
 114 : (require 'org-collector)
 115
 116
 117 * Credits
 118
 119 =org-collector= was developed by Eric Schulte with much-appreciated
 120 help from Carsten Dominik.