Header lexy/input/file.hpp

Read from files or stdin.

Class lexy::read_file_result

lexy/input/file.hpp
namespace lexy
{
    enum class file_error
    {
        os_error,
        file_not_found,
        permission_denied,
    };

    template <typename Encoding       = default_encoding,
              typename MemoryResource = default-resource>
    class read_file_result
    {
    public:
        using encoding  = Encoding;
        using char_type = typename encoding::char_type;

        explicit operator bool() const noexcept;

        file_error error() const noexcept;

        const lexy::buffer<Encoding, MemoryResource>& buffer() const& noexcept;
        lexy::buffer<Encoding, MemoryResource>&&      buffer() &&     noexcept;
    };

}

The result of reading a file or from stdin.

It is a union of the error code lexy::file_error and lexy::buffer :

  • If it contains an error code, operator bool() returns false, error() returns the error code, and buffer().

  • If it contains a buffer, operator bool() returns true, buffer() returns the buffer, and error() must not be called.

Input lexy::read_file

lexy/input/file.hpp
namespace lexy
{
    template <encoding Encoding          = default_encoding,
              encoding_endianness Endian = encoding_endianness::bom,
              typename MemoryResource>
    auto read_file(const char     path,
                   MemoryResource resource = default-resource)
        -> read_file_result<Encoding, MemoryResource>;
}

The function read_file reads the contents of the file and makes it available as an input.

read_file tries to read the file at path into a buffer whose memory is allocated using the specified resource and whose contents are interpreted as code units of the encoding Encoding with the specified lexy::encoding_endianness , as if lexy::make_buffer_from_raw  is used. If this is successful, the returned lexy::read_file_result  will contain the lexy::buffer .

Otherwise, it will contain a lexy::file_error :

  • file_error::file_not_found if the path did not resolve to a file,

  • file_error::permission_denied if the path resolved to a file that cannot be read by the process,

  • or file_error::os_error if any other error occurred.

Example 1. Read UTF-32 from a file with a BOM.
// Read the file encoded in UTF-32.
auto file = lexy::read_file<lexy::utf32_encoding>("input.txt");
if (!file)
    throw my_file_read_error_exception(result.error());

// Use the file's buffer as input.
auto result = lexy::match<production>(file.buffer());
…

Input lexy::read_stdin

lexy/input/file.hpp
namespace lexy
{
    template <encoding Encoding          = default_encoding,
              encoding_endianness Endian = encoding_endianness::bom,
              typename MemoryResource>
    auto read_stdin(MemoryResource* resource = default-resource)
        -> read_file_result<Encoding, MemoryResource>;
}

The function read_stdin eagerly reads stdin and makes it available as an input.

It will repeatedly read data from stdin, until EOF is reached. If stdin is a terminal, this will prompt the user for input until they’ve closed stdin by typing Ctrl+D on Linux or Ctrl+Z on Windows.

The read data is interpreted as code units of the encoding Encoding with the specified lexy::encoding_endianness , as if lexy::make_buffer_from_raw  is used. If this is successful, the returned lexy::read_file_result  will contain the lexy::buffer , whose memory is allocated using the given resource.

Otherwise, it will contain a lexy::file_error . The only error code used is file_error::os_error, if reading has failed.

Caution
After a call to read_stdin, all further reads from stdin will fail.
Note
If stdin is a terminal, Encoding and Endian must match the encoding used by the terminal.

See also