Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Improve example and reformat data types in readme

  • Loading branch information...
commit c047eba5dd676128fe3931c99a3dcb3a30f431c7 1 parent b3e84a6
@mscdex authored
Showing with 103 additions and 124 deletions.
  1. +103 −124 README.md
View
227 README.md
@@ -19,81 +19,74 @@ Examples
* Get a pretty-printed directory listing of the current (remote) working directory:
- var FTPClient = require('./ftp'), util = require('util'), conn;
- function formatDate(d) {
- return (d.year < 10 ? '0' : '') + d.year + '-' + (d.month < 10 ? '0' : '')
- + d.month + '-' + (d.date < 10 ? '0' : '') + d.date;
+```javascript
+ var FTPClient = require('ftp');
+
+ // connect to localhost:21
+ var conn = new FTPClient();
+ conn.on('connect', function() {
+ // authenticate as anonymous
+ conn.auth(function(e) {
+ if (e)
+ throw e;
+ conn.list(function(e, entries) {
+ if (e)
+ throw e;
+ console.log('<start of directory list>');
+ for (var i=0,len=entries.length; i<len; ++i) {
+ if (typeof entries[i] === 'string')
+ console.log('<raw entry>: ' + entries[i]);
+ else {
+ if (entries[i].type === 'l')
+ entries[i].type = 'LINK';
+ else if (entries[i].type === '-')
+ entries[i].type = 'FILE';
+ else if (entries[i].type === 'd')
+ entries[i].type = 'DIR';
+ console.log(' ' + entries[i].type + ' ' + entries[i].size
+ + ' ' + entries[i].date + ' ' + entries[i].name);
+ }
}
- conn = new FTPClient({ host: '127.0.0.1' });
- conn.on('connect', function() {
- conn.auth(function(e) {
- if (e)
- throw e;
- conn.list(function(e, iter) {
- if (e)
- throw e;
- var begin = false;
- iter.on('entry', function(entry) {
- if (!begin) {
- begin = true;
- console.log('<start of directory list>');
- }
- if (entry.type === 'l')
- entry.type = 'LINK';
- else if (entry.type === '-')
- entry.type = 'FILE';
- else if (entry.type === 'd')
- entry.type = 'DIR.';
- console.log(' ' + entry.type + ' ' + entry.size + ' '
- + formatDate(entry.date) + ' ' + entry.name);
- });
- iter.on('raw', function(s) {
- console.log('<raw entry>: ' + s);
- });
- iter.on('end', function() {
- console.log('<end of directory list>');
- });
- iter.on('error', function(e) {
- console.log('ERROR during list(): ' + util.inspect(e));
- conn.end();
- });
- iter.on('success', function() {
- conn.end();
- });
- });
- });
- });
- conn.connect();
+ console.log('<end of directory list>');
+ conn.end();
+ });
+ });
+ });
+ conn.connect();
+```
* Download remote file 'foo.txt' and save it to the local file system:
- // Assume we have the same connection 'conn' from before and are currently
- // authenticated ...
- var fs = require('fs');
- conn.get('foo.txt', function(e, stream) {
- if (e)
- throw e;
- stream.on('success', function() {
- conn.end();
- });
- stream.on('error', function(e) {
- console.log('ERROR during get(): ' + util.inspect(e));
- conn.end();
- });
- stream.pipe(fs.createWriteStream('localfoo.txt'));
- });
+```javascript
+ // Assume we have the same connection 'conn' from before and are currently
+ // authenticated ...
+ var fs = require('fs');
+ conn.get('foo.txt', function(e, stream) {
+ if (e)
+ throw e;
+ stream.on('success', function() {
+ conn.end();
+ });
+ stream.on('error', function(e) {
+ console.log('ERROR during get(): ' + e);
+ conn.end();
+ });
+ stream.pipe(fs.createWriteStream('localfoo.txt'));
+ });
+```
* Upload local file 'foo.txt' to the server:
- // Assume we have the same connection 'conn' from before and are currently
- // authenticated ...
- var fs = require('fs');
- conn.put(fs.createReadStream('foo.txt'), 'remotefoo.txt', function(e) {
- if (e)
- throw e;
- conn.end();
- });
-
+```javascript
+ // Assume we have the same connection 'conn' from before and are currently
+ // authenticated ...
+ var fs = require('fs');
+ conn.put(fs.createReadStream('foo.txt'), 'remotefoo.txt', function(e) {
+ if (e)
+ throw e;
+ conn.end();
+ });
+```
API
===
@@ -105,11 +98,11 @@ _Events_
* **timeout**() - Fires if the connection timed out while attempting to connect to the server.
-* **close**(Boolean:hasError) - Fires when the connection is completely closed (similar to net.Socket's close event). The specified Boolean indicates whether the connection was terminated due to a transmission error or not.
+* **close**(<_boolean_>hasError) - Fires when the connection is completely closed (similar to net.Socket's close event). The specified boolean indicates whether the connection was terminated due to a transmission error or not.
* **end**() - Fires when the connection has ended.
-* **error**(Error:err) - Fires when an exception/error occurs (similar to net.Socket's error event). The given Error object represents the error raised.
+* **error**(<_Error_>err) - Fires when an exception/error occurs (similar to net.Socket's error event). The given Error object represents the error raised.
_Methods_
@@ -117,92 +110,78 @@ _Methods_
**\* Note 1: If a particular action results in an FTP-specific error, the error object supplied to the callback or 'error' event will contain 'code' and 'text' properties that contain the relevant FTP response code and the associated error text respectively.**
-**\* Note 2: Methods that return a Boolean success value will immediately return false if the action couldn't be carried out for reasons including: no server connection or the relevant command is not available on that particular server.**
+**\* Note 2: Methods that return a boolean success value will immediately return false if the action couldn't be carried out for reasons including: no server connection or the relevant command is not available on that particular server.**
### Standard
These are actions defined by the "original" FTP RFC (959) and are generally supported by all FTP servers.
-* **(constructor)**([Object:config]) - Creates and returns a new instance of the FTP module using the specified configuration object. Valid properties of the passed in object are:
- * **String:host** - The hostname or IP address of the FTP server. **Default:** "127.0.0.1"
- * **Integer:port** - The port of the FTP server. **Default:** 21
- * **Function:debug** - Accepts a string and gets called for debug messages **Default:** (no debug output)
- * **Integer:connTimeout** - The number of milliseconds to wait for a connection to be established. **Default:** 15000
+* **(constructor)**([<_object_>config]) - Creates and returns a new instance of the FTP module using the specified configuration object. Valid properties of the passed in object are:
+ * <_string_>host - The hostname or IP address of the FTP server. **Default:** "localhost"
+ * <_integer_>port - The port of the FTP server. **Default:** 21
+ * <_integer_>connTimeout - The number of milliseconds to wait for a connection to be established. **Default:** 15000
+ * <_function_>debug - Accepts a string and gets called for debug messages **Default:** (no debug output)
-* **connect**([Number:port],[String:host]) - _(void)_ - Attempts to connect to the FTP server. If the port and host are specified here, they override and overwrite those set in the constructor.
+* **connect**(<_integer_>port,][<_string_>host]) - _(void)_ - Attempts to connect to the FTP server. If the port and host are specified here, they override and overwrite those set in the constructor.
* **end**() - _(void)_ - Closes the connection to the server.
-* **auth**([String:username], [String:password], Function:callback) - _Boolean:success_ - Authenticates with the server (leave out username and password to log in as anonymous). The callback has these parameters: the error (undefined if none).
+* **auth**([<_string_>username, <_string_>password,] <_function_>callback) - <_boolean_>success - Authenticates with the server (leave out username and password to log in as anonymous). The callback has these parameters: the error (undefined if none).
-* **list**([String:path], [Boolean:streamList], Function:callback) - _Boolean:success_ - Retrieves the directory listing of the specified path. If path is not supplied, the current working directory is used. If streamList is set to true, an EventEmitter will be passed to the callback, otherwise an array of directory entries will be passed in. The callback has these parameters: the error (undefined if none) and an EventEmitter or array. The EventEmitter emits the following events:
+* **list**([<_string_>path,] [<_boolean_>streamList,] <_function_>callback) - <_boolean_>success_ - Retrieves the directory listing of the specified path. path defaults to the current working directory. If streamList is set to true, an EventEmitter will be passed to the callback, otherwise an array of objects (format shown below) and raw strings will be passed in to the callback. The callback has these parameters: the error (undefined if none) and a list source. If streaming the list, the following events are emitted on the list source:
- * **entry**(Object:entryInfo) - Fires for each file or subdirectory. entryInfo contains the following possible properties:
- * **String:name** - The name of the entry.
- * **String:type** - A single character denoting the entry type: 'd' for directory, '-' for file, or 'l' for symlink (UNIX only).
- * **String:size** - The size of the entry in bytes.
- * **Object:date** - The last modified date of the entry.
- * **Integer:month** - (1 through 12)
- * **Integer:date** - (1 through 31)
- * **Integer:year** - (1, 2, or 4-digits)
- * **[Object:time]** - The last modified time of the entry.
- * **Integer:hour** - (0 through 23)
- * **Integer:minute** - (0 through 59)
- * **Object:rights** - (UNIX only) - The various permissions for this entry.
- * **String:user** - Contains any combination of 'r', 'w', 'x', or an empty string.
- * **String:group** - Contains any combination of 'r', 'w', 'x', or an empty string.
- * **String:other** - Contains any combination of 'r', 'w', 'x', or an empty string.
- * **String:owner** - (UNIX only) - The user name or ID that this entry belongs to.
- * **String:group** - (UNIX only) - The group name or ID that this entry belongs to.
- * **[String:target]** - (UNIX only) - For symlink entries, this is the symlink's target.
+ * **entry**(<_object_>entryInfo) - Emitted for each file or subdirectory. entryInfo contains the following possible properties:
+ * <_string_>name - The name of the entry.
+ * <_string_>type - A single character denoting the entry type: 'd' for directory, '-' for file, or 'l' for symlink (UNIX only).
+ * <_string_>size - The size of the entry in bytes.
+ * <_Date_>date - The last modified date of the entry.
+ * <_object_>rights - **(*NIX only)** - The various permissions for this entry.
+ * <_string_>user - An empty string or any combination of 'r', 'w', 'x'.
+ * <_string_>group - An empty string or any combination of 'r', 'w', 'x'.
+ * <_string_>other - An empty string or any combination of 'r', 'w', 'x'.
+ * <_string_>owner - **(*NIX only)** - The user name or ID that this entry belongs to.
+ * <_string_>group - **(*NIX only)** - The group name or ID that this entry belongs to.
+ * <_string_>target - **(*NIX only)** - For symlink entries, this is the symlink's target.
- * **raw**(String:rawListing) - Fires when a directory listing couldn't be parsed and provides you with the raw directory listing line.
+ * **raw**(<_string_>rawListing) - Emitted when a directory listing couldn't be parsed and provides you with the raw directory listing from the server.
- * **end**() - Fires when the server has finished sending the directory listing, which may or may not be due to error.
+ * **end**() - Emitted when the server has finished sending the directory listing, which may or may not be due to error.
- * **success**() - Fires when the server says it successfully sent the entire directory listing.
+ * **success**() - Emitted when the server says it successfully sent the entire directory listing.
- * **error**(Error:err) - Fires when an error was encountered while obtaining the directory listing.
+ * **error**(<_Error_>err) - Emitted when an error was encountered while obtaining the directory listing.
-* **pwd**(Function:callback) - _Boolean:success_ - Retrieves the current working directory. The callback has these parameters: the error (undefined if none) and a string containing the current working directory.
+* **pwd**(<_function_>callback) - <_boolean_>success - Retrieves the current working directory. The callback has these parameters: the error (undefined if none) and a string containing the current working directory.
-* **cwd**(String:newPath, Function:callback) - _Boolean:success_ - Changes the current working directory to newPath. The callback has these parameters: the error (undefined if none).
+* **cwd**(<_string_>newPath, <_function_>callback) - <_boolean_>success - Changes the current working directory to newPath. The callback has these parameters: the error (undefined if none).
-* **cdup**(Function:callback) - _Boolean:success_ - Changes the working directory to the parent of the current directory. The callback has these parameters: the error (undefined if none).
+* **cdup**(<_function_>callback) - <_boolean_>success - Changes the working directory to the parent of the current directory. The callback has these parameters: the error (undefined if none).
-* **get**(String:filename, Function:callback) - _Boolean:success_ - Retrieves a file from the server. The callback has these parameters: the error (undefined if none) and a ReadableStream. The ReadableStream will emit 'success' if the file was successfully transferred.
+* **get**(<_string_>filename, <_function_>callback) - <_boolean_>success - Retrieves a file from the server. The callback has these parameters: the error (undefined if none) and a ReadableStream. The ReadableStream will emit 'success' if the file was successfully transferred.
-* **put**(ReadableStream:inStream, String:filename, Function:callback) - _Boolean:success_ - Sends a file to the server. The callback has these parameters: the error (undefined if none).
+* **put**(<_ReadableStream_>inStream, <_string_>filename, <_function_>callback) - <_boolean_>success - Sends a file to the server. The callback has these parameters: the error (undefined if none).
-* **append**(ReadableStream:inStream, String:filename, Function:callback) - _Boolean:success_ - Same as **put**, except if the file already exists, it will be appended to instead of overwritten.
+* **append**(<_ReadableStream_>inStream, <_string_>filename, <_function_>callback) - <_boolean_>success - Same as **put**, except if the file already exists, it will be appended to instead of overwritten.
-* **mkdir**(String:dirname, Function:callback) - _Boolean:success_ - Creates a new directory on the server. The callback has these parameters: the error (undefined if none) and a string containing the path of the newly created directory.
+* **mkdir**(<_string_>dirname, <_function_>callback) - <_boolean_>success - Creates a new directory on the server. The callback has these parameters: the error (undefined if none) and a string containing the path of the newly created directory.
-* **rmdir**(String:dirname, Function:callback) - _Boolean:success_ - Removes a directory on the server. The callback has these parameters: the error (undefined if none).
+* **rmdir**(<_string_>dirname, <_function_>callback) - <_boolean_>success - Removes a directory on the server. The callback has these parameters: the error (undefined if none).
-* **delete**(String:entryName, Function:callback) - _Boolean:success_ - Deletes a file on the server. The callback has these parameters: the error (undefined if none).
+* **delete**(<_string_>entryName, <_function_>callback) - <_boolean_>success - Deletes a file on the server. The callback has these parameters: the error (undefined if none).
-* **rename**(String:oldFilename, String:newFilename, Function:callback) - _Boolean:success_ - Renames a file on the server. The callback has these parameters: the error (undefined if none).
+* **rename**(<_string_>oldFilename, <_string_>newFilename, <_function_>callback) - <_boolean_>success - Renames a file on the server. The callback has these parameters: the error (undefined if none).
-* **system**(Function:callback) - _Boolean:success_ - Retrieves information about the server's operating system. The callback has these parameters: the error (undefined if none) and a string containing the text returned by the server.
+* **system**(<_function_>callback) - <_boolean_>success - Retrieves information about the server's operating system. The callback has these parameters: the error (undefined if none) and a string containing the text returned by the server.
-* **status**(Function:callback) - _Boolean:success_ - Retrieves human-readable information about the server's status. The callback has these parameters: the error (undefined if none) and a string containing the text returned by the server.
+* **status**(<_function_>callback) - <_boolean_>success - Retrieves human-readable information about the server's status. The callback has these parameters: the error (undefined if none) and a string containing the text returned by the server.
### Extended
These are actions defined by later RFCs that may not be supported by all FTP servers.
-* **size**(String:filename, Function:callback) - _Boolean:success_ - Retrieves the size of the specified file. The callback has these parameters: the error (undefined if none) and a string containing the size of the file in bytes.
-
-* **lastMod**(String:filename, Function:callback) - _Boolean:success_ - Retrieves the date and time the specified file was last modified. The callback has these parameters: the error (undefined if none) and an object:
+* **size**(<_string_>filename, <_function_>callback) - <_boolean_>success - Retrieves the size of the specified file. The callback has these parameters: the error (undefined if none) and a string containing the size of the file in bytes.
- * **Object:modTime**
- * **Integer:month** - (1 through 12)
- * **Integer:date** - (1 through 31)
- * **Integer:year** - (4-digit)
- * **Integer:hour** - (0 through 23)
- * **Integer:minute** - (0 through 59)
- * **Float:second** - (0 through 60 -- with 60 being used only at a leap second)
+* **lastMod**(<_string_>filename, <_function_>callback) - <_boolean_>success - Retrieves the date and time the specified file was last modified. The callback has these parameters: the error (undefined if none) and a _Date_ instance representing the last modified date.
-* **restart**(String/Integer:byteOffset, Function:callback) - _Boolean:success_ - Sets the file byte offset for the next file transfer action (get/put/append). The callback has these parameters: the error (undefined if none).
+* **restart**(<_mixed_>byteOffset, <_function_>callback) - <_boolean_>success - Sets the file byte offset for the next file transfer action (get/put/append). byteOffset can be an _integer_ or _string_. The callback has these parameters: the error (undefined if none).
Please sign in to comment.
Something went wrong with that request. Please try again.