buffer.h File Reference

Byte buffer type with read/write cursors for tokenizer input. More...

#include "x-type.h"

Go to the source code of this file.

Macros
#define	X_TYPE_BUFFER_NAME   "BUFFER"
#define	X_TYPE_BUFFER_FLAG_INNER   X_OBJ_FLAG_4
Predicates
#define	x_obj_type_isbuffer(B, X)   x_obj_is_type((B), (X), X_TYPE_BUFFER_NAME)
Accessors
#define	x_bufferval(X)   x_firststr(X)
#define	x_bufferread(X)   x_firststr(x_restobj(X))
#define	x_bufferwrite(X)   x_reststr(x_restobj(X))
#define	x_bufferlen(X)   (x_bufferread(X) - x_bufferval(X))
#define	x_bufferunread(X)   (x_bufferwrite(X) - x_bufferread(X))
#define	x_bufferlastchar(X)   (x_bufferread(X)[-1])
#define	x_buffereof(X)   (x_bufferread(X) >= x_bufferwrite(X))
Constructors
#define	x_mkbuffer(B, P)   x_make_buffer((B), X_OBJ_FLAG_NONE, (P))
#define	x_mkbufferro(B, P)   x_make_buffer((B), X_OBJ_FLAG_RO, (P))
#define	x_mkfbuffer(B, F, P)   x_make_buffer((B), (F), (P))
#define	x_mkbufferown(B, P)   x_make_buffer((B), X_OBJ_FLAG_OWN, (P))
#define	x_mkfbufferown(B, F, P)   x_make_buffer((B), X_OBJ_FLAG_OWN | (F), (P))

Functions
x_obj_t *	x_make_buffer (x_obj_t *p_base, x_obj_flag_t flags, void *p)
x_obj_t *	x_type_buffer_register (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_buffer_struct (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_buffer_mark (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_buffer_make (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_buffer_reset (x_obj_t *p_base, x_obj_t *p_obj)
x_obj_t *	x_type_buffer_retain (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_buffer_append (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_buffer_read (x_obj_t *p_base, x_obj_t *p_args)
x_obj_t *	x_type_buffer_read_text (x_obj_t *p_base, x_obj_t *p_args)

Detailed Description

Byte buffer type with read/write cursors for tokenizer input.

A BUFFER wraps a character array with separate read and write pointers, supporting incremental consumption from stdin or a pre-filled string. The read cursor advances as characters are consumed; the write cursor advances as new input arrives. Read-only buffers (X_OBJ_FLAG_RO) do not extend from stdin when exhausted.

Buffer layout: (base-ptr . (read-ptr . write-ptr)).

Author

Jon Ruttan (jonru.nosp@m.ttan.nosp@m.@gmai.nosp@m.l.co.nosp@m.m)

Copyright

2021 Jon Ruttan @license MIT No Attribution (MIT-0)

Macro Definition Documentation

x_buffereof

#define x_buffereof

(

X

)

(x_bufferread(X) >= x_bufferwrite(X))

True when the read cursor has reached the write cursor.

x_bufferlastchar

#define x_bufferlastchar

(

X

)

(x_bufferread(X)[-1])

The last character consumed (one behind the read cursor).

x_bufferlen

#define x_bufferlen

(

X

)

(x_bufferread(X) - x_bufferval(X))

Number of characters already consumed (read - base).

x_bufferread

#define x_bufferread

(

X

)

x_firststr(x_restobj(X))

Read cursor – next character to be consumed.

x_bufferunread

#define x_bufferunread

(

X

)

(x_bufferwrite(X) - x_bufferread(X))

Number of characters available to read (write - read).

x_bufferval

#define x_bufferval

(

X

)

x_firststr(X)

Base pointer – start of the underlying character array.

x_bufferwrite

#define x_bufferwrite

(

X

)

x_reststr(x_restobj(X))

Write cursor – next position for incoming data.

x_mkbuffer

#define x_mkbuffer	(		B,
			P
	)		x_make_buffer((B), X_OBJ_FLAG_NONE, (P))

Create a read/write buffer with default flags.

x_mkbufferown

#define x_mkbufferown	(		B,
			P
	)		x_make_buffer((B), X_OBJ_FLAG_OWN, (P))

Create an owning buffer (frees underlying array on GC).

x_mkbufferro

#define x_mkbufferro	(		B,
			P
	)		x_make_buffer((B), X_OBJ_FLAG_RO, (P))

Create a read-only buffer.

x_mkfbuffer

#define x_mkfbuffer	(		B,
			F,
			P
	)		x_make_buffer((B), (F), (P))

Create a buffer with explicit flags.

x_mkfbufferown

#define x_mkfbufferown	(		B,
			F,
			P
	)		x_make_buffer((B), X_OBJ_FLAG_OWN | (F), (P))

Create an owning buffer with extra flags.

x_obj_type_isbuffer

#define x_obj_type_isbuffer	(		B,
			X
	)		x_obj_is_type((B), (X), X_TYPE_BUFFER_NAME)

Test whether X is a BUFFER object.

X_TYPE_BUFFER_FLAG_INNER

#define X_TYPE_BUFFER_FLAG_INNER   X_OBJ_FLAG_4

The flag that marks a buffer's INNER object, (read . write), apart from its outer, (bytes . inner). Both are BUFFER-typed, and the inner's two slots are raw pointers into the bytes, so nothing may read them as objects to tell the two apart: the make sets this bit on the inner, and the save reads it. It shares its bit with the evaluator's #X_OBJ_FLAG_FNFRAME, which marks env spine cells; a buffer is never one.

X_TYPE_BUFFER_NAME

#define X_TYPE_BUFFER_NAME   "BUFFER"

Canonical type name (overridable).

Function Documentation

x_make_buffer()

x_obj_t * x_make_buffer	(	x_obj_t *	p_base,
		x_obj_flag_t	flags,
		void *	p
	)

Allocate a BUFFER wrapping the character array at p.

Allocate a BUFFER wrapping the character array at p.

Both read and write cursors are initialized to point at p.

Parameters

p_base	Base (execution context).
flags	Object flags (e.g. X_OBJ_FLAG_OWN, X_OBJ_FLAG_RO).
p	Pointer to the underlying character array.

Returns

Newly allocated BUFFER object.

x_type_buffer_append()

x_obj_t * x_type_buffer_append	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Append a single character at the write cursor.

Append a single character at the write cursor.

Writes the character from the second argument and advances the write cursor by one.

Parameters

p_base	Base (execution context).
p_args	Argument list: (buffer char-object).

Returns

The buffer object.

x_type_buffer_make()

x_obj_t * x_type_buffer_make	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Type-system make handler for BUFFER objects.

Type-system make handler for BUFFER objects.

Creates a two-level structure: the outer pair holds the base pointer, and the inner pair holds the read and write cursors (both initialized to the base pointer). The X_OBJ_FLAG_OWN flag is set only on the outer object.

Parameters

p_base	Base (execution context).
p_args	Argument list: (buffer-atom [flags-atom]).

Returns

Newly allocated BUFFER object.

x_type_buffer_mark()

x_obj_t * x_type_buffer_mark	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

GC mark handler – flags inner bookkeeping object without traversing raw pointers.

GC mark handler for BUFFER objects.

Flags the inner bookkeeping pair directly without traversing its slots, since those contain raw char* pointers rather than objects.

Parameters

p_base	Base (execution context).
p_args	Argument list: (buffer-object flags).

Returns

NULL (mark handlers have no meaningful return).

x_type_buffer_read()

x_obj_t * x_type_buffer_read	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Read one character, extending from stdin if needed.

Read one character from the buffer, extending from stdin if needed.

If the buffer is exhausted and not read-only, reads one character from the base input channel and appends it. Advances the read cursor by one and tracks newlines for error reporting.

Parameters

p_base	Base (execution context).
p_args	Argument list whose first element is the buffer.

Returns

The buffer object after advancing, or NULL on EOF.

Note

Read-only buffers return NULL when exhausted instead of reading from stdin.

x_type_buffer_read_text()

x_obj_t * x_type_buffer_read_text	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Read one text character, treating NUL as EOF.

Read one text character, treating NUL as EOF.

Delegates to x_type_buffer_read() and returns NULL if the result is NULL or the last character read was '\0'.

Parameters

p_base	Base (execution context).
p_args	Argument list whose first element is the buffer.

Returns

The buffer object after advancing, or NULL on EOF/NUL.

See also

x_type_buffer_read

x_type_buffer_register()

x_obj_t * x_type_buffer_register	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Register (or retrieve) the BUFFER type in the type alist.

Register (or retrieve) the BUFFER type in the type alist.

Parameters

p_base	Base (execution context).
p_args	Unused.

Returns

The registered BUFFER type object.

x_type_buffer_reset()

x_obj_t * x_type_buffer_reset	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Reset both cursors to the base pointer.

Reset both read and write cursors to the base pointer.

Effectively empties the buffer without deallocating the array.

Parameters

p_base	Base (execution context).
p_args	Argument list whose first element is the buffer.

Returns

The buffer object.

x_type_buffer_retain()

x_obj_t * x_type_buffer_retain	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Compact unread data to the front of the array.

Compact unread data to the front of the underlying array.

Copies the remaining unread bytes to position 0 and adjusts both cursors accordingly, freeing space at the end of the buffer.

Parameters

p_base	Base (execution context).
p_args	Argument list whose first element is the buffer.

Returns

The buffer object.

x_type_buffer_struct()

x_obj_t * x_type_buffer_struct	(	x_obj_t *	p_base,
		x_obj_t *	p_args
	)

Build the BUFFER type struct descriptor.