wavelength 1.0.0
Loading...
Searching...
No Matches
Tools::Common Namespace Reference

Code that the host tools share. More...

Classes

struct  Error
 Failure returned through std::expected. More...
class  SourceImage
 Random access to the sectors of an ISO disc image. More...
struct  DirectoryExtent
 The extent of a directory in the ISO9660 tree. More...
struct  LocatedFile
 A file found in the ISO9660 tree. More...
class  Volume
 The data sectors of an ISO9660 volume, from a disc image or built from a disc root. More...

Typedefs

using Seconds = std::chrono::sys_seconds
 A UTC time with a resolution of one second.

Enumerations

enum class  ErrorCode { InvalidInput , Io , Network , Process }
 Kind of failure a tool reports. More...

Functions

std::uint16_t readLittle16 (std::span< const std::uint8_t > bytes, std::size_t offset)
 Read a little-endian 16-bit value.
std::uint32_t readLittle32 (std::span< const std::uint8_t > bytes, std::size_t offset)
 Read a little-endian 32-bit value.
void writeLittle (std::span< std::uint8_t > bytes, std::size_t offset, std::uint32_t value, std::size_t width=4)
 Write a little-endian value.
void writeBig (std::span< std::uint8_t > bytes, std::size_t offset, std::uint32_t value, std::size_t width=4)
 Write a big-endian value.
void writeBoth (std::span< std::uint8_t > bytes, std::size_t offset, std::uint32_t value, std::size_t width=4)
 Write a value in the ISO9660 both-endian form, little-endian followed by big-endian.
std::expected< std::vector< std::uint8_t >, Error > readFile (const std::filesystem::path &path)
 Read a whole file.
std::expected< std::vector< std::string >, Error > readLines (const std::filesystem::path &path)
 Read the lines of a text file, without their line endings, skipping empty lines.
std::expected< void, Error > writeLines (const std::filesystem::path &path, const std::vector< std::string > &lines)
 Write lines to a text file, each ending with a line feed.
std::expected< void, Error > writeFile (const std::filesystem::path &path, std::span< const std::uint8_t > data)
 Replace a file with the given bytes.
std::expected< void, Error > writeFile (const std::filesystem::path &path, std::string_view text)
 Replace a file with the given text, written as is.
std::unexpected< Error > invalidInput (std::string message)
 Report that an input file does not have the expected format.
std::unexpected< Error > discImageError (std::string message)
 Report that the disc image cannot be read or rewritten.
std::unexpected< Error > artifactError (std::string message)
 Report that build artifacts cannot be fetched from GitHub.
std::unexpected< Error > ioError (std::string message)
 Report that a file cannot be read or written.
void writeRecordDate (std::span< std::uint8_t > bytes, std::size_t offset, Seconds time)
 Write the seven-byte date of a directory record, in UTC.
Seconds readRecordDate (std::span< const std::uint8_t > bytes, std::size_t offset)
 Read the seven-byte date of a directory record.
std::string volumeDate (Seconds time)
 Format the 16 digits of a volume descriptor date, in UTC with hundredths of zero.
std::optional< Seconds > readVolumeDate (std::span< const std::uint8_t > bytes, std::size_t offset)
 Read the 17-byte date of a volume descriptor.
std::expected< Seconds, Error > fileModificationTime (const std::filesystem::path &path)
 Read the modification time of a file or directory.
void setupLogging (bool debug)
 Send log messages to standard error as LEVEL: message, the format of Python's logging.basicConfig(format='%(levelname)s: %(message)s').

Variables

constexpr int kIsoZoneMinutes = 15
 Minutes in one step of an ISO9660 zone offset.

Detailed Description

Code that the host tools share.

Typedef Documentation

◆ Seconds

using Tools::Common::Seconds = std::chrono::sys_seconds

A UTC time with a resolution of one second.

Enumeration Type Documentation

◆ ErrorCode

enum class Tools::Common::ErrorCode
strong

Kind of failure a tool reports.

Enumerator
InvalidInput 

An input file does not have the expected format.

Io 

Reading or writing a file failed.

Network 

A download failed.

Process 

A child process failed.

Function Documentation

◆ readLittle16()

std::uint16_t Tools::Common::readLittle16 ( std::span< const std::uint8_t > bytes,
std::size_t offset )
inline

Read a little-endian 16-bit value.

Parameters
bytesBuffer to read.
offsetOffset of the value's first byte.
Returns
The value.

◆ readLittle32()

std::uint32_t Tools::Common::readLittle32 ( std::span< const std::uint8_t > bytes,
std::size_t offset )
inline

Read a little-endian 32-bit value.

Parameters
bytesBuffer to read.
offsetOffset of the value's first byte.
Returns
The value.

◆ writeLittle()

void Tools::Common::writeLittle ( std::span< std::uint8_t > bytes,
std::size_t offset,
std::uint32_t value,
std::size_t width = 4 )
inline

Write a little-endian value.

Parameters
bytesBuffer to write.
offsetOffset of the value's first byte.
valueValue to write.
widthWidth of the value in bytes.

◆ writeBig()

void Tools::Common::writeBig ( std::span< std::uint8_t > bytes,
std::size_t offset,
std::uint32_t value,
std::size_t width = 4 )
inline

Write a big-endian value.

Parameters
bytesBuffer to write.
offsetOffset of the value's first byte.
valueValue to write.
widthWidth of the value in bytes.

◆ writeBoth()

void Tools::Common::writeBoth ( std::span< std::uint8_t > bytes,
std::size_t offset,
std::uint32_t value,
std::size_t width = 4 )
inline

Write a value in the ISO9660 both-endian form, little-endian followed by big-endian.

Parameters
bytesBuffer to write.
offsetOffset of the little-endian copy.
valueValue to write.
widthWidth of one copy in bytes.

◆ readFile()

std::expected< std::vector< std::uint8_t >, Error > Tools::Common::readFile ( const std::filesystem::path & path)

Read a whole file.

Parameters
pathFile to read.
Returns
The file contents, or an ErrorCode::Io error.

◆ readLines()

std::expected< std::vector< std::string >, Error > Tools::Common::readLines ( const std::filesystem::path & path)

Read the lines of a text file, without their line endings, skipping empty lines.

Parameters
pathFile to read.
Returns
The lines, or an ErrorCode::Io error.

◆ writeLines()

std::expected< void, Error > Tools::Common::writeLines ( const std::filesystem::path & path,
const std::vector< std::string > & lines )

Write lines to a text file, each ending with a line feed.

Parameters
pathFile to write.
linesThe lines.
Returns
Nothing, or an ErrorCode::Io error.

◆ writeFile() [1/2]

std::expected< void, Error > Tools::Common::writeFile ( const std::filesystem::path & path,
std::span< const std::uint8_t > data )

Replace a file with the given bytes.

Parameters
pathFile to write.
dataNew contents.
Returns
Nothing, or an ErrorCode::Io error.

◆ writeFile() [2/2]

std::expected< void, Error > Tools::Common::writeFile ( const std::filesystem::path & path,
std::string_view text )

Replace a file with the given text, written as is.

Parameters
pathFile to write.
textNew contents.
Returns
Nothing, or an ErrorCode::Io error.

◆ invalidInput()

std::unexpected< Error > Tools::Common::invalidInput ( std::string message)
inline

Report that an input file does not have the expected format.

Parameters
messageSentence describing the failure.
Returns
An ErrorCode::InvalidInput error.

◆ discImageError()

std::unexpected< Error > Tools::Common::discImageError ( std::string message)
inline

Report that the disc image cannot be read or rewritten.

Parameters
messageSentence describing the failure.
Returns
An ErrorCode::InvalidInput error.

◆ artifactError()

std::unexpected< Error > Tools::Common::artifactError ( std::string message)
inline

Report that build artifacts cannot be fetched from GitHub.

Parameters
messageSentence describing the failure.
Returns
An ErrorCode::Network error.

◆ ioError()

std::unexpected< Error > Tools::Common::ioError ( std::string message)
inline

Report that a file cannot be read or written.

Parameters
messageSentence describing the failure.
Returns
An ErrorCode::Io error.

◆ writeRecordDate()

void Tools::Common::writeRecordDate ( std::span< std::uint8_t > bytes,
std::size_t offset,
Seconds time )
inline

Write the seven-byte date of a directory record, in UTC.

Parameters
bytesBuffer holding the record.
offsetOffset of the date's first byte.
timeTime to write.

◆ readRecordDate()

Seconds Tools::Common::readRecordDate ( std::span< const std::uint8_t > bytes,
std::size_t offset )
inline

Read the seven-byte date of a directory record.

Parameters
bytesBuffer holding the record.
offsetOffset of the date's first byte.
Returns
The date in UTC, with the record's zone offset removed.

◆ volumeDate()

std::string Tools::Common::volumeDate ( Seconds time)
inline

Format the 16 digits of a volume descriptor date, in UTC with hundredths of zero.

Parameters
timeTime to format.
Returns
The digits; the descriptor's 17th byte, the zone offset, is written separately.

◆ readVolumeDate()

std::optional< Seconds > Tools::Common::readVolumeDate ( std::span< const std::uint8_t > bytes,
std::size_t offset )
inline

Read the 17-byte date of a volume descriptor.

Parameters
bytesBuffer holding the descriptor.
offsetOffset of the date's first digit.
Returns
The date in UTC, or nothing when the date is unset (all digits zero) or not digits.

◆ fileModificationTime()

std::expected< Seconds, Error > Tools::Common::fileModificationTime ( const std::filesystem::path & path)
inline

Read the modification time of a file or directory.

Parameters
pathFile or directory to examine.
Returns
The time in UTC, or an error when the path cannot be examined.

◆ setupLogging()

void Tools::Common::setupLogging ( bool debug)

Send log messages to standard error as LEVEL: message, the format of Python's logging.basicConfig(format='%(levelname)s: %(message)s').

Parameters
debugWhether debug messages are shown. Information and higher levels are always shown.

Variable Documentation

◆ kIsoZoneMinutes

int Tools::Common::kIsoZoneMinutes = 15
constexpr

Minutes in one step of an ISO9660 zone offset.