Skip to content

Commit

Permalink
Improve example and reformat data types in readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@mscdex
mscdex committed Aug 2, 2012
1 parent b3e84a6 commit c047eba
Showing 1 changed file with 103 additions and 124 deletions.
227 changes: 103 additions & 124 deletions README.md
View file
Expand Up @@ -19,81 +19,74 @@ Examples


* Get a pretty-printed directory listing of the current (remote) working directory: * Get a pretty-printed directory listing of the current (remote) working directory:


var FTPClient = require('./ftp'), util = require('util'), conn; ```javascript
function formatDate(d) { var FTPClient = require('ftp');
return (d.year < 10 ? '0' : '') + d.year + '-' + (d.month < 10 ? '0' : '')
+ d.month + '-' + (d.date < 10 ? '0' : '') + d.date; // 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' }); console.log('<end of directory list>');
conn.on('connect', function() { conn.end();
conn.auth(function(e) { });
if (e) });
throw e; });
conn.list(function(e, iter) { conn.connect();
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();


* Download remote file 'foo.txt' and save it to the local file system: * 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 ```javascript
// authenticated ... // Assume we have the same connection 'conn' from before and are currently
var fs = require('fs'); // authenticated ...
conn.get('foo.txt', function(e, stream) { var fs = require('fs');
if (e) conn.get('foo.txt', function(e, stream) {
throw e; if (e)
stream.on('success', function() { throw e;
conn.end(); stream.on('success', function() {
}); conn.end();
stream.on('error', function(e) { });
console.log('ERROR during get(): ' + util.inspect(e)); stream.on('error', function(e) {
conn.end(); console.log('ERROR during get(): ' + e);
}); conn.end();
stream.pipe(fs.createWriteStream('localfoo.txt')); });
}); stream.pipe(fs.createWriteStream('localfoo.txt'));
});
```


* Upload local file 'foo.txt' to the server: * Upload local file 'foo.txt' to the server:


// Assume we have the same connection 'conn' from before and are currently ```javascript
// authenticated ... // Assume we have the same connection 'conn' from before and are currently
var fs = require('fs'); // authenticated ...
conn.put(fs.createReadStream('foo.txt'), 'remotefoo.txt', function(e) { var fs = require('fs');
if (e) conn.put(fs.createReadStream('foo.txt'), 'remotefoo.txt', function(e) {
throw e; if (e)
conn.end(); throw e;
}); conn.end();

});
```


API API
=== ===
Expand All @@ -105,104 +98,90 @@ _Events_


* **timeout**() - Fires if the connection timed out while attempting to connect to the server. * **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. * **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_ _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 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 ### Standard


These are actions defined by the "original" FTP RFC (959) and are generally supported by all FTP servers. 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: * **(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" * <_string_>host - The hostname or IP address of the FTP server. **Default:** "localhost"
* **Integer:port** - The port of the FTP server. **Default:** 21 * <_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
* **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. * **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: * **entry**(<_object_>entryInfo) - Emitted for each file or subdirectory. entryInfo contains the following possible properties:
* **String:name** - The name of the entry. * <_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_>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. * <_string_>size - The size of the entry in bytes.
* **Object:date** - The last modified date of the entry. * <_Date_>date - The last modified date of the entry.
* **Integer:month** - (1 through 12) * <_object_>rights - **(*NIX only)** - The various permissions for this entry.
* **Integer:date** - (1 through 31) * <_string_>user - An empty string or any combination of 'r', 'w', 'x'.
* **Integer:year** - (1, 2, or 4-digits) * <_string_>group - An empty string or any combination of 'r', 'w', 'x'.
* **[Object:time]** - The last modified time of the entry. * <_string_>other - An empty string or any combination of 'r', 'w', 'x'.
* **Integer:hour** - (0 through 23) * <_string_>owner - **(*NIX only)** - The user name or ID that this entry belongs to.
* **Integer:minute** - (0 through 59) * <_string_>group - **(*NIX only)** - The group name or ID that this entry belongs to.
* **Object:rights** - (UNIX only) - The various permissions for this entry. * <_string_>target - **(*NIX only)** - For symlink entries, this is the symlink's target.
* **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.


* **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 ### Extended


These are actions defined by later RFCs that may not be supported by all FTP servers. 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. * **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:


* **Object:modTime** * **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.
* **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)


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

0 comments on commit c047eba

Please sign in to comment.