net: make connect() accept options

This makes API even with tls.connect().
Refs #1983.

See also:
http://groups.google.com/group/nodejs-dev/msg/3b6dbcc4a9a82d99

Fixes #2487.

1 files changed, 35 insertions, 15 deletions

diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 1e3dfbdd4d..e3e319529a 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -15,7 +15,7 @@ event.
     { allowHalfOpen: false
     }
 
-If `allowHalfOpen` is `true`, then the socket won't automatically send FIN
+If `allowHalfOpen` is `true`, then the socket won't automatically send a FIN
 packet when the other end of the socket sends a FIN packet. The socket becomes
 non-readable, but still writable. You should call the `end()` method explicitly.
 See ['end'](#event_end_) event for more information.
@@ -49,25 +49,29 @@ Use `nc` to connect to a UNIX domain socket server:
 
     nc -U /tmp/echo.sock
 
-### net.connect(arguments...)
-### net.createConnection(arguments...)
+### net.connect(options, [cnnectionListener])
+### net.createConnection(options, [cnnectionListener])
 
-Construct a new socket object and opens a socket to the given location. When
-the socket is established the ['connect'](#event_connect_) event will be
+Constructs a new socket object and opens the socket to the given location.
+When the socket is established, the ['connect'](#event_connect_) event will be
 emitted.
 
-The arguments for these methods change the type of connection:
+For TCP sockets, `options` argument should be an object which specifies:
 
-* `net.connect(port, [host], [connectListener])`
-* `net.createConnection(port, [host], [connectListener])`
+  - `port`: Port the client should connect to (Required).
 
-  Creates a TCP connection to `port` on `host`. If `host` is omitted,
-  `'localhost'` will be assumed.
+  - `host`: Host the client should connect to. Defaults to `'localhost'`.
 
-* `net.connect(path, [connectListener])`
-* `net.createConnection(path, [connectListener])`
+For UNIX domain sockets, `options` argument should be an object which specifies:
 
-  Creates unix socket connection to `path`.
+  - `path`: Path the client should connect to (Required).
+
+Common options are:
+
+  - `allowHalfOpen`: if `true`, the socket won't automatically send
+    a FIN packet when the other end of the socket sends a FIN packet. 
+    Defaults to `false`.
+    See ['end'](#event_end_) event for more information.
 
 The `connectListener` parameter will be added as an listener for the
 ['connect'](#event_connect_) event.
@@ -75,7 +79,8 @@ The `connectListener` parameter will be added as an listener for the
 Here is an example of a client of echo server as described previously:
 
     var net = require('net');
-    var client = net.connect(8124, function() { //'connect' listener
+    var client = net.connect({port: 8124},
+        function() { //'connect' listener
       console.log('client connected');
       client.write('world!\r\n');
     });
@@ -90,7 +95,22 @@ Here is an example of a client of echo server as described previously:
 To connect on the socket `/tmp/echo.sock` the second line would just be
 changed to
 
-    var client = net.connect('/tmp/echo.sock', function() { //'connect' listener
+    var client = net.connect({path: '/tmp/echo.sock'},
+
+### net.connect(port, [host], [connectListener])
+### net.createConnection(port, [host], [connectListener])
+
+Creates a TCP connection to `port` on `host`. If `host` is omitted,
+`'localhost'` will be assumed.
+The `connectListener` parameter will be added as an listener for the
+['connect'](#event_connect_) event.
+
+### net.connect(path, [connectListener])
+### net.createConnection(path, [connectListener])
+
+Creates unix socket connection to `path`.
+The `connectListener` parameter will be added as an listener for the
+['connect'](#event_connect_) event.
 
 ---