changeset 14217:7912e682aa30

doc: Update docstrings for @ftp class. * aspell-octave.en.pws: Add new functions to spellchecker. * system.txi: Add DOCSTRING entries for all @ftp functions * ascii.m, binary.m, cd.m, close.m, delete.m, dir.m, ftp.m, loadobj.m, mget.m, mkdir.m, mput.m, rename.m, rmdir.m: Update docstrings.
author Rik <octave@nomad.inbox5.com>
date Wed, 18 Jan 2012 21:15:50 -0800
parents b3730ed107a6
children bed72845115f
files doc/interpreter/doccheck/aspell-octave.en.pws doc/interpreter/system.txi scripts/@ftp/ascii.m scripts/@ftp/binary.m scripts/@ftp/cd.m scripts/@ftp/close.m scripts/@ftp/delete.m scripts/@ftp/dir.m scripts/@ftp/ftp.m scripts/@ftp/loadobj.m scripts/@ftp/mget.m scripts/@ftp/mkdir.m scripts/@ftp/mput.m scripts/@ftp/rename.m scripts/@ftp/rmdir.m
diffstat 15 files changed, 74 insertions(+), 22 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/doccheck/aspell-octave.en.pws
+++ b/doc/interpreter/doccheck/aspell-octave.en.pws
@@ -555,6 +555,7 @@
 metafiles
 Metafont
 mex
+mget
 Michelsen
 Microsystems
 MinGW
@@ -565,6 +566,7 @@
 MIP
 miscompiled
 Misra
+mkdir
 mkoctfile
 mldivide
 mmd
@@ -578,6 +580,7 @@
 Montanet
 mpoles
 mpower
+mput
 mrdivide
 MSYS
 mtimes
@@ -771,6 +774,7 @@
 Rightarrow
 rightarrow
 rline
+rmdir
 RMS
 rnd
 roffset
--- a/doc/interpreter/system.txi
+++ b/doc/interpreter/system.txi
@@ -266,16 +266,34 @@
 @node FTP Objects
 @subsection FTP Objects
 
+Octave supports the FTP protocol through an object-oriented interface.
+Use the function @code{ftp} to create an FTP object which represents the
+connection.  All FTP functions take an FTP object as the first argument.
+
 @DOCSTRING(@ftp/ftp)
 
+@DOCSTRING(@ftp/close)
+
 @DOCSTRING(@ftp/mget)
 
 @DOCSTRING(@ftp/mput)
 
+@DOCSTRING(@ftp/cd)
+
+@DOCSTRING(@ftp/dir)
+
 @DOCSTRING(@ftp/ascii)
 
 @DOCSTRING(@ftp/binary)
 
+@DOCSTRING(@ftp/delete)
+
+@DOCSTRING(@ftp/rename)
+
+@DOCSTRING(@ftp/mkdir)
+
+@DOCSTRING(@ftp/rmdir)
+
 @node URL Manipulation
 @subsection URL Manipulation
 
--- a/scripts/@ftp/ascii.m
+++ b/scripts/@ftp/ascii.m
@@ -18,7 +18,11 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} ascii (@var{f})
-## Put the FTP connection @var{f} into ascii mode.
+## Set the FTP connection @var{f} to use ASCII mode for transfers.
+## ASCII mode is only appropriate for text files as it will convert
+## the remote host's newline representation to the local host's newline
+## representation.
+##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
--- a/scripts/@ftp/binary.m
+++ b/scripts/@ftp/binary.m
@@ -18,7 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} binary (@var{f})
-## Put the FTP connection @var{f} into binary mode.
+## Set the FTP connection @var{f} to use binary mode for transfers.
+## In binary mode there is no conversion of newlines from the remote
+## representation to the local representation.
+##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
--- a/scripts/@ftp/cd.m
+++ b/scripts/@ftp/cd.m
@@ -19,6 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} cd (@var{f}, @var{path})
 ## Set the remote directory to @var{path} on the FTP connection @var{f}.
+##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
--- a/scripts/@ftp/close.m
+++ b/scripts/@ftp/close.m
@@ -18,7 +18,8 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} close (@var{f})
-## Close the FTP connection represented by the given FTP object @var{f}.
+## Close the FTP connection represented by the FTP object @var{f}.
+##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
--- a/scripts/@ftp/delete.m
+++ b/scripts/@ftp/delete.m
@@ -18,7 +18,8 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} delete (@var{f}, @var{file})
-## Delete the remote file @var{file}, over the FTP connection @var{f}.
+## Delete the remote file @var{file} over the FTP connection @var{f}.
+##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
--- a/scripts/@ftp/dir.m
+++ b/scripts/@ftp/dir.m
@@ -19,7 +19,9 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {@var{lst} =} dir (@var{f})
 ## List the current directory in verbose form for the FTP connection
-## @var{f}.  @var{f} is an FTP object returned by the @code{ftp} function.
+## @var{f}.
+##
+## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
 function lst = dir (f)
--- a/scripts/@ftp/ftp.m
+++ b/scripts/@ftp/ftp.m
@@ -23,23 +23,38 @@
 ## If @var{username} and @var{password} are not specified, user "anonymous"
 ## with no password is used.  The returned FTP object @var{f} represents the
 ## established FTP connection.
+##
+## The list of actions for an FTP object are shown below.  All functions
+## require an FTP object as the first argument.
+##
+## @multitable @columnfractions 0.15 0.8
+## @headitem Method @tab Description
+## @item ascii @tab Set transfer type to ascii
+## @item binary @tab Set transfer type to binary
+## @item cd @tab Change remote working directory 
+## @item close @tab Close FTP connection
+## @item delete @tab Delete remote file 
+## @item dir @tab List remote directory contents 
+## @item mget @tab Download remote files
+## @item mkdir @tab Create remote directory
+## @item mput @tab Upload local files
+## @item rename @tab Rename remote file or directory
+## @item rmdir @tab Remove remote directory
+## @end multitable
+## 
 ## @end deftypefn
 
-function obj = ftp (host, username = "anonymous", password = "")
-  if (nargin == 0)
-    p.host = "";
-    p.username = username;
-    p.password = password;
-    p.curlhandle = tmpnam ("ftp-");
-    obj = class (p, "ftp");
-  elseif (nargin == 1 && strcmp (class (host), "ftp"))
-    obj = host;
+function obj = ftp (host = "", username = "anonymous", password = "")
+  if (nargin == 1 && isa (host, "ftp"))
+    obj = host;   # Copy constructor
   else
     p.host = host;
     p.username = username;
     p.password = password;
     p.curlhandle = tmpnam ("ftp-");
-    __ftp__ (p.curlhandle, host, username, password);
+    if (nargin > 0)
+      __ftp__ (p.curlhandle, host, username, password);
+    endif
     obj = class (p, "ftp");
   endif
 endfunction
--- a/scripts/@ftp/loadobj.m
+++ b/scripts/@ftp/loadobj.m
@@ -30,7 +30,7 @@
     b = rmfield (b, "dir");
   elseif (isfield (b, "remotePwd"))
     ## FIXME: Can we read matlab java stringBuffer objects?
-    warning ("can not change remote directory in loqded FTP object");
+    warning ("can not change remote directory in loaded FTP object");
     b = rmfield (b, "remotePwd");
   endif
 endfunction
--- a/scripts/@ftp/mget.m
+++ b/scripts/@ftp/mget.m
@@ -19,7 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} mget (@var{f}, @var{file})
 ## @deftypefnx {Function File} {} mget (@var{f}, @var{dir})
-## @deftypefnx {Function File} {} mget (@dots{}, @var{target})
+## @deftypefnx {Function File} {} mget (@var{f}, @var{remote_name}, @var{target})
 ## Download a remote file @var{file} or directory @var{dir} to the local
 ## directory on the FTP connection @var{f}.  @var{f} is an FTP object
 ## returned by the @code{ftp} function.
@@ -28,8 +28,8 @@
 ## files or directories on the remote server that match will be downloaded.
 ##
 ## If a third argument @var{target} is given, then a single file or
-## directory will be downloaded with the name @var{target} to the local
-## directory.
+## directory will be downloaded to the local directory and the local name
+## will be changed to @var{target}.
 ## @end deftypefn
 
 function mget (f, file)
--- a/scripts/@ftp/mkdir.m
+++ b/scripts/@ftp/mkdir.m
@@ -19,6 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} mkdir (@var{f}, @var{path})
 ## Create the remote directory @var{path}, over the FTP connection @var{f}.
+##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn
 
--- a/scripts/@ftp/mput.m
+++ b/scripts/@ftp/mput.m
@@ -22,7 +22,7 @@
 ## the FTP connection @var{f}.  @var{f} is an FTP object returned by the
 ## ftp function.
 ##
-## The argument @var{file} is passed by the @dfn{glob} function and any
+## The argument @var{file} is passed through the @code{glob} function and any
 ## files that match the wildcards in @var{file} will be uploaded.
 ## @end deftypefn
 
--- a/scripts/@ftp/rename.m
+++ b/scripts/@ftp/rename.m
@@ -19,8 +19,9 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} rename (@var{f}, @var{oldname}, @var{newname})
 ## Rename or move the remote file or directory @var{oldname} to @var{newname},
-##  over the FTP connection @var{f}.  @var{f} is an FTP object returned by the
-## ftp function.
+## over the FTP connection @var{f}.
+##
+## @var{f} is an FTP object returned by the ftp function.
 ## @end deftypefn
 
 function rename (f, oldname, newname)
--- a/scripts/@ftp/rmdir.m
+++ b/scripts/@ftp/rmdir.m
@@ -19,6 +19,7 @@
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} rmdir (@var{f}, @var{path})
 ## Remove the remote directory @var{path}, over the FTP connection @var{f}.
+##
 ## @var{f} is an FTP object returned by the @code{ftp} function.
 ## @end deftypefn