NaturalDocs::BinaryFile

Exporter
NaturalDocs::BinaryFile

A package to manage Natural Docs’ binary data files.

Usage

  • Only one data file can be managed with this package at a time.  You must close the file before opening another one.
Summary
NaturalDocs::BinaryFileA package to manage Natural Docs’ binary data files.
Format
Standard Header
Data TypesAll the integer data types are written most significant byte first, aka big endian.
BINARY_FORMATAn 8-bit constant that’s used as the first byte of binary data files.
Variables
FH_BINARYDATAFILEThe file handle used for the data file.
currentFileThe FileName for the current configuration file being parsed.
File Functions
OpenForReadingOpens a binary file for reading.
OpenForWritingOpens a binary file for writing and writes the standard header.
CloseCloses the current configuration file.
Reading Functions
GetUInt8Reads and returns a UInt8 from the open file.
GetUInt16Reads and returns a UInt16 from the open file.
GetUInt32Reads and returns a UInt32 from the open file.
GetAString16Reads and returns an AString16 from the open file.
GetUString16Reads and returns a UString16 from the open file.
Writing Functions
WriteUInt8Writes a UInt8 to the open file.
WriteUInt16Writes a UInt32 to the open file.
WriteUInt32Writes a UInt32 to the open file.
WriteAString16Writes an AString16 to the open file.
WriteUString16Writes an UString16 to the open file.

Format

Standard Header

[UInt8: BINARY_FORMAT]
[VersionInt: app version]

The first byte is BINARY_FORMAT, which distinguishes binary configuration files from text ones, since Natural Docs used to use text data files with the same name.

The next section is the version of Natural Docs that wrote the file, as defined by NaturalDocs::Settings->AppVersion and written by NaturalDocs::Version->ToBinaryFile().

Data Types

All the integer data types are written most significant byte first, aka big endian.

An AString16 is a UInt16 followed by that many 8-bit ASCII characters.  It doesn’t include a null character at the end.  Undef strings are represented by a zero for the UInt16 and nothing following it.

A UString16 is a UInt16 followed by that many UTF-8 encoded bytes.  It doesn’t include a null character at the end.  Undef strings are represented by a zero for the UInt16 and nothing following it.

BINARY_FORMAT

An 8-bit constant that’s used as the first byte of binary data files.  This is used so that you can easily distinguish between binary and old-style text data files.  It’s not a character that would appear in plain text files.

Variables

FH_BINARYDATAFILE

The file handle used for the data file.

currentFile

my $currentFile

The FileName for the current configuration file being parsed.

File Functions

OpenForReading

sub OpenForReading #(FileName file,
optional VersionInt minimumVersion) => VersionInt

Opens a binary file for reading.

Parameters

minimumVersionThe minimum version of the file format that is acceptible.  May be undef.

Returns

The format VersionInt or undef if it failed.  It could fail for any of the following reasons.

  • The file doesn’t exist.
  • The file couldn’t be opened.
  • The file didn’t have the proper header.
  • Either the application or the file was from a development release, and they’re not the exact same development release.
  • The file’s format was less than the minimum version, if one was defined.
  • The file was from a later application version than the current.

OpenForWriting

sub OpenForWriting #(FileName file)

Opens a binary file for writing and writes the standard header.  Dies if the file cannot be opened.

Close

sub Close

Closes the current configuration file.

Reading Functions

GetUInt8

sub GetUInt8 # => UInt8

Reads and returns a UInt8 from the open file.

GetUInt16

sub GetUInt16 # => UInt16

Reads and returns a UInt16 from the open file.

GetUInt32

sub GetUInt32 # => UInt32

Reads and returns a UInt32 from the open file.

GetAString16

sub GetAString16 # => string

Reads and returns an AString16 from the open file.  Supports undef strings.

GetUString16

sub GetUString16 # => string

Reads and returns a UString16 from the open file.  Supports undef strings.

Writing Functions

WriteUInt8

sub WriteUInt8 #(UInt8 value)

Writes a UInt8 to the open file.

WriteUInt16

sub WriteUInt16 #(UInt16 value)

Writes a UInt32 to the open file.

WriteUInt32

sub WriteUInt32 #(UInt32 value)

Writes a UInt32 to the open file.

WriteAString16

sub WriteAString16 #(string value)

Writes an AString16 to the open file.  Supports undef strings.

WriteUString16

sub WriteUString16 #(string value)

Writes an UString16 to the open file.  Supports undef strings.

my $currentFile
The FileName for the current configuration file being parsed.
A string representing the absolute, platform-dependent path to a file.
sub OpenForReading #(FileName file,
optional VersionInt minimumVersion) => VersionInt
Opens a binary file for reading.
sub OpenForWriting #(FileName file)
Opens a binary file for writing and writes the standard header.
sub Close
Closes the current configuration file.
sub GetUInt8 # => UInt8
Reads and returns a UInt8 from the open file.
sub GetUInt16 # => UInt16
Reads and returns a UInt16 from the open file.
sub GetUInt32 # => UInt32
Reads and returns a UInt32 from the open file.
sub GetAString16 # => string
Reads and returns an AString16 from the open file.
sub GetUString16 # => string
Reads and returns a UString16 from the open file.
sub WriteUInt8 #(UInt8 value)
Writes a UInt8 to the open file.
sub WriteUInt16 #(UInt16 value)
Writes a UInt32 to the open file.
sub WriteUInt32 #(UInt32 value)
Writes a UInt32 to the open file.
sub WriteAString16 #(string value)
Writes an AString16 to the open file.
sub WriteUString16 #(string value)
Writes an UString16 to the open file.
An 8-bit constant that’s used as the first byte of binary data files.
sub AppVersion
Returns Natural Docs’ version number as an integer.
sub ToBinaryFile #(handle fileHandle,
VersionInt version)
Writes a VersionInt to a binary file.
A comparable integer representing a version number.
Close