Skip to content

Commit e57235f

Browse files
committed
Added a better example to the "Usage" section of the README.
1 parent 99187af commit e57235f

1 file changed

Lines changed: 22 additions & 12 deletions

File tree

README.md

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,36 +3,46 @@ use. It abstracts away the FTP plumbing, such as establishing and closing
33
connections. Options include retrying your commands on flakey FTP servers, and
44
forced timeouts. FTP Secure (FTPS) is also supported.
55

6-
## Examples
7-
8-
# get a file with no username, password or other options
9-
ftp("localhost") { |ftp| ftp.get("some_file.txt") }
6+
## Usage
107

11-
# put a file to an FTP Secure (FTPS) server
12-
ftp("localhost", { username: "anonymous", password: "FTP_FTL", ftps: true }) do |ftp|
13-
ftp.put("some_file.txt")
14-
end
8+
# Mixin the +NiFTP+ module, which provides the +ftp+ method.
9+
class SomeObject
10+
include NiFTP
11+
12+
def ftp_stuff
13+
# put a file using no username, password or other options
14+
ftp("localhost") { |client| client.put("some_file.txt") }
15+
16+
# get a file on an FTP Secure (FTPS) server
17+
ftp("ftp.secure.com", { username: "some_user", password: "FTP_FTL",
18+
ftps: true }) do |client|
19+
client.resume = true
20+
file = client.get("some_file.txt")
21+
# ...
22+
end
23+
end
24+
end
1525

1626
## Options
1727

1828
* **username**: The user name, if required by the host (default: "").
1929
* **password**: The password, if required by the host (default: "").
2030
* **port**: The port for the host (default: 21).
2131
* **ftps**: Set to true if connecting to a FTP Secure server (default: false).
22-
* **retries**: The number of times to re-try the given FTP commands upon any
32+
* **retries**: The number of times to re-try the given FTP commands upon any
2333
exception, before raising the exception (Default: 1).
24-
* **timeout**: The number of seconds to wait before timing out (default: 5).
34+
* **timeout**: The number of seconds to wait before timing out (default: 5).
2535
Use 0 to disable the timeout.
2636
* **passive**: Set to false to prevent a connection in passive mode (default:
2737
true).
28-
38+
2939
## Caveats
3040

3141
Based on the way the [retryable]("https://github.com/nfedyashev/retryable")
3242
gem works, any FTP commands will be retried at least once upon any
3343
exception. Setting the :retries option to 0 will raise a runtime error. I'm
3444
fine with this for now as I prefer this behavior.
35-
45+
3646
## Testing
3747

3848
Tests are written with Shoulda and Mocha. This gem is tested in Ruby 1.8.7

0 commit comments

Comments
 (0)