-*- outline -*-

                             scsh-yp 0.1

* Introduction

  Scsh-yp is a package for scsh, the Scheme shell[1] that provides
  bindings to the YP/NIS functions.  This enables the scsh user to
  lookup data in a NIS or YP database without calling the
  corresponding external program (i. e. ypbind, ypmatch etc).

** How to install

   Scsh has the ability to load shared object files dynamically at run
   time.  That makes it easy to add functionality like scsh-yp to an
   existing scsh installation without having to recompile everything.
   In order to build such a shared module run

   ./configure --prefix=<path> --with-scsh-includes=<path>

   It is important to provide a correct path to the scsh include
   directory of your system.  Once the configure script found out how
   to build shared objects for your system you can run 'make' to build
   scsh-yp and 'make install' to copy the files to the installation
   directory of your scsh library path.

** Running scsh-yp

   Scsh-yp comes with an script called 'load-yp.scm' which loads the
   shared object and loads the scheme package and interface
   definitions for scsh-yp. 

   If the installation directory of scsh-yp is in scsh's library path
   you can load scsh-yp at start-up by

     scsh -lel scsh-yp-0.1/scheme/load-yp.scm

   The scsh user manual explains how to set the library path.  Now
   everything is set up to open the package "yp":

     ,open yp

   You can also load scsh-yp interactively using the command
 
     ,exec ,load <path>/scheme/load-yp.scm
 
   where <path> is the argument of the --prefix option of configure.

* Using scsh-yp

** yp-error condition hierarchy

   Scsh-yp uses scsh's condition system to signal exceptions.  In this
   system conditions are organized hierarchially.  Use one of the
   following predicates to check what kind of error occurred:

    yp-error?
    |
    +-- yp-communication-error?
    |   |
    |   +-- yp-bad-domain?
    |   +-- yp-no-domain?
    |   +-- yp-portmap-failure?
    |   +-- yp-rpc-failure?
    |   +-- yp-bind-failure?
    |   +-- yp-binding-error?
    |   +-- yp-server-error?
    | 
    +-- yp-bad-arguments?
    |
    +-- yp-bad-database?
    |
    +-- yp-unknown-resource-error?
    |   |
    |   +-- yp-unknown-key?
    |   +-- yp-unknown-map?
    |
    +-- yp-internal-error?

   These errors correspond to the return codes of C yp_*() function
   calls.  The yp_* man pages explain the error codes in detail.

** function reference

   This sections gives an brief overview on the functions provided by
   the scsh-yp package.  The man pages of the underlying yp_*()
   function calls explain these functions in greater detail.  Almost
   all of the functions listed here have an optional parameter DOMAIN
   that tells YP/NIS which YP/NIS domain you are referring to.  If
   this parameter is omitted, the default domain will be used, that
   is, the domain name that can be obtained with
   YP-GET-DEFAULT-DOMAIN.

   (yp-get-default-domain) -> string
   Returns the default YP/NIS domain.

   (yp-bind [domain]) -> #t 
   Connect and use to the YP/NIS domain DOMAIN.  Returns #t on success
   or raises a yp-error condition.
 
   (yp-unbind [domain]) -> #t
   Unbind from the domain DOMAIN.  Returns #t on success or raises a
   yp-error condition.

   (yp-match map key [domain]) -> list-of-strings
   Returns the entries in MAP (a string) that match KEY (a string).
   Make sure to use a full NIS/YP map name, e.g. "passwd.byname"
   instead of "passwd".  May raise an yp-error condition.

   (yp-order map [domain]) -> integer
   Returns the order number of a MAP (a string).  May raise an yp-error.

   (yp-master map [domain]) -> string
   Returns the master server that serves MAP (a string).  May raise an
   yp-error.

   (yp-first map [domain]) -> {string string}
   (yp-next map key [domain]) -> {string-or-bool string-or-bool}
   Use YP-FIRST and YP-NEXT to step through all entries of MAP (a
   string).  YP-FIRST returns two strings: The key and the complete
   map entry for that key.  To obtain the next value(s) in the map
   call YP-NEXT with the key.  If YP-NEXT hits the end of the map it
   returns {#f #f}.  Both functions may raise an yp-error.

   (yp-map->list map [domain]) -> list-of-pairs
   Reads all entries from a YP/NIS MAP (a string) and return them as a
   list of pairs.  The CAR of each pair is the key of the entry, the
   CDR contains the complete entry.  May raise an yp-error.

** Examples

   Using yp-first and yp-next to obtain a list of all keys in the map
   passwd.byname (uses RECEIVE from SRFI 8):

   ,----
   | define (yp-all-keys map domain)
   |  (receive (key val) (yp-first map domain)
   |    (let loop ((key key) (res (cons key '())))
   |      (receive (key val)
   |          (yp-next map key domain)
   |          (if val
   |            (loop key (cons key res))
   |            res)))))
   | 
   | > (yp-all-keys "passwd.byname" "wsi")
   | (... very long list ...)
   `----

    Searching for an entry in passwd.byname an parsing the result:

   ,----
   | (define (yp-account-data user)
   |   (let ((splitter (infix-splitter (rx ":"))))
   |     (cond ((yp-match "passwd.byname" user)
   |            => splitter)
   |      (else #f))))
   | 
   | > (yp-account-data "knauel")
   | '("knauel" "geheim" "5324" "3010" "Eric Knauel" 
   |   "/afs/informatik.uni-tuebingen.de/home/knauel" "/bin/tcsh")
   | > (yp-account-data "klabautermann")
   | 
   | Error: yp-unknown-key
   |        5
   |       (yp-match map "passwd.byname" key "klabautermann" domain ---)
   | 1> 
   `----

* Caveats

  There is only a synchronous high-level interface to YP/NIS, so
  calling a yp_*() function causes scsh and all scsh threads to block.
  I hope to solve that problem in a future version of scsh-yp.

*  Bug reporting

   Please report bugs to <scsh-bugs@zurich.ai.mit.edu>.

*  Version history

   Dec 2003: released 0.1

*  Acknowlegdements

   I would like to thank Martin Gasbichler who was fearless enough to
   engage in a battle with automake and wrote the automake build
   files.


   Eric Knauel
   <knauel@informatik.uni-tuebingen.de>
   T<>bingen, December 2003

Footnotes: 
[1]  <http://www.scsh.net/>