1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix line wrapping in docs. Add tics for constants in docs text.

Browse Source
This commit is contained in:
Oleg Efimov 2010-11-18 15:00:24 +03:00 committed by Ryan Dahl
parent 57eb5cb9a0
commit 8b980d729c
9 changed files with 95 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/addons.markdown
View File

@ -69,7 +69,7 @@ like this:
Running `node-waf configure build` will create a file
`build/default/hello.node` which is our Addon.
`node-waf` is just http://code.google.com/p/waf/[WAF], the python-based build system. `node-waf` is
`node-waf` is just [WAF](http://code.google.com/p/waf/), the python-based build system. `node-waf` is
provided for the ease of users.
All Node addons must export a function called `init` with this signature:

3
doc/api/assert.markdown
View File

@ -45,4 +45,5 @@ Expects `block` not to throw an error.
### assert.ifError(value)
Tests if value is not a false value, throws if it is a true value. Useful when testing the first argument, `error` in callbacks.
Tests if value is not a false value, throws if it is a true value. Useful when
testing the first argument, `error` in callbacks.

67
doc/api/crypto.markdown
View File

@ -2,7 +2,9 @@
Use `require('crypto')` to access this module.
The crypto module requires OpenSSL to be available on the underlying platform. It offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or http connection.
The crypto module requires OpenSSL to be available on the underlying platform.
It offers a way of encapsulating secure credentials to be used as part
of a secure HTTPS net or http connection.
It also offers a set of wrappers for OpenSSL's hash, hmac, cipher, decipher, sign and verify methods.
@ -14,23 +16,28 @@ Creates a credentials object, with the optional details being a dictionary with
* `cert` : a string holding the PEM encoded certificate
* `ca` : either a string or list of strings of PEM encoded CA certificates to trust.
If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in
http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
If no 'ca' details are given, then node.js will use the default publicly trusted list of CAs as given in
<http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
### crypto.createHash(algorithm)
Creates and returns a hash object, a cryptographic hash with the given algorithm which can be used to generate hash digests.
Creates and returns a hash object, a cryptographic hash with the given algorithm
which can be used to generate hash digests.
`algorithm` is dependent on the available algorithms supported by the version of OpenSSL on the platform. Examples are sha1, md5, sha256, sha512, etc. On recent releases, `openssl list-message-digest-algorithms` will display the available digest algorithms.
`algorithm` is dependent on the available algorithms supported by the version
of OpenSSL on the platform. Examples are `'sha1'`, `'md5'`, `'sha256'`, `'sha512'`, etc.
On recent releases, `openssl list-message-digest-algorithms` will display the available digest algorithms.
### hash.update(data)
Updates the hash content with the given `data`. This can be called many times with new data as it is streamed.
Updates the hash content with the given `data`.
This can be called many times with new data as it is streamed.
### hash.digest(encoding='binary')
Calculates the digest of all of the passed data to be hashed. The `encoding` can be 'hex', 'binary' or 'base64'.
Calculates the digest of all of the passed data to be hashed.
The `encoding` can be `'hex'`, `'binary'` or `'base64'`.
### crypto.createHmac(algorithm, key)
@ -42,66 +49,82 @@ Creates and returns a hmac object, a cryptographic hmac with the given algorithm
### hmac.update(data)
Update the hmac content with the given `data`. This can be called many times with new data as it is streamed.
Update the hmac content with the given `data`.
This can be called many times with new data as it is streamed.
### hmac.digest(encoding='binary')
Calculates the digest of all of the passed data to the hmac. The `encoding` can be 'hex', 'binary' or 'base64'.
Calculates the digest of all of the passed data to the hmac.
The `encoding` can be `'hex'`, `'binary'` or `'base64'`.
### crypto.createCipher(algorithm, key)
Creates and returns a cipher object, with the given algorithm and key.
`algorithm` is dependent on OpenSSL, examples are aes192, etc. On recent releases, `openssl list-cipher-algorithms` will display the available cipher algorithms.
`algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc.
On recent releases, `openssl list-cipher-algorithms` will display the available cipher algorithms.
### cipher.update(data, input_encoding='binary', output_encoding='binary')
Updates the cipher with `data`, the encoding of which is given in `input_encoding` and can be 'utf8', 'ascii' or 'binary'. The `output_encoding` specifies the output format of the enciphered data, and can be 'binary', 'base64' or 'hex'.
Updates the cipher with `data`, the encoding of which is given in `input_encoding`
and can be `'utf8'`, `'ascii'` or `'binary'`. The `output_encoding` specifies
the output format of the enciphered data, and can be `'binary'`, `'base64'` or `'hex'`.
Returns the enciphered contents, and can be called many times with new data as it is streamed.
### cipher.final(output_encoding='binary')
Returns any remaining enciphered contents, with `output_encoding` being one of: 'binary', 'ascii' or 'utf8'.
Returns any remaining enciphered contents, with `output_encoding` being one of: `'binary'`, `'ascii'` or `'utf8'`.
### crypto.createDecipher(algorithm, key)
Creates and returns a decipher object, with the given algorithm and key. This is the mirror of the cipher object above.
Creates and returns a decipher object, with the given algorithm and key.
This is the mirror of the cipher object above.
### decipher.update(data, input_encoding='binary', output_encoding='binary')
Updates the decipher with `data`, which is encoded in 'binary', 'base64' or 'hex'. The `output_decoding` specifies in what format to return the deciphered plaintext - either 'binary', 'ascii' or 'utf8'.
Updates the decipher with `data`, which is encoded in `'binary'`, `'base64'` or `'hex'`.
The `output_decoding` specifies in what format to return the deciphered plaintext: `'binary'`, `'ascii'` or `'utf8'`.
### decipher.final(output_encoding='binary')
Returns any remaining plaintext which is deciphered, with `output_encoding' being one of: 'binary', 'ascii' or 'utf8'.
Returns any remaining plaintext which is deciphered,
with `output_encoding' being one of: `'binary'`, `'ascii'` or `'utf8'`.
### crypto.createSign(algorithm)
Creates and returns a signing object, with the given algorithm. On recent OpenSSL releases, `openssl list-public-key-algorithms` will display the available signing algorithms. Examples are 'RSA-SHA256'.
Creates and returns a signing object, with the given algorithm.
On recent OpenSSL releases, `openssl list-public-key-algorithms` will display
the available signing algorithms. Examples are `'RSA-SHA256'`.
### signer.update(data)
Updates the signer object with data. This can be called many times with new data as it is streamed.
Updates the signer object with data.
This can be called many times with new data as it is streamed.
### signer.sign(private_key, output_format='binary')
Calculates the signature on all the updated data passed through the signer. `private_key` is a string containing the PEM encoded private key for signing.
Calculates the signature on all the updated data passed through the signer.
`private_key` is a string containing the PEM encoded private key for signing.
Returns the signature in `output_format` which can be 'binary', 'hex' or 'base64'
Returns the signature in `output_format` which can be `'binary'`, `'hex'` or `'base64'`.
### crypto.createVerify(algorithm)
Creates and returns a verification object, with the given algorithm. This is the mirror of the signing object above.
Creates and returns a verification object, with the given algorithm.
This is the mirror of the signing object above.
### verifier.update(data)
Updates the verifyer object with data. This can be called many times with new data as it is streamed.
Updates the verifyer object with data.
This can be called many times with new data as it is streamed.
### verifier.verify(public_key, signature, signature_format='binary')
Verifies the signed data by using the `public_key` which is a string containing the PEM encoded public key, and `signature`, which is the previously calculates signature for the data, in the `signature_format` which can be 'binary', 'hex' or 'base64'.
Verifies the signed data by using the `public_key` which is a string containing
the PEM encoded public key, and `signature`, which is the previously calculates
signature for the data, in the `signature_format` which can be `'binary'`, `'hex'` or `'base64'`.
Returns true or false depending on the validity of the signature for the data and public key.

27
doc/api/http.markdown
View File

@ -123,9 +123,14 @@ when the server has been bound.
### server.setSecure(credentials)
Enables HTTPS support for the server, with the crypto module credentials specifying the private key and certificate of the server, and optionally the CA certificates for use in client authentication.
Enables HTTPS support for the server, with the crypto module credentials
specifying the private key and certificate of the server, and optionally
the CA certificates for use in client authentication.
If the credentials hold one or more CA certificates, then the server will request for the client to submit a client certificate as part of the HTTPS connection handshake. The validity and content of this can be accessed via verifyPeer() and getPeerCertificate() from the server's request.connection.
If the credentials hold one or more CA certificates, then the server will request
for the client to submit a client certificate as part of the HTTPS connection handshake.
The validity and content of this can be accessed via `verifyPeer()`
and `getPeerCertificate()` from the server's `request.connection`.
### server.close()
@ -134,8 +139,8 @@ Stops the server from accepting new connections.
## http.ServerRequest
This object is created internally by a HTTP server--not by
the user--and passed as the first argument to a `'request'` listener.
This object is created internally by a HTTP server -- not by
the user -- and passed as the first argument to a `'request'` listener.
This is an `EventEmitter` with the following events:
@ -382,9 +387,13 @@ Constructs a new HTTP client. `port` and
`host` refer to the server to be connected to. A
stream is not established until a request is issued.
`secure` is an optional boolean flag to enable https support and `credentials` is an optional credentials object from the crypto module, which may hold the client's private key, certificate, and a list of trusted CA certificates.
`secure` is an optional boolean flag to enable https support and `credentials` is an optional
credentials object from the crypto module, which may hold the client's private key,
certificate, and a list of trusted CA certificates.
If the connection is secure, but no explicit CA certificates are passed in the credentials, then node.js will default to the publicly trusted list of CA certificates, as given in http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt
If the connection is secure, but no explicit CA certificates are passed
in the credentials, then node.js will default to the publicly trusted list
of CA certificates, as given in <http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt>.
### client.request(method='GET', path, [request_headers])
@ -407,11 +416,13 @@ the user to stream a body to the server with `request.write()`.)
### client.verifyPeer()
Returns true or false depending on the validity of the server's certificate in the context of the defined or default list of trusted CA certificates.
Returns true or false depending on the validity of the server's certificate
in the context of the defined or default list of trusted CA certificates.
### client.getPeerCertificate()
Returns a JSON structure detailing the server's certificate, containing a dictionary with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to'
Returns a JSON structure detailing the server's certificate, containing a dictionary
with keys for the certificate `'subject'`, `'issuer'`, `'valid_from'` and `'valid_to'`.
## http.ClientRequest

9
doc/api/net.markdown
View File

@ -168,7 +168,7 @@ for use in peer authentication.
If the credentials hold one ore more CA certificates, then the stream will request
for the peer to submit a client certificate as part of the SSL connection handshake.
The validity and content of this can be accessed via verifyPeer() and getPeerCertificate().
The validity and content of this can be accessed via `verifyPeer()` and `getPeerCertificate()`.
#### stream.verifyPeer()
@ -178,7 +178,7 @@ context of the defined or default list of trusted CA certificates.
#### stream.getPeerCertificate()
Returns a JSON structure detailing the peer's certificate, containing a dictionary
with keys for the certificate 'subject', 'issuer', 'valid\_from' and 'valid\_to'
with keys for the certificate `'subject'`, `'issuer'`, `'valid_from'` and `'valid_to'`.
#### stream.write(data, encoding='ascii')
@ -315,9 +315,8 @@ following this event.
`function (had_error) { }`
Emitted once the stream is fully closed. The argument `had_error` is a boolean which says if
the stream was closed due to a transmission
error.
Emitted once the stream is fully closed. The argument `had_error` is a boolean
which says if the stream was closed due to a transmission error.
---

3
doc/api/path.markdown
View File

@ -74,7 +74,8 @@ the first character, then it returns an empty string. Examples:
### path.exists(p, [callback])
Test whether or not the given path exists. Then, call the `callback` argument with either true or false. Example:
Test whether or not the given path exists. Then, call the `callback` argument
with either true or false. Example:
path.exists('/etc/passwd', function (exists) {
util.debug(exists ? "it's there" : "no passwd!");

14
doc/api/process.markdown
View File

@ -170,14 +170,17 @@ The shell that executed node should see the exit code as 1.
### process.getgid()
Gets the group identity of the process. (See getgid(2).) This is the numerical group id, not the group name.
Gets the group identity of the process. (See getgid(2).)
This is the numerical group id, not the group name.
console.log('Current gid: ' + process.getgid());
### process.setgid(id)
Sets the group identity of the process. (See setgid(2).) This accepts either a numerical ID or a groupname string. If a groupname is specified, this method blocks while resolving it to a numerical ID.
Sets the group identity of the process. (See setgid(2).) This accepts either
a numerical ID or a groupname string. If a groupname is specified, this method
blocks while resolving it to a numerical ID.
console.log('Current gid: ' + process.getgid());
try {
@ -191,14 +194,17 @@ Sets the group identity of the process. (See setgid(2).) This accepts either a
### process.getuid()
Gets the user identity of the process. (See getuid(2).) This is the numerical userid, not the username.
Gets the user identity of the process. (See getuid(2).)
This is the numerical userid, not the username.
console.log('Current uid: ' + process.getuid());
### process.setuid(id)
Sets the user identity of the process. (See setuid(2).) This accepts either a numerical ID or a username string. If a username is specified, this method blocks while resolving it to a numerical ID.
Sets the user identity of the process. (See setuid(2).) This accepts either
a numerical ID or a username string. If a username is specified, this method
blocks while resolving it to a numerical ID.
console.log('Current uid: ' + process.getuid());
try {

15
doc/api/querystring.markdown
View File

@ -1,10 +1,12 @@
## Query String
This module provides utilities for dealing with query strings. It provides the following methods:
This module provides utilities for dealing with query strings.
It provides the following methods:
### querystring.stringify(obj, sep='&', eq='=')
Serialize an object to a query string. Optionally override the default separator and assignment characters.
Serialize an object to a query string.
Optionally override the default separator and assignment characters.
Example:
@ -18,7 +20,8 @@ Example:
### querystring.parse(str, sep='&', eq='=')
Deserialize a query string to an object. Optionally override the default separator and assignment characters.
Deserialize a query string to an object.
Optionally override the default separator and assignment characters.
Example:
@ -28,8 +31,10 @@ Example:
### querystring.escape
The escape function used by `querystring.stringify`, provided so that it could be overridden if necessary.
The escape function used by `querystring.stringify`,
provided so that it could be overridden if necessary.
### querystring.unescape
The unescape function used by `querystring.parse`, provided so that it could be overridden if necessary.
The unescape function used by `querystring.parse`,
provided so that it could be overridden if necessary.

4
doc/api/repl.markdown
View File

@ -95,8 +95,8 @@ Things in the `context` object appear as local within the REPL:
There are a few special REPL commands:
- `.break` - While inputting a multi-line expression, sometimes you get lost or just don't care
about completing it. `.break` will start over.
- `.break` - While inputting a multi-line expression, sometimes you get lost
or just don't care about completing it. `.break` will start over.
- `.clear` - Resets the `context` object to an empty object and clears any multi-line expression.
- `.exit` - Close the I/O stream, which will cause the REPL to exit.
- `.help` - Show this list of special commands.