This web site is a front end to a
repository
of Awk code.
The site, and the code, is maintained
by the international awk community (which includes you)
so there are many ways you can contribute:
Test the page by placing it on a publicly readable site, then see if it renders ok.
Email the url of that page to mail@awk.info. Do NOT send the page.
When writing a page, please follow these guidelines:
Do not use <hr> tags: these are reserved for dividing pages in a multi-page view.
Use only one <h1> tag at the top of page. Everything else should
<h2> or below.
Try to avoid using tricky CSS/HTML styling tricks. Vanilla HMTL is best.
The page you write will end up being rendered as the
middle pane of this site (around 550 pixels wide). So don't
write wide pages.
If you include code samples, note that our CSS wraps pre-formatted
code if it gets too wide. For example, at the time
of this writing, the following pre-formatted texts
gets ugly after about 75 characters:
In the language of this site, a function file is a 100% standalone file containing one or more
functions with no dependancies on other files.
Note that if your function file depends on other files, then it becomes a package (see below).
Functions are stored in a file caled myfunc.awk.
Add a Package
In the language of this site, a package is a file that depends on other files
(and the other files may depend on yet others, recursively).
Following a recent discussion in comp.lang.awk, we say that these dependancies are commented with
#use file.awk
where file.awk is some
file (e.g. a file in the current directory).
Note that :
file.awk will be loaded before the file containing the reference to #use file.awk.
Once you've got it "looking pretty", please consider contributing that code to awk.info,
so our code library can grow. To do so, either email mail@awk.info
with the URL of your pretty code or zip up the files and email them across.
HTML-based Commenting Conventions
The first paragraph of the file will be ignored. Use this first para
for copyright notices or comments about down-in-the weeds trivia. Note: the
first para ends with one blank line.
The next paragraph should start with
#.H1 <join>Title</join>
The code could should be topped and tailed as follows:
#<pre>
code
#</pre>
All other comment lines should start with a single "#" at front-of-line.
These comment characters will be stripped away by the awk.info renderer.
Awk.info's renderer adopts the following html shorthand. If a line starts with
#.WORD other words
this this is replaced with
<WORD> other words</WORD>
If no other words follow #.WORD then the line becomes just <WORD>
Awk.info's renderer supports a few HTML extensions:
#.IN path includes a file found in the LAWKER repositoriy at some path inside the trunk.
#.CODE path includes the contents
of path, wrapped in <pre> tags, and prefixed by the path.
#.BODY path is the same as #.CODE but it
skips the first paragraph (this is useful when the first paragraph includes tedious details
you want to hite from the user).
Note that, for #.IN, #.CODE, #.BODY, the path must appear after a single space.
That's it. Now you can pretty print your code on the web just be adding
a little html in the comments.
Or a regression suite that checks that new changes does not mess up existing code.
Accordingly code offered to this site can contain unit tests, using the methods
described in this page.
But before going on, we stress that
awk.info gratefully accepts
awk contributions in any form. That is, including unit tests with code is optional.
Files
If your code is in directory yourcode then create a sub-directory yourcode/eg
Write a test in a file yourcode/eg/yourtest. Divide that test into two parts:
In the first paragraph of that file, write any tedious set up required to get the system ready for the test.
In the second, third, etc paragraph, write the code that shows the test
For example, in the following code, the real test comes after some low-level environmental set up:
# assumes
# - the LAWKER trunk has been checked out and
# - .bash_profile contains: export Lawker="$HOME/svns/lawker/fridge"
. $Lawker/lib/bash/setup
gawk -f join.awk --source '
BEGIN { split("tim tom tam",a)
print join(a,2)
}'
Write the expected output of that test case in yourcode/eg/yourtest.out
Regression Tests
The above file conventions mean that an automatic tool can run over the entire code base and perform a regression test (checking if all the tests generate
all the *.out files.
Displaying the Tests (and Output)
Another advantage of the above scheme is that you can use the tests to document your code.
To show the test case, add the following into your .awk file:
Then zip the directory yourcode (including yourcode/eg) and send it to awk.info. Once
we install those files on our site then
when awk.info displays that file, the test case trivia is hidden and the users only see the essential details.
For an example of this, see http://awk.info/?gawk/array/join.awk.
