[Pkg-haskell-commits] [SCM] haskell-testpack branch, master, updated. debian/1.0.2-1-4-gb0d6b36

John Goerzen jgoerzen at complete.org
Fri Apr 23 14:45:49 UTC 2010


The following commit has been merged in the master branch:
commit e5826c7c9d1a0270df951b9c70f28c290606f2e3
Author: John Goerzen <jgoerzen at complete.org>
Date:   Sun Oct 24 12:18:21 2004 +0100

    updated docs
    
    Keywords:
    
    
    (jgoerzen at complete.org--projects/missingh--head--1.0--patch-118)

diff --git a/ChangeLog b/ChangeLog
index 3b5020d..6184be3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,6 +2,18 @@
 # arch-tag: automatic-ChangeLog--jgoerzen at complete.org--projects/missingh--head--1.0
 #
 
+2004-10-24 06:18:21 GMT	John Goerzen <jgoerzen at complete.org>	patch-118
+
+    Summary:
+      updated docs
+    Revision:
+      missingh--head--1.0--patch-118
+
+
+    modified files:
+     ChangeLog libsrc/MissingH/Network/FTP/Client.hs
+
+
 2004-10-24 04:49:25 GMT	John Goerzen <jgoerzen at complete.org>	patch-117
 
     Summary:
diff --git a/libsrc/MissingH/Network/FTP/Client.hs b/libsrc/MissingH/Network/FTP/Client.hs
index 10f7991..b7753b7 100644
--- a/libsrc/MissingH/Network/FTP/Client.hs
+++ b/libsrc/MissingH/Network/FTP/Client.hs
@@ -23,13 +23,141 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
    Maintainer : John Goerzen, 
    Maintainer : jgoerzen at complete.org
-   Stability  : provisional
+   Stability  : experimental
    Portability: systems with networking
 
 This module provides a client-side interface to the File Transfer Protocol.
 
 Written by John Goerzen, jgoerzen\@complete.org
 
+Welcome to the FTP module for Haskell.
+
+Here is a quick usage example to get you started.  This is a log of a real
+session with ghci: 
+
+(This would be similar in a "do" block.  You could also save it to a file and
+run that with Hugs.)
+
+> Prelude> :l MissingH.Network.FTP.Client
+> ...
+
+The above loads the module.
+
+Next, we enable the debugging.  This will turn on all the @"FTP sent"@ and
+@"FTP received"@ messages you'll see.
+
+> Prelude MissingH.Network.FTP.Client> enableFTPDebugging
+
+Now, connect to the server on @ftp.kernel.org at .
+
+> *MissingH.Network.FTP.Client> h <- easyConnectFTP "ftp.kernel.org"
+> FTP received: 220 Welcome to ftp.kernel.org.
+
+And log in anonymously.
+
+> *MissingH.Network.FTP.Client> loginAnon h
+> FTP sent: USER anonymous
+> FTP received: 331 Please specify the password.
+> FTP sent: PASS anonymous@
+> ...
+> FTP received: 230 Login successful.
+
+Change the directory...
+
+> Prelude MissingH.Network.FTP.Client> cwd h "/pub/linux/kernel/Historic"
+> FTP sent: CWD /pub/linux/kernel/Historic
+> FTP received: 250 Directory successfully changed.
+
+Let's look at the directory. 'nlst' returns a list of strings, each string
+corresponding to a filename.  Here, @putStrLn . unlines@ will simply
+print them out, one per line.
+
+> Prelude MissingH.Network.FTP.Client> nlst h Nothing >>= putStrLn . unlines
+> FTP sent: TYPE A
+> FTP received: 200 Switching to ASCII mode.
+> FTP sent: PASV
+> FTP received: 227 Entering Passive Mode (204,152,189,116,130,143)
+> FTP sent: NLST
+> FTP received: 150 Here comes the directory listing.
+> linux-0.01.tar.bz2
+> linux-0.01.tar.bz2.sign
+> linux-0.01.tar.gz
+> linux-0.01.tar.gz.sign
+> linux-0.01.tar.sign
+> old-versions
+> v0.99
+> FTP received: 226 Directory send OK.
+
+Let's try downloading something and print it to the screen.  Again, we use
+ at putStrLn@.  We use @fst@ here because 'getbinary' returns a tuple consisting
+of a string representing the data and a 'FTPResult' code.
+
+> Prelude MissingH.Network.FTP.Client> getbinary h "linux-0.01.tar.gz.sign" >>= putStrLn . fst
+> FTP sent: TYPE I
+> FTP received: 200 Switching to Binary mode.
+> FTP sent: PASV
+> FTP received: 227 Entering Passive Mode (204,152,189,116,121,121)
+> FTP sent: RETR linux-0.01.tar.gz.sign
+> FTP received: 150 Opening BINARY mode data connection for linux-0.01.tar.gz.sign (248 bytes).
+> -----BEGIN PGP SIGNATURE-----
+> Version: GnuPG v1.0.0 (GNU/Linux)
+> Comment: See http://www.kernel.org/signature.html for info
+> 
+> iD8DBQA54rf0yGugalF9Dw4RAqelAJ9lafFni4f/QyJ2IqDXzW2nz/ZIogCfRPtg
+> uYpWffOhkyByfhUt8Lcelec=
+> =KnLA
+> -----END PGP SIGNATURE-----
+> FTP received: 226 File send OK.
+
+Here's an example showing you what the result code looks like.
+
+> Prelude MissingH.Network.FTP.Client> getbinary h "linux-0.01.tar.gz.sign" >>= print . snd
+> ...
+> (226,["File send OK."])
+
+The first component of the 'FTPResult' object is the numeric status code from
+the server.  The second component is a list of message lines from the server.
+
+Now, let's get a more detailed directory listing:
+
+> Prelude MissingH.Network.FTP.Client> dir h Nothing >>= putStrLn . unlines
+> ...
+> -r--r--r--    1 536      536         63362 Oct 30  1993 linux-0.01.tar.bz2
+> -r--r--r--    1 536      536           248 Oct 30  1993 linux-0.01.tar.bz2.sign
+> -r--r--r--    1 536      536         73091 Oct 30  1993 linux-0.01.tar.gz
+> -r--r--r--    1 536      536           248 Oct 30  1993 linux-0.01.tar.gz.sign
+> -r--r--r--    1 536      536           248 Oct 30  1993 linux-0.01.tar.sign
+> drwxrwsr-x    5 536      536          4096 Mar 20  2003 old-versions
+> drwxrwsr-x    2 536      536          4096 Mar 20  2003 v0.99
+> FTP received: 226 Directory send OK.
+
+And finally, log out:
+
+> Prelude MissingH.Network.FTP.Client> quit h
+> FTP sent: QUIT
+> FTP received: 221 Goodbye.
+
+Here is one big important caution:
+
+/You MUST consume all data from commands that return file data before you
+issue any other FTP commands./
+
+That's due to the lazy nature of Haskell.  This means that, for instance,
+you can't just iterate over the items 'nlst' returns, trying to 'getbinary'
+each one of them -- the system is still transferring 'nlst' data while you
+are trying that, and confusion will ensue.  Either open two FTP connections
+or make sure you consume the 'nlst' data first.
+
+Here is a partial list of commands effected: 'nlst', 'dir', 'getbinary',
+'getlines', 'downloadbinary', 'downloadlines'.
+
+The corrolary is:
+
+/Actions that yield lazy data for data uploading must not issue FTP
+commands themselves./
+
+This will be fairly rare.  Just be aware of this.
+
 Useful standards:
 
 * RFC959, <http://www.cse.ohio-state.edu/cgi-bin/rfc/rfc0959.html>
@@ -49,10 +177,10 @@ Useful standards:
 -}
 
 module MissingH.Network.FTP.Client(-- * Establishing\/Removing connections
-                                   easyConnectTo, connectTo,
-                                   loginAnon, login, quit,
+                                   easyConnectFTP, connectFTP,
+                                   loginAnon, login, quit, 
                                    -- * Configuration
-                                   setPassive,
+                                   setPassive, enableFTPDebugging,
                                    -- * Directory listing
                                    nlst, dir, 
                                    -- * File downloads
@@ -102,13 +230,26 @@ sendcmd h c = do logsend c
 {- | Connect to the remote FTP server and read but discard
    the welcome.  Assumes
    default FTP port, 21, on remote. -}
-easyConnectTo :: Network.HostName -> IO FTPConnection
-easyConnectTo h = do x <- connectTo h 21
-                     return (fst x)
+easyConnectFTP :: Network.HostName -> IO FTPConnection
+easyConnectFTP h = do x <- connectFTP h 21
+                      return (fst x)
+
+{- | Enable logging of FTP messages through 'MissingH.Logging.Logger'.
+This sets the log levels of @"MissingH.Network.FTP.Parser"@ and
+@"MissingH.Network.FTP.Client"@ to DEBUG.  By default, this means that
+full protocol dumps will be sent to stderr.
+
+The effect is global and persists until changed.
+-}
+enableFTPDebugging :: IO ()
+enableFTPDebugging = 
+    do
+    updateGlobalLogger "MissingH.Network.FTP.Parser" (setLevel DEBUG)
+    updateGlobalLogger "MissingH.Network.FTP.Client" (setLevel DEBUG)
 
 {- | Connect to remote FTP server and read the welcome. -}
-connectTo :: Network.HostName -> PortNumber -> IO (FTPConnection, FTPResult)
-connectTo h p =
+connectFTP :: Network.HostName -> PortNumber -> IO (FTPConnection, FTPResult)
+connectFTP h p =
     let readchars :: Handle -> IO String
         readchars h = do
                       c <- hGetChar h
@@ -116,8 +257,6 @@ connectTo h p =
                       return (c : next)
         in
     do
-    updateGlobalLogger "MissingH.Network.FTP.Parser" (setLevel DEBUG)
-    updateGlobalLogger "MissingH.Network.FTP.Client" (setLevel DEBUG)
     s <- connectTCP h p
     r <- socketToHandle s ReadMode
     hSetBuffering r LineBuffering

-- 
haskell-testpack



More information about the Pkg-haskell-commits mailing list