Home Manual Reference Source Test 
import CorrodeBase from 'corrode/src/base.js'
public class | source

CorrodeBase

Extends:

readable-stream~Transform → CorrodeBase

Direct Subclass:

Corrode

This class lies at the very base of this library.

It's responsible for reading variables, looping and tapping values and other more or less low-level stuff. It extends the {Transform}-stream, so you can pipe other streams into your corrode instance. This makes corrode an efficient library for even huge files. Unless necessary or explicitly wanted by the user, corrode flushes it's internal buffer Corrode#streamBuffer asap.

The library doesn't work directly when called. If you call e.g. Corrode#uint32be there won't be a direct read from a given buffer. Instead there will be a new job, added to Corrode#jobs. This array of jobs is responsible for managing the work to be done once data flows. This way, it's possible to insert new jobs on the fly and making for an imperative way of using this library.

Corrode will process the given stream as long as long as there's new chunks and jobs. Once either of these drain, corrode will stop and clean possibly remaining jobs (i.e. remove all read-jobs).

In fact CorrodeBase can be used as a standalone-library, if low-level is your thing.

Test:

Static Member Summary

Static Public Members
public static

static constant for big endian
public static

static constant for little endian
public static

Defaults Object for available options CorrodeBase#constructor

Constructor Summary

Public Constructor
public

options default to Corrode.defaults, also accepts options for Transform#constructor.

Member Summary

Public Members
public

offset in the current running chunk (CorrodeBase#streamBuffer)
public

indicates whether automatic flushes are disabled
public

indicates whether only pops are getting processed
public

array holding the jobs which are to be processed
public
public

available primitve jobs.
public

streamBuffer: BufferList

internal buffer for stream-chunks not yet processable
public

offset in the whole piped stream
public

the VariableStack holding the layers and variables of this instance
public get

vars: Object | *: *

get variables of the current stack
public set

vars(val: Object | *)

replace the current value

Method Summary

Public Methods
public

buffer(name: string, length: number | string): CorrodeBase

pushes a buffer-job onto the job-array the buffer-job will read a buffer with the given length starting at the current offset CorrodeBase#bufferOffset.
public

push a double job with default endianness (CorrodeBase#options.endianness) onto the job-array
public

push a double job with big endianness onto the job-array
public

push a double job with little endianness onto the job-array
public

re-starts the jobLoop with the job-list cleaned from any read jobs CorrodeBase#removeReadJobs CorrodeBase#isUnwinding
public

push a float job with default endianness (CorrodeBase#options.endianness) onto the job-array
public

push a float job with big endianness onto the job-array
public

push a float job with little endianness onto the job-array
public

push a int16 (signed) job with default endianness (CorrodeBase#options.endianness) onto the job-array
public

push a int16 (signed) job with big endianness onto the job-array
public

push a int16 (signed) job with little endianness onto the job-array
public

push a int32 (signed) job with default endianness (CorrodeBase#options.endianness) onto the job-array
public

push a int32 (signed) job with big endianness onto the job-array
public

push a int32 (signed) job with little endianness onto the job-array
public

push a int64 (signed) job with default endianness (CorrodeBase#options.endianness) onto the job-array note that in64 may be unprecise, due to number-values being double in js
public

push a int64 (signed) job with big endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js
public

push a int64 (signed) job with little endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js
public

push a int8 (signed) job onto the job-array
public
this method was deprecated. int8 needs no endianness, use int8() instead

push a int8 (signed) job onto the job-array
public
this method was deprecated. int8 needs no endianness, use int8() instead

push a int8 (signed) job onto the job-array
public

internal function to process the array of jobs still remaing.
public

loop(name: string, callback: function(end: function, discard: function, i: number)): CorrodeBase

push a loop-job onto the job-array a loop-job is a special kind of job allowing the developer to create loops in the current job-array.
public

push a pop-job onto the job-array the pop-job pops a layer from CorrodeBase#varStack.
public

push(name: string, value: *): CorrodeBase

push a push-job onto the job-array the push-job pushes a new layer onto CorrodeBase#varStack.
public

remove all jobs from CorrodeBase#jobs with the ability to re-add them back later.
public

purges all jobs from the job-queue, which need to read from the stream
public

push a skip-job onto the job-array skip-jobs allow the developer to skip a given number of bytes.
public

string(name: string, length: number | string, encoding: string): CorrodeBase

pushes a string-job onto the job-array the string-job will read a string with the given length starting at the current offset CorrodeBase#bufferOffset
public

tap(name: string, callback: function(...args: *), args: Array): CorrodeBase

push a tap-job onto the job-array a tap-job is a special kind of job allowing the developer to peek into the current variables and creating more complex structures and behaviour based on available information.
public

push a uint16 (unsigned) job with default endianness (CorrodeBase#options.endianness) onto the job-array
public

push a uint16 (unsigned) job with big endianness onto the job-array
public

push a uint16 (unsigned) job with little endianness onto the job-array
public

push a uint32 (unsigned) job with default endianness (CorrodeBase#options.endianness) onto the job-array
public

push a uint32 (unsigned) job with big endianness onto the job-array
public

push a uint32 (unsigned) job with little endianness onto the job-array
public

push a uint64 (unsigned) job with default endianness (CorrodeBase#options.endianness) onto the job-array note that in64 may be unprecise, due to number-values being double in js
public

push a uint64 (unsigned) job with big endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js
public

push a uint64 (unsigned) job with little endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js
public

push a uint8 (unsigned) job onto the job-array
public
this method was deprecated. uint8 needs no endianness, use uint8() instead

push a uint8 (unsigned) job onto the job-array
public
this method was deprecated. uint8 needs no endianness, use uint8() instead

push a uint8 (unsigned) job onto the job-array
Private Methods
private

_flush(done: *)

finish remaining jobs if finishJobsOnEOF is enabled
private

_moveOffset(by: *)

utility method to move both CorrodeBase#chunkOffset and CorrodeBase#streamOffset by a given amount of bytes
private

_pushJob(name: *, type: *, length: *, endianness: *): CorrodeBase

utility method to push a new job onto the job-array
private

_transform(chunk: *, encoding: *, done: *): *

add a new chunk to the internal buffer and process remaining jobs this TransformStream won't call the push-method as it is not able to guarantee correct ouptut while still reading data. this depends not on corrode, but on the way you use it.

Static Public Members

public static BIG_ENDIAN: string source

static constant for big endian

public static LITTLE_ENDIAN: string source

static constant for little endian

public static defaults: Object source

Defaults Object for available options CorrodeBase#constructor

Public Constructors

public constructor() source

options default to Corrode.defaults, also accepts options for Transform#constructor.

Params:

NameTypeAttributeDescription
options.endianness string
  • default: CorrodeBase#LITTLE_ENDIAN

endianness, when none is explicitly given by the job
options.loopIdentifier *
  • default: Symbol(loop-variable)

identifier of the temporary variable used internally for loops
options.encoding string
  • default: 'utf8'

default encoding, when none is explicitly given by the job
options.finishJobsOnEOF boolean
  • default: true

whether to finish all remaining jobs on stream-end or leave the corrode-instance in an unfinished state with possibly many unresolved functions and unpredictable state (see tests)
options.anonymousLoopDiscardDeep boolean
  • default: false

when anonymous loop-jobs get discarded, the original state which gets restored is either a shallow copy or a deep copy of the original object (see tests)
options.strictObjectMode boolean
  • default: true

whether to prevent none-object values from being pushed onto CorrodeBase#vars (catches mistakes)

Public Members

public chunkOffset: Number source

offset in the current running chunk (CorrodeBase#streamBuffer)

Test:

public isSeeking: Boolean source

indicates whether automatic flushes are disabled

Test:

public isUnwinding: Boolean source

indicates whether only pops are getting processed

public jobs: Array<Object> source

array holding the jobs which are to be processed

Test:

public options: Object source

Test:

public primitveMap: Object source

available primitve jobs. these are the functions really reading data from the buffer.

public streamBuffer: BufferList source

internal buffer for stream-chunks not yet processable

public streamOffset: Number source

offset in the whole piped stream

Test:

public varStack: VariableStack source

the VariableStack holding the layers and variables of this instance

Test:

public get vars: Object | *: * source

get variables of the current stack

Return:

Object | *

topmost value

public set vars(val: Object | *) source

replace the current value

Public Methods

public buffer(name: string, length: number | string): CorrodeBase source

pushes a buffer-job onto the job-array the buffer-job will read a buffer with the given length starting at the current offset CorrodeBase#bufferOffset. The returned Buffer will be a slice (not a copy) of the underlying CorrodeBase#streamBuffer

Params:

NameTypeAttributeDescription
name string

name of the buffer-variable
length number | string

length of the buffer in bytes. Given a string, corrode will try to find a variable with the given string in the current layer

Return:

CorrodeBase

this

Test:

public double(name: string): CorrodeBase source

push a double job with default endianness (CorrodeBase#options.endianness) onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public doublebe(name: string): CorrodeBase source

push a double job with big endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public doublele(name: string): CorrodeBase source

push a double job with little endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public finishRemainingJobs() source

re-starts the jobLoop with the job-list cleaned from any read jobs CorrodeBase#removeReadJobs CorrodeBase#isUnwinding

Test:

public float(name: string): CorrodeBase source

push a float job with default endianness (CorrodeBase#options.endianness) onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public floatbe(name: string): CorrodeBase source

push a float job with big endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public floatle(name: string): CorrodeBase source

push a float job with little endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int16(name: string): CorrodeBase source

push a int16 (signed) job with default endianness (CorrodeBase#options.endianness) onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int16be(name: string): CorrodeBase source

push a int16 (signed) job with big endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int16le(name: string): CorrodeBase source

push a int16 (signed) job with little endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int32(name: string): CorrodeBase source

push a int32 (signed) job with default endianness (CorrodeBase#options.endianness) onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int32be(name: string): CorrodeBase source

push a int32 (signed) job with big endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int32le(name: string): CorrodeBase source

push a int32 (signed) job with little endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int64(name: string): CorrodeBase source

push a int64 (signed) job with default endianness (CorrodeBase#options.endianness) onto the job-array note that in64 may be unprecise, due to number-values being double in js

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int64be(name: string): CorrodeBase source

push a int64 (signed) job with big endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int64le(name: string): CorrodeBase source

push a int64 (signed) job with little endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int8(name: string): CorrodeBase source

push a int8 (signed) job onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int8be(name: string): CorrodeBase source

this method was deprecated. int8 needs no endianness, use int8() instead

push a int8 (signed) job onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public int8le(name: string): CorrodeBase source

this method was deprecated. int8 needs no endianness, use int8() instead

push a int8 (signed) job onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public jobLoop() source

internal function to process the array of jobs still remaing. this function is synchronous. this is due to the fact of keeping things more simple. if you intend to use this library expecting taps and loops to work async you're invited to create an issue to inform me of the need for this kind of behaviour. Until then corrode should satisfy most use cases.

if you desperately need async behaviour when parsing data, i'd recommend doing that after corrode has finished parsing the buffer, separately.

Throw:

Error

assertion-errors, runtime-errors

Test:

public loop(name: string, callback: function(end: function, discard: function, i: number)): CorrodeBase source

push a loop-job onto the job-array a loop-job is a special kind of job allowing the developer to create loops in the current job-array. this allows for iteration, seeking and more complex behaviours

Params:

NameTypeAttributeDescription
name string
  • optional

name of the new variable-layer. if none is provided, the current layer will be used
callback function(end: function, discard: function, i: number)

called until end() is called. end(true) can be used to end and discard the current loop. discard() can be used to reset the current layer (CorrodeBase#options.anonymousLoopDiscardDeep). i is the current iteration count

Return:

CorrodeBase

this

Test:

public pop(): CorrodeBase source

push a pop-job onto the job-array the pop-job pops a layer from CorrodeBase#varStack. this most probably doesn't have to get called manually, as CorrodeBase#tap and CorrodeBase#loop will do this automatically

Return:

CorrodeBase

this

Test:

public push(name: string, value: *): CorrodeBase source

push a push-job onto the job-array the push-job pushes a new layer onto CorrodeBase#varStack. this most probably doesn't have to get called manually, as CorrodeBase#tap and CorrodeBase#loop will do this automatically

Params:

NameTypeAttributeDescription
name string

name of the new layer
value *
  • optional
  • default: {}

value of the new layer (default is from VariableStack)

Return:

CorrodeBase

this

Test:

public queueJobs(): function source

remove all jobs from CorrodeBase#jobs with the ability to re-add them back later.

Return:

function

function to append all queued jobs back onto the jobs-array (borrowed from redux)

Example:

  + [
  |   { type: 'push', name: 'struct', fn },
  |   { type: 'uint8', name: 'var' ' }
  | ]
  |
  | jobLoop - iteration
  |
  | var unqueueJobs = queJobs();
  |
  | []
  |
  | fn();
  |
  | [
  |   { type: 'uint8', name: 'strvar' }
  | ]
  |
  | unqueueJobs();
  |
  | [
  |   { type: 'uint8', name: 'strvar' },
  |   { type: 'uint8', name: 'var'   }
  v ]

Test:

public removeReadJobs() source

purges all jobs from the job-queue, which need to read from the stream

Test:

public skip(length: number | string): CorrodeBase source

push a skip-job onto the job-array skip-jobs allow the developer to skip a given number of bytes. If the amount of bytes exceeds the current available byte-count in the internal buffer CorrodeBase#streamBuffer the job will wait for enough data. If this data won't come the job gets aborted and corrode ends. If you want to skip a negative amount of bytes you have to disable auto-flushing. this can be done by setting CorrodeBase#isSeeking to true.

Params:

NameTypeAttributeDescription
length number | string

how many bytes to skip. Given a string, corrode will try to find a variable with the given string in the current layer

Return:

CorrodeBase

this

Test:

public string(name: string, length: number | string, encoding: string): CorrodeBase source

pushes a string-job onto the job-array the string-job will read a string with the given length starting at the current offset CorrodeBase#bufferOffset

Params:

NameTypeAttributeDescription
name string

name of the string-variable
length number | string

length of the string in bytes (not characters). Given a string, corrode will try to find a variable with the given string in the current layer
encoding string
  • optional
  • default: CorrodeBase#options.encoding

encoding encoding used to decode the string, defaults to 'utf8'. available encodings can be found here https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings

Return:

CorrodeBase

this

Test:

public tap(name: string, callback: function(...args: *), args: Array): CorrodeBase source

push a tap-job onto the job-array a tap-job is a special kind of job allowing the developer to peek into the current variables and creating more complex structures and behaviour based on available information.

Params:

NameTypeAttributeDescription
name string
  • optional

name of the new variable-layer. if none is provided, the current layer will be used
callback function(...args: *)

called when this job is reached
args Array

array of possible arguments being passed to the callback

Return:

CorrodeBase

this

Test:

public uint16(name: string): CorrodeBase source

push a uint16 (unsigned) job with default endianness (CorrodeBase#options.endianness) onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint16be(name: string): CorrodeBase source

push a uint16 (unsigned) job with big endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint16le(name: string): CorrodeBase source

push a uint16 (unsigned) job with little endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint32(name: string): CorrodeBase source

push a uint32 (unsigned) job with default endianness (CorrodeBase#options.endianness) onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint32be(name: string): CorrodeBase source

push a uint32 (unsigned) job with big endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint32le(name: string): CorrodeBase source

push a uint32 (unsigned) job with little endianness onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint64(name: string): CorrodeBase source

push a uint64 (unsigned) job with default endianness (CorrodeBase#options.endianness) onto the job-array note that in64 may be unprecise, due to number-values being double in js

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint64be(name: string): CorrodeBase source

push a uint64 (unsigned) job with big endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint64le(name: string): CorrodeBase source

push a uint64 (unsigned) job with little endianness onto the job-array note that in64 may be unprecise, due to number-values being double in js

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint8(name: string): CorrodeBase source

push a uint8 (unsigned) job onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint8be(name: string): CorrodeBase source

this method was deprecated. uint8 needs no endianness, use uint8() instead

push a uint8 (unsigned) job onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

public uint8le(name: string): CorrodeBase source

this method was deprecated. uint8 needs no endianness, use uint8() instead

push a uint8 (unsigned) job onto the job-array

Params:

NameTypeAttributeDescription
name string

name of the variable to be created

Return:

CorrodeBase

this

Test:

Private Methods

private _flush(done: *) source

finish remaining jobs if finishJobsOnEOF is enabled

Params:

NameTypeAttributeDescription
done *

private _moveOffset(by: *) source

utility method to move both CorrodeBase#chunkOffset and CorrodeBase#streamOffset by a given amount of bytes

Params:

NameTypeAttributeDescription
by *

private _pushJob(name: *, type: *, length: *, endianness: *): CorrodeBase source

utility method to push a new job onto the job-array

Params:

NameTypeAttributeDescription
name *
type *
length *
endianness *

Return:

CorrodeBase

this

private _transform(chunk: *, encoding: *, done: *): * source

add a new chunk to the internal buffer and process remaining jobs this TransformStream won't call the push-method as it is not able to guarantee correct ouptut while still reading data. this depends not on corrode, but on the way you use it.

Params:

NameTypeAttributeDescription
chunk *
encoding *
done *

Return:

*