mirror of
https://github.com/musix-org/musix-oss
synced 2024-11-14 16:00:17 +00:00
265 lines
9.1 KiB
Plaintext
265 lines
9.1 KiB
Plaintext
|
doctype 5
|
||
|
|
html(lang="en")
|
||
|
|
head
|
||
|
|
meta(charset="utf-8")
|
||
|
|
title "ref" documentation v#{package.version}
|
||
|
|
meta(name="description", content=package.description)
|
||
|
|
meta(name="keywords", content=['node.js', package.name].concat(package.keywords).join(', '))
|
||
|
|
meta(name="author", content="Nathan Rajlich")
|
||
|
|
meta(name="viewport", content="width=device-width, initial-scale=1, maximum-scale=1")
|
||
|
|
|
||
|
|
link(rel="stylesheet", href="stylesheets/hightlight.css")
|
||
|
|
link(rel="stylesheet", href="stylesheets/base.css")
|
||
|
|
link(rel="stylesheet", href="stylesheets/skeleton.css")
|
||
|
|
link(rel="stylesheet", href="stylesheets/layout.css")
|
||
|
|
|
||
|
|
link(rel="shortcut icon", href="images/favicon.ico")
|
||
|
|
link(rel="apple-touch-icon", href="images/apple-touch-icon.png")
|
||
|
|
link(rel="apple-touch-icon", sizes="72x72", href="images/apple-touch-icon-72x72.png")
|
||
|
|
link(rel="apple-touch-icon", sizes="114x114", href="images/apple-touch-icon-114x114.png")
|
||
|
|
|
||
|
|
body
|
||
|
|
.container
|
||
|
|
.columns.three.logo
|
||
|
|
a(href="")
|
||
|
|
h1 #{package.name}
|
||
|
|
span.pointer *
|
||
|
|
span.version v#{package.version}
|
||
|
|
.columns.thirteen.subtitle
|
||
|
|
h3= package.description
|
||
|
|
.columns.sixteen.intro
|
||
|
|
h4 What is <code>ref</code>?
|
||
|
|
p
|
||
|
|
code ref
|
||
|
|
| is a native addon for
|
||
|
|
a(href="http://nodejs.org") Node.js
|
||
|
|
| that aids in doing C programming in JavaScript, by extending
|
||
|
|
| the built-in
|
||
|
|
a(href="http://nodejs.org/api/buffer.html")
|
||
|
|
code Buffer
|
||
|
|
| class
|
||
|
|
| with some fancy additions like:
|
||
|
|
ul
|
||
|
|
li Getting the memory address of a Buffer
|
||
|
|
li Checking the endianness of the processor
|
||
|
|
li Checking if a Buffer represents the NULL pointer
|
||
|
|
li Reading and writing "pointers" with Buffers
|
||
|
|
li Reading and writing C Strings (NULL-terminated)
|
||
|
|
li Reading and writing JavaScript Object references
|
||
|
|
li Reading and writing
|
||
|
|
strong int64_t
|
||
|
|
| and
|
||
|
|
strong uint64_t
|
||
|
|
| values
|
||
|
|
li A "type" convention to define the contents of a Buffer
|
||
|
|
p
|
||
|
|
| There is indeed a lot of
|
||
|
|
em meat
|
||
|
|
| to
|
||
|
|
code ref
|
||
|
|
| , but it all fits together in one way or another in the end.
|
||
|
|
br
|
||
|
|
| For simplicity,
|
||
|
|
code ref
|
||
|
|
| 's API can be broken down into 3 sections:
|
||
|
|
a.nav.columns.five(href='#exports')
|
||
|
|
h4 ref <code>exports</code>
|
||
|
|
p
|
||
|
|
| All the static versions of
|
||
|
|
code ref
|
||
|
|
| 's functions and default "types" available on the exports returned from
|
||
|
|
code require('ref')
|
||
|
|
| .
|
||
|
|
a.nav.columns.five(href='#types')
|
||
|
|
h4 <em>"type"</em> system
|
||
|
|
p
|
||
|
|
| The
|
||
|
|
em "type"
|
||
|
|
| system allows you to define a "type" on any Buffer instance, and then
|
||
|
|
| use generic
|
||
|
|
code ref()
|
||
|
|
| and
|
||
|
|
code deref()
|
||
|
|
| functions to reference and dereference values.
|
||
|
|
a.nav.columns.five(href='#extensions')
|
||
|
|
h4 <code>Buffer</code> extensions
|
||
|
|
p
|
||
|
|
code Buffer.prototype
|
||
|
|
| gets extended with some convenience functions. These all just mirror
|
||
|
|
| their static counterpart, using the Buffer's
|
||
|
|
code this
|
||
|
|
| variable as the
|
||
|
|
code buffer
|
||
|
|
| variable.
|
||
|
|
|
||
|
|
|
||
|
|
hr
|
||
|
|
.columns.eight.section.exports
|
||
|
|
a(name="exports")
|
||
|
|
a(href="#exports")
|
||
|
|
h2 ref exports
|
||
|
|
.columns.sixteen.intro
|
||
|
|
p
|
||
|
|
| This section documents all the functions exported from
|
||
|
|
code require('ref')
|
||
|
|
| .
|
||
|
|
each doc in exports
|
||
|
|
if (!doc.ignore)
|
||
|
|
.columns.sixteen.section
|
||
|
|
a(name='exports-' + doc.name)
|
||
|
|
a(href='#exports-' + doc.name)
|
||
|
|
isFunc = doc.type == 'method' || doc.isPrivate
|
||
|
|
h3
|
||
|
|
| ref.#{doc.name}
|
||
|
|
if (isFunc)
|
||
|
|
| (
|
||
|
|
each param, i in doc.paramTypes
|
||
|
|
span.param #{param.types.join('|')} #{param.name}
|
||
|
|
if (i + 1 < doc.paramTypes.length)
|
||
|
|
| ,
|
||
|
|
| )
|
||
|
|
if (doc.returnType)
|
||
|
|
|
|
||
|
|
span.rtn → #{doc.returnType.types.join('|')}
|
||
|
|
if (!isFunc)
|
||
|
|
|
|
||
|
|
span.rtn ⇒ #{doc.type}
|
||
|
|
if (doc.paramTypes.length > 0 || doc.returnType)
|
||
|
|
ul
|
||
|
|
each param in doc.paramTypes
|
||
|
|
li #{param.name} - !{param.description}
|
||
|
|
if (doc.returnType)
|
||
|
|
li
|
||
|
|
strong Return:
|
||
|
|
| !{doc.returnType.description}
|
||
|
|
!= (doc && doc.description.full || '').replace(/\<br ?\/?\>/g, ' ')
|
||
|
|
|
||
|
|
|
||
|
|
hr
|
||
|
|
.columns.eight.section.types
|
||
|
|
a(name="types")
|
||
|
|
a(href="#types")
|
||
|
|
h2
|
||
|
|
em "type"
|
||
|
|
| system
|
||
|
|
.columns.sixteen.intro.types
|
||
|
|
p
|
||
|
|
| A "type" in
|
||
|
|
code ref
|
||
|
|
| is simply an plain 'ol JavaScript Object, with a set
|
||
|
|
| of expected properties attached that implement the logic for getting
|
||
|
|
| & setting values on a given
|
||
|
|
code Buffer
|
||
|
|
| instance.
|
||
|
|
p
|
||
|
|
| To attach a "type" to a Buffer instance, you simply attach the "type"
|
||
|
|
| object to the Buffer's <code>type</code> property.
|
||
|
|
code ref
|
||
|
|
| comes with a set of commonly used types which are described in this
|
||
|
|
| section.
|
||
|
|
h4 Creating your own "type"
|
||
|
|
p
|
||
|
|
| It's trivial to create your own "type" that reads and writes your
|
||
|
|
| own custom datatype/class to and from Buffer instances using
|
||
|
|
code ref
|
||
|
|
| 's unified API.
|
||
|
|
br
|
||
|
|
| To create your own "type", simply create a JavaScript Object with
|
||
|
|
| the following properties defined:
|
||
|
|
table
|
||
|
|
tr
|
||
|
|
th Name
|
||
|
|
th Data Type
|
||
|
|
th Description
|
||
|
|
tr
|
||
|
|
td: code size
|
||
|
|
td: code Number
|
||
|
|
td The size in bytes required to hold this datatype.
|
||
|
|
tr
|
||
|
|
td: code indirection
|
||
|
|
td: code Number
|
||
|
|
td
|
||
|
|
| The current level of indirection of the buffer. When defining
|
||
|
|
| your own "types", just set this value to <code>1</code>.
|
||
|
|
tr
|
||
|
|
td: code get
|
||
|
|
td: code Function
|
||
|
|
td
|
||
|
|
| The function to invoke when
|
||
|
|
a(href="#exports-get")
|
||
|
|
code ref.get()
|
||
|
|
| is invoked on a buffer of this type.
|
||
|
|
tr
|
||
|
|
td: code set
|
||
|
|
td: code Function
|
||
|
|
td
|
||
|
|
| The function to invoke when
|
||
|
|
a(href="#exports-set")
|
||
|
|
code ref.set()
|
||
|
|
| is invoked on a buffer of this type.
|
||
|
|
tr
|
||
|
|
td: code name
|
||
|
|
td: code String
|
||
|
|
td
|
||
|
|
em (Optional)
|
||
|
|
| The name to use during debugging for this datatype.
|
||
|
|
tr
|
||
|
|
td: code alignment
|
||
|
|
td: code Number
|
||
|
|
td
|
||
|
|
em (Optional)
|
||
|
|
| The alignment of this datatype when placed inside a struct.
|
||
|
|
| Defaults to the type's
|
||
|
|
code size
|
||
|
|
| .
|
||
|
|
h4 The built-in "types"
|
||
|
|
p
|
||
|
|
| Here is the list of
|
||
|
|
code ref
|
||
|
|
| 's built-in "type" Objects. All these built-in "types" can be found
|
||
|
|
| on the
|
||
|
|
code ref.types
|
||
|
|
| export Object. All the built-in types use "native endianness" when
|
||
|
|
| multi-byte datatypes are involved.
|
||
|
|
each doc in types
|
||
|
|
if (!doc.ignore)
|
||
|
|
.columns.sixteen.section
|
||
|
|
a(name='types-' + doc.name)
|
||
|
|
a(href='#types-' + doc.name)
|
||
|
|
h3 types.#{doc.name}
|
||
|
|
!= doc.description.full.replace(/\<br ?\/?\>/g, ' ')
|
||
|
|
|
||
|
|
|
||
|
|
hr
|
||
|
|
.columns.eight.section.exports
|
||
|
|
a(name="extensions")
|
||
|
|
a(href="#extensions")
|
||
|
|
h2 Buffer extensions
|
||
|
|
.columns.sixteen.intro
|
||
|
|
p
|
||
|
|
code Buffer.prototype
|
||
|
|
| gets extended with some convenience functions that you can use in
|
||
|
|
| your modules and/or applications.
|
||
|
|
each doc in extensions
|
||
|
|
if (!doc.ignore)
|
||
|
|
.columns.sixteen.section
|
||
|
|
a(name='extensions-' + doc.name)
|
||
|
|
a(href='#extensions-' + doc.name)
|
||
|
|
h3 Buffer##{doc.name}()
|
||
|
|
if (doc.name === 'inspect')
|
||
|
|
!= doc.description.full.replace(/\<br ?\/?\>/g, ' ')
|
||
|
|
else
|
||
|
|
p
|
||
|
|
| Shorthand for
|
||
|
|
a(href='#exports-' + doc.name)
|
||
|
|
code ref.#{doc.name}(this, …)
|
||
|
|
| .
|
||
|
|
!= (doc.ref && doc.ref.description.full || '').replace(/\<br ?\/?\>/g, ' ')
|
||
|
|
|
||
|
|
|
||
|
|
.ribbon
|
||
|
|
a(href="https://github.com/TooTallNate/ref", rel="me") Fork me on GitHub
|
||
|
|
|
||
|
|
script(src="scripts/jquery-1.7.2.min.js")
|
||
|
|
script(src="scripts/main.js")
|