* Introduction

  This file (org-babel-table-proc.org) contains the documentation and living examples for
  org-babel-table-proc.el, which is a libary of functions, which in turn makes it easier
  to process tables with babel, which is part of orgmode.

  The functions within this library take two tables and apply simple filter or set
  operations on them. The first column within each table plays the role of a key, which
  determines how the table-lines is treated; the remaining columns are payload.

* Installation

  To install the library org-babel-table-proc.el within emacs you need to do two things:

  First: Move the file into any directory within your emacs load-path
  (see [[id:b3ec5718-8a32-4b1e-8203-f620aa819d82][Finding out, what your load-path is]] for details)

  Second: Put the following line

  (require 'org-babel-table-proc)

  into your emacs-startup file (".emacs" in most cases). For now, it is even
  enough to execute the following source-code-block (see [[id:170aa925-e8e1-4937-9ed7-c889b83e8419][Executing code blocks]])

#+begin_src emacs-lisp
  (require 'org-babel-table-proc)
#+end_src

* Some input tables, that are used within the examples

  For the examples in the rest of this document, we will use two input tables: "lower" and
  "upper" (see below). Each of these tables associates a position within the alphabet with
  a letter (either lower or upper case).
  
  For example the table line "| 2 | b |" below simply expresses the fact, that the letter "b"
  comes at position 2 within the alphabet.

#+name: lower
| 2 | b |
| 4 | d |
| 5 | e |
| 6 | h |

#+name: upper
|  1 | A |
|  3 | C |
|  4 | D |
| 10 | J |
|  2 | B |

  Please note further, that those tables have names
  (given by the line "#+name: lower").

  A third table, named "keys", has only one column, which will be used as keys to select rows from
  the other tables.

#+name: keys
| 1 |
| 2 |
| 4 |

* Set operations

#+begin_src emacs-lisp :var t1=lower :var t2=upper
   (babel-table-proc-merge t1 t2)
#+end_src

#+results:
|  1 |   | A |
|  2 | b | B |
|  3 |   | C |
|  4 | d | D |
|  5 | e |   |
|  6 | h |   |
| 10 |   | J |


#+begin_src emacs-lisp :var t1=keys :var t2=upper
   (babel-table-proc-remove t1 t2)
#+end_src

#+results:
|  3 | C |
| 10 | J |




* Appendices
** Executing code blocks
   :PROPERTIES:
   :ID:       170aa925-e8e1-4937-9ed7-c889b83e8419
   :END:

   Throughout this document you will be urged to execute code blocks.

   This refers to orgmode's feature of beeing able to run code that
   is embedded within the document; such code blocks begin with 
   a line "#+begin_src" and end with "#+end_src".

   Throughout this document you will find many such code blocks, just see
   below for an example.

   For a complete description of the many great things, that can be done
   with such code blocks, please refer to the orgmode manual, chapter 14
   ("Working with source code").

   For the moment however, it is enough to know, how to execute those
   blocks: Just move the cursor to the line below (the one starting with
   "#+begin_src") and press C-c C-c (this means: Hold down the control-key
   an press the key "c" twice).

#+begin_src emacs-lisp
   (current-time-string)
#+end_src

   The result of executing this block of code can be seen above, following
   the line starting with "#+results:". It is simply the current time.

   If you execute this code block again, the old result is overwritten with a new
   timestamp. If you want to remove the whole result to restore the "clean" state of this
   buffer, please check out [[id:224b0c4a-6b2c-495c-afc1-8a52c9dea778][Cleaning up results]].

   For the purpose of this document, you do not need to know much more about executing
   code blocks and you may read on.
   
** Finding out, what your load-path is
   :PROPERTIES:
   :ID:       b3ec5718-8a32-4b1e-8203-f620aa819d82
   :END:

#+begin_src emacs-lisp
   (mapcar 'list load-path)
#+end_src

** Cleaning up results
   :PROPERTIES:
   :ID:       224b0c4a-6b2c-495c-afc1-8a52c9dea778
   :END:

   Execute the code block below (see [[id:170aa925-e8e1-4937-9ed7-c889b83e8419][Executing code blocks]]) to clear any
   results that have been generated previously from executing other code
   blocks within this document.

   However, as each execution of a code block overwrites any results of
   previous executions, there is no real need to clean up anything.
   If at all, than only to tidy up the file, before passing it along.

#+begin_src emacs-lisp
(save-excursion
(beginning-of-buffer)
     (while (re-search-forward "^#\\+results:\n\\(^\|\\|:.*\n\\)*\n" nil t)
       (replace-match ""))
)
#+end_src

#+results:

   Note, that the only remaining result (introduced by the line "#+results:") ist the one
   immediately above.