ref - npm Package Compare versions

Comparing version 0.0.20 to 0.1.0

History.md

 
+0.1.0 / 2012-07-22
+==================
+
+ - initial release of the documentation (http://tootallnate.github.com/ref)
+ - binding: make "endianness" and "NULL" be 'frozen'
+ - lib: make derefType() throw an Error when given a "type" with indirection 1
+ - augment the Buffer#inspect() function to print out the memory address as well
+
 0.0.20 / 2012-06-27
@@ -3,0 +11,0 @@ ===================

lib/ref.js

@@ -8,12 +8,294 @@
 /**
+ * A `Buffer` that references the C NULL pointer. That is, its memory address
+ * points to 0. Its `length` is 0 because accessing any data from this buffer
+ * would cause a _segmentation fault_.
+ *
+ * ```
+ * console.log(ref.NULL);
+ * <SlowBuffer@0x0 >
+ * ```
+ *
+ * @name NULL
+ * @type Buffer
+ */
+
+/**
+ * A string that represents the native endianness of the machine's processor.
+ * The possible values are either `"LE"` or `"BE"`.
+ *
+ * ```
+ * console.log(ref.endianness);
+ * 'LE'
+ * ```
+ *
+ * @name endianness
+ * @type String
+ */
+
+/**
+ * Accepts a `Buffer` instance and returns the memory address of the buffer
+ * instance.
+ *
+ * ```
+ * console.log(ref.address(new Buffer(1)));
+ * 4320233616
+ *
+ * console.log(ref.address(ref.NULL)));
+ * 0
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to get the memory address of.
+ * @return {Number} The memory address the buffer instance.
+ * @name address
+ * @type method
+ */
+
+/**
+ * Accepts a `Buffer` instance and returns _true_ if the buffer represents the
+ * NULL pointer, _false_ otherwise.
+ *
+ * ```
+ * console.log(ref.isNull(new Buffer(1)));
+ * false
+ *
+ * console.log(ref.isNull(ref.NULL));
+ * true
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to check for NULL.
+ * @return {Boolean} true or false.
+ * @name isNull
+ * @type method
+ */
+
+/**
+ * Reads a JavaScript Object that has previously been written to the given
+ * _buffer_ at the given _offset_.
+ *
+ * ```
+ * var obj = { foo: 'bar' };
+ * var buf = ref.alloc('Object', obj);
+ *
+ * var obj2 = ref.readObject(buf, 0);
+ * console.log(obj === obj2);
+ * true
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to read an Object from.
+ * @param {Number} offset The offset to begin reading from.
+ * @return {Object} The Object that was read from _buffer_.
+ * @name readObject
+ * @type method
+ */
+
+/**
+ * Reads a Buffer instance from the given _buffer_ at the given _offset_.
+ * The _size_ parameter specifies the `length` of the returned Buffer instance,
+ * which defaults to __0__.
+ *
+ * ```
+ * var buf = new Buffer('hello world');
+ * var pointer = ref.alloc('pointer');
+ *
+ * var buf2 = ref.readPointer(pointer, 0, buf.length);
+ * console.log(buf.toString());
+ * 'hello world'
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to read a Buffer from.
+ * @param {Number} offset The offset to begin reading from.
+ * @return {Buffer} The Buffer instance that was read from _buffer_.
+ * @name readPointer
+ * @type method
+ */
+
+/**
+ * Returns a JavaScript String read from _buffer_ at the given _offset_. The
+ * C String is read until the first NULL byte, which indicates the end of the
+ * String.
+ *
+ * This function can read beyond the `length` of a Buffer.
+ *
+ * ```
+ * var buf = new Buffer('hello\0world\0');
+ *
+ * var str = ref.readCString(buf, 0);
+ * console.log(str);
+ * 'hello'
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to read a Buffer from.
+ * @param {Number} offset The offset to begin reading from.
+ * @return {String} The String that was read from _buffer_.
+ * @name readCString
+ * @type method
+ */
+
+/**
+ * Returns a big-endian signed 64-bit int read from _buffer_ at the given
+ * _offset_.
+ *
+ * If the returned value will fit inside a JavaScript Number without losing
+ * precision, then a Number is returned, otherwise a String is returned.
+ *
+ * ```
+ * var buf = ref.alloc('int64');
+ * ref.writeInt64BE(buf, 0, '9223372036854775807');
+ *
+ * var val = ref.readInt64BE(buf, 0)
+ * console.log(val)
+ * '9223372036854775807'
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to read a Buffer from.
+ * @param {Number} offset The offset to begin reading from.
+ * @return {Number|String} The Number or String that was read from _buffer_.
+ * @name readInt64BE
+ * @type method
+ */
+
+/**
+ * Returns a little-endian signed 64-bit int read from _buffer_ at the given
+ * _offset_.
+ *
+ * If the returned value will fit inside a JavaScript Number without losing
+ * precision, then a Number is returned, otherwise a String is returned.
+ *
+ * ```
+ * var buf = ref.alloc('int64');
+ * ref.writeInt64LE(buf, 0, '9223372036854775807');
+ *
+ * var val = ref.readInt64LE(buf, 0)
+ * console.log(val)
+ * '9223372036854775807'
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to read a Buffer from.
+ * @param {Number} offset The offset to begin reading from.
+ * @return {Number|String} The Number or String that was read from _buffer_.
+ * @name readInt64LE
+ * @type method
+ */
+
+/**
+ * Returns a big-endian unsigned 64-bit int read from _buffer_ at the given
+ * _offset_.
+ *
+ * If the returned value will fit inside a JavaScript Number without losing
+ * precision, then a Number is returned, otherwise a String is returned.
+ *
+ * ```
+ * var buf = ref.alloc('uint64');
+ * ref.writeUInt64BE(buf, 0, '18446744073709551615');
+ *
+ * var val = ref.readUInt64BE(buf, 0)
+ * console.log(val)
+ * '18446744073709551615'
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to read a Buffer from.
+ * @param {Number} offset The offset to begin reading from.
+ * @return {Number|String} The Number or String that was read from _buffer_.
+ * @name readUInt64BE
+ * @type method
+ */
+
+/**
+ * Returns a little-endian unsigned 64-bit int read from _buffer_ at the given
+ * _offset_.
+ *
+ * If the returned value will fit inside a JavaScript Number without losing
+ * precision, then a Number is returned, otherwise a String is returned.
+ *
+ * ```
+ * var buf = ref.alloc('uint64');
+ * ref.writeUInt64LE(buf, 0, '18446744073709551615');
+ *
+ * var val = ref.readUInt64LE(buf, 0)
+ * console.log(val)
+ * '18446744073709551615'
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to read a Buffer from.
+ * @param {Number} offset The offset to begin reading from.
+ * @return {Number|String} The Number or String that was read from _buffer_.
+ * @name readUInt64LE
+ * @type method
+ */
+
+/**
+ * Writes the _input_ Number or String as a big-endian signed 64-bit int into
+ * _buffer_ at the given _offset_.
+ *
+ * ```
+ * var buf = ref.alloc('int64');
+ * ref.writeInt64BE(buf, 0, '9223372036854775807');
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to write to.
+ * @param {Number} offset The offset to begin writing from.
+ * @param {Number|String} input This String or Number which gets written.
+ * @name writeInt64BE
+ * @type method
+ */
+
+/**
+ * Writes the _input_ Number or String as a little-endian signed 64-bit int into
+ * _buffer_ at the given _offset_.
+ *
+ * ```
+ * var buf = ref.alloc('int64');
+ * ref.writeInt64LE(buf, 0, '9223372036854775807');
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to write to.
+ * @param {Number} offset The offset to begin writing from.
+ * @param {Number|String} input This String or Number which gets written.
+ * @name writeInt64LE
+ * @type method
+ */
+
+/**
+ * Writes the _input_ Number or String as a big-endian unsigned 64-bit int into
+ * _buffer_ at the given _offset_.
+ *
+ * ```
+ * var buf = ref.alloc('uint64');
+ * ref.writeUInt64BE(buf, 0, '18446744073709551615');
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to write to.
+ * @param {Number} offset The offset to begin writing from.
+ * @param {Number|String} input This String or Number which gets written.
+ * @name writeUInt64BE
+ * @type method
+ */
+
+/**
+ * Writes the _input_ Number or String as a little-endian unsigned 64-bit int
+ * into _buffer_ at the given _offset_.
+ *
+ * ```
+ * var buf = ref.alloc('uint64');
+ * ref.writeUInt64LE(buf, 0, '18446744073709551615');
+ * ```
+ *
+ * @param {Buffer} buffer The buffer to write to.
+ * @param {Number} offset The offset to begin writing from.
+ * @param {Number|String} input This String or Number which gets written.
+ * @name writeUInt64LE
+ * @type method
+ */
+
+/**
  * Returns a new clone of the given "type" object, with its
- * "indirection" level incremented by 1.
+ * `indirection` level incremented by **1**.
  *
- * So for example, to create a type representing a `void *`:
+ * Say you wanted to create a type representing a `void *`:
  *
- * ``` js
- * var voidPtrType = ref.refType(ref.types.void)
  * ```
+ * var voidPtrType = ref.refType(ref.types.void);
+ * ```
  *
- * @param {Object} type
+ * @param {Object|String} type The "type" object to create a reference type from. Strings get coerced first.
  * @return {Object} The new "type" object with its `indirection` incremented by 1.
@@ -34,5 +316,5 @@ */
  * Returns a new clone of the given "type" object, with its
- * "indirection" level decremented by 1.
+ * `indirection` level decremented by 1.
  *
- * @param {Object} type
+ * @param {Object|String} type The "type" object to create a dereference type from. Strings get coerced first.
  * @return {Object} The new "type" object with its `indirection` decremented by 1.
@@ -43,2 +325,5 @@ */
   var _type = exports.coerceType(type)
+  if (_type.indirection === 1) {
+    throw new Error('Cannot create deref\'d type for type with indirection 1')
+  }
   var rtn = Object.getPrototypeOf(_type)
@@ -53,9 +338,22 @@ if (rtn.indirection !== _type.indirection - 1) {
 /**
- * Coerces a "type" object from a String or a real "type" object. So:
+ * Coerces a "type" object from a String or an actual "type" object. String values
+ * are looked up from the `ref.types` Object. So:
  *
- *   * "int" gets coerced into `ref.types.int`.
- *   * "int *" gets translated into `ref.refType(ref.types.int)`
- *   * `ref.types.int` gets translated into `ref.types.int` (itself)
+ *   * `"int"` gets coerced into `ref.types.int`.
+ *   * `"int *"` gets translated into `ref.refType(ref.types.int)`
+ *   * `ref.types.int` gets translated into `ref.types.int` (returns itself)
  *
- * @param {Object|String} type
+ * Throws an Error if no valid "type" object could be determined. Most `ref`
+ * functions use this function under the hood, so anywhere a "type" object is
+ * expected, a String may be passed as well, including simply setting the
+ * `buffer.type` property.
+ *
+ * ```
+ * var type = ref.coerceType('int **');
+ *
+ * console.log(type.indirection);
+ * 3
+ * ```
+ *
+ * @param {Object|String} type The "type" Object or String to coerce.
  * @return {Object} A "type" object
@@ -125,9 +423,10 @@ */
  * Calls the `get()` function of the Buffer's current "type" (or the
- * passed in type when present) at the given offset. This function handles
- * checking the "indirection" level and returning a proper "dereferenced"
- * Bufffer instance when necessary.
+ * passed in _type_ if present) at the given _offset_.
  *
+ * This function handles checking the "indirection" level and returning a
+ * proper "dereferenced" Bufffer instance when necessary.
+ *
  * @param {Buffer} buffer The Buffer instance to read from.
  * @param {Number} offset (optional) The offset on the Buffer to start reading from. Defaults to 0.
- * @param {Object} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
+ * @param {Object|String} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
  * @return {?} Whatever value the "type" used when reading returns.
@@ -160,10 +459,12 @@ */
 /**
- * Calls the `set()` function of the given Buffer's "type" (or the given
- * "type" object if present) at the given offset with the given "value" to set.
+ * Calls the `set()` function of the Buffer's current "type" (or the
+ * passed in _type_ if present) at the given _offset_.
  *
+ * This function handles checking the "indirection" level writing a pointer rather
+ * than calling the `set()` function if the indirection is greater than 1.
+ *
  * @param {Buffer} buffer The Buffer instance to write to.
  * @param {Number} offset The offset on the Buffer to start writing to.
  * @param {?} value The value to write to the Buffer instance.
- * @param {Object} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
- * @return {undefined}
+ * @param {Object|String} type (optional) The "type" object to use when reading. Defaults to calling `getType()` on the buffer.
  */
@@ -181,3 +482,3 @@
   debug('set(): (offset: %d)', offset, buffer, value)
-  assert(type.indirection > 0, '"indirection" level must be at least 1')
+  assert(type.indirection >= 1, '"indirection" level must be at least 1')
   if (type.indirection === 1) {
@@ -200,4 +501,4 @@ type.set(buffer, offset, value)
  *
- * @param {Object} type The "type" object to allocate.
- * @param {?} value (optional) The initial value set on the returned Buffer.
+ * @param {Object|String} type The "type" object to allocate. Strings get coerced first.
+ * @param {?} value (optional) The initial value set on the returned Buffer, using _type_'s `set()` function.
  * @return {Buffer} A new Buffer instance with it's `type` set to "type", and (optionally) "value" written to it.
@@ -225,8 +526,16 @@ */
 /**
- * Returns a new Buffer instance with the given String written to it in the
- * given encoding (defaults to 'utf8'). The Buffer is 1 byte longer than the
+ * Returns a new `Buffer` instance with the given String written to it with the
+ * given encoding (defaults to __'utf8'__). The buffer is 1 byte longer than the
  * string itself, and is NUL terminated.
  *
- * @param {String} string The JS string to be converted to a C string.
- * @param {String} encoding (optional) The encoding to use for the C string. Defaults to 'utf8'.
+ * ```
+ * var buf = ref.allocCString('hello world');
+ *
+ * console.log(buf.toString());
+ * 'hello world\u0000'
+ * ```
+ *
+ * @param {String} string The JavaScript string to be converted to a C string.
+ * @param {String} encoding (optional) The encoding to use for the C string. Defaults to __'utf8'__.
+ * @return {Buffer} The new `Buffer` instance with the specified String wrtten to it, and a trailing NUL byte.
  */
@@ -247,3 +556,3 @@
  * Writes the given string as a C String (NULL terminated) to the given buffer
- * at the given offset. "encoding" is optional and defaults to 'utf8'.
+ * at the given offset. "encoding" is optional and defaults to __'utf8'__.
  *
@@ -255,4 +564,4 @@ * Unlike `readCString()`, this function requires the buffer to actually have the
  * @param {Number} offset The offset of the buffer to begin writing at.
- * @param {String} string The JS String to write that will be written to the buffer.
- * @param {String} encoding (optional) The encoding to read the C string as. Defaults to 'utf8'.
+ * @param {String} string The JavaScript String to write that will be written to the buffer.
+ * @param {String} encoding (optional) The encoding to read the C string as. Defaults to __'utf8'__.
  */
@@ -320,3 +629,3 @@
  * @param {Buffer} buffer A Buffer instance to create a reference to.
- * @return {Buffer} A new Buffer instance pointing to "buffer".
+ * @return {Buffer} A new Buffer instance pointing to _buffer_.
  */
@@ -331,10 +640,21 @@
 /**
- * `deref()` acceps a Buffer instance and attempts to "dereference" it.
- * That is, first it checks the "indirection" count, and if it's greater than
- * 0 then it merely returns another Buffer, but with one level less indirection.
- * When the buffer is at indirection 0, or undefined, then it checks for "type"
- * which should be an Object with it's own "get()" function.
+ * Acceps a Buffer instance and attempts to "dereference" it.
+ * That is, first it checks the "indirection" count of _buffer_'s "type", and if
+ * it's greater than __1__ then it merely returns another Buffer, but with one
+ * level less `indirection`.
  *
- * @param {Buffer} buffer A Buffer instance to read a reference from.
- * @return {?} The returned value after dereferencing "buffer".
+ * When _buffer_'s indirection is at __1__, then it checks for `buffer.type`
+ * which should be an Object with its own `get()` function.
+ *
+ * ```
+ * var buf = ref.alloc('int', 6);
+ *
+ * var val = ref.deref(buf);
+ * console.log(val);
+ * 6
+ * ```
+ *
+ *
+ * @param {Buffer} buffer A Buffer instance to dereference.
+ * @return {?} The returned value after dereferencing _buffer_.
  */
@@ -348,8 +668,8 @@
 /**
- * `attach()` is meant for retaining references to Objects/Buffers in JS-land
- * from calls to `_writeObject()` and `_writePointer()`. C-land doesn't retain the
- * source Buffer in `writePointer()`, and `writeObject()` uses a weak reference
- * when writing the Object, so attaching afterwards in necessary. See below...
+ * Attaches _object_ to _buffer_ such that it prevents _object_ from being garbage
+ * collected until _buffer_ does.
  *
- * @private true
+ * @param {Buffer} buffer A Buffer instance to attach _object_ to.
+ * @param {Object|Buffer} object An Object or Buffer to prevent from being garbage collected until _buffer_ does.
+ * @api private
  */
@@ -365,7 +685,10 @@
 /**
- * The private `writeObject()` function does the actual writing of the given
- * Object to the given Buffer instance. This version does not _attach_ the Object
- * to the Buffer, which is potentially unsafe.
+ * Same as `ref.writeObject()`, except that this version does not _attach_ the
+ * Object to the Buffer, which is potentially unsafe if the garbage collector
+ * runs.
  *
- * @private true
+ * @param {Buffer} buffer A Buffer instance to write _object_ to.
+ * @param {Number} offset The offset on the Buffer to start writing at.
+ * @param {Object} object The Object to be written into _buffer_.
+ * @api private
  */
@@ -376,4 +699,16 @@
 /**
- * Overwrite the native "writeObject" function so that it keeps a ref to the
- * passed in Object in JS-land by adding it to the Bufer's _refs array.
+ * Writes a pointer to _object_ into _buffer_ at the specified _offset.
+ *
+ * This function "attaches" _object_ to _buffer_ to prevent it from being garbage
+ * collected.
+ *
+ * ```
+ * var buf = ref.alloc('Object');
+ * ref.writeObject(buf, 0, { foo: 'bar' });
+ *
+ * ```
+ *
+ * @param {Buffer} buffer A Buffer instance to write _object_ to.
+ * @param {Number} offset The offset on the Buffer to start writing at.
+ * @param {Object} object The Object to be written into _buffer_.
  */
@@ -388,7 +723,10 @@
 /**
- * The private `writePointer()` function does the actual writing of the given
- * pointer Buffer to the target Buffer instance. This version does not _attach_
- * the pointer Buffer to the target Buffer, which is potentially unsafe.
+ * Same as `ref.writePointer()`, except that this version does not attach
+ * _pointer_ to _buffer_, which is potentially unsafe if the garbage collector
+ * runs.
  *
- * @private true
+ * @param {Buffer} buffer A Buffer instance to write _pointer to.
+ * @param {Number} offset The offset on the Buffer to start writing at.
+ * @param {Buffer} pointer The Buffer instance whose memory address will be written to _buffer_.
+ * @api private
  */
@@ -399,4 +737,16 @@
 /**
- * Overwrite the native "writePointer" function so that it keeps a ref to the
- * passed in Buffer in JS-land by adding it to the Bufer's _refs array.
+ * Writes the memory address of _pointer_ to _buffer_ at the specified _offset_.
+ *
+ * This function "attaches" _object_ to _buffer_ to prevent it from being garbage
+ * collected.
+ *
+ * ```
+ * var someBuffer = new Buffer('whatever');
+ * var buf = ref.alloc('pointer');
+ * ref.writePointer(buf, 0, someBuffer);
+ * ```
+ *
+ * @param {Buffer} buffer A Buffer instance to write _pointer to.
+ * @param {Number} offset The offset on the Buffer to start writing at.
+ * @param {Buffer} pointer The Buffer instance whose memory address will be written to _buffer_.
  */
@@ -411,7 +761,10 @@
 /**
- * Overwrite the native "reinterpret" function so that the reinterpreted buffer
- * retains a reference to the original buffer, so that it doesn't get GC'd while
- * the reinterpreted buffer is still watching it.
+ * Same as `ref.reinterpret()`, except that this version does not attach
+ * _buffer_ to the returned Buffer, which is potentially unsafe if the
+ * garbage collector runs.
  *
- * @private true
+ * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
+ * @param {Number} size The `length` property of the returned Buffer.
+ * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and the requested _size_.
+ * @api private
  */
@@ -422,3 +775,11 @@
 /**
- * Returns a new Buffer instance with the specified size.
+ * Returns a new Buffer instance with the specified _size_, with the same memory
+ * address as _buffer_.
+ *
+ * This function "attaches" _buffer_ to the returned Buffer to prevent it from
+ * being garbage collected.
+ *
+ * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
+ * @param {Number} size The `length` property of the returned Buffer.
+ * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and the requested _size_.
  */
@@ -434,10 +795,10 @@
 /**
- * Accepts a `Buffer` instance and a number of `NULL` bytes to read from the
- * pointer. This function will scan past the boundary of the Buffer's `length`
- * until it finds `size` number of aligned `NULL` bytes.
+ * Same as `ref.reinterpretUntilZeros()`, except that this version does not
+ * attach _buffer_ to the returned Buffer, which is potentially unsafe if the
+ * garbage collector runs.
  *
- * This private version does not "attach" the original `Buffer` to the returned
- * `Buffer`, which could be potentially dangerous. Use with caution!
- *
- * @private true
+ * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
+ * @param {Number} size The number of sequential, aligned `NULL` bytes that are required to terminate the buffer.
+ * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and a variable `length` that is terminated by _size_ NUL bytes.
+ * @api private
  */
@@ -455,3 +816,3 @@
  *
- * ``` js
+ * ```
  * function readCString (buf) {
@@ -462,2 +823,8 @@ *   return ref.reinterpretUntilZeros(buf, 1).toString('utf8')
  *
+ * This function "attaches" _buffer_ to the returned Buffer to prevent it from
+ * being garbage collected.
+ *
+ * @param {Buffer} buffer A Buffer instance to base the returned Buffer off of.
+ * @param {Number} size The number of sequential, aligned `NULL` bytes are required to terminate the buffer.
+ * @return {Buffer} A new Buffer instance with the same memory address as _buffer_, and a variable `length` that is terminated by _size_ NUL bytes.
  */
@@ -472,9 +839,4 @@
 
-/**
- * Here are all the built-in "types" in ref's Type System. All of the built-in
- * types read and write "native endianness" when multi-byte types are used.
- *
- * @section types
- */
 
+// the built-in "types"
 var types = exports.types = {}
@@ -484,2 +846,4 @@
  * The `void` type.
+ *
+ * @section types
  */
@@ -714,66 +1078,80 @@
  *
- * Variable-length (1-byte 99% of the time) type that can hold `true` or
- * `false` values.
+ * Wrapper type around `types.uint8` that accepts/returns `true` or
+ * `false` Boolean JavaScript values.
+ *
+ * @name bool
+ *
  */
-types.bool = types;
 
 /**
  * The `byte` type.
+ *
+ * @name byte
  */
-types.byte = types;
 
 /**
  * The `char` type.
+ *
+ * @name char
  */
-types.char = types;
 
 /**
  * The `uchar` type.
+ *
+ * @name uchar
  */
-types.uchar = types;
 
 /**
  * The `short` type.
+ *
+ * @name short
  */
-types.short = types;
 
 /**
  * The `ushort` type.
+ *
+ * @name ushort
  */
-types.ushort = types;
 
 /**
  * The `int` type.
+ *
+ * @name int
  */
-types.int = types;
 
 /**
  * The `uint` type.
+ *
+ * @name uint
  */
-types.uint = types;
 
 /**
  * The `long` type.
+ *
+ * @name long
  */
-types.long = types;
 
 /**
  * The `ulong` type.
+ *
+ * @name ulong
  */
-types.ulong = types;
 
 /**
  * The `longlong` type.
+ *
+ * @name longlong
  */
-types.longlong = types;
 
 /**
  * The `ulonglong` type.
+ *
+ * @name ulonglong
  */
-types.ulonglong = types;
 
 /**
  * The `size_t` type.
+ *
+ * @name size_t
  */
-types.size_t = types;
 
@@ -829,2 +1207,8 @@ // "typedef"s for the variable-sized types
 /*!
+ * This `char *` type is used by "allocCString()" above.
+ */
+
+var charPtrType = exports.refType(exports.types.char)
+
+/*!
  * Set the `type` property of the `NULL` pointer Buffer object.
@@ -836,4 +1220,4 @@ */
 /**
- * `NULL_POINTER` is a Buffer pointing to `NULL`. So it's equivalent to the
- * following C code:
+ * `NULL_POINTER` is a pointer-sized `Buffer` instance pointing to `NULL`.
+ * Conceptually, it's equivalent to the following C code:
  *
@@ -844,2 +1228,4 @@ * ``` c
  * ```
+ *
+ * @type Buffer
  */
@@ -849,10 +1235,4 @@
 
-/*!
- * This `char *` type is used by "allocCString()" above.
- */
-
-var charPtrType = exports.refType(exports.types.char)
-
 /**
- * `ref` adds a few convenience methods added to `Buffer.prototype`.
+ * All these '...' comment blocks below are for the documentation generator.
  *
@@ -862,8 +1242,2 @@ * @section buffer
 
-/**
- * Calls `ref.address()` on the Buffer instance.
- *
- * @return {Number} The memory address of the Buffer.
- */
-
 Buffer.prototype.address = function address () {
@@ -874,9 +1248,5 @@ return exports.address(this)
 /**
- * Calls `ref.isNull()` on the Buffer instance.
- *
- * @return {Boolean} `true` if the memory address of the Buffer is NULL,
- * `false` otherwise.
+ * ...
  */
 
-
 Buffer.prototype.isNull = function isNull () {
@@ -887,5 +1257,3 @@ return exports.isNull(this)
 /**
- * Calls `ref.ref()` on the Buffer instance.
- *
- * @return {Buffer} A new "pointer" `Buffer` instance pointing to this `Buffer`.
+ * ...
  */
@@ -898,5 +1266,3 @@
 /**
- * Calls `ref.deref()` on the Buffer instance.
- *
- * @return {?} The dereferenced value from this Buffer.
+ * ...
  */
@@ -909,7 +1275,3 @@
 /**
- * Calls `ref.readObject()` on the Buffer instance.
- *
- * @param {Number} offset The offset of the Buffer to read the Object from.
- * @return {Object} The JavaScript object that was written to the specified memory
- * address in the Buffer.
+ * ...
  */
@@ -922,6 +1284,3 @@
 /**
- * Calls `ref.writeObject()` on the Buffer instance.
- *
- * @param {Object} obj The Object to write.
- * @param {Number} offset The offet of the Buffer to write the Object at.
+ * ...
  */
@@ -933,2 +1292,6 @@
 
+/**
+ * ...
+ */
+
 Buffer.prototype.readPointer = function readPointer (offset, size) {
@@ -938,2 +1301,6 @@ return exports.readPointer(this, offset, size)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.writePointer = function writePointer (ptr, offset) {
@@ -943,2 +1310,6 @@ return exports.writePointer(this, offset, ptr)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.readCString = function readCString (offset) {
@@ -948,2 +1319,6 @@ return exports.readCString(this, offset)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.writeCString = function writeCString (string, offset, encoding) {
@@ -953,2 +1328,6 @@ return exports.writeCString(this, offset, string, encoding)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.readInt64BE = function readInt64BE (offset) {
@@ -958,2 +1337,6 @@ return exports.readInt64BE(this, offset)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.writeInt64BE = function writeInt64BE (val, offset) {
@@ -963,2 +1346,6 @@ return exports.writeInt64BE(this, offset, val)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.readUInt64BE = function readUInt64BE (offset) {
@@ -968,2 +1355,6 @@ return exports.readUInt64BE(this, offset)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.writeUInt64BE = function writeUInt64BE (val, offset) {
@@ -973,2 +1364,6 @@ return exports.writeUInt64BE(this, offset, val)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.readInt64LE = function readInt64LE (offset) {
@@ -978,2 +1373,6 @@ return exports.readInt64LE(this, offset)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.writeInt64LE = function writeInt64LE (val, offset) {
@@ -983,2 +1382,6 @@ return exports.writeInt64LE(this, offset, val)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.readUInt64LE = function readUInt64LE (offset) {
@@ -988,2 +1391,6 @@ return exports.readUInt64LE(this, offset)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.writeUInt64LE = function writeUInt64LE (val, offset) {
@@ -993,2 +1400,6 @@ return exports.writeUInt64LE(this, offset, val)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.reinterpret = function reinterpret (size) {
@@ -998,2 +1409,6 @@ return exports.reinterpret(this, size)
 
+/**
+ * ...
+ */
+
 Buffer.prototype.reinterpretUntilZeros = function reinterpretUntilZeros (size) {
@@ -1003,2 +1418,25 @@ return exports.reinterpretUntilZeros(this, size)
 
+/**
+ * `ref` overwrites the default `Buffer#inspect()` function to include the
+ * hex-encoded memory address of the Buffer instance when invoked.
+ *
+ * This is simply a nice-to-have.
+ *
+ * **Before**:
+ *
+ * ``` js
+ * console.log(new Buffer('ref'));
+ * <Buffer 72 65 66>
+ * ```
+ *
+ * **After**:
+ *
+ * ``` js
+ * console.log(new Buffer('ref'));
+ * <Buffer@0x103015490 72 65 66>
+ * ```
+ */
+
+Buffer.prototype.inspect = overwriteInspect(Buffer.prototype.inspect)
+
 // does SlowBuffer inherit from Buffer? (node >= v0.7.9)
@@ -1034,2 +1472,10 @@ if (!(exports.NULL instanceof Buffer)) {
   SlowBuffer.prototype.writeUInt64LE = Buffer.prototype.writeUInt64LE
+  SlowBuffer.prototype.inspect = overwriteInspect(SlowBuffer.prototype.inspect)
 }
+
+function overwriteInspect (inspect) {
+  return function () {
+    var v = inspect.apply(this, arguments)
+    return v.replace('Buffer', 'Buffer@0x' + this.address().toString(16))
+  }
+}

package.json

@@ -19,3 +19,3 @@ { "name": "ref"
   ]
-, "version": "0.0.20"
+, "version": "0.1.0"
 , "author": "Nathan Rajlich <[e-mail]> (http://tootallnate.net)"
@@ -25,3 +25,3 @@ , "repository": { "type": "git", "url": "git://github.com/TooTallNate/ref.git" }
 , "scripts": {
-      "docs": "jade docs/index.jade --obj \"{ dox: $(dox < lib/ref.js) }\""
+      "docs": "node docs/compile"
     , "test": "mocha -gc --reporter spec"
@@ -34,8 +34,10 @@ }
 , "devDependencies": {
-      "mocha": "*"
+      "dox": "*"
+    , "highlight.js": "1"
+    , "jade": "*"
+    , "marked": "*"
+    , "mocha": "*"
     , "weak": "*"
-    , "dox": "*"
-    , "jade": "*"
   }
 , "engines": { "node": "*" }
 }

README.md

@@ -334,3 +334,18 @@ ref
 
+Build the docs
+--------------
 
+Install the dev dependencies
+
+``` bash
+$ npm install
+```
+
+Generate the docs
+
+``` bash
+$ npm run docs
+```
+
+
 License
@@ -337,0 +352,0 @@ -------

test/address.js

@@ -44,2 +44,10 @@
 
+  describe('inspect()', function () {
+
+    it('should overwrite the default Buffer#inspect() to print the memory address', function () {
+      assert(buf.inspect().indexOf(buf.address().toString(16)) !== -1)
+    })
+
+  })
+
 })

test/types.js

@@ -24,2 +24,20 @@
 
+  describe('derefType()', function () {
+
+    it('should return a new "type" with its `indirection` level decreased by 1', function () {
+      var intPtr = Object.create(ref.types.int)
+      intPtr.indirection++
+      var int = ref.derefType(intPtr)
+      assert.equal(intPtr.size, intPtr.size)
+      assert.equal(intPtr.indirection - 1, int.indirection)
+    })
+
+    it('should throw an Error when given a "type" with its `indirection` level already at 1', function () {
+      assert.throws(function () {
+        ref.derefType(ref.types.int)
+      })
+    })
+
+  })
+
   describe('size', function () {
@@ -26,0 +44,0 @@ Object.keys(ref.types).forEach(function (name) {

New alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

353595

increased by308.75%

Number of package files

34

increased by54.55%

Lines of code

2841

increased by106.17%

Number of lines in readme file

375

increased by4.17%

Worsened metrics

Dev dependency count

6

increased by50%

Number of low supply chain risk alerts

1

increased byInfinity%

No dependency changes