ngdb.reader

Class for handling the low-level reading of a Norton Guide database.

GuideReader

GuideReader(guide)

Low-level guide reading class.

Note

For now, no optimisation has taken place, in many cases the way this class reads data from a guide will be a method that's on the slower side. This is on purpose; it's about readable code that represents the underlying data structure rather than the fastest method of getting data into memory.

Once the rest of the library is done and working well this extra bit if docstring will likely be removed because work to improve the speed of this class will finally take place.

Parameters:

Name	Type	Description	Default
guide	Path	The guide to open.	required

RLE_MARKER class-attribute instance-attribute

RLE_MARKER = chr(255)

The value that marks run-length-encoded spaces.

closed property

closed

Is the file closed?

pos property

pos

The current position within the file.

close

close()

Close the guide.

goto

goto(pos)

Go to a specific byte position within the guide.

Parameters:

Name	Type	Description	Default
pos	int	The position to go to.	required

Returns:

Type	Description
Self	self

peek_word

peek_word(decrypt=True)

Read a two-byte word but don't move the file location.

Parameters:

Name	Type	Description	Default
decrypt	bool	Should the value be decrypted?	True

Returns:

Type	Description
int	The word value read.

read_byte

read_byte(decrypt=True)

Read a byte from the guide.

Parameters:

Name	Type	Description	Default
decrypt	bool	Should the value be decrypted?	True

Returns:

Type	Description
int	The byte value read.

read_long

read_long(decrypt=True)

Read a four-byte long word from the guide.

Parameters:

Name	Type	Description	Default
decrypt	bool	Should the value be decrypted?	True

Returns:

Type	Description
int	The long integer value read.

read_offset

read_offset()

Read an offset value from the guide.

Returns:

Type	Description
int	The offset value read.

Note

This function ensures that an offset value that means 'there is no offset' returns as -1.

read_str

read_str(length, decrypt=True)

Read a fixed-length string from the guide.

Parameters:

Name	Type	Description	Default
length	int	The length of the string to read.	required
decrypt	bool	Should the string be decrypted?	True

Returns:

Type	Description
str	The string value read.

read_strz

read_strz(length, decrypt=True)

Read a nul-terminated string from the guide.

This is similar to read_str, but it will read only as far as the first nul it encounters, within the bounds of length, and the file read location will be correctly settled to take this into account.

Parameters:

Name	Type	Description	Default
length	int	The maximum length of the string to read.	required
decrypt	bool	Should the string be decrypted?	True

Returns:

Type	Description
str	The string value read.

read_word

read_word(decrypt=True)

Read a two-byte word from the guide.

Parameters:

Name	Type	Description	Default
decrypt	bool	Should the value be decrypted?	True

Returns:

Type	Description
int	The word value read.

skip

skip(count=1)

Skip a number of bytes in the guide.

Parameters:

Name	Type	Description	Default
count	int	The optional number of bytes to skip.	1

Returns:

Type	Description
Self	Self.

skip_entry

skip_entry()

Skip a whole entry in the guide.

Returns:

Type	Description
Self	Self.

unrle classmethod

unrle(rle_text)

Un-run-length-encode the given string.

Parameters:

Name	Type	Description	Default
rle_text	str	The text that needs expanding.	required

Returns:

Type	Description
str	The given text with all RLE components expanded.

Note

Norton Guide database files use a very simple form of run-length-encoding for spaces. Simply put, if you find a byte in a string that is 0xFF, then the next byte is the number of spaces to insert into the string at this point. I've also found that 0xFF followed by 0xFF seems to mean you should insert a literal 0xFF (I think), although I've found that using a literal space makes more sense.