source.h File Reference

An opaque type representing the source code being parsed, regardless of origin (constant memory, file, memory-mapped file, or stream). More...

#include "prism/compiler/exported.h"
#include "prism/compiler/filesystem.h"
#include "prism/compiler/nodiscard.h"
#include "prism/compiler/nonnull.h"
#include <stddef.h>
#include <stdint.h>

Include dependency graph for source.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct pm_source_t	pm_source_t
	An opaque type representing source code being parsed.
typedef char *()	pm_source_stream_fgets_t(char *string, int size, void *stream)
	This function is used to retrieve a line of input from a stream.
typedef int()	pm_source_stream_feof_t(void *stream)
	This function is used to check whether a stream is at EOF.

Enumerations
enum	pm_source_init_result_t { PM_SOURCE_INIT_SUCCESS = 0 , PM_SOURCE_INIT_ERROR_GENERIC = 1 , PM_SOURCE_INIT_ERROR_DIRECTORY = 2 , PM_SOURCE_INIT_ERROR_NON_REGULAR = 3 }
	Represents the result of initializing a source from a file. More...

Functions
PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t *	pm_source_constant_new (const uint8_t *data, size_t length)
	Create a new source that wraps existing constant memory.
PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t *	pm_source_shared_new (const uint8_t *data, size_t length)
	Create a new source that wraps existing shared memory.
PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t *	pm_source_owned_new (uint8_t *data, size_t length)
	Create a new source that owns its memory.
PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t *	pm_source_file_new (const char *filepath, pm_source_init_result_t *result) PRISM_NONNULL(1
	Create a new source by reading a file into a heap-allocated buffer.
PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t *	pm_source_mapped_new (const char *filepath, int open_flags, pm_source_init_result_t *result) PRISM_NONNULL(1
	Create a new source by memory-mapping a file.
PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t *	pm_source_stream_new (void *stream, pm_source_stream_fgets_t *fgets, pm_source_stream_feof_t *feof)
	Create a new source by reading from a stream using the provided callbacks.
PRISM_EXPORTED_FUNCTION void	pm_source_free (pm_source_t *source) PRISM_NONNULL(1)
	Free the given source and any memory it owns.
PRISM_EXPORTED_FUNCTION size_t	pm_source_length (const pm_source_t *source) PRISM_NONNULL(1)
	Returns the length of the source data in bytes.
PRISM_EXPORTED_FUNCTION const uint8_t *	pm_source_source (const pm_source_t *source) PRISM_NONNULL(1)
	Returns a pointer to the source data.

Detailed Description

An opaque type representing the source code being parsed, regardless of origin (constant memory, file, memory-mapped file, or stream).

Typedef Documentation

pm_source_stream_fgets_t

typedef char *() pm_source_stream_fgets_t(char *string, int size, void *stream)

This function is used to retrieve a line of input from a stream.

It closely mirrors that of fgets so that fgets can be used as the default implementation.

As with fgets, implementations MUST write at most size bytes into string, including the terminating NUL byte (i.e. at most size - 1 bytes of data followed by a '\0'). The caller relies on this bound for memory safety, so an implementation that reads from a source which may return more data than requested (for example a multi-byte-aware gets) is responsible for clamping the amount it copies. Returns string, or NULL on EOF.

pm_source_stream_feof_t

typedef int() pm_source_stream_feof_t(void *stream)

This function is used to check whether a stream is at EOF.

It closely mirrors that of feof so that feof can be used as the default implementation.

Enumeration Type Documentation

pm_source_init_result_t

enum pm_source_init_result_t

Represents the result of initializing a source from a file.

Enumerator
PM_SOURCE_INIT_SUCCESS	Indicates that the source was successfully initialized.
PM_SOURCE_INIT_ERROR_GENERIC	Indicates a generic error from a source init function, where the type of error should be read from errno or GetLastError().
PM_SOURCE_INIT_ERROR_DIRECTORY	Indicates that the file that was attempted to be opened was a directory.
PM_SOURCE_INIT_ERROR_NON_REGULAR	Indicates that the file is not a regular file (e.g. a pipe or character device) and the caller should handle reading it.

Function Documentation

pm_source_constant_new()

PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t * pm_source_constant_new	(	const uint8_t *	data,
		size_t	length
	)

Create a new source that wraps existing constant memory.

The memory is not owned and will not be freed.

Parameters

data	The pointer to the source data.
length	The length of the source data in bytes.

Returns

A new source. Aborts on allocation failure.

pm_source_shared_new()

PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t * pm_source_shared_new	(	const uint8_t *	data,
		size_t	length
	)

Create a new source that wraps existing shared memory.

The memory is not owned and will not be freed. Semantically a "slice" of another source.

Parameters

data	The pointer to the source data.
length	The length of the source data in bytes.

Returns

A new source. Aborts on allocation failure.

pm_source_owned_new()

PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t * pm_source_owned_new	(	uint8_t *	data,
		size_t	length
	)

Create a new source that owns its memory.

The memory will be freed with xfree when the source is freed.

Parameters

data	The pointer to the heap-allocated source data.
length	The length of the source data in bytes.

Returns

A new source. Aborts on allocation failure.

pm_source_file_new()

PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t * pm_source_file_new	(	const char *	filepath,
		pm_source_init_result_t *	result
	)

Create a new source by reading a file into a heap-allocated buffer.

Parameters

filepath	The path to the file to read.
result	Out parameter for the result of the initialization.

Returns

A new source, or NULL on error (with result written to out param).

pm_source_mapped_new()

PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t * pm_source_mapped_new	(	const char *	filepath,
		int	open_flags,
		pm_source_init_result_t *	result
	)

Create a new source by memory-mapping a file.

Falls back to file reading on platforms without mmap support.

If the file is a non-regular file (e.g. a pipe or character device), PM_SOURCE_INIT_ERROR_NON_REGULAR is returned, allowing the caller to handle it appropriately (e.g. by reading it through their own I/O layer).

Parameters

filepath	The path to the file to read.
open_flags	Additional flags to pass to open(2) (e.g. O_NONBLOCK).
result	Out parameter for the result of the initialization.

Returns

A new source, or NULL on error (with result written to out param).

pm_source_stream_new()

PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t PRISM_EXPORTED_FUNCTION PRISM_NODISCARD pm_source_t * pm_source_stream_new	(	void *	stream,
		pm_source_stream_fgets_t *	fgets,
		pm_source_stream_feof_t *	feof
	)

Create a new source by reading from a stream using the provided callbacks.

Parameters

stream	The stream to read from.
fgets	The function to use to read from the stream.
feof	The function to use to check if the stream is at EOF.

Returns

A new source. Aborts on allocation failure.

pm_source_free()

PRISM_EXPORTED_FUNCTION void pm_source_free

(

pm_source_t *

source

)

Free the given source and any memory it owns.

Parameters

source

The source to free.

pm_source_length()

PRISM_EXPORTED_FUNCTION size_t pm_source_length

(

const pm_source_t *

source

)

Returns the length of the source data in bytes.

Parameters

source

The source to get the length of.

Returns

The length of the source data.

pm_source_source()

PRISM_EXPORTED_FUNCTION const uint8_t * pm_source_source

(

const pm_source_t *

source

)

Returns a pointer to the source data.

Parameters

source

The source to get the data of.

Returns

A pointer to the source data.