org-contrib/babel/languages/ob-doc-awk.org

   1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
   5 #+TITLE:      AWK Source Code Blocks in Org Mode
   6 #+AUTHOR:     Thomas S. Dye
   7 #+EMAIL:      tsd[at]tsdye[dot]com
   8 #+LANGUAGE:   en
   9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
  10 #+LINK_UP:    ../languages.html
  11 #+LINK_HOME:  http://orgmode.org/worg/
  12 #+EXPORT_EXCLUDE_TAGS: noexport
  13
  14 #+name: banner
  15 #+begin_html
  16   <div id="subtitle" style="float: center; text-align: center;">
  17   <p>
  18   Org Mode support for <a href="http://c2.com/cgi/wiki?AwkLanguage">AWK</a>
  19   </p>
  20   </div>
  21 #+end_html
  22
  23 * Template Checklist [12/12]                                       :noexport:
  24   - [X] Revise #+TITLE:
  25   - [X] Indicate #+AUTHOR:
  26   - [X] Add #+EMAIL:
  27   - [X] Revise banner source block [3/3]
  28     - [X] Add link to a useful language web site
  29     - [X] Replace "Language" with language name
  30     - [X] Find a suitable graphic and use it to link to the language
  31       web site
  32   - [X] Write an [[Introduction]]
  33   - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
  34   - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
  35   - [X] Describe [[Header%20Arguments][Header Arguments]]
  36   - [X] Describe support for [[Sessions]]
  37   - [X] Describe [[Result%20Types][Result Types]]
  38   - [X] Describe [[Other]] differences from supported languages
  39   - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
  40 * Introduction
  41 =AWK= is a task-specific language optimized for regular expression
  42 record data manipulation. It is a little language that is Turing
  43 complete, efficient to execute, reasonably simple to express, powerful
  44 within its scope, and pathologically cryptic.
  45
  46 A natural Org mode representation of the record data =AWK= was
  47 designed to manipulate is the table.
  48
  49 * Requirements and Setup
  50 There are many [[http://www.faqs.org/faqs/computer-lang/awk/faq/][well-maintained AWK compatible languages]].  The
  51 variable =org-babel-awk-command= holds the name of =AWK= executable.
  52 The default is "awk".
  53
  54 To configure =AWK= source code blocks in Org mode, add the appropriate
  55 dotted pair to =org-babel-load-languages=
  56
  57 #+begin_src emacs-lisp :exports code
  58   (org-babel-do-load-languages
  59    'org-babel-load-languages
  60    '((awk . t)))
  61 #+end_src
  62
  63 * Org Mode Features for AWK Source Code Blocks
  64 ** Header Arguments
  65 There are three =AWK=-specific header arguments.
  66    - =:cmd-line= :: takes command line arguments to pass to the =AWK= executable
  67    - =:in-file= :: takes a path to a file of data to be processed by =AWK=
  68    - =:stdin= :: takes an Org-mode data or code block reference, the
  69                  value of which will be passed to the =AWK= process
  70                  through STDIN
  71 ** Sessions
  72 =AWK= does not support sessions.
  73
  74 * Examples of Use
  75
  76 Two examples from [[http://www.gnu.org/software/gawk/manual/gawk.html#Getting-Started][GNU Awk User's Guide]] show simple uses of =AWK=.
  77
  78 Given the table =bbs-list=
  79
  80 #+name: bbs-list
  81 | aardvark | 555-5553 | 1200/300      | B |
  82 | alpo-net | 555-3412 | 2400/1200/300 | A |
  83 | barfly   | 555-7685 | 1200/300      | A |
  84 | bites    | 555-1675 | 2400/1200/300 | A |
  85 | camelot  | 555-0542 | 300           | C |
  86 | core     | 555-2912 | 1200/300      | C |
  87 | fooey    | 555-1234 | 2400/1200/300 | B |
  88 | foot     | 555-6699 | 1200/300      | B |
  89 | macfoo   | 555-6480 | 1200/300      | A |
  90 | sdace    | 555-3430 | 2400/1200/300 | A |
  91 | sabafoo  | 555-2127 | 1200/300      | C |
  92
  93 this =AWK= source code block
  94 #+begin_example
  95 ,#+begin_src awk :stdin bbs-list
  96 /foo/ { print $0 }
  97 ,#+end_src
  98 #+end_example
  99
 100 returns a subset of the original table
 101
 102 #+begin_src awk :stdin bbs-list :exports results
 103 /foo/ { print $0 }
 104 #+end_src
 105
 106 #+results:
 107 | fooey   | 555-1234 | 2400/1200/300 | B |
 108 | foot    | 555-6699 | 1200/300      | B |
 109 | macfoo  | 555-6480 | 1200/300      | A |
 110 | sabafoo | 555-2127 | 1200/300      | C |
 111
 112
 113 Given the table =inventory-shipped=
 114
 115 #+name: inventory-shipped
 116 | Jan | 13 | 25 | 15 | 115 |
 117 | Feb | 15 | 32 | 24 | 226 |
 118 | Mar | 15 | 24 | 34 | 228 |
 119 | Apr | 31 | 52 | 63 | 420 |
 120 | May | 16 | 34 | 29 | 208 |
 121 | Jun | 31 | 42 | 75 | 492 |
 122 | Jul | 24 | 34 | 67 | 436 |
 123 | Aug | 15 | 34 | 47 | 316 |
 124 | Sep | 13 | 55 | 37 | 277 |
 125 | Oct | 29 | 54 | 68 | 525 |
 126 | Nov | 20 | 87 | 82 | 577 |
 127 | Dec | 17 | 35 | 61 | 401 |
 128 |     |    |    |    |     |
 129 | Jan | 21 | 36 | 64 | 620 |
 130 | Feb | 26 | 58 | 80 | 652 |
 131 | Mar | 24 | 75 | 70 | 495 |
 132 | Apr | 21 | 70 | 74 | 514 |
 133
 134 this bit of =AWK= code
 135
 136 #+begin_example
 137 ,#+begin_src awk :stdin inventory-shipped :exports results
 138 $1 ~ /J/
 139 ,#+end_src
 140 #+end_example
 141
 142 returns this subset of the table
 143
 144 #+begin_src awk :stdin inventory-shipped :exports results
 145 $1 ~ /J/
 146 #+end_src
 147
 148 #+results:
 149 | Jan | 13 | 25 | 15 | 115 |
 150 | Jun | 31 | 42 | 75 | 492 |
 151 | Jul | 24 | 34 | 67 | 436 |
 152 | Jan | 21 | 36 | 64 | 620 |
 153