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 [[http://orgmode.org/worg/sources/org-contrib/org-collector-example.org][example file]], which contains the
  24 following headlines/properties.
  25
  26 [[file:../images/org-collector/dec-spending.png]]
  27
  28 This property information can then be collected into tables.
  29
  30 *** Simple Example
  31
  32 Lets look at the following org-collector block.
  33
  34 : #+BEGIN: propview :id "december" :conds ((string= spendtype "food")) :cols (ITEM amount)
  35 : #+END:
  36
  37 To evaluate this block press =\C-c\C-c= with your cursor on the
  38 =#+BEGIN= line of the block.  Evaluation will result in the following
  39
  40 : #+BEGIN: propview :id "december" :conds ((string= spendtype "food")) :cols (ITEM amount)
  41 : | "ITEM"                           | "amount" |
  42 : |----------------------------------+----------|
  43 : | "Grocery Store [2008-12-01 Mon]" |    56.77 |
  44 : | "Restaurant [2008-12-08 Mon]"    |    30.67 |
  45 : |----------------------------------+----------|
  46 : |                                  |          |
  47 : #+END:
  48
  49 Lets look at the arguments one by one.
  50
  51 - :id "december" ::
  52   The =:id= argument has the effect of limiting the search to headers
  53   under the header with the id of "december".
  54 - :conds ((string= spendtype "food")) ::
  55   The =:conds= argument accepts a list of e-lisp expressions.  Only
  56   headlines which match all of these expressions will be displayed in
  57   the table.  The names of properties of a headline can be used as
  58   variables in the expressions.  This particular expression only
  59   returns true when the =spendtype= property of a headline is equal to "food".
  60 - :cols (ITEM amount) ::
  61   The =:cols= property controls what each row of the table should look
  62   like.  In this case we are showing =ITEM= which shows the actual
  63   text of the headline as well as =amount= which show the value of the
  64   =amount= property of each headline.
  65
  66
  67
  68 *** More Complex Example
  69
  70 This example demonstrates a couple of new headline arguments for
  71 =org-collector=.
  72
  73 : #+BEGIN: propview :cols (ITEM (+ 400 amount)) :scope tree :match "example"
  74 : | "ITEM"                                                                          | "(+ 400 amount)" |
  75 : |---------------------------------------------------------------------------------+------------------|
  76 : | "December Spending                                                   :example:" |                0 |
  77 : | "Week One"                                                                      |                0 |
  78 : | "Grocery Store [2008-12-01 Mon]"                                                |           456.77 |
  79 : | "Athletic club [2008-12-02 Tue]"                                                |            475.0 |
  80 : | "Week Two "                                                                     |                0 |
  81 : | "Restaurant [2008-12-08 Mon]"                                                   |           430.67 |
  82 : |---------------------------------------------------------------------------------+------------------|
  83 : |                                                                                 |                  |
  84 : #+END:
  85
  86 - :cols (ITEM (+ 400 amount)) ::
  87   Notice that the =:cols= list in this example contains an elisp
  88   expression for one of the column values.  It is possible to run
  89   arbitrary elisp over the header properties the results of which will
  90   be used when building the resulting table.
  91 - :scope "tree" :match "example" ::
  92   The =:scope tree= and =:match= header arguments limits the included
  93   headlines to those which have a tag matching "example" or their
  94   descendents.
  95
  96
  97 ** Loading it (No surprises here)
  98
  99 The easiest way is by
 100
 101 : M-x customize-variables RET 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 * Credits
 117
 118 =org-collector= was developed by Eric Schulte with much-appreciated help
 119 from Carsten Dominik.