[Chicken-users] Chicken Gazette - Issue 9

[Jim Ursetto]

     _/_/_/  _/        _/            _/                             /
  _/        _/_/_/          _/_/_/  _/  _/      _/_/    _/_/_/     /
 _/        _/    _/  _/  _/        _/_/      _/_/_/_/  _/    _/   /
_/        _/    _/  _/  _/        _/  _/    _/        _/    _/   /
 _/_/_/  _/    _/  _/    _/_/_/  _/    _/    _/_/_/  _/    _/   .

--[ Issue 9 ]-------------------------------------- G A Z E T T E
                               brought to you by the Chicken Team


== 0. Introduction

Welcome to issue 9 of the Chicken Gazette, brought to you by the
letter `k` and the procedure `call/cc`.

== 1. The Hatching Farm

First off, this week's egg news.

  * http-session (http://wiki.call-cc.org/egg/http-session): fix a
    bug in session ID generation for long-lived processes, due to a
    timer overflow in `current-milliseconds`;
  * estraier (http://wiki.call-cc.org/egg/estraier-client):
    performance improvement and regex dependency dropped;
  * wiki-parse (http://wiki.call-cc.org/egg/wiki-parse): deleted,
    as it was unused and had diverged too far from upstream to be
    maintained;
  * chickadee (http://wiki.call-cc.org/egg/chickadee): added a
    wrapper program which simplifies installing and running a server;
  * shell (http://wiki.call-cc.org/egg/shell): a thin wrapper around
    a turtle;
  * salmonella (http://wiki.call-cc.org/egg/salmonella): now checks
    that eggs are documented and executes egg tests; also something
    you can find on a turtle

To take advantage of the new salmonella egg testing, a proper exit
code was added to `tests/run.scm` in many eggs, reflecting whether a
test failure occurred.

Additionally, explicit dependencies on the new `regex` egg were added
to yet more eggs for compatibility with 4.6.2 and later.

And now a public service announcement. Egg authors, now hear this.
When your egg installs both library files via `install-extension` and
also an executable via `install-program`, you need to use different
IDs for each. By convention, the library files should use the name
of the egg (such as `chicken-doc`) and the executable should use this
same name with something appended, such as `chicken-doc-cmd`. This
prevents the uninstaller from losing track of files. Specifically,
the .setup-info files created by `chicken-install` to track extension
metadata will clobber each other if the IDs are identical.

== 2. Yolklore

Chicken core development was relatively active this week. Dare I say
excitingly so? Yes, I dare it.

Peter Bex committed a patch to the irregex-bugfixes branch that fixes
ticket 411 (https://bugs.call-cc.org/ticket/411), correcting an issue
introduced in 4.6.2.  It makes submatch accessors return `#f` instead
of throwing an error when the submatch is in range but non-matching.
For example, this no longer errors out:

  (string-search-positions "(foo)|(bar)|(baz)" "bar")
  ;=> ((0 3) (#f #f) (0 3) (#f #f))

The new blob literal syntax mentioned in the last issue was changed
from #{HEX ...} to #${HEX ...} after concerns were voiced about the
loss of valuable ASCII real-estate. The use of $ to mean hex is of
course well-known to assembly-language programmers of a certain age.

`integer64` and `unsigned-integer64` are now supported as FFI
return values, including in `let-location`, fixing ticket 413
(https://bugs.call-cc.org/ticket/413).

When fed a non-link argument, `read-symbolic-link` in `Unit posix`
now returns that argument when told to resolve symlinks recursively.
Previously it threw an error.

`delete-directory` in `Unit posix` now accepts an optional argument
telling it to delete recursively.

Optional per-slot SRFI-17 setters have been added to `define-record`.

And there were a few `types.db` fixes, as occur from time to time.
`types.db` is a database of procedure signatures for the core, and
is used by the scrutinizer to check procedure argument types at
compile-time.

== 3. Chicken Talk

In which I summarize our last week of mail.

Enwin Thun wrote in
(http://www.mail-archive.com/address@hidden/msg12297.html)
with a problem installing eggs after upgrading to Ubuntu Maverick.
The cause is that the Chicken infrastructure migrated to new
servers between 4.5.0 and 4.6.0, but Maverick is still on 4.5.0
which points to the old servers. The solution is to provide the
`-l` option to `chicken-install` to override the remote repository
location or, preferably, to change its configuration file.
The changes are detailed at the infrastructure migration page
(http://wiki.call-cc.org/infrastructure-migration).

Discussion is ongoing about the proper procedure to install datafiles
(http://www.mail-archive.com/address@hidden/msg12208.html)
for eggs, as well as the proper place for compliance with the
Filesystem Hierarchy Standard and BSD's hier(7).  The only eggs known
to the author to be affected are slatex, chicken-doc, and chickadee,
but egg authors are advised to keep an eye on this breaking issue.

On a related note, Kon Lovett recommended using setup-api's
create-directory/parents instead of posix's create-directory when
making new directories in `.setup` scripts, because the former
respects `chicken-install -s` (the s is for sudo). That was news to me
(http://www.mail-archive.com/address@hidden/msg12321.html).

Alan Post asked how to access mmapped memory as a string
(http://www.mail-archive.com/address@hidden/msg12313.html)
and, having received a couple ideas from your illustrious
developers, graciously wrote them up on the wiki
(http://wiki.call-cc.org/manual/Unit%20posix#memory-mapped-io-example).

Felix informed us that a "wish-list" page has been added to the wiki
(http://wiki.call-cc.org/wish-list) as a place where users can
describe their most earnest desires and fever-dreams. About Chicken.

Finally, Mario Goulart let us know that the `salmonella` egg tester
has been updated to check if eggs are documented and to run egg
tests. Authors are urged to update their test scripts for salmonella
compliance; see Mario's mail for details
(http://www.mail-archive.com/address@hidden/msg12334.html).

== 4. Omelette Recipes

My momma always said "write what you know," so today you'll be
learning about `chicken-doc`.

`chicken-doc` is, perhaps surprisingly, a documentation system for
Chicken. Its primary goal is to provide access to documentation from
the command-line and REPL.

Now, Chicken doesn't provide introspection in the form of docstrings,
nor are docs installed alongside the eggs. Instead, the core and
eggs are thoroughly documented on the wiki so that everyone can
contribute. So, chicken-doc's approach is to process a copy of the
wiki documentation and make it available to you offline via a nice
interface. And, since you have access to all documentation at once
-- instead of just the eggs you have installed -- you can quickly
explore everything the community has to offer.

==== Install

First, install chicken-doc.

  $ chicken-install -s chicken-doc

The nicest way to work with chicken-doc is to check out a copy of
the wiki from Subversion, then use chicken-doc-admin to prepare it
for use. But the quickest way to get started is to download today's
pre-baked chicken-doc repository, a 1.4MB gzipped tarball:

  $ cd `csi -p '(chicken-home)'` &&
    curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz |
    sudo tar zx

The repository goes inside your Chicken install directory and you may
need sudo to write to it. Alternatively, you could put the repository
anywhere you want like this:

  export CHICKEN_DOC_REPOSITORY=/path/to/my/cdoc/repo/dir

==== The command-line

Now you can ask for docs on any identifier:

  $ chicken-doc +
  path: (scheme +)

  -- procedure: (+ z[1] ...)
  -- procedure: (* z[1] ...)

  These procedures return the sum or product of their arguments.

You can ask for docs on any documented egg or unit:

  $ chicken-doc atom
  path: (atom)

  == atom

  Read and write Atom 1.0 feeds.
  [... rest of doc elided ...]

The identifier you ask for might be duplicately named:

  $ chicken-doc file-open
  Found 2 matches:
  (9p file-open)     (file-open connection path mode)
  (posix file-open)  (file-open FILENAME FLAGS [MODE])

in which case you can disambiguate it:

  $ chicken-doc posix file-open

  -- procedure: (file-open FILENAME FLAGS [MODE])

  Opens the file specified with the string `FILENAME` and open-flags
  `FLAGS` using the C function `open(2)`. On success a file-descriptor
  for the opened file is returned.

You can ask for the contents of any egg or unit (a list of
identifiers):

  $ chicken-doc -c posix
  _exit                        (_exit [CODE])
  block-device?                (block-device? FILE)
  change-directory             (change-directory NAME)
  [...]

And you can do a regular-expression match across the entire
identifier space:

  $ chicken-doc -m call-
  (scheme call-with-output-file)   (call-with-output-file string proc)
  (ports call-with-output-string)  (call-with-output-string PROC)
  (sql-de-lite call-with-database) (call-with-database filename proc)
  (library get-call-chain)         (get-call-chain [START [THREAD]])
  [...]

  $ chicken-doc -m o.O
  (glut glut:PostWindowOverlayRedisplay)
                        (glut:PostWindowOverlayRedisplay INTEGER)

==== The REPL

Just `(use chicken-doc)` from the REPL, and you gain three toplevel
commands: `,doc`, `,toc`, and `,wtf`.

`,doc` shows docs on its argument, like calling chicken-doc with no
options:

  #;> ,doc +
  path: (scheme +)
  -- procedure: (+ z[1] ...)
  #;> ,doc file-open
  Found 2 matches:
  (9p file-open)     (file-open connection path mode)
  (posix file-open)  (file-open FILENAME FLAGS [MODE])
  #;> ,doc (posix file-open)      ;; use parentheses to disambiguate

`,toc` shows egg or unit contents, like `chicken-doc -c`:

  #;> ,toc posix
  _exit                        (_exit [CODE])
  block-device?                (block-device? FILE)
  change-directory             (change-directory NAME)

`,wtf` ("where to find") matches identifiers, like `chicken-doc -m`:

  #;> ,wtf call-
  (scheme call-with-output-file)   (call-with-output-file string proc)
  (ports call-with-output-string)  (call-with-output-string PROC)
  [...]

Emacs integration is possible as well, and is covered in the egg
documentation.

==== chickadee

chickadee (http://3e8.org/chickadee/chickadee) is a web-based
interface to chicken-doc. That sounds rather roundabout, doesn't it?
Why not just use the wiki? Why not, indeed. Well, chickadee has some
features you might find useful:

  * fast, incremental identifier search
  * convenient contents sidebar
  * easy installation and use offline
  * documentation server for your own projects
  * a local preview of wiki doc changes
  * a sort of lisp-machine chic

You can use the primary chickadee server at http://3e8.org/chickadee,
or you can run your own copy after setting up a chicken-doc
repository:

  $ chicken-install -s chickadee
  $ chickadee serve               # start on http://localhost:8080
  $ chickadee serve --port 8081   # start on http://localhost:8081

The look and feel of the server is customizable through CSS and
Javascript but some layout is still hardcoded, particularly the front
page.

==== chicken-doc-admin

So this is the way to use chicken-doc as nature intended: checkout
the wiki and then process it with chicken-doc-admin. First, grab a
copy of the wiki and initialize an empty chicken-doc repository:

  $ chicken-install -s chicken-doc-admin
  $ sudo chicken-doc-admin -i
  $ svn co --username anonymous --password "" \
      http://code.call-cc.org/svn/chicken-eggs/wiki

Then add the Chicken 4 man and egg pages to your database:

  $ sudo chicken-doc-admin -m wiki/man/4
  49 man pages processed, 49 updated
  $ sudo chicken-doc-admin -e wiki/eggref/4
  347 eggs processed, 347 updated

Now you can use chicken-doc as before. Later, you can update your
checkout and rerun the processor:

  $ svn up wiki/eggref/4
  $ sudo chicken-doc-admin -e wiki/eggref/4
  347 eggs processed, 28 updated

chicken-doc-admin updates only the nodes that have changed since last
run. So if you make some local changes, you can easily preview them
without checking in:

  $ emacs wiki/eggref/4/atom
  $ sudo chicken-doc-admin -e wiki/eggref/4
  347 eggs processed, 1 updated

chicken-doc-admin has more options than you could possibly dream
of (as long as you can count no higher than ten); check out the
documentation (http://3e8.org/chickadee/chicken-doc-admin) for
details.

== 5. Chick'n Chunks

This is a recurring Gazette feature which appears at least once
every nine issues, and dispenses Chicken wisdom in tasty, bite-sized
morsels.

  * Use the `-S` option to `csc` to turn on the scrutinizer and
    get free static type checking on calls to core procedures. Drop
    everything and use it right now.
  * The `-local` option to `csc` may give a speed boost to
    performance-critical code that is exported from your modules;
    code generation is improved by letting the compiler assume these
    globals can't be changed. It's like a less blocky version of
    `-block`. It's especially good with a dollop of `-inline`, and is
    now automatically set at `-O3` and higher.
  * Use `csc -J` instead of `csc -j module` to save a little typing
    in your extensions.

== 6. About the Chicken Gazette

The Gazette is produced weekly by a volunteer from the
Chicken community. The latest issue can be found at
http://gazette.call-cc.org or you can follow it in your
feed reader at http://gazette.call-cc.org/feed.atom. If
you'd like to write an issue, check out the instructions
(http://bugs.call-cc.org/browser/gazette/README.txt) and come and
find us in `#chicken` on Freenode!

[ --- End of this issue --- ]