| Title: | Viewing Binary Files |
|---|---|
| Description: | Functions to view files in raw binary form like in a hex editor. Additional functions to specify and read arbitrary binary formats. |
| Authors: | Paul Murrell [aut, cre], Chao Bian [ctb] |
| Maintainer: | Paul Murrell <[email protected]> |
| License: | GPL-2 |
| Version: | 0.3-4 |
| Built: | 2024-08-28 06:26:03 UTC |
| Source: | CRAN |
This function takes a "rawBlock" object and
generates human-readable strings for displaying the block.
Each string contains a binary offset, the binary data
in a raw machine format, and an interpretation of
the data in a human-readable format.
## S3 method for class 'rawBlock' as.character(x, width = NULL, machine = NULL, sep1 = " : ", sep2 = " | ", showOffset = TRUE, showHuman = TRUE, ...)## S3 method for class 'rawBlock' as.character(x, width = NULL, machine = NULL, sep1 = " : ", sep2 = " | ", showOffset = TRUE, showHuman = TRUE, ...)
x |
A |
width |
The number of bytes to display per string. |
machine |
The machine format to display;
either |
sep1 |
A separator to insert between the block offset and the machine format. |
sep2 |
A separator to insert between the machine format and the human-readable format. |
showOffset |
If |
showHuman |
If |
... |
Other arguments to |
If either width or machine is NULL,
the relevant value is taken from the
"rawBlock" object. The human-readable format is
taken from the "rawBlock" object.
A character vector.
Paul Murrell
fileBlock <- readRaw(hexViewFile("rawTest.txt"), width=8) as.character(fileBlock)fileBlock <- readRaw(hexViewFile("rawTest.txt"), width=8) as.character(fileBlock)
This function takes a "rawFormat" object and
generates human-readable strings for displaying the format.
Each string contains a binary offset, the binary data
in a raw machine format, and an interpretation of
the data in a human-readable format. The format
consists of one or more sub-blocks and a heading line
is added for each block.
## S3 method for class 'rawFormat' as.character(x, sep1 = " : ", sep2 = " | ", blockHead = TRUE, blockChar = "=", ...)## S3 method for class 'rawFormat' as.character(x, sep1 = " : ", sep2 = " | ", blockHead = TRUE, blockChar = "=", ...)
x |
A |
sep1 |
A separator to insert between the format offset and the machine format. |
sep2 |
A separator to insert between the machine format and the human-readable format. |
blockHead |
A logical indicating whether to print a header between blocks of the format. |
blockChar |
The character used as a prefix to the block names for printing headers between blocks. |
... |
Other arguments to |
Information on the number of bytes on each line, the machine representation
of each byte and the human-readable format are all taken from the
taken from the "rawBlock" elements of the "rawFormat"
object. Consequently each block can have a quite different
appearance. Considerable effort is made to line up the separators
across all blocks within the format.
A character vector.
Paul Murrell
fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) as.character(fileFormat)fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) as.character(fileFormat)
This function creates an "atomicBlock" object, which is
a description of a block of binary data. This can be used
as part of a description of a binary format.
atomicBlock(type = "char", width = NULL, machine = "hex", size = switch(type, char = 1, int = 4, real = 8), endian = "little", signed = TRUE)atomicBlock(type = "char", width = NULL, machine = "hex", size = switch(type, char = 1, int = 4, real = 8), endian = "little", signed = TRUE)
type |
How the block of binary data will be interpreted.
either |
width |
The number of bytes to print per row when displaying the block. |
machine |
How to print each byte when displaying; either
|
size |
The number of bytes used to generate each value when interpreting the raw binary as character or numeric data. |
endian |
The endianness of the binary data; used when interpreting bytes as numeric values. |
signed |
Whether the bytes should be interpreted as a signed numeric value. |
An "atomicBlock" object describes a binary block
representing a single value.
Several standard binary types are predefined (with common
C type equivalents in brackets):
ASCIIchar (char),
integer1 (signed char),
integer2 (short),
integer3,
integer4 (int, long),
integer8 (long long),
real4 (float),
real8 (double).
An "atomicBlock" object.
Paul Murrell
memFormat
readFormat
memBlock
vectorBlock
lengthBlock
mixedBlock
markedBlock
# A C long atomicBlock("int", size=4) integer4# A C long atomicBlock("int", size=4) integer4
The blockValue function returns the interpreted value of a block
of binary data (a "rawBlock" object).
The blockString function returns a null-terminated string
from a block
of binary data that is interpreted as a character data.
blockValue(block) blockString(block)blockValue(block) blockString(block)
block |
A |
The type
of the value returned is determined when the binary
block is created (e.g., by readRaw)
not when the value is extracted
by the blockValue function.
The blockString function is useful for extracting
a value from a binary block which is a string padded with
null characters.
The blockString function throws an error if the
block is not interpreted as a character value.
Either a character, or numeric vector depending on how the binary block should be interpreted.
Paul Murrell
charBlock <- readRaw(hexViewFile("rawTest.txt"), width=8) blockValue(charBlock) blockString(charBlock) intBlock <- readRaw(hexViewFile("rawTest.int"), human="int") blockValue(intBlock)charBlock <- readRaw(hexViewFile("rawTest.txt"), width=8) blockValue(charBlock) blockString(charBlock) intBlock <- readRaw(hexViewFile("rawTest.int"), human="int") blockValue(intBlock)
This is just a convenience function for specifying one of the example files contained in the hexView package. It is used in examples in hexView help pages.
hexViewFile(filename)hexViewFile(filename)
filename |
The name of the example file. |
The full path to the appropriate example file.
Paul Murrell
hexViewFile("rawTest.txt")hexViewFile("rawTest.txt")
This function creates a "markedBlock" object, which is
a description of a block of binary data. This can be used
as part of a description of a binary format.
markedBlock(marker=integer4, switch=function(marker) { ASCIIchar }, markerLabel="marker", blockLabel="block")markedBlock(marker=integer4, switch=function(marker) { ASCIIchar }, markerLabel="marker", blockLabel="block")
marker |
A |
switch |
A function that returns a |
markerLabel |
A label to name the marker component of the
|
blockLabel |
A label to name the component that is read
after the marker component of the
|
A "markedBlock" object describes a block of binary data that consists
of a “marker” block containing information on further blocks.
The marker block is read first, then this block is passed
to the switch function. The switch function
can look at the contents of the marker block and decide
what sort of block should be read next (the blockValue()
function may be useful here). The result of the
switch function is read from the end of the marker
block. The marker block and the result of the switch
function can be any type
of "memBlock" object. If the result of the switch()
function is NULL then only the marker block is returned
(no further memory is read).
A "markedBlock" object.
Paul Murrell
memFormat
readFormat
memBlock
atomicBlock
vectorBlock
lengthBlock
mixedBlock
blockValue
# A single-byte integer which dictates how many # subsequent four-byte reals to read markedBlock(integer1, function(marker) { lengthBlock(real4, blockValue(marker)) })# A single-byte integer which dictates how many # subsequent four-byte reals to read markedBlock(integer1, function(marker) { lengthBlock(real4, blockValue(marker)) })
This function creates a "memBlock" object, which is
a description of a block of binary data. This can be used
as part of a description of a binary format.
memBlock(nbytes = 1, width = NULL, machine = "hex")memBlock(nbytes = 1, width = NULL, machine = "hex")
nbytes |
The number of bytes in the block. |
width |
The number of bytes to print per row when displaying the block. |
machine |
How to print each byte when displaying; either
|
A binary block that is read in from a file using this description
is interpreted as nbytes single-byte characters.
The description includes parameters controlling how a block of data should be displayed if this description is used to read in a block of binary data.
A "memBlock" object.
Paul Murrell
memFormat
readFormat
atomicBlock
vectorBlock
lengthBlock
mixedBlock
markedBlock
memBlock(8)memBlock(8)
This function creates a "memFormat" object which is
a description of a binary file format.
memFormat(...)memFormat(...)
... |
One or more |
A "memFormat" object is made up of one or more
"memBlock" objects.
A "memFormat" object.
Paul Murrell
readFormat
memBlock
atomicBlock
vectorBlock
lengthBlock
mixedBlock
markedBlock
memFormat(int1=integer4, int2=integer4)memFormat(int1=integer4, int2=integer4)
This function creates a "mixedBlock" object, which is
a description of a block of binary data. This can be used
as part of a description of a binary format.
mixedBlock(...)mixedBlock(...)
... |
One or more |
A "mixedBlock" object describes a block of binary data that consists
of a series of sub-blocks. Each sub-block can be any type
of "memBlock" object.
A "mixedBlock" object.
Paul Murrell
memFormat
readFormat
memBlock
atomicBlock
vectorBlock
lengthBlock
markedBlock
# A line of text followed by a four-byte integer mixedBlock(ASCIIline, integer4)# A line of text followed by a four-byte integer mixedBlock(ASCIIline, integer4)
This function displays a "rawBlock" object.
Each line of output contains a binary offset, the binary data
in a raw machine format, and an interpretation of
the data in a human-readable format.
The object contains parameters controlling the format
of the display, some of which may be overridden in
the call to print.
## S3 method for class 'rawBlock' print(x, width = NULL, machine = NULL, sep1 = " : ", sep2 = " | ", showOffset = TRUE, showHuman = TRUE, page = FALSE, ...)## S3 method for class 'rawBlock' print(x, width = NULL, machine = NULL, sep1 = " : ", sep2 = " | ", showOffset = TRUE, showHuman = TRUE, page = FALSE, ...)
x |
A |
width |
The number of bytes to display per line of output. |
machine |
The machine format to display;
either |
sep1 |
A separator to insert between the block offset and the machine format. |
sep2 |
A separator to insert between the machine format and the human-readable format. |
showOffset |
If |
showHuman |
If |
page |
If |
... |
Other arguments to |
If either width or machine is NULL,
the relevant value is taken from the
"rawBlock" object. The human-readable format is
taken from the "rawBlock" object.
Paul Murrell
fileBlock <- readRaw(hexViewFile("rawTest.txt")) print(fileBlock) print(fileBlock, width=8) print(fileBlock, machine="binary", width=4)fileBlock <- readRaw(hexViewFile("rawTest.txt")) print(fileBlock) print(fileBlock, width=8) print(fileBlock, machine="binary", width=4)
This function displays a "rawFormat" object.
Each line of output contains a binary offset, the binary data
in a raw machine format, and an interpretation of
the data in a human-readable format. The format
consists of one or more sub-blocks and a heading line
is added for each block.
The object contains parameters controlling the format
of the display, some of which may be overridden in
the call to print.
## S3 method for class 'rawFormat' print(x, sep1 = " : ", sep2 = " | ", blockHead = TRUE, blockChar = "=", page = FALSE, ...)## S3 method for class 'rawFormat' print(x, sep1 = " : ", sep2 = " | ", blockHead = TRUE, blockChar = "=", page = FALSE, ...)
x |
A |
sep1 |
A separator to insert between the format offset and the machine format. |
sep2 |
A separator to insert between the machine format and the human-readable format. |
blockHead |
A logical indicating whether to print a header between blocks of the format. |
blockChar |
The character used as a prefix to the block names for printing headers between blocks. |
page |
If |
... |
Other arguments to |
Information on the number of bytes on each line, the machine representation
of each byte and the human-readable format are all taken from the
taken from the "rawBlock" elements of the "rawFormat"
object. Consequently each block can have a quite different
appearance. Considerable effort is made to line up the separators
across all blocks within the format.
Paul Murrell
readFormat
as.character.rawFormat
fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) print(fileFormat) print(fileFormat, sep2=":")fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) print(fileFormat) print(fileFormat, sep2=":")
This function reads a file in Eviews format (Eviews is an econometrics package).
readEViews(filename, time.stamp=TRUE, as.data.frame = TRUE)readEViews(filename, time.stamp=TRUE, as.data.frame = TRUE)
filename |
The name of the file. |
time.stamp |
A logical indicating whether to include a
|
as.data.frame |
If |
This function is just a demonstration of how the functions in this package can be used to read a complex binary format. It has been tested on a few sample files (and works), but there is no guarantee it will work for all Eviews files (this is not helped by the fact that it is based on reverse-engineering information about the Eviews format, NOT an official description of the format.
Either a data frame or a list of variables.
Paul Murrell
http://www.eviews.com/ and http://www.ecn.wfu.edu/~cottrell/eviews_format/
readEViews(hexViewFile("data4-1.wf1"))readEViews(hexViewFile("data4-1.wf1"))
Read the raw binary content of a file using a description of the binary format.
readFormat(file, format, width = NULL, offset = 0, machine = "hex", flatten = TRUE)readFormat(file, format, width = NULL, offset = 0, machine = "hex", flatten = TRUE)
file |
The name of a file or a connection. |
format |
A |
width |
The number of bytes to print per row when displaying the file. |
offset |
An offset within the file to start reading. |
machine |
How to print each byte when displaying the file; either
|
flatten |
If |
This function uses a "memFormat" description to
read the raw binary content of a file and interpret
sub-blocks of the file as distinct (blocks of) values.
The "memFormat" can described a nested structure of
blocks. The flatten argument is used to convert
nested format structures to a flat (depth of one) structure.
The format is always flattened for display, but extracting
A "rawFormat" object, which is a list:
blocks |
A list (of lists) of |
offset |
The offset in the file where reading began. |
nbytes |
The number of bytes read from the file. |
Paul Murrell
viewFormat
memFormat
as.character.rawFormat
print.rawFormat
readRaw
readBin
fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) blockValue(fileFormat$blocks$int2) fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(integers=vectorBlock(integer4, 20))) blockValue(fileFormat$blocks$integers)fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) blockValue(fileFormat$blocks$int2) fileFormat <- readFormat(hexViewFile("rawTest.int"), memFormat(integers=vectorBlock(integer4, 20))) blockValue(fileFormat$blocks$integers)
Read the contents of a file as bytes and create an object containing the raw data, plus optionally an interpretation of the bytes as numeric values, plus parameters controlling how to display the data.
readRaw(file, width = NULL, offset = 0, nbytes = NULL, machine = "hex", human = "char", size = switch(human, char = 1, int = 4, real = 8), endian = .Platform$endian, signed = TRUE)readRaw(file, width = NULL, offset = 0, nbytes = NULL, machine = "hex", human = "char", size = switch(human, char = 1, int = 4, real = 8), endian = .Platform$endian, signed = TRUE)
file |
The name of a file or a connection. |
width |
The number of bytes to print per row when displaying the data. |
offset |
An offset within the file to start reading. |
nbytes |
The number of bytes to read from the file.
|
machine |
How to print each byte when displaying; either
|
human |
How to print a human-readable form of the data;
either |
size |
The number of bytes used to generate each value when interpreting the raw binary as character or numeric data. |
endian |
The endianness of the binary data; used when interpreting bytes as numeric values. |
signed |
Whether the bytes should be interpreted as a signed numeric value. |
Each individual byte is printed in the appropriate machine
format, but there is only one value printed in the appropriate
human format for every size bytes. Consequently,
the width
must be a multiple of the size.
An object of class "rawBlock".
Paul Murrell
viewRaw
readBin
as.character.rawBlock
print.rawBlock
blockValue
readFormat
readLines(hexViewFile("rawTest.txt")) fileBlock <- readRaw(hexViewFile("rawTest.txt"), width=8) blockValue(fileBlock) fileBlock <- readRaw(hexViewFile("rawTest.int"), human="int") blockValue(fileBlock)readLines(hexViewFile("rawTest.txt")) fileBlock <- readRaw(hexViewFile("rawTest.txt"), width=8) blockValue(fileBlock) fileBlock <- readRaw(hexViewFile("rawTest.int"), human="int") blockValue(fileBlock)
These functions create a "vectorBlock" or
lengthBlock object, which are
a descriptions of a block of binary data. These can be used
as part of a description of a binary format.
vectorBlock(block = ASCIIchar, length = 1) lengthBlock(length = integer4, block = ASCIIchar, blockLabel = "block")vectorBlock(block = ASCIIchar, length = 1) lengthBlock(length = integer4, block = ASCIIchar, blockLabel = "block")
block |
An object derived from the |
length |
The number of |
blockLabel |
A label to name the block component of the
|
These objects describe a block of binary data that consists
of a repeating sub-block. The sub-block can be any type
of "memBlock" object.
There is also a predefined ASCIIline block, which is
a block of single-byte characters terminated by a newline
character.
A "vectorBlock" or
lengthBlock object.
Paul Murrell
memFormat
readFormat
memBlock
atomicBlock
mixedBlock
markedBlock
# A block of 20 four-byte blocks # which are interpreted as integer values vectorBlock(integer4, 20)# A block of 20 four-byte blocks # which are interpreted as integer values vectorBlock(integer4, 20)
Displays the raw bytes of a file like a hex editor, showing offsets within the file, raw bytes in binary or hexadecimal form, and a human-readable representation of the bytes as either ASCII characters, integers, or real values. The file is broken up into blocks according to a supplied file format specification.
viewFormat(..., page = FALSE)viewFormat(..., page = FALSE)
... |
Arguments passed to the function |
page |
If |
This function is only called for its side-effect, which is to display the file.
Paul Murrell
viewFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) viewFormat(hexViewFile("rawTest.int"), memFormat(integers=vectorBlock(integer4, 20)))viewFormat(hexViewFile("rawTest.int"), memFormat(int1=integer4, int2=integer4)) viewFormat(hexViewFile("rawTest.int"), memFormat(integers=vectorBlock(integer4, 20)))
Displays the raw bytes of a file like a hex editor, showing offsets within the file, raw bytes in binary or hexadecimal form, and a human-readable representation of the bytes as either ASCII characters, integers, or real values.
viewRaw(..., page = FALSE)viewRaw(..., page = FALSE)
... |
Arguments passed to the function |
page |
If |
This function is only called for its side-effect, which is to display the file.
Paul Murrell
viewRaw(hexViewFile("rawTest.txt"), width=8) viewRaw(hexViewFile("rawTest.txt"), machine="binary", width=4) # UNICODE text # rawTest.unicode created using Notepad on Windows viewRaw(hexViewFile("rawTest.unicode"), width=8) viewRaw(hexViewFile("rawTest.int"), human="int") viewRaw(hexViewFile("rawTest.real"), human="real", width=8, endian="big")viewRaw(hexViewFile("rawTest.txt"), width=8) viewRaw(hexViewFile("rawTest.txt"), machine="binary", width=4) # UNICODE text # rawTest.unicode created using Notepad on Windows viewRaw(hexViewFile("rawTest.unicode"), width=8) viewRaw(hexViewFile("rawTest.int"), human="int") viewRaw(hexViewFile("rawTest.real"), human="real", width=8, endian="big")