NaturalDocs::BinaryFile

Exporter

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::BinaryFile	A package to manage Natural Docs’ binary data files.
Format
Standard Header
Data Types	All the integer data types are written most significant byte first, aka big endian.
BINARY_FORMAT	An 8-bit constant that’s used as the first byte of binary data files.
Variables
FH_BINARYDATAFILE	The file handle used for the data file.
currentFile	The FileName for the current configuration file being parsed.
File Functions
OpenForReading	Opens a binary file for reading.
OpenForWriting	Opens a binary file for writing and writes the standard header.
Close	Closes the current configuration file.
Reading Functions
GetUInt8	Reads and returns a UInt8 from the open file.
GetUInt16	Reads and returns a UInt16 from the open file.
GetUInt32	Reads and returns a UInt32 from the open file.
GetAString16	Reads and returns an AString16 from the open file.
Writing Functions
WriteUInt8	Writes a UInt8 to the open file.
WriteUInt16	Writes a UInt32 to the open file.
WriteUInt32	Writes a UInt32 to the open file.
WriteAString16	Writes an AString16 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.

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

minimumVersion

The 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.

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.