-*- 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).

* 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 and 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

   Mar 2004: released 0.2
   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/>