path: root/src/algebra/net.spad.pamphlet

\documentclass{article}
\usepackage{axiom}

\author{Gabriel Dos~Reis}

\begin{document}

\begin{abstract}
\end{abstract}

\tableofcontents
\eject

\section{The Conduit category}

<<category CONDUIT Conduit>>=
)abbrev category CONDUIT Conduit
++ Author: Gabriel Dos Reis
++ Date Created: August 24, 2008
++ Date Last Modified: August 24, 2008
++ Description:
++   This category is the root of the I/O conduits.
Conduit(): Category == with
    close!: % -> %
      ++ close!(c) closes the conduit c, changing its state to one
      ++ that is invalid for future read or write operations.

@

\subsection{The InputByteConduit category}

<<category INBCON InputByteConduit>>=
)abbrev category INBCON InputByteConduit
++ Author: Gabriel Dos Reis
++ Date Created: August 24, 2008
++ Date Last Modified: August 24, 2008
++ Description:
++   This category describes input byte stream conduits.
InputByteConduit(): Category == Conduit with
    readByteIfCan!: % -> SingleInteger
      ++ readByteIfCan!(cond) attempts to read a byte from the
      ++ input conduit `cond'.  Returns the read byte if successful,
      ++ otherwise return -1.
      ++ Note: Ideally, the return value should have been of type
      ++   Maybe Byte; but that would have implied allocating
      ++   a cons cell for every read attempt, which is overkill.
    readBytes!: (%,ByteBuffer) -> SingleInteger
      ++ readBytes!(c,b) reads byte sequences from conduit `c' into
      ++ the byte buffer `b'.  The actual number of bytes written
      ++ is returned.
  add
    readBytes!(cond,buf) ==
      count: SingleInteger := 0
      b : SingleInteger
      while count < capacity buf and ((b := readByteIfCan! cond) >= 0) repeat
        qsetelt!(buf,count,b : Byte)
        count := count + 1
      count

@

\subsection{The OutputByteConduit category}

<<category OUTBCON OutputByteConduit>>=
)abbrev category OUTBCON OutputByteConduit
++ Author: Gabriel Dos Reis
++ Date Created: August 24, 2008
++ Date Last Modified: August 24, 2008
++ Description:
++   This category describes output byte stream conduits.
OutputByteConduit(): Category == Conduit with
    writeByteIfCan!: (%,Byte) -> SingleInteger
      ++ writeByteIfCan!(c,b) attempts to write the byte `b' on
      ++ the conduit `c'.  Returns the written byte if successful,
      ++ otherwise, returns -1.
      ++ Note: Ideally, the return value should have been of type
      ++   Maybe Byte; but that would have implied allocating
      ++   a cons cell for every write attempt, which is overkill.
    writeBytes!: (%,ByteBuffer) -> SingleInteger
      ++ writeBytes!(c,b) write bytes from buffer `b' 
      ++ onto the conduit `c'.  The actual number of written 
      ++ bytes is returned.
  add
    writeBytes!(cond,buf) ==
      count: SingleInteger := 0
      while count < capacity buf and 
        writeByteIfCan!(cond,qelt(buf,count)) >= 0 repeat
          count := count + 1
      count

@

\subsection{The InputOutputByteConduit category}

<<category IOBCON InputOutputByteConduit>>=
)abbrev category IOBCON InputOutputByteConduit
++ Author: Gabriel Dos Reis
++ Date Created: August 24, 2008
++ Date Last Modified: August 24, 2008
++ See Also: InputByteConduit, OutputByteConduit.
++ Description:
++   This category describes byte stream conduits supporting
++   both input and output operations.
InputOutputByteConduit(): Category ==
    Join(InputByteConduit,OutputByteConduit)

@


\subsection{The InputBinaryFile domain}

<<domain INBFILE InputBinaryFile>>=
)abbrev domain INBFILE InputBinaryFile
++ Author: Gabriel Dos Reis
++ Date Created: September 30, 2008
++ Date Last Modified: September 30, 2008
++ Description:
++   This domain provides representation for binary files open
++   for input operations.  `Binary' here means that the conduits
++   do not interpret their contents.
InputBinaryFile(): Public == Private where
  Public == Join(InputByteConduit, CoercibleTo OutputForm) with
    inputBinaryFile: FileName -> %
      ++ inputBinaryFile(f) returns an input conduit obtained by
      ++ opening the file named by `f' as a binary file.
    inputBinaryFile: String -> %
      ++ inputBinaryFile(f) returns an input conduit obtained by
      ++ opening the file named by `f' as a binary file.
    eof?: % -> Boolean
      ++ eof?(ifile) holds when the last read reached end of file.
    isOpen?: % -> Boolean
      ++ open?(ifile) holds if `ifile' is in open state.
    position: % -> SingleInteger
      ++ position(f) returns the current byte-position in the file `f'.
    position!: (%,SingleInteger) -> SingleInteger
      ++ position(f,p) sets the current byte-position to `i'.
  Private == add
    Rep == Record(stream: SExpression, filename: FileName, eof: Boolean)
    inputBinaryFile(f: FileName) ==
      per [openBinaryFile(f::String,input$IOMode)$Lisp,f,false]
    inputBinaryFile(f: String) ==
      per [openBinaryFile(f,input$IOMode)$Lisp,f::FileName,false]
    isOpen? ifile ==
      not null? rep(ifile).stream
    readByteIfCan! ifile ==
      isOpen? ifile => 
        b: SingleInteger := readByteFromFile(rep(ifile).stream)$Lisp
        if b < 0@SingleInteger then 
          rep(ifile).eof := true
        b
      error "file is not open"
    eof? ifile ==
      isOpen? ifile => rep(ifile).eof
      error "file is not open"
    close! ifile ==
      if isOpen? ifile then
        rep(ifile).stream := closeFile(rep(ifile).stream)$Lisp
        rep(ifile).eof := true
      ifile
    position ifile ==
      isOpen? ifile =>
        FILE_-POSITION(rep(ifile).stream)$Lisp
      error "file is not open"
    position!(ifile,p) ==
      isOpen? ifile =>
        FILE_-POSITION(rep(ifile).stream,p)$Lisp
        p
      error "file is not open"
    coerce(ifile: %): OutputForm ==
      rep(ifile).filename::OutputForm
@

\subsection{The OutputBinaryFile domain}

<<domain OUTBFILE OutputBinaryFile>>=
)abbrev domain OUTBFILE OutputBinaryFile
++ Author: Gabriel Dos Reis
++ Date Created: September 30, 2008
++ Date Last Modified: September 30, 2008
++ Description:
++   This domain provides representation for binary files open
++   for output operations.  `Binary' here means that the conduits
++   do not interpret their contents.
OutputBinaryFile(): Public == Private where
  Public == Join(OutputByteConduit, CoercibleTo OutputForm) with
    outputBinaryFile: FileName -> %
      ++ outputBinaryFile(f) returns an output conduit obtained by
      ++ opening the file named by `f' as a binary file.
    outputBinaryFile: String -> %
      ++ outputBinaryFile(f) returns an output conduit obtained by
      ++ opening the file named by `f' as a binary file.
    isOpen?: % -> Boolean
      ++ open?(ifile) holds if `ifile' is in open state.
  Private == add
    Rep == Record(stream: SExpression, filename: FileName)
    outputBinaryFile(f: FileName) ==
      per [openBinaryFile(f::String,output$IOMode)$Lisp,f]
    outputBinaryFile(f: String) ==
      per [openBinaryFile(f,output$IOMode)$Lisp,f::FileName]
    isOpen? ifile ==
      not null? rep(ifile).stream
    writeByteIfCan!(ifile,b) ==
      isOpen? ifile => writeByteToFile(rep(ifile).stream,b)$Lisp
      error "file is not open"
    close! ifile ==
      if isOpen? ifile then
        rep(ifile).stream := closeFile(rep(ifile).stream)$Lisp
      ifile
    coerce(ifile: %): OutputForm ==
      rep(ifile).filename::OutputForm
@

\subsection{The InputOutputBinaryFile domain}

<<domain IOBFILE InputOutputBinaryFile>>=
)abbrev domain IOBFILE InputOutputBinaryFile
++ Author: Gabriel Dos Reis
++ Date Created: October 21, 2008
++ Date Last Modified: October 21, 2008
++ Description:
++   This domain provides representation for binary files open
++   for input and output operations.
++ See Also: InputBinaryFile, OutputBinaryFile
InputOutputBinaryFile(): Public == Private where
  Public == Join(InputOutputByteConduit, CoercibleTo OutputForm) with
    inputOutputBinaryFile: FileName -> %
      ++ inputOutputBinaryFile(f) returns an input/output conduit obtained
      ++ by opening the file designated by `f' as a binary file.
    inputOutputBinaryFile: String -> %
      ++ inputOutputBinaryFile(f) returns an input/output conduit obtained
      ++ by opening the file named by `f' as a binary file.
    isOpen?: % -> Boolean
      ++ isOpen?(f) holds if `f' is in open state.
  Private == (InputBinaryFile, OutputBinaryFile) add
    Rep == Record(stream: SExpression, filename: FileName)
    inputOutputBinaryFile(f: FileName) ==
      per [openBinaryFile(f::String,bothWays$IOMode)$Lisp,f]
    inputOutputBinaryFile(f: String) ==
      per [openBinaryFile(f,bothWays$IOMode)$Lisp,f::FileName]
@


\section{The Hostname domain}

<<domain HOSTNAME Hostname>>=
)abbrev domain HOSTNAME Hostname
++ Author: Gabriel Dos Reis
++ Date Created: August 23, 2008
++ Date Last Modified: August 23, 2008
++ References: RFC 1034, RFC 1035
++ Description:  
++   This domain represents hostnames on computer network.
Hostname(): Public == Private where
  Public == Join(SetCategory, CoercibleTo String) with
    host: String -> %
      ++ host(n) constructs a Hostname from the name `n'.
  Private == add
    Rep == String
    host n == per n
    x = y == rep x = rep y
    coerce(x: %): String == rep x
    coerce(x: %): OutputForm == rep(x)::OutputForm

@

\section{The PortNumber domain}
<<domain PORTNUM PortNumber>>=
)abbrev domain PORTNUM PortNumber
++ Author: Gabriel Dos Reis
++ Date Created: August 23, 2008
++ Date Last Modified: August 23, 2008
++ Description:  
++   This domain represents network port numbers (notable TCP and UDP).
PortNumber(): Public == Private where
  Public == Join(SetCategory,CoercibleTo SingleInteger) with
    port: SingleInteger -> %
      ++ port(n) constructs a PortNumber from the integer `n'.
  Private == add
    Rep == SingleInteger
    port n == per n
    x = y == rep x = rep y
    coerce(x: %): SingleInteger == rep x
    coerce(x: %): OutputForm == rep(x)::OutputForm

@

\section{The IP4Address domain}

<<domain IP4ADDR IP4Address>>=
)abbrev domain IP4ADDR IP4Address
++ Author: Gabriel Dos Reis
++ Date Created: October 22, 2008
++ Date Last Modified: October 22, 2008
++ Description:  
++   This domain provides representation for ARPA Internet IP4 addresses.
IP4Address(): Public == Private where
  Public == SetCategory with
    ip4Address: String -> %
      ++ ip4Address(a) builds a numeric address out of the ASCII form `a'.
    bytes: % -> DataArray(4,Byte)
      ++ bytes(x) returns the bytes of the numeric address `x'.
    resolve: Hostname -> Union(%,"failed")
      ++ resolve(h) returns the IP4 address of host `h'.
  Private == add
    Rep == DataArray(4,Byte)
    ip4Address a ==
      n := new()$Rep
      presentationToNumeric(a,4,n)$Lisp = 0@SingleInteger => per n
      userError "invalid Internet IP4 address"
    resolve h ==
      n := new()$Rep
      hostnameToNumeric(h::String,4,n)$Lisp = 0@SingleInteger => per n
      "failed"
    bytes x == rep x
    x = y == rep x = rep y
    coerce(x: %): OutputForm == 
      infix('_.::OutputForm, 
        [qelt(rep x,i)::OutputForm for i in 0..3])$OutputForm
@


\section{The NetworkClientSocket category}

<<category NETCLT NetworkClientSocket>>=
)abbrev category NETCLT NetworkClientSocket
NetworkClientSocket(T: SetCategory): Category == InputOutputByteConduit with
   connectTo: (T, PortNumber) -> Union(%,"failed")
   isConnected?: % -> Boolean
@


\section{The InetClientStreamSocket domain}

<<domain INETCLTS InetClientStreamSocket>>=
)abbrev domain INETCLTS InetClientStreamSocket
InetClientStreamSocket(): Public == Private where
  Public == Join(NetworkClientSocket IP4Address, CoercibleTo OutputForm) with
    connectTo: (Hostname, PortNumber) -> Union(%,"failed")
  Private == add
    -- we hope that a small integer is OK on all platform
    Host == Union(IP4Address,Hostname)
    Rep == Record(%host: Host, %port: PortNumber, %sock: SingleInteger)

    connectTo(ip: IP4Address, p: PortNumber) ==
      s: SingleInteger := connectToHostAndPort(ip,4,p)$Lisp
      s = -1::SingleInteger => "failed"
      per [ip::Host,p,s]

    connectTo(h: Hostname, p: PortNumber) ==
      (ip := resolve(h)$IP4Address) case "failed" => "failed"
      s: SingleInteger := connectToHostAndPort(ip::IP4Address,4,p)$Lisp
      s = -1::SingleInteger => "failed"
      per [h::Host,p,s]

    isConnected? s ==
      rep(s).%sock ~= -1::SingleInteger

    readBytes!(x,b) ==
      n: SingleInteger := 
          readFromStreamSocket(rep(x).%sock,b, capacity b)$Lisp
      if n <= 0 then close! x
      else setLength!(b,n : NonNegativeInteger)
      n
    readByteIfCan! x ==
      r: SingleInteger := readByteFromStreamSocket(rep(x).%sock)$Lisp
      if r < 0 then close! x
      r

    writeBytes!(x,b) ==
      n: SingleInteger := 
          writeToStreamSocket(rep(x).%sock,b, capacity b)$Lisp
      if n <= 0 then close! x
      else setLength!(b,n : NonNegativeInteger)
      n

    writeByteIfCan!(x,b) ==
      r: SingleInteger := writeByteToStreamSocket(rep(x).%sock,b)$Lisp
      if r < 0 then close! x
      r

    close! x ==
      closeSocket(rep(x).%sock)$Lisp
      rep(x).%sock := -1::SingleInteger
      x

    coerce(x: %): OutputForm ==
      x' := rep x
      h := 
        x'.%host case IP4Address => x'.%host::IP4Address::OutputForm
        x'.%host::Hostname::OutputForm
      infix('_:::OutputForm,h,x'.%port::OutputForm)$OutputForm
      
@



\section{License}

<<license>>=
-- Copyright (C) 2007-2008, Gabriel Dos Reis.
-- All rights reserved.
-- 
-- Redistribution and use in source and binary forms, with or without
-- modification, are permitted provided that the following conditions are
-- met:
-- 
--     - Redistributions of source code must retain the above copyright
--       notice, this list of conditions and the following disclaimer.
-- 
--     - Redistributions in binary form must reproduce the above copyright
--       notice, this list of conditions and the following disclaimer in
--       the documentation and/or other materials provided with the
--       distribution.
-- 
--     - Neither the name of The Numerical Algorithms Group Ltd. nor the
--       names of its contributors may be used to endorse or promote products
--       derived from this software without specific prior written permission.
-- 
-- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
-- IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
-- TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
-- PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
-- OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
-- EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
-- PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

@

<<*>>=
<<license>>

<<category CONDUIT Conduit>>
<<category INBCON InputByteConduit>>
<<category OUTBCON OutputByteConduit>>
<<category IOBCON InputOutputByteConduit>>
<<category NETCLT NetworkClientSocket>>

<<domain INBFILE InputBinaryFile>>
<<domain OUTBFILE OutputBinaryFile>>
<<domain IOBFILE InputOutputBinaryFile>>

<<domain HOSTNAME Hostname>>
<<domain PORTNUM PortNumber>>
<<domain IP4ADDR IP4Address>>

<<domain INETCLTS InetClientStreamSocket>>

@

\end{document}