Added babel documentation for awk
authorThomas Dye <tsd@tsdye.com>
Sun, 7 Oct 2012 02:34:15 +0000 (16:34 -1000)
committerThomas Dye <tsd@tsdye.com>
Sun, 7 Oct 2012 02:34:15 +0000 (16:34 -1000)
org-contrib/babel/languages.org
org-contrib/babel/languages/ob-doc-awk.org [new file with mode: 0644]

index 65d4b69..3aab51e 100644 (file)
@@ -25,7 +25,7 @@ language documentation.
 | Language       | Identifier      | Documentation        | Requirements                                |
 |----------------+-----------------+----------------------+---------------------------------------------|
 | Asymptote      | asymptote       | [[file:languages/ob-doc-asymptote.org][ob-doc-asymptote]]     | [[http://asymptote.sourceforge.net/][asymptote]], [[http://asymptote.sourceforge.net/doc/Editing-modes.html][asy-mode]]                         |
-| Awk            | awk             |                      | Awk                                         |
+| Awk            | awk             | [[file:languages/ob-doc-awk.org][ob-doc-awk]]           | awk                                         |
 | C              | c               | [[file:languages/ob-doc-C.org][ob-doc-C]]             | none                                        |
 | C++            | cpp             | [[file:languages/ob-doc-C.org][ob-doc-C]]             | none                                        |
 | Calc           | calc            |                      | none                                        |
diff --git a/org-contrib/babel/languages/ob-doc-awk.org b/org-contrib/babel/languages/ob-doc-awk.org
new file mode 100644 (file)
index 0000000..ddcbf2e
--- /dev/null
@@ -0,0 +1,148 @@
+#+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
+#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
+#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
+#+TITLE:      AWK Source Code Blocks in Org Mode
+#+AUTHOR:     Thomas S. Dye
+#+EMAIL:      tsd[at]tsdye[dot]com
+#+LANGUAGE:   en
+#+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
+#+LINK_UP:    ../languages.html
+#+LINK_HOME:  http://orgmode.org/worg/
+#+EXPORT_EXCLUDE_TAGS: noexport
+
+#+name: banner
+#+begin_html
+  <div id="subtitle" style="float: center; text-align: center;">
+  <p>
+  Org Mode support for <a href="http://c2.com/cgi/wiki?AwkLanguage">AWK</a>
+  </p>
+  </div>
+#+end_html
+
+* Template Checklist [12/12]                                       :noexport:
+  - [X] Revise #+TITLE:
+  - [X] Indicate #+AUTHOR:
+  - [X] Add #+EMAIL:
+  - [X] Revise banner source block [3/3]
+    - [X] Add link to a useful language web site
+    - [X] Replace "Language" with language name
+    - [X] Find a suitable graphic and use it to link to the language
+      web site
+  - [X] Write an [[Introduction]]
+  - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
+  - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
+  - [X] Describe [[Header%20Arguments][Header Arguments]]
+  - [X] Describe support for [[Sessions]]
+  - [X] Describe [[Result%20Types][Result Types]]
+  - [X] Describe [[Other]] differences from supported languages
+  - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
+* Introduction
+=AWK= is a task-specific language optimized for regular expression
+record data manipulation.
+
+* Requirements and Setup
+There are many [[http://www.faqs.org/faqs/computer-lang/awk/faq/][well-maintained AWK compatible languages]].  The
+variable =org-babel-awk-command= holds the name of =AWK= executable.
+The default is "awk".
+
+To configure =AWK= source code blocks in Org mode, add the appropriate
+dotted pair to =org-babel-load-languages=
+
+#+begin_src emacs-lisp :exports code
+  (org-babel-do-load-languages
+   'org-babel-load-languages
+   '((awk . t)))
+#+end_src
+
+* Org Mode Features for AWK Source Code Blocks
+** Header Arguments
+There are three =AWK=-specific header arguments.
+   - =:cmd-line= :: takes command line arguments to pass to the =AWK= executable
+   - =:in-file= :: takes a path to a file of data to be processed by =AWK=
+   - =:stdin= :: takes an Org-mode data or code block reference, the
+                 value of which will be passed to the =AWK= process
+                 through STDIN
+** Sessions
+=AWK= does not support sessions.
+
+* Examples of Use
+
+Two examples from [[http://www.gnu.org/software/gawk/manual/gawk.html#Getting-Started][GNU Awk User's Guide]] show simple uses of =AWK=.
+
+Given the table =bbs-list=
+
+#+name: bbs-list
+| aardvark | 555-5553 | 1200/300      | B |
+| alpo-net | 555-3412 | 2400/1200/300 | A |
+| barfly   | 555-7685 | 1200/300      | A |
+| bites    | 555-1675 | 2400/1200/300 | A |
+| camelot  | 555-0542 | 300           | C |
+| core     | 555-2912 | 1200/300      | C |
+| fooey    | 555-1234 | 2400/1200/300 | B |
+| foot     | 555-6699 | 1200/300      | B |
+| macfoo   | 555-6480 | 1200/300      | A |
+| sdace    | 555-3430 | 2400/1200/300 | A |
+| sabafoo  | 555-2127 | 1200/300      | C |
+
+this =AWK= source code block
+#+begin_example
+,#+begin_src awk :stdin bbs-list
+/foo/ { print $0 }
+,#+end_src
+#+end_example
+
+returns a subset of the original table
+
+#+begin_src awk :stdin bbs-list :exports results
+/foo/ { print $0 }
+#+end_src
+
+#+results:
+| fooey   | 555-1234 | 2400/1200/300 | B |
+| foot    | 555-6699 | 1200/300      | B |
+| macfoo  | 555-6480 | 1200/300      | A |
+| sabafoo | 555-2127 | 1200/300      | C |
+
+
+Given the table =inventory-shipped=
+
+#+name: inventory-shipped
+| Jan | 13 | 25 | 15 | 115 |
+| Feb | 15 | 32 | 24 | 226 |
+| Mar | 15 | 24 | 34 | 228 |
+| Apr | 31 | 52 | 63 | 420 |
+| May | 16 | 34 | 29 | 208 |
+| Jun | 31 | 42 | 75 | 492 |
+| Jul | 24 | 34 | 67 | 436 |
+| Aug | 15 | 34 | 47 | 316 |
+| Sep | 13 | 55 | 37 | 277 |
+| Oct | 29 | 54 | 68 | 525 |
+| Nov | 20 | 87 | 82 | 577 |
+| Dec | 17 | 35 | 61 | 401 |
+|     |    |    |    |     |
+| Jan | 21 | 36 | 64 | 620 |
+| Feb | 26 | 58 | 80 | 652 |
+| Mar | 24 | 75 | 70 | 495 |
+| Apr | 21 | 70 | 74 | 514 |
+
+this bit of =AWK= code 
+
+#+begin_example
+,#+begin_src awk :stdin inventory-shipped :exports results
+$1 ~ /J/
+,#+end_src
+#+end_example
+
+returns this subset of the table
+
+#+begin_src awk :stdin inventory-shipped :exports results
+$1 ~ /J/
+#+end_src
+
+#+results:
+| Jan | 13 | 25 | 15 | 115 |
+| Jun | 31 | 42 | 75 | 492 |
+| Jul | 24 | 34 | 67 | 436 |
+| Jan | 21 | 36 | 64 | 620 |
+