Blog Dion Format Metadesk Team Gallery FAQ

Metadesk Reference

  1. Helper Macros
  2. Linked-List Macros
  3. Memory Operations
  4. Characters
  5. Strings
  6. Memory Management
  7. Tokens
  8. Parsing
  9. Nodes
  10. Code Locations
  11. String Generation
  12. Map
  13. Expression Parser
  14. Command Line Helper
  15. File System Helper

Helper Macros

MD_FUNCTION

Specified before all Metadesk library functions. Expands to nothing by default. Can be overridden in usage code by using #define MD_FUNCTION ... (where ... is whatever you want to be in front of all functions).

#define MD_FUNCTION ...

MD_GLOBAL

Specified before all Metadesk library global variables. Expands to static by default. Can be overridden in usage code by using #define MD_GLOBAL ... (where ... is whatever you want to be in front of all global variable declarations).

#define MD_GLOBAL ...

MD_Assert

Will cause a crash when c is false.

#define MD_Assert(c) ...

MD_StaticAssert

Will cause a compilation failure when c is false.

#define MD_StaticAssert(c, label) ...

Parameters

label

A label for this static assertion. Necessary for static asserts in C.

MD_ArrayCount

Treats a as a static array to calculate the number of elements in the array. Does not work on pointers used to point at a number of elements.

#define MD_ArrayCount(a) ...

MD_Min

Expands to an expression returning the lesser of a and b. Expands both arguments multiple times, so avoiding complex expressions for a and b is recommended.

#define MD_Min(a, b) ...

MD_Max

Expands to an expression returning the higher of a and b. Expands both arguments multiple times, so avoiding complex expressions for a and b is recommended.

#define MD_Max(a, b) ...

MD_ClampBot

Equivalent to MD_Max.

#define MD_ClampBot(a, b) ...

MD_ClampTop

Equivalent to MD_Min.

#define MD_ClampTop(a, b) ...

MD_AlignPow2

Expands to an expression returning a multiple of b that is nearest to x, while still being larger.

#define MD_AlignPow2(x, b) ...

Linked-List Macros

MD_CheckNull

Returns true if p is a null pointer. Used as a helper in other linked list macros.

#define MD_CheckNull(p) ...

MD_SetNull

Sets p to a null pointer. Used as a helper in other linked list macros.

#define MD_SetNull(p) ...

MD_CheckNil

Returns true if p is a nil MD_Node pointer. Used as a helper in other linked list macros.

#define MD_CheckNil(p) ...

See Also

MD_NilNode, MD_NodeIsNil

MD_SetNil

Sets p to a nil MD_Node pointer. Used as a helper in other linked list macros.

#define MD_SetNil(p) ...

See Also

MD_NilNode, MD_NodeIsNil

MD_QueuePush_NZ

Expands to an expression that pushes n into a singly-linked-list queue, with f being a pointer to the first element in the queue, and l being a pointer to the last element in the queue. Allows for overrides on both what is considered the zero-value, as well as what the name of the next pointer inside of the associated type is.

#define MD_QueuePush_NZ(f, l, n, next, zchk, zset) ...

Parameters

f

A pointer to the first element of the queue. When the queue is empty, this should be equivalent to a zero-value compatible with the zchk and zset arguments.

l

A pointer to the last element of the queue. When the queue is empty, this should be equivalent to a zero-value compatible with the zchk and zset arguments.

n

A pointer to the element that is to be added to the end of the queue.

next

The name of the next pointer member within the type used for the queue.

zchk

The name of a macro that accepts one argument, and returns whether it is considered the zero-value.

zset

The name of a macro that accepts one argument, and assigns the zero-value to it.

MD_QueuePop_NZ

Expands to an expression that pops the first element out of the queue, with f being a pointer to the first element in the queue, and l being a pointer to the last element in the queue. Allows for overrides on both what is considered the zero-value, as well as what the name of the next pointer inside of the associated type is.

#define MD_QueuePop_NZ(f, l, next, zset) ...

Parameters

f

A pointer to the first element of the queue. When the queue is empty, this should be equivalent to a zero-value compatible with the zchk and zset arguments.

l

A pointer to the last element of the queue. When the queue is empty, this should be equivalent to a zero-value compatible with the zchk and zset arguments.

next

The name of the next pointer member within the type used for the queue.

zset

The name of a macro that accepts one argument, and assigns the zero-value to it.

MD_StackPush_N

Expands to an expression that pushes a new element onto the top of a singly-linked stack, with f being a pointer to the top of the stack. Allows overriding the name of the pointer member inside of the type used for the stack, which is used to point at the next node in the chain.

#define MD_StackPush_N(f, n, next) ...

Parameters

f

A pointer to the first element of the stack. When the stack is empty, this should be 0.

n

A pointer to the new element to be added to the stack.

next

The name of the next pointer member within the type used for the stack.

MD_StackPop_NZ

Expands to an expression that pops the top of a singly-linked stack. Does not return the popped element, which should be grabbed before using this macro. Allows overriding both the name of the pointer member inside of the type used for the stack's links, and how the zero-value is checked.

#define MD_StackPop_NZ(f, next, zchk) ...

Parameters

f

A pointer to the first element of the stack. When the stack is empty, this should be 0.

next

The name of the next pointer member within the type used for the stack.

zchk

The name of a macro that accepts one argument, and returns whether it is considered the zero-value.

MD_DblPushBack_NPZ

Expands to an expression that pushes a new element to the back of a doubly-linked-list, with f being a pointer to the first element in the linked list, l being a pointer to the last element in the linked list, and n being the new element to add. Allows overriding the names of the pointer members used to store the next and previous links of a node, and the way that the zero-value is both checked for and set.

#define MD_DblPushBack_NPZ(f, l, n, next, prev, zchk, zset) ...

Parameters

f

A pointer to the first element of the list. When the list is empty, this should be the zero-value compatible with the zchk and zset arguments.

l

A pointer to the last element of the list. When the list is empty, this should be the zero-value compatible with the zchk and zset arguments.

n

A pointer to the new element of the list to be added.

next

The name of the pointer member in the list's type to consider as encoding the next node in the list.

prev

The name of the pointer member in the list's type to consider as encoding the previous node in the list.

zchk

The name of a macro that accepts one argument, and returns whether it is considered the zero-value.

zset

The name of a macro that accepts one argument, and assigns the zero-value to it.

MD_DblRemove_NPZ

Expands to an expression that removes an element from a doubly-linked-list, with f being a pointer to the first element in the linked list, l being a pointer to the last element in the linked list, and n being the node to be removed. Allows overriding the names of the pointer members used to store the next and previous links of a node, and the way that the zero-value is both checked for and set.

#define MD_DblRemove_NPZ(f, l, n, next, prev, zset) ...

Parameters

f

A pointer to the first element of the list. When the list is empty, this should be the zero-value compatible with the zchk and zset arguments.

l

A pointer to the last element of the list. When the list is empty, this should be the zero-value compatible with the zchk and zset arguments.

n

A pointer to the new element of the list to be removed.

next

The name of the pointer member in the list's type to consider as encoding the next node in the list.

prev

The name of the pointer member in the list's type to consider as encoding the previous node in the list.

zset

The name of a macro that accepts one argument, and assigns the zero-value to it.

MD_QueuePush

Expands to an expression that pushes a node n to the back of a singly-linked-list queue defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Null pointers are used to delimit the end of the list, and to encode that the list is empty. Expects that there exists a next member inside of the type of f, l, and n, which encodes the link to the next node.

#define MD_QueuePush(f, l, n) ...

MD_QueuePop

Expands to an expression that pops a node n from the front of a singly-linked-list queue defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Null pointers are used to delimit the end of the list, and to encode that the list is empty. Expects that there exists a next member inside of the type of f, l, and n, which encodes the link to the next node.

#define MD_QueuePop(f, l) ...

MD_StackPush

Expands to an expression that pushes a node n to the top of a singly-linked-list stack defined by f, a pointer to the top element of the stack. Null pointers are used to delimit the end of the stack, and an empty stack. Expects that there exists a next member inside of the type of f and n, which encodes the link to the next node.

#define MD_StackPush(f, n) ...

MD_StackPop

Expands to an expression that pops a node n off the top of a singly-linked-list stack defined by f, a pointer to the top element of the stack. Null pointers are used to delimit the end of the stack, and an empty stack. Expects that there exists a next member inside of the type of f, which encodes the link to the next node in the stack.

#define MD_StackPop(f) ...

MD_DblPushBack

Expands to an expression that pushes a node n to the back of a doubly-linked-list defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Null pointers are used to delimit the end of the list, and to encode that the list is empty. Expects that there exists a next member inside of the type of f, l, and n, which encodes the link to the next node. Expects that there also exists a prev member inside of the type of f, l, and n, which encodes the link to the previous node.

#define MD_DblPushBack(f, l, n) ...

MD_DblPushFront

Expands to an expression that pushes a node n to the front of a doubly-linked-list defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Null pointers are used to delimit the end of the list, and to encode that the list is empty. Expects that there exists a next member inside of the type of f, l, and n, which encodes the link to the next node. Expects that there also exists a prev member inside of the type of f, l, and n, which encodes the link to the previous node.

#define MD_DblPushFront(f, l, n) ...

MD_DblRemove

Expands to an expression that removes a node n from a doubly-linked-list defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Null pointers are used to delimit the end of the list, and to encode that the list is empty. Expects that there exists a next member inside of the type of f, l, and n, which encodes the link to the next node. Expects that there also exists a prev member inside of the type of f, l, and n, which encodes the link to the previous node.

#define MD_DblRemove(f, l, n) ...

MD_NodeDblPushBack

Expands to an expression that pushes an MD_Node n to the back of a doubly-linked-list defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Nil pointers, identical to those returned by MD_NilNode, are used to delimit the end of the list, and to encode that the list is empty.

#define MD_NodeDblPushBack(f, l, n) ...

MD_NodeDblPushFront

Expands to an expression that pushes an MD_Node n to the front of a doubly-linked-list defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Nil pointers, identical to those returned by MD_NilNode, are used to delimit the end of the list, and to encode that the list is empty.

#define MD_NodeDblPushFront(f, l, n) ...

MD_NodeDblRemove

Expands to an expression that removes an MD_Node n from a doubly-linked-list defined by f, a pointer to the first element in the list, and l, a pointer to the last element in the list. Nil pointers, identical to those returned by MD_NilNode, are used to delimit the end of the list, and to encode that the list is empty.

#define MD_NodeDblRemove(f, l, n) ...

Memory Operations

MD_MemorySet

A macro that expands to an overrideable memset equivalent call that sets size bytes at the address stored in memory to byte_value.

#define MD_MemorySet(memory, byte_value, size) ...

MD_MemoryZero

A macro that expands to an overrideable memset equivalent call that zeroes size bytes at the address stored in memory.

#define MD_MemoryZero(memory, size) ...

MD_MemoryZeroStruct

A macro that expands to an overrideable memset equivalent call that zeroes sizeof(*(struct_pointer)) bytes at the address stored in struct_pointer.

#define MD_MemoryZeroStruct(struct_pointer) ...

MD_MemoryCopy

A macro that expands to an overrideable memmove equivalent call that copies size bytes from source to destination. The ranges defined by the pointers and size may overlap.

#define MD_MemoryCopy(destination, source, size) ...

Characters

MD_CharIsAlpha

Returns whether an ASCII character is alphabetic.

MD_b32 MD_CharIsAlpha(MD_u8 c);

MD_CharIsAlphaUpper

Returns whether an ASCII character is alphabetic and upper-case.

MD_b32 MD_CharIsAlphaUpper(MD_u8 c);

MD_CharIsAlphaLower

Returns whether an ASCII character is alphabetic and lower-case.

MD_b32 MD_CharIsAlphaLower(MD_u8 c);

MD_CharIsDigit

Returns whether an ASCII character is numeric.

MD_b32 MD_CharIsDigit(MD_u8 c);

MD_CharIsUnreservedSymbol

Returns whether an ASCII character is a non-reserved symbol as defined by the Metadesk grammar: ~, !, $, %, ^, &, *, -, =, +, <, ., >, /, ?, or |.

MD_b32 MD_CharIsUnreservedSymbol(MD_u8 c);

MD_CharIsReservedSymbol

Returns whether an ASCII character is a reserved symbol as defined by the Metadesk grammar: {, }, (, ), \\, [, ], #, ,, ;, :, or @.

MD_b32 MD_CharIsReservedSymbol(MD_u8 c);

MD_CharIsSpace

Return whether an ASCII character is whitespace.

MD_b32 MD_CharIsSpace(MD_u8 c);

MD_CharToUpper

Return the alphabetic uppercase equivalent of an ASCII character, or just returns the passed-in character if it is not alphabetic.

MD_u8 MD_CharToUpper(MD_u8 c);

MD_CharToLower

Return the alphabetic lowercase equivalent of an ASCII character, or just returns the passed-in character if it is not alphabetic.

MD_u8 MD_CharToLower(MD_u8 c);

MD_CharToForwardSlash

Return a / if \\ is passed in, otherwise just returns the passed character.

MD_u8 MD_CharToForwardSlash(MD_u8 c);

Strings

MD_String8

This type is used as the fundamental string type in Metadesk, and as the type for byte granularity data blobs. Strings of this type are encoded in UTF-8.

struct MD_String8
{
  MD_u8* str;
  MD_u64 size;
};

See Also

MD_String8List

MD_String16

This type represents a string encoded in UTF-16.

struct MD_String16
{
  MD_u16* str;
  MD_u64 size;
};

MD_String32

This type represents a string encoded in UTF-32.

struct MD_String32
{
  MD_u32* str;
  MD_u64 size;
};

MD_String8Node

MD_String8Node forms one node in a linked list of strings. Generally used as a part of an MD_String8List data structure.

struct MD_String8Node
{
  MD_String8Node* next;
  MD_String8 string;
};

Members

The next node in the list, or null if this is the last node.

MD_String8 string

The string value stored at this node.

MD_String8List

This type is implemented as a singly linked list with an MD_String8 at each node.

struct MD_String8List
{
  MD_u64 node_count;
  MD_u64 total_size;
  MD_String8Node* first;
  MD_String8Node* last;
};

Members

MD_u64 node_count

The number of nodes in the list.

MD_u64 total_size

The size of all strings in the list summed together.

A pointer to the first node in the list.

A pointer to the last node in the list.

See Also

MD_S8ListPush, MD_S8Split, MD_S8ListJoin

A sample loop over MD_String8List:


MD_String8List list;
for(MD_String8Node *node = list.first; node != 0; node = node->next)
{
    MD_String8 string = node->string;
    // ... work on string ...
}

The node_count and total_size are automatically maintained by the helpers for inserting to the list, and are used in the string joining functions. Hand rolled code for building string lists should take those fields into consideration if the join functions need to work.

MD_StringJoin

Used as optional parameters for MD_S8ListJoin.

struct MD_StringJoin
{
  MD_String8 pre;
  MD_String8 mid;
  MD_String8 post;
};

Members

The string to insert before the joined strings in the list.

The string to insert between each node in the string list.

MD_String8 post

The string to insert after the joined strings in the list.

See Also

MD_S8ListJoin, MD_String8List, MD_String8

MD_MatchFlags

These flags control matching rules in routines that perform matching on strings and MD_Node trees. Not all flags are within this enum. These flags must not be overlapping with those in the MD_StringMatchFlags enum, nor those in the MD_NodeMatchFlags enum. This allows all flags to be associated with their respective behaviors, but also be combined when appropriate.

typedef MD_u32 MD_MatchFlags;
enum
{
  MD_MatchFlag_FindLast           = 1<<0,
};

Values

MD_MatchFlag_FindLast

For routines returning the location of a substring, alters the behavior to return the last match instead of the first match.

See Also

MD_Node, MD_String8, MD_S8Match, MD_NodeMatch, MD_NodeDeepMatch, MD_StringMatchFlags, MD_NodeMatchFlags

MD_StringMatchFlags

These flags control matching rules in routines that perform matching on strings. These flags must not be overlapping with those in the MD_MatchFlags enum, nor those in the MD_NodeMatchFlags enum. This allows all flags to be associated with their respective behaviors, but also be combined when appropriate.

typedef MD_u32 MD_StringMatchFlags;
enum
{
  MD_StringMatchFlag_CaseInsensitive    = 1<<4,
  MD_StringMatchFlag_RightSideSloppy    = 1<<5,
  MD_StringMatchFlag_SlashInsensitive   = 1<<6,
};

Values

MD_StringMatchFlag_CaseInsensitive

When comparing strings, consider lower case letters equivalent to upper case equivalents in the ASCII range.

MD_StringMatchFlag_RightSideSloppy

When comparing strings, do not require the strings to be the same length. If one of the strings is a prefix of another, the two strings will count as a match.

MD_StringMatchFlag_SlashInsensitive

When comparing strings, consider forward slash and backward slash to be equivalents.

See Also

MD_Node, MD_String8, MD_S8Match, MD_NodeMatch, MD_NodeDeepMatch, MD_MatchFlags, MD_NodeMatchFlags

MD_NodeMatchFlags

These flags control matching rules in routines that perform matching on MD_Node trees. These flags must not be overlapping with those in the MD_MatchFlags enum, nor those in the MD_StringMatchFlags enum. This allows all flags to be associated with their respective behaviors, but also be combined when appropriate.

typedef MD_u32 MD_NodeMatchFlags;
enum
{
  MD_NodeMatchFlag_Tags               = 1<<16,
  MD_NodeMatchFlag_TagArguments       = 1<<17,
};

Values

MD_NodeMatchFlag_Tags

When comparing nodes with this flag set, differences in the order and names of tags on a node count as differences in the input nodes. Without this flag tags are ignored in tree comparisons.

MD_NodeMatchFlag_TagArguments

When comparing nodes with this flag set in addition to MD_NodeMatchFlag_Tags, the differences in the arguments of each tag (the tag's children in the tree) count as differences in the input nodes. Tag arguments are compared with fully recursive compares, whether or not the compare routine would be recursive or not.

See Also

MD_Node, MD_String8, MD_S8Match, MD_NodeMatch, MD_NodeDeepMatch, MD_StringMatchFlags, MD_MatchFlags

MD_DecodedCodepoint

This type is used to report the results of consuming one character from a unicode encoded stream.

struct MD_DecodedCodepoint
{
  MD_u32 codepoint;
  MD_u32 advance;
};

Members

MD_u32 codepoint

The codepoint of the consumed character.

MD_u32 advance

The size of the character in the encoded stream, measured in 'units'. A unit is one byte in UTF-8, two bytes in UTF-16, and four bytes in UTF-32.

See Also

MD_DecodeCodepointFromUtf8, MD_DecodeCodepointFromUtf16

MD_IdentifierStyle

These constants control how MD_S8Stylize forms strings.

enum MD_IdentifierStyle
{
  MD_IdentifierStyle_UpperCamelCase,
  MD_IdentifierStyle_LowerCamelCase,
  MD_IdentifierStyle_UpperCase,
  MD_IdentifierStyle_LowerCase,
};

Values

MD_IdentifierStyle_UpperCamelCase

Creates identifiers where each word begins with an upper-case letter, with each subsequent letter in the word being lower-case. With no word separators, creates identifiers that look like ExampleIdentifier.

MD_IdentifierStyle_LowerCamelCase

Creates identifiers where each word begins with an upper-case letter, except the first word (which begins with a lower-case letter), with each subsequent letter in the word being lower-case. With no word separators, creates identifiers that look like exampleIdentifier.

MD_IdentifierStyle_UpperCase

All letters in all words are upper-case.

MD_IdentifierStyle_LowerCase

All letters in all words are lower-case.

MD_CalculateCStringLength

Calculates the number of bytes in a C-string by checking for a null-terminator.

MD_u64 MD_CalculateCStringLength(char* cstr);

MD_S8

Constructs an MD_String8.

MD_String8 MD_S8(MD_u8* str, MD_u64 size);

Parameters

MD_u8* str

The base pointer of the returned MD_String8.

MD_u64 size

The size of the returned MD_String8.

MD_S8CString

Constructs an MD_String8 from a C-string by calling MD_CalculateCStringLength.

#define MD_S8CString(s) ...

MD_S8Lit

Constructs an MD_String8 from a C-string literal by using sizeof. In C++, the equivalent can be done with the user-defined literal code provided in the library, which uses _md as a suffix on a string literal.

#define MD_S8Lit(s) ...

MD_S8LitComp

Constructs an MD_String8 from a C-string literal by using sizeof. Differs from MD_S8Lit in that it does not expand with (MD_String8) before the brace initializer, allowing it to be used in C for static initializations.

#define MD_S8LitComp(s) ...

MD_S8Range

Constructs an MD_String8 from two pointers into the same buffer, corresponding to the beginning and one past the last byte of a string.

MD_String8 MD_S8Range(MD_u8* first, MD_u8* opl);

MD_S8Substring

Returns an MD_String8 encoding a sub-range of the passed MD_String8.

MD_String8 MD_S8Substring(MD_String8 str, MD_u64 min, MD_u64 max);

Parameters

The string for which the substring is returned.

MD_u64 min

The offset, from the passed string's base, of the first character of the returned substring.

MD_u64 max

The offset, from the passed string's base, of one byte past the last character of the returned substring.

MD_S8Skip

Returns a sub-range of the passed MD_String8, skipping the first min bytes.

MD_String8 MD_S8Skip(MD_String8 str, MD_u64 min);

Parameters

The string for which the substring is returned.

MD_u64 min

The new minimum offset, relative to the base of str. Also the number of bytes to skip at the beginning of str.

MD_S8Chop

Returns a sub-range of the passed MD_String8, chopping off the last nmax bytes.

MD_String8 MD_S8Chop(MD_String8 str, MD_u64 nmax);

Parameters

The string for which the substring is returned.

MD_u64 nmax

The number of bytes to chop off at the end of str.

MD_S8Prefix

Returns a prefix of the passed MD_String8.

MD_String8 MD_S8Prefix(MD_String8 str, MD_u64 size);

Parameters

The string for which the substring is returned.

MD_u64 size

The desired size of the returned prefix.

MD_S8Suffix

Returns a suffix of the passed MD_String8.

MD_String8 MD_S8Suffix(MD_String8 str, MD_u64 size);

Parameters

The string for which the substring is returned.

MD_u64 size

The desired size of the returned suffix.

MD_S8Match

Compares the passed strings a and b, and determines whether or not the two strings match. The passed MD_MatchFlags argument will modify the string matching algorithm; for example, allowing case insensitivity. Return 1 if the strings are found to match, and 0 otherwise.

Parameters

The first string to compare.

The second string to compare.

Controls for the string matching algorithm.

Return Value

1 if the strings match, or 0 otherwise.

MD_S8FindSubstring

Searches str for an occurrence of substring. The passed flags can be used to modify the matching rules. Returns the position at which the search ended; if the return value is equivalent to str.size, then the substring was not found.

MD_u64 MD_S8FindSubstring(MD_String8 str, MD_String8 substring, MD_u64 start_pos, MD_MatchFlags flags);

Parameters

The string to search within for the substring.

MD_String8 substring

The 'needle' string to find within str.

MD_u64 start_pos

The first position, in bytes relative to the base of str, to conduct the search from.

Controls for the string matching algorithm.

Return Value

The last position at which the substring was searched for. Will be equal to str.size if the substring was not found. If it is less than that, the substring was found at the returned offset.

MD_S8Copy

Copies string by allocating an entirely new portion of memory and copying the passed string's memory to the newly allocated memory. Returns the copy of string using the new memory.

MD_S8FmtV

Allocates a new string, with the contents of the string being determined by a mostly-standard C formatting string passed in fmt, with a variable-argument list being passed in args. Used when composing variable argument lists at multiple levels, and when you need to pass a va_list. The format string is non-standard because it allows %S as a specifier for MD_String8 arguments. Before this call, it is expected that you call va_start on the passed va_list, and also that you call va_end after the function returns. If you just want to pass variable arguments yourself (instead of a va_list), then see MD_S8Fmt.

MD_String8 MD_S8FmtV(MD_Arena* arena, char* fmt, va_list args);

See Also

MD_S8Fmt, MD_S8Copy

MD_S8Fmt

Allocates a new string, with the contents of the string being determined by a mostly-standard C formatting string passed in fmt, with variable arguments fitting the expected ones in fmt being passed in after. The format string is non-standard because it allows %S as a specifier for MD_String8 arguments. If you are composing this with your own variable-arguments call, use MD_S8FmtV instead.

MD_String8 MD_S8Fmt(MD_Arena* arena, char* fmt, ...);

See Also

MD_S8FmtV, MD_S8Copy

MD_S8VArg

This is a helper macro that is normally used with passing an MD_String8 into a printf like function, usually used in combination with the %.*s format specifier. Metadesk uses length-based strings, not null-terminated (like many C functions expect), so this is often convenient when interacting with C-like APIs. This will expand to passing the size of the passed string first, a comma, and the pointer to the base of the string being passed immediately after.

#define MD_S8VArg(s) ...

See Also

MD_String8

MD_S8ListPush

Pushes a new MD_String8 to an MD_String8List by allocating a new MD_String8Node, filling it with string, and modifying the existing list elements in list to end with the newly allocated node.

void MD_S8ListPush(MD_Arena* arena, MD_String8List* list, MD_String8 string);

See Also

MD_String8List, MD_String8Node, MD_String8

MD_S8ListPushFmt

Pushes a new MD_String8 to an MD_String8List by allocating a new MD_String8Node, filling it with a C-style format string defined by fmt and the variadic arguments following it, and modifying the existing list elements in list to end with the newly allocated node.

void MD_S8ListPushFmt(MD_Arena* arena, MD_String8List* list, char* fmt, ...);

See Also

MD_String8List, MD_String8Node, MD_String8

MD_S8ListConcat

Pushes an MD_String8List to another MD_String8List. This will zero all memory in to_push, so you cannot expect to_push to retain any of the list elements it had before this call. This is because no strings nor nodes are copied, so the nodes in to_push are repurposed for being a part of list.

See Also

MD_String8List, MD_String8Node, MD_String8, MD_S8ListPush

MD_S8Split

Divides string into an MD_String8List, each node of which corresponds to a substring of string that was separated by an occurrence of one of the 'splitter's passed in splits.

MD_String8List MD_S8Split(MD_Arena* arena, MD_String8 string, MD_u32 split_count, MD_String8* splits);

Parameters

MD_Arena* arena

The arena to use for allocation.

MD_String8 string

The string to search for splitting strings, and to subdivide.

MD_u32 split_count

The number of splitting strings to search for.

MD_String8* splits

A pointer to an array of strings stored as MD_String8 objects, each corresponding to a string pattern that should split string.

Return Value

A list containing all of the strings separated by the passed splitter strings. None of the strings will contain the splitter strings themselves.

See Also

MD_String8, MD_String8List, MD_String8Node, MD_S8ListJoin

MD_S8ListJoin

Returns a new MD_String8 that contains the contents of each string in list, in order, with the separator string inserted between each string.

Parameters

MD_Arena* arena

The arena to use for allocation.

The list to join.

Optional join parameters.

See Also

MD_String8, MD_String8List, MD_String8Node, MD_S8Split

MD_S8Stylize

Provided an MD_String8 string in a traditional identifier style, attempts heuristically to return a transformed version of string to a new identifier style. Cannot be fully correct in all cases.

Parameters

MD_Arena* arena

The arena to use for allocation.

MD_String8 string

The string to attempt to transform.

The style that each word should have.

MD_String8 separator

A string to separate each word in the returned string.

See Also

MD_IdentifierStyle

MD_DecodeCodepointFromUtf8

MD_DecodeCodepointFromUtf16

MD_Utf8FromCodepoint

MD_u32 MD_Utf8FromCodepoint(MD_u8* out, MD_u32 codepoint);

MD_Utf16FromCodepoint

MD_u32 MD_Utf16FromCodepoint(MD_u16* out, MD_u32 codepoint);

MD_S8FromS16

Converts a UTF-16 string, encoded into an MD_String16 object, into a UTF-8 string. Allocates the required storage for the UTF-8 string onto arena.

Parameters

MD_Arena* arena

The arena to use for memory allocation.

The UTF-16 string to convert.

MD_S16FromS8

Converts a UTF-8 string, encoded into an MD_String8 object, into a UTF-16 string. Allocates the required storage for the UTF-16 string onto arena.

Parameters

MD_Arena* arena

The arena to use for memory allocation.

The UTF-8 string to convert.

MD_S8FromS32

Converts a UTF-32 string, encoded into an MD_String32 object, into a UTF-8 string. Allocates the required storage for the UTF-8 string onto arena.

Parameters

MD_Arena* arena

The arena to use for memory allocation.

The UTF-32 string to convert.

MD_S32FromS8

Converts a UTF-8 string, encoded into an MD_String8 object, into a UTF-32 string. Allocates the required storage for the UTF-32 string onto arena.

Parameters

MD_Arena* arena

The arena to use for memory allocation.

The UTF-8 string to convert.

MD_PathChopLastPeriod

Searches string for the last . character occurring in the string, and chops the . and anything following after it off of the returned string.

See Also

MD_S8Chop

MD_PathSkipLastSlash

Searches string for the last / or \\ character occurring in the string, and skips it and anything before it in the returned string.

See Also

MD_S8Skip

MD_PathSkipLastPeriod

Searches string for the last . character, and returns the substring starting at the character after it, to the end of the string. For usual file naming schemes where the extension of a file is encoded by any characters following the last . of a filename, this will return the extension.

See Also

MD_PathChopLastSlash, MD_S8Suffix, MD_S8Substring, MD_S8Chop

MD_PathChopLastSlash

Searches string for the last / or \\ character, and returns the substring that ends with that character. For usual file naming schemes where folders are encoded with / or \\ characters, this will return the entire path to the passed filename, not including the filename itself.

See Also

MD_PathSkipLastPeriod, MD_S8Prefix, MD_S8Substring, MD_S8Skip

MD_S8SkipWhitespace

Returns the equivalent of string with all leading whitespace skipped.

See Also

MD_S8Substring, MD_S8ChopWhitespace, MD_S8Skip, MD_S8Chop

MD_S8ChopWhitespace

Returns the equivalent of string with all trailing whitespace chopped.

See Also

MD_S8Substring, MD_S8SkipWhitespace, MD_S8Skip, MD_S8Chop

MD_StringIsU64

Returns 1 if string appears to encode an integer value with a base of radix, or 0 otherwise.

MD_b32 MD_StringIsU64(MD_String8 string, MD_u32 radix);

MD_StringIsCStyleInt

Returns 1 if string appears to encode an integer value in C-style syntax, or 0 otherwise.

MD_U64FromString

Parses string as an integer with a base defined by radix. Returns the parsed value.

MD_u64 MD_U64FromString(MD_String8 string, MD_u32 radix);

MD_CStyleIntFromString

Parses string as an integer with a base defined by C-like rules: If the numeric part of the string begins with 0x, then it will be parsed as base-16. If it begins with 0b, it will be parsed as base-2. Otherwise, it will be parsed as base 10. Returns the parsed value.

MD_F64FromString

Parses string as a floating point number, and returns the parsed value.

MD_f64 MD_F64FromString(MD_String8 string);

MD_CStyleHexStringFromU64

Builds and returns a string on arena that is the textual representation of x.

MD_String8 MD_CStyleHexStringFromU64(MD_Arena* arena, MD_u64 x, MD_b32 caps);

Parameters

MD_b32 caps

Determines whether or not the alphabetic characters used in the hex textual representation are upper-case or lower-case.

Memory Management

MD_ArenaDefault

The type used for the default arena allocator implementation. This type is used for MD_Arena if an override is not provided by usage code.

struct MD_ArenaDefault
{
  MD_ArenaDefault* prev;
  MD_ArenaDefault* current;
  MD_u64 base_pos;
  MD_u64 pos;
  MD_u64 cmt;
  MD_u64 cap;
  MD_u64 align;
};

See Also

MD_Arena

MD_Arena

The name defined to refer to a memory arena allocator handle. Equivalent to MD_IMPL_Arena, which can be overridden by a custom arena implementation. If an override is not specified, then this type is equivalent to MD_ArenaDefault.

struct MD_Arena
{
  // opaque
};

See Also

MD_ArenaDefault

MD_ArenaTemp

This type is used for temporary lifetimes where a portion of an arena is treated like a stack temporarily. This type stores the position at which stack-like allocation began, so that everything pushed onto the arena during this temporary lifetime can be freed all at once.

struct MD_ArenaTemp
{
  MD_Arena* arena;
  MD_u64 pos;
};

Members

MD_Arena* arena

The arena that is being used for temporary allocation.

MD_u64 pos

The position to which the arena should be restored when the associated temporary lifetime ends.

See Also

MD_Arena, MD_ArenaBeginTemp, MD_ArenaEndTemp, MD_GetScratch, MD_ReleaseScratch

MD_ArenaAlloc

Returns a newly allocated MD_Arena, which can be used as a bucket for memory allocation.

See Also

MD_Arena, MD_ArenaRelease, MD_ArenaClear, MD_PushArray, MD_ArenaTemp, MD_ArenaBeginTemp, MD_ArenaEndTemp

MD_ArenaRelease

Releases an MD_Arena allocated originally with MD_ArenaAlloc.

void MD_ArenaRelease(MD_Arena* arena);

See Also

MD_Arena, MD_ArenaAlloc

MD_ArenaPush

Allocates a block of memory on arena that is size bytes large.

void* MD_ArenaPush(MD_Arena* arena, MD_u64 size);

Parameters

MD_Arena* arena

The arena from which the block of memory should be allocated.

MD_u64 size

The number of bytes to allocate.

Return Value

A pointer to the beginning of the allocated block, or 0 on failure.

See Also

MD_Arena, MD_ArenaAlloc

MD_ArenaPutBack

Pops size bytes off of arena, freeing that space for more allocations.

void MD_ArenaPutBack(MD_Arena* arena, MD_u64 size);

Parameters

MD_Arena* arena

The arena to pop bytes from.

MD_u64 size

The number of bytes to pop.

See Also

MD_Arena, MD_ArenaPush

MD_ArenaSetAlign

Sets the auto-alignment value for arena. Calls to MD_ArenaPush will automatically align to this value.

void MD_ArenaSetAlign(MD_Arena* arena, MD_u64 boundary);

Parameters

MD_Arena* arena

The arena to set alignment for.

MD_u64 boundary

The number of bytes to which allocations should align.

See Also

MD_Arena, MD_ArenaAlloc

MD_ArenaPushAlign

Pushes the required number of bytes onto arena in order to guarantee that the following call to MD_ArenaPush returns an allocation that is aligned to boundary bytes.

void MD_ArenaPushAlign(MD_Arena* arena, MD_u64 boundary);

Parameters

MD_Arena* arena

The arena to use.

MD_u64 boundary

The number of bytes to which the arena's next allocation should align.

See Also

MD_Arena, MD_ArenaAlloc, MD_ArenaPush

MD_ArenaClear

Pops all bytes off of arena, freeing that space for more allocations. Does not deallocate the arena entirely (for that, use MD_ArenaRelease); this function is to be used when more allocations are expected on the same arena, but all of the present allocations are no longer needed.

void MD_ArenaClear(MD_Arena* arena);

Parameters

MD_Arena* arena

The arena to clear.

See Also

MD_Arena, MD_ArenaPutBack, MD_ArenaRelease

MD_PushArray

A helper macro for easily allocating blocks of memory for c instances of type T onto arena a.

#define MD_PushArray(a, T, c) ...

Parameters

a

The arena to use for allocation.

T

The type that should be allocated.

c

The number of instances of T to allocate.

See Also

MD_Arena, MD_ArenaAlloc, MD_ArenaPush

MD_PushArrayZero

A helper macro for easily allocating blocks of memory for c instances of type T onto arena a, with the returned block of memory being guaranteed to be zero-initialized.

#define MD_PushArrayZero(a, T, c) ...

Parameters

a

The arena to use for allocation.

T

The type that should be allocated.

c

The number of instances of T to allocate.

See Also

MD_Arena, MD_ArenaAlloc, MD_ArenaPush, MD_MemoryZero

MD_ArenaBeginTemp

Initializes an MD_ArenaTemp instance for arena which can be used for temporary memory allocations. MD_ArenaEndTemp should be called once with the return value of this function, to avoid leaving temporary allocations as being allocated within the memory belonging to arena. This function, along with MD_ArenaEndTemp, can be useful for using an arena like a stack.

See Also

MD_Arena, MD_ArenaTemp, MD_ArenaEndTemp, MD_ArenaPush, MD_ArenaPutBack

MD_ArenaEndTemp

Pops all bytes allocated onto the arena stored in temp, after temp was constructed with MD_ArenaBeginTemp.

See Also

MD_Arena, MD_ArenaTemp, MD_ArenaBeginTemp, MD_ArenaPush, MD_ArenaPutBack

MD_GetScratch

Retrieves an arena for temporary stack-like scratch memory allocation from a thread-local set of arenas.

MD_ArenaTemp MD_GetScratch(MD_Arena** conflicts, MD_u64 count);

Parameters

MD_Arena** conflicts

Scratch arenas already obtained from previous calls to MD_GetScratch—generally arenas that have been passed into a function that could be scratch arenas—that should not be returned. Most often used when a passed arena, which could be a scratch arena, is being used to push results onto, and one desires a separate channel for scratch allocation that is not required to be allocated onto the arena which is being used for results.

MD_u64 count

The number of MD_Arena pointers pointed to by conflicts.

See Also

MD_Arena, MD_ArenaTemp, MD_ReleaseScratch

MD_ReleaseScratch

Expands to MD_ArenaEndTemp. Equivalent in usage, just used as the symmetric counterpart for MD_GetScratch.

#define MD_ReleaseScratch(scratch) ...

See Also

MD_Arena, MD_ArenaTemp, MD_GetScratch, MD_ArenaEndTemp

Tokens

MD_TokenKind

Flags encoding the kind of a token produced by the lexer.

enum MD_TokenKind
{
  MD_TokenKind_Identifier         = (1<<0),
  MD_TokenKind_NumericLiteral     = (1<<1),
  MD_TokenKind_StringLiteral      = (1<<2),
  MD_TokenKind_Symbol             = (1<<3),
  MD_TokenKind_Reserved           = (1<<4),
  MD_TokenKind_Comment            = (1<<5),
  MD_TokenKind_Whitespace         = (1<<6),
  MD_TokenKind_Newline            = (1<<7),
  MD_TokenKind_BrokenComment      = (1<<8),
  MD_TokenKind_BrokenStringLiteral = (1<<9),
  MD_TokenKind_BadCharacter       = (1<<10),
};

Values

MD_TokenKind_Identifier

When this bit is set, the token follows C-like identifier rules. It may start with an alphabetic character or an underscore, and can contain alphanumeric characters or underscores inside it.

MD_TokenKind_NumericLiteral

When this bit is set, the token follows C-like numeric literal rules.

MD_TokenKind_StringLiteral

When this bit is set, the token was recognized as a string literal. These may be formed with C-like rules, with a single-quote or double-quote around the string contents. They may also be formed with Metadesk's additional rules. These rules allow using ` characters to mark the boundaries of the string, and also using triplets of any of these characters (```This is a string```) to allow newlines within the string's contents.

MD_TokenKind_Symbol

When this bit is set, the token was recognized as a symbolic character. Whether a character is considered symbolic is determined by the MD_CharIsSymbol function.

MD_TokenKind_Reserved

When this bit is set, the token is reserved for special uses by the Metadesk parser.

MD_TokenKind_Comment

When this bit is set, the token was recognized as a comment. Comments can be formed in the traditional C-like ways, using // for single-line, or /* and */ for multiline. Metadesk differs, slightly, in that it allows nested multiline comments. So, every /* must be matched by a */.

MD_TokenKind_Whitespace

When this bit is set, the token contains only whitespace.

MD_TokenKind_Newline

When this bit is set, the token is a newline character.

MD_TokenKind_BrokenComment

When this bit is set, the token is a comment that was malformed syntactically.

MD_TokenKind_BrokenStringLiteral

When this bit is set, the token is a string literal that was malformed syntactically.

MD_TokenKind_BadCharacter

When this bit is set, the token contains a character in an encoding that is not supported by the parser Metadesk.

See Also

MD_TokenFromString

MD_TokenGroups

Used to group several MD_TokenKind flags; used in the parser.

enum MD_TokenGroups
{
  MD_TokenGroup_Comment            = MD_TokenKind_Comment,
  MD_TokenGroup_Whitespace         = (MD_TokenKind_Whitespace|MD_TokenKind_Newline),
  MD_TokenGroup_Irregular          = (MD_TokenGroup_Comment|MD_TokenGroup_Whitespace),
  MD_TokenGroup_Regular            = ~MD_TokenGroup_Irregular,
  MD_TokenGroup_Label              = (MD_TokenKind_Identifier|MD_TokenKind_Numeric|MD_TokenKind_StringLiteral|MD_TokenKind_Symbol),
  MD_TokenGroup_Error              = (MD_TokenKind_BrokenComment|MD_TokenKind_BrokenStringLiteral|MD_TokenKind_BadCharacter),
};

See Also

MD_TokenKind, MD_Token, MD_TokenFromString

MD_Token

The type used for encoding data about any token produced by the lexer.

struct MD_Token
{
  MD_TokenKind kind;
  MD_NodeFlags node_flags;
  MD_String8 string;
  MD_String8 raw_string;
};

Members

MD_NodeFlags node_flags

Flags that should be attached to an MD_Node that uses this token to define its string. Only includes flags that can be understood by the lexer; is not the comprehensive set of node flags that a node needs.

MD_String8 string

The contents of this token, not including any boundary characters.

MD_String8 raw_string

The full contents of the string used to form this token, including all boundary characters.

MD_TokenFromString

Produces a single token, given some input string.

See Also

MD_Token, MD_TokenKind

MD_LexAdvanceFromSkips

Returns the number of bytes that can be skipped, when skipping over certain token kinds.

MD_u64 MD_LexAdvanceFromSkips(MD_String8 string, MD_TokenKind skip_kinds);

See Also

MD_Token, MD_TokenKind

Parsing

MD_MessageKind

This type distinguishes the roles of messages, including errors and warnings.

enum MD_MessageKind
{
  MD_MessageKind_Null,
  MD_MessageKind_Note,
  MD_MessageKind_Warning,
  MD_MessageKind_Error,
  MD_MessageKind_FatalError,
};

Values

MD_MessageKind_Null

The message does not have a particular role.

MD_MessageKind_Note

The message is not suggesting that anything wrong occurred, but is instead just providing additional information.

MD_MessageKind_Warning

The message is a warning.

MD_MessageKind_Error

The message has information about a non-catastrophic error. Reasonable results may still have been produced, but something illegal was encountered.

MD_MessageKind_FatalError

The message has information about a catastrophic error, meaning that the output of whatever the error was for cannot be trusted, and should be treated as a complete failure.

MD_Message

This type encodes information about messages.

struct MD_Message
{
  MD_Message* next;
  MD_Node* node;
  MD_MessageKind kind;
  MD_String8 string;
};

Members

MD_Message* next

A pointer to the next error, in a chain of errors. This is 0 when it is the last error in a chain.

MD_Node* node

The node that this message refers to.

This message's kind.

MD_String8 string

The message contents.

MD_MessageList

This type is for a chain of error messages, with data about the entire list.

struct MD_MessageList
{
  MD_MessageKind max_message_kind;
  MD_u64 node_count;
  MD_Message* first;
  MD_Message* last;
};

Members

MD_MessageKind max_message_kind

The most severe message kind in this chain, where a message kind is more severe than another if it has a higher numeric value (if it is defined later in MD_MessageKind) than another.

MD_u64 node_count

The number of errors in this list.

MD_Message* first

The first error in the list.

MD_Message* last

The last error in the list.

MD_ParseSetRule

An enum to describe how a list of nodes should be delimited.

enum MD_ParseSetRule
{
  MD_ParseSetRule_EndOnDelimiter,
  MD_ParseSetRule_Global,
};

Values

MD_ParseSetRule_EndOnDelimiter

The list of nodes stops being parsed when a delimiter, meaning a set closing symbol or an implicitly-delimited set closer, is encountered in the token stream.

MD_ParseSetRule_Global

The list of nodes is never terminated until there are no tokens remaining in the token stream; used when parsing entire files.

See Also

MD_ParseNodeSet

MD_ParseResult

This type is used to return results from all MD_Node parsing functions.

struct MD_ParseResult
{
  MD_Node* node;
  MD_u64 string_advance;
  MD_MessageList errors;
};

Members

MD_Node* node

The root node of the Metadesk tree that was parsed.

MD_u64 string_advance

The number of bytes that were parsed. Skipping this many bytes in the parse input string will provide the point at which the parser stopped parsing.

A list of messages (especially errors) that were encountered during the parse. If this list contains an MD_Message with MD_MessageKind_FatalError set as its MD_MessageKind, then the output of the parser should not be trusted.

See Also

MD_ParseWholeFile, MD_ParseWholeString, MD_ParseOneNode, MD_ParseNodeSet

MD_ParseResultZero

Constructs a default MD_ParseResult, which indicates that nothing was parsed.

See Also

MD_ParseResult

MD_ParseNodeSet

Parses a single Metadesk node set, starting at offset bytes into string. Parses the associated set delimiters in accordance with rule.

MD_ParseResult MD_ParseNodeSet(MD_Arena* arena, MD_String8 string, MD_u64 offset, MD_Node* parent, MD_ParseSetRule rule);

Parameters

MD_Arena* arena

The arena onto which the parser should allocate memory.

MD_String8 string

The string containing the source text to parse.

MD_u64 offset

The offset into string where this function should start parsing.

MD_Node* parent

The parent node for which the set's children are being parsed.

The rule to use for determining the end of the set.

See Also

MD_ParseSetRule

MD_ParseOneNode

Parses a single Metadesk subtree, starting at offset bytes into string.

MD_ParseResult MD_ParseOneNode(MD_Arena* arena, MD_String8 string, MD_u64 offset);

Parameters

MD_Arena* arena

The arena onto which the parser should allocate memory.

MD_String8 string

The string containing the source text to parse.

MD_u64 offset

The offset into string where this function should start parsing.

MD_ParseWholeString

Parses an entire string encoding Metadesk. Parents all parsed nodes with a node with MD_NodeKind_File set as its kind.

Parameters

MD_Arena* arena

The arena onto which the parser should allocate memory.

MD_String8 filename

The filename to associate with the parse.

MD_String8 contents

The string that contains the text to parse.

See Also

MD_NodeKind

MD_ParseWholeFile

Uses the C standard library to load the file associated with filename, and parses all of it to return a single tree for the whole file.

Parameters

MD_Arena* arena

The arena onto which the parser should allocate memory.

MD_String8 filename

The filename for the file to be loaded and parsed.

MD_MakeErrorMarkerNode

Constructs an MD_Node on arena for the purpose of marking the location at which an error in source text input occurred.

MD_Node* MD_MakeErrorMarkerNode(MD_Arena* arena, MD_String8 parse_contents, MD_u64 offset);

Parameters

MD_Arena* arena

The arena onto which the returned message should be allocated.

MD_String8 parse_contents

The string that was being parsed, in which an error was found.

MD_u64 offset

The offset, in bytes, into parse_contents where the error occurred.

See Also

MD_MakeNode, MD_MakeNodeError

MD_MakeNodeError

Allocates and initializes an MD_Message associated with a particular MD_Node.

Parameters

MD_Arena* arena

The arena onto which the returned message should be allocated.

MD_Node* node

The node associated with the message.

The message kind, encoding its severity.

The string for the message.

See Also

MD_Message

MD_MakeDetachedError

Allocates and initializes an MD_Message associated with a user-controlled pointer.

Parameters

MD_Arena* arena

The arena onto which the returned message should be allocated.

MD_Node* node

The node associated with the message.

The message kind, encoding its severity.

The string for the message.

See Also

MD_Message

MD_MakeTokenError

Allocates and initializes an MD_Message associated with a particular MD_Token.

Parameters

MD_String8 parse_contents

The entire string that is being parsed. The parser used a substring of this string to form token.

MD_Token token

The token associated with this message.

The message kind, encoding its severity.

The string for the message.

See Also

MD_Message

MD_MessageListPush

Pushes a constructed MD_Message into an MD_MessageList.

See Also

MD_Message, MD_MessageList

MD_MessageListConcat

Pushes the contents of to_push into list. Zeroes to_push; the memory used in forming to_push will be used in list, and nothing will be copied.

See Also

MD_Message, MD_MessageList

Nodes

MD_NodeKind

These constants distinguish major roles of MD_Node in the Metadesk abstract syntax tree data structure.

enum MD_NodeKind
{
  MD_NodeKind_Nil,
  MD_NodeKind_File,
  MD_NodeKind_ErrorMarker,
  MD_NodeKind_Main,
  MD_NodeKind_Tag,
  MD_NodeKind_List,
  MD_NodeKind_Reference,
  MD_NodeKind_COUNT,
};

Values

MD_NodeKind_Nil

The Nil node is a unique node representing the lack of information, for example iterating off the end of a list, or up to the parent of a root node results in Nil.

MD_NodeKind_File

A File node represents parsed Metadesk source text.

MD_NodeKind_ErrorMarker

An ErrorMarker node is generated when reporting errors. It is used to record the location of an error that occurred in the lexing phase of a parse.

MD_NodeKind_Main

A Main node represents the main structure of the metadesk abstract syntax tree. Some of these nodes have children which will also be Main nodes. These nodes can be given their text by identifiers, numerics, string and character literals, and operator symbols.

MD_NodeKind_Tag

A Tag node represents a tag attached to a label node with the @identifer syntax. The children of a tag node represent the arguments placed in the tag.

MD_NodeKind_List

A List node serves as the root of an externally chained list of nodes. Its children are nodes with the MD_NodeKind_Reference kind.

MD_NodeKind_Reference

A Reference node is an indirection to another node. The node field ref_target contains a pointer to the referenced node. These nodes are typically used for creating externally chained linked lists that gather nodes from a parse tree.

MD_NodeKind_COUNT

Not a real kind value given to nodes, this is always one larger than the largest enum value that can be given to a node.

MD_NodeFlags

These flags are set on MD_Node to indicate particular details about the strings that were parsed to create the node.

typedef MD_u32 MD_NodeFlags;
enum
{
  MD_NodeFlag_HasParenLeft       = (1<<0),
  MD_NodeFlag_HasParenRight      = (1<<1),
  MD_NodeFlag_HasBracketLeft     = (1<<2),
  MD_NodeFlag_HasBracketRight    = (1<<3),
  MD_NodeFlag_HasBraceLeft       = (1<<4),
  MD_NodeFlag_HasBraceRight      = (1<<5),
  MD_NodeFlag_IsBeforeSemicolon  = (1<<6),
  MD_NodeFlag_IsAfterSemicolon   = (1<<7),
  MD_NodeFlag_IsBeforeComma      = (1<<8),
  MD_NodeFlag_IsAfterComma       = (1<<9),
  MD_NodeFlag_StringSingleQuote  = (1<<10),
  MD_NodeFlag_StringDoubleQuote  = (1<<11),
  MD_NodeFlag_StringTick         = (1<<12),
  MD_NodeFlag_StringTriplet      = (1<<13),
  MD_NodeFlag_Numeric            = (1<<14),
  MD_NodeFlag_Identifier         = (1<<15),
  MD_NodeFlag_StringLiteral      = (1<<16),
};

Values

MD_NodeFlag_HasParenLeft

This node's children open with (

MD_NodeFlag_HasParenRight

This node's children close with )

MD_NodeFlag_HasBracketLeft

This node's children open with [

MD_NodeFlag_HasBracketRight

This node's children close with ]

MD_NodeFlag_HasBraceLeft

This node's children open with {

MD_NodeFlag_HasBraceRight

This node's children close with }

MD_NodeFlag_IsBeforeSemicolon

The delimiter between this node and its next sibling is a ;

MD_NodeFlag_IsAfterSemicolon

The delimiter between this node and its previous sibling is a ;

MD_NodeFlag_IsBeforeComma

The delimiter between this node and its next sibling is a ,

MD_NodeFlag_IsAfterComma

The delimiter between this node and its previous sibling is a ,

MD_NodeFlag_StringSingleQuote

This is a string literal, with ' character(s) marking the boundaries.

MD_NodeFlag_StringDoubleQuote

This is a string literal, with " character(s) marking the boundaries.

MD_NodeFlag_StringTick

This is a string literal, with ` character(s) marking the boundaries.

MD_NodeFlag_StringTriplet

This is a string literal that used triplets (three of its boundary characters in a row, on either side) to mark its boundaries, making it multiline.

MD_NodeFlag_Numeric

The label on this node comes from a token with the MD_TokenKind_Numeric kind.

MD_NodeFlag_Identifier

The label on this node comes from a token with the MD_TokenKind_Identifier kind.

MD_NodeFlag_StringLiteral

The label on this node comes from a token with the MD_TokenKind_StringLiteral kind.

See Also

MD_Node, MD_TokenKind

MD_Node

The MD_Node is the main 'lego-brick' for modeling the result of a Metadesk parse. Also used in some auxiliary data structures.

struct MD_Node
{
  MD_Node* next;
  MD_Node* prev;
  MD_Node* parent;
  MD_Node* first_child;
  MD_Node* last_child;
  MD_Node* first_tag;
  MD_Node* last_tag;
  MD_NodeKind kind;
  MD_NodeFlags flags;
  MD_String8 string;
  MD_String8 raw_string;
  MD_u64 string_hash;
  MD_String8 prev_comment;
  MD_String8 next_comment;
  MD_u64 offset;
  MD_Node* ref_target;
};

Members

MD_Node* next

The next sibling in the hierarchy, or the next tag in a list of tags, or next node in an externally chained linked list.

MD_Node* prev

The previous sibling in the hierarchy, or the previous tag in a list of tags, or previous node in an externally chained linked list.

MD_Node* parent

The parent in the hierarchy, or root node of an externally chained linked list.

MD_Node* first_child

The first child in the hierarchy, or the first node in an externally chained linked list.

MD_Node* last_child

The last child in the hierarchy, or the last node in an externally chained linked list.

MD_Node* first_tag

The first tag attached to a node.

MD_Node* last_tag

The last tag attached to a node.

Indicates the role that the node plays in metadesk node graph.

MD_NodeFlags flags

Extra information about the source that generated this node in the parse.

MD_String8 string

The string of the token labeling this node, after processing. Processing removing quote marks that delimits string literals and character literals

MD_String8 raw_string

The raw string of the token labeling this node.

MD_u64 string_hash

A hash of the string field using the metadesk built in hash function.

MD_String8 prev_comment

The raw string of the comment token before this node, if there is one.

MD_String8 next_comment

The raw string of the comment token after this node, if there is one.

MD_u64 offset

The byte-offset into the string from which this node was parsed. Used for producing data for an MD_CodeLoc.

MD_Node* ref_target

The external pointer from an MD_NodeKind_Reference kind node in an externally linked list.

MD_StringFromNodeKind

Returns a string that contains a name matching kind.

MD_StringListFromNodeFlags

Builds a string list for all bits set in flags, with each string being the name of one of the flags that is set.

MD_NodeIsNil

Returns 1 if the node is nil, or 0 otherwise. A nil node pointer is not equivalent to a null pointer. It can still be dereferenced, and is treated as a dummy placeholder node value.

MD_b32 MD_NodeIsNil(MD_Node* node);

See Also

MD_NilNode

MD_NilNode

Returns a nil node pointer.

See Also

MD_NodeIsNil

MD_PushChild

Links new_child up as being a child of parent, inserting it into the end of parent's children list.

void MD_PushChild(MD_Node* parent, MD_Node* new_child);

MD_PushTag

Links tag up as being a tag of node, inserting it into the end of node's tag list.

void MD_PushTag(MD_Node* node, MD_Node* tag);

MD_PushNewReference

Creates a new reference node, pointing at target, and links it up as a child of list.

MD_FirstNodeWithString

Finds a node in the range defined by first and one_past_last, with the string matching string in accordance with flags, or returns a nil node pointer if it is not found.

Parameters

MD_Node* first

The first node in the range to search.

MD_String8 string

The string to search for.

Controls what is considered a match, when doing string matching.

Return Value

The found node, or a nil node pointer if no node was found.

See Also

MD_NodeAtIndex, MD_S8Match

MD_NodeAtIndex

Finds the nth node in the range defined by first and one_past_last, or returns a nil node pointer if it is not found. 0 would match first, 1 would match first->next, and so on.

MD_Node* MD_NodeAtIndex(MD_Node* first, int n);

Parameters

MD_Node* first

The first node in the range to search.

int n

The index to search for.

Return Value

The found node, or a nil node pointer if no node was found.

See Also

MD_FirstNodeWithString

MD_FirstNodeWithFlags

Given a starting node first, will scan across the node's siblings in-order to find a node that has flags that overlap the passed flags. Useful when, for example, finding the set of node ranges delimited by commas or semicolons inside of a single MD_Node children list.

See Also

MD_NodeFlags

MD_IndexFromNode

Finds the child index of node, with 0 being the first child, 1 being the second, and so on.

See Also

MD_NodeAtIndex

MD_RootFromNode

Finds the highest-most node in the parent chain of node, starting with node. If node has no parent, then node is returned.

Parameters

MD_Node* node

The node for which the root is to be found.

Return Value

The found root.

MD_ChildFromString

Finds a child of node with a string matching child_string, where the rules of matching are determined by flags.

Parameters

MD_Node* node

The parent whose children are to be searched.

MD_String8 child_string

The string that the found child should match.

Controls what is considered a string match.

Return Value

The found node, or a nil node pointer if no node was found.

See Also

MD_FirstNodeWithString, MD_TagFromString

MD_TagFromString

Finds a tag on node with a string matching tag_string, where the rules of matching are determined by flags.

Parameters

MD_Node* node

The parent whose tags are to be searched.

MD_String8 tag_string

The string that the found tag should match.

Controls what is considered a string match.

Return Value

The found node, or a nil node pointer if no node was found.

See Also

MD_FirstNodeWithString, MD_ChildFromString

MD_ChildFromIndex

Finds a child of node with an index matching n. Returns a nil node pointer if no such child is found.

Parameters

MD_Node* node

The node whose children are to be searched.

int n

The index that the return value should match.

Return Value

The found node, or a nil node pointer if no such node was found.

See Also

MD_NodeAtIndex, MD_IndexFromNode, MD_TagFromIndex

MD_TagFromIndex

Finds a tag on node with an index matching n. Returns a nil node pointer if no such tag is found.

Parameters

MD_Node* node

The node whose tags are to be searched.

int n

The index that the return value should match.

Return Value

The found node, or a nil node pointer if no such node was found.

See Also

MD_NodeAtIndex, MD_IndexFromNode, MD_ChildFromIndex

MD_TagArgFromIndex

Finds the nth tag argument of the tag matching tag_string on node, with the matching on tag_string being controlled by flags. Returns a nil node pointer if no such node was found.

MD_Node* MD_TagArgFromIndex(MD_Node* node, MD_String8 tag_string, MD_MatchFlags flags, int n);

Parameters

MD_Node* node

The node whose tags are to be searched.

MD_String8 tag_string

The string that the found tag should match.

Controls what is considered a string match.

int n

The index that the return value should match.

Return Value

The found node, or a nil node pointer if no such node was found.

MD_TagArgFromString

Finds the tag argument with a string matching arg_string, of the tag matching tag_string, on node. Matching tag_string is controlled by tag_str_flags. Matching arg_string is controlled by arg_str_flags. Returns a nil node pointer if no such node was found.

MD_Node* MD_TagArgFromString(MD_Node* node, MD_String8 tag_string, MD_MatchFlags tag_str_flags, int arg_string, MD_MatchFlags arg_str_flags);

Parameters

MD_Node* node

The node whose tags are to be searched.

MD_String8 tag_string

The string that the found tag should match.

MD_MatchFlags tag_str_flags

Controls what is considered a string match, when finding the appropriate tag.

int arg_string

The string that the found tag argument should match.

MD_MatchFlags arg_str_flags

Controls what is considered a string match, when finding the appropriate tag argument.

Return Value

The found node, or a nil node pointer if no such node was found.

MD_NodeHasChild

Returns 1 if node has a child with a string matching string, with the matching rules being controlled by flags, or 0 otherwise.

MD_b32 MD_NodeHasChild(MD_Node* node, MD_String8 string, MD_MatchFlags flags);

Parameters

MD_Node* node

The node whose children are to be searched.

MD_String8 string

The string that should match a child in node.

Controls what is considered a match, when comparing against string.

Return Value

1 if a suitable child was found, or 0 otherwise.

See Also

MD_ChildFromIndex, MD_ChildFromString, MD_NodeHasTag

MD_NodeHasTag

Returns 1 if node has a tag with a string matching tag_string, with the matching rules being controlled by flags, or 0 otherwise.

MD_b32 MD_NodeHasTag(MD_Node* node, MD_String8 tag_string, MD_MatchFlags flags);

Parameters

MD_Node* node

The node whose tags are to be searched.

MD_String8 tag_string

The string that should match a tag in node.

Controls what is considered a match, when comparing against tag_string.

Return Value

1 if a suitable tag was found, or 0 otherwise.

See Also

MD_TagFromIndex, MD_TagFromString, MD_NodeHasChild

MD_ChildCountFromNode

Returns the number of children of node.

MD_TagCountFromNode

Returns the number of tags on node.

MD_ResolveNodeFromReference

If node is of kind MD_NodeKind_Reference, will follow the chain of ref_targets until the final referenced node.

MD_NodeNextWithLimit

Moves to the next sibling of node, unless it is opl, in which case it returns a nil node.

See Also

MD_NilNode

MD_PrevCommentFromNode

Gets the string of the comment that immediately preceded node, if any.

MD_NextCommentFromNode

Gets the string of the comment that immediately followed node, if any.

MD_EachNode

A helper macro for building for-loops over entire lists of nodes. Place inside of the parentheses of a for-loop, e.g. for(MD_EachNode(child, node->first_child)), to use.

#define MD_EachNode(it, first) ...

Parameters

it

The name of the iterator node, as it will be available in the for-loop.

first

The first node to iterate on.

MD_StringFromMessageKind

Returns a string encoding the name of the passed kind value.

See Also

MD_MessageKind

MD_FmtCodeLoc

Returns the format string for code locations that matches normal encodings of code locations (in error or warning messages by compilers, namely). This string is "%.*s:%i:%i". Used with MD_CodeLocVArg, can be used for easily printing code locations.

#define MD_FmtCodeLoc ...

See Also

MD_CodeLocVArg

MD_CodeLocVArg

Expands to the appropriate C format string arguments for an MD_CodeLoc loc matching the format string for code-locations provided by MD_FmtCodeLoc.

#define MD_CodeLocVArg(loc) ...

See Also

MD_FmtCodeLoc

MD_FormatMessage

Provides a standard way to format a message string that is associated with an MD_CodeLoc and an MD_MessageKind.

Parameters

MD_Arena* arena

The arena to use for allocating the string.

The location to associate this message with.

The MD_MessageKind to associate this message with.

MD_String8 string

The contents of the message.

MD_PrintMessage

Formats and prints a standardly-formatted string that is associated with an MD_CodeLoc and MD_MessageKind, in the same format that MD_FormatMessage uses. Relies on MD_DISABLE_PRINT_HELPERS not being set, as it relies on fprintf and the passed FILE *.

void MD_PrintMessage(FILE* file, MD_CodeLoc loc, MD_MessageKind kind, MD_String8 string);

Parameters

FILE* file

The output file stream to which the formatted message is printed.

The location to associate this message with.

The MD_MessageKind to associate this message with.

MD_String8 string

The contents of the message.

See Also

MD_FormatMessage, MD_PrintMessageFmt

MD_PrintMessageFmt

Formats and prints a standardly-formatted string (being derived from a C-style format-string) that is associated with an MD_CodeLoc and MD_MessageKind, in the same format that MD_FormatMessage uses. Relies on MD_DISABLE_PRINT_HELPERS not being set, as it relies on fprintf and the passed FILE *.

void MD_PrintMessageFmt(FILE* file, MD_CodeLoc loc, MD_MessageKind kind, char* fmt, ...);

Parameters

FILE* file

The output file stream to which the formatted message is printed.

The location to associate this message with.

The MD_MessageKind to associate this message with.

char* fmt

The C-style format C-string for the message.

See Also

MD_FormatMessage, MD_PrintMessage

MD_PrintGenNoteCComment

Uses fprintf to print a C-style comment that specifies the location of the code that was used to generate it. Useful when correlating generated code with associated generator code.

#define MD_PrintGenNoteCComment(f) ...

Parameters

f

The FILE* to which the comment is printed.

MD_NodeMatch

Compares the passed MD_Node nodes a and b non-recursively, and determines whether or not they match. flags determines the rules used in the matching algorithm, including tag-sensitivity and case-sensitivity.

MD_b32 MD_NodeMatch(MD_Node* a, MD_Node* b, MD_MatchFlags flags);

See Also

MD_S8Match, MD_MatchFlags

MD_NodeDeepMatch

Compares the passed MD_Node trees a and b recursively, and determines whether or not they and their children match. flags determines the rules used in the matching algorithm, including tag-sensitivity and case-sensitivity.

See Also

MD_NodeMatch, MD_S8Match, MD_MatchFlags

Code Locations

MD_CodeLoc

This type encodes source code locations using file, line, column coordinates.

struct MD_CodeLoc
{
  MD_String8 filename;
  MD_u32 line;
  MD_u32 column;
};

Members

MD_u32 line

Line numbers are 1 based, the lowest valid location is on line number 1.

MD_u32 column

Column numbers are 1 based, the lowest valid location is on column number 1.

MD_CodeLocFromFileOffset

Calculates a position in a source code file in filename/line/column coordinates, provided a filename, a base pointer for the file's contents, and an offset into the file's contents.

MD_CodeLoc MD_CodeLocFromFileOffset(MD_String8 filename, MD_u8* base, MD_u64 offset);

See Also

MD_CodeLocFromNode

MD_CodeLocFromNode

Calculates a position in a source code file in filename/line/column coordinates, provided a parsed MD_Node.

See Also

MD_CodeLocFromFileOffset

String Generation

MD_GenerateFlags

These flags are used to control what is generated in an MD_Node tree string generation function.

typedef MD_u32 MD_GenerateFlags;
enum
{
  MD_GenerateFlag_Tags               = (1<<0),
  MD_GenerateFlag_TagArguments       = (1<<1),
  MD_GenerateFlag_Children           = (1<<2),
  MD_GenerateFlag_Comments           = (1<<3),
  MD_GenerateFlag_NodeKind           = (1<<4),
  MD_GenerateFlag_NodeFlags          = (1<<5),
  MD_GenerateFlag_StringHash         = (1<<6),
  MD_GenerateFlag_Location           = (1<<7),
  MD_GenerateFlag_Tree               = MD_GenerateFlag_Tags | MD_GenerateFlag_TagArguments | MD_GenerateFlag_Children,
  MD_GenerateFlag_All                = 0xffffffff,
};

Values

MD_GenerateFlag_Tags

This turns on the code that generates strings associated with tags attached to nodes. This will not enable string generation for tag arguments, which is separately controlled by the MD_GenerateFlag_TagArguments flag.

MD_GenerateFlag_TagArguments

This turns on the code that generates strings associated with tags arguments. Does nothing if MD_GenerateFlag_Tags is not set.

MD_GenerateFlag_Children

This enables recursive descent on the input MD_Node tree, generating strings for all children recursively.

MD_GenerateFlag_Comments

This enables string generation for comments that were identified by the Metadesk parser as being attached to nodes.

MD_GenerateFlag_NodeKind

This enables string generation relating to each node's MD_NodeKind value.

MD_GenerateFlag_NodeFlags

This enables string generation relating to each node's MD_NodeFlags value.

MD_GenerateFlag_StringHash

This enables string generation for the 64-bit hash associated with the string of an MD_Node, which is generated by the parser automatically.

MD_GenerateFlag_Location

This enables string generation for the source code coordinates of the originally-parsed MD_Node structure.

MD_GenerateFlag_Tree

A mask used to generate strings for the entire tree structure of an MD_Node tree. Skips comments, location, and other metadata.

MD_GenerateFlag_All

A mask used to generate everything.

MD_DebugDumpFromNode

Writes to out, writing legal Metadesk strings that document details of node.

void MD_DebugDumpFromNode(MD_Arena* arena, MD_String8List* out, MD_Node* node, int indent, MD_String8 indent_string, MD_GenerateFlags flags);

Parameters

MD_Arena* arena

The arena to use for string allocation.

The string list to push to.

MD_Node* node

The node for which details are printed.

int indent

The indentation level to generate strings for, with each indentation level implying one occurrence of indent_string.

MD_String8 indent_string

The string to output per-indentation level.

Used to control which aspects of node are generated.

MD_ReconstructionFromNode

Writes to out, writing legal Metadesk strings that attempt to reconstruct the code that was parsed to form node as closely as possible.

void MD_ReconstructionFromNode(MD_Arena* arena, MD_String8List* out, MD_Node* node, int indent, MD_String8 indent_string);

Parameters

MD_Arena* arena

The arena to use for string allocation.

The string list to push to.

MD_Node* node

The node for which details are printed.

int indent

The indentation level to generate strings for, with each indentation level implying one occurrence of indent_string.

MD_String8 indent_string

The string to output per-indentation level.

Map

MD_MapKey

An abstraction over the types of keys used in an MD_Map and the work of hashing those keys. Can be constructed from an MD_String8 or a void *.

struct MD_MapKey
{
  MD_u64 hash;
  MD_u64 size;
  void* ptr;
};

Members

MD_u64 hash

The hash of the key. The hash function used is determined from the key type.

MD_u64 size

For a non-empty MD_String8, the size of the string data. For a void*, zero.

void* ptr

For a non-empty MD_String8, points to the string data of the key. For a void*, the direct pointer value.

MD_MapSlot

A slot containing one (key,value) pair in an MD_Map.

struct MD_MapSlot
{
  MD_MapSlot* next;
  MD_MapKey key;
  void* value;
};

Members

MD_MapSlot* next

The next slot in the same bucket of the MD_Map.

MD_MapKey key

The key that maps to this slot.

void* value

The value part of the pair.

MD_MapBucket

The data used to form a table in an MD_Map. Stores pointers that form a linked list of all MD_MapSlot instances that mapped to this bucket.

struct MD_MapBucket
{
  MD_MapSlot* first;
  MD_MapSlot* last;
};

MD_Map

The map is a chained hash table data structure. Data written to the map is a key-value pair. The key of a pair may either be a pointer, or a string. Both types may be mixed inside a single map. Keys stored with one type never match keys of the other type. The values of the pairs are pointers.

struct MD_Map
{
  MD_MapBucket* buckets;
  MD_u64 bucket_count;
};

MD_HashStr

Returns a 64-bit hash of the input string. Used in implementing string-to-slot mapping in MD_MapKeyStr.

MD_u64 MD_HashStr(MD_String8 string);

See Also

MD_MapKeyStr

MD_HashPtr

Returns a 64-bit hash of the passed pointer. Used in implementing pointer-to-slot mapping in MD_MapKeyPtr.

void MD_HashPtr(void* p);

See Also

MD_MapKeyPtr

MD_MapMakeBucketCount

Constructs a new MD_Map on arena with the specified bucket_count.

MD_Map MD_MapMakeBucketCount(MD_Arena* arena, MD_u64 bucket_count);

See Also

MD_MapMake

MD_MapMake

Constructs a new MD_Map on arena with a default bucket count that fits common cases. MD_MapMakeBucketCount can be used as an alternative for constructing an MD_Map with a specific number of buckets.

See Also

MD_MapMakeBucketCount

MD_MapKeyStr

Forms an MD_Map key from a string.

See Also

MD_HashStr

MD_MapKeyPtr

Forms an MD_Map key from a pointer.

MD_MapKey MD_MapKeyPtr(void* ptr);

See Also

MD_HashPtr

MD_MapLookup

Returns a pointer to the stored MD_MapSlot that is associated with key inside of map, if it exists.

See Also

MD_MapSlot, MD_MapScan, MD_MapKeyStr, MD_MapKeyPtr

MD_MapScan

Given a pointer to an existing MD_MapSlot (constructed from a function like MD_MapLookup), scans to the next MD_MapSlot in the table's hash-chain that uses the same key. Useful in cases when you are mapping one key to multiple values, instead of assuming a one-to-one mapping.

See Also

MD_MapLookup, MD_MapKeyStr, MD_MapKeyPtr

MD_MapInsert

Inserts a new value associated with key into map. Allocates a new slot for the value with arena.

MD_MapSlot* MD_MapInsert(MD_Arena* arena, MD_Map* map, MD_MapKey key, void* val);

MD_MapOverwrite

Overwrites the first existing slot associated with key with a new value, or allocates a new slot if an existing slot does not already exist.

MD_MapSlot* MD_MapOverwrite(MD_Arena* arena, MD_Map* map, MD_MapKey key, void* val);

Expression Parser

MD_ExprOprKind

This type determines how an operator entered into the expression system is parsed.

enum MD_ExprOprKind
{
  MD_ExprOprKind_Null,
  MD_ExprOprKind_Prefix,
  MD_ExprOprKind_Postfix,
  MD_ExprOprKind_Binary,
  MD_ExprOprKind_BinaryRightAssociative,
  MD_ExprOprKind_COUNT,
};

Values

MD_ExprOprKind_Prefix

The operator is parsed as a prefix unary operator.

MD_ExprOprKind_Postfix

The operator is parsed as a postfix unary operator.

MD_ExprOprKind_Binary

The operator is parsed as a left-to-right binary operator.

MD_ExprOprKind_BinaryRightAssociative

The operator is parsed as a right-to-left binary operator.

MD_ExprOpr

This type carries the primary information regarding an operator in an expression system.

struct MD_ExprOpr
{
  MD_ExprOpr* next;
  MD_u32 op_id;
  MD_ExprOprKind kind;
  MD_u32 precedence;
  MD_String8 string;
  void* op_ptr;
};

Members

MD_ExprOpr* next

Internal - used in forming chains of operators.

MD_u32 op_id

User data set on the creation of the operator.

Determines what kind of associativity the operator has.

MD_u32 precedence

Determines the precedence level of the operator.

MD_String8 string

The string of the operator.

void* op_ptr

User data set on the creation of the operator.

See Also

MD_ExprOprKind

MD_ExprOprList

A simple linked list of MD_ExprOpr nodes. This type is used to gather operators before they are baked down to an optimized operator table.

struct MD_ExprOprList
{
  MD_ExprOpr* first;
  MD_ExprOpr* last;
  MD_u64 count;
};

Members

MD_ExprOpr* first

First node of the chain.

MD_ExprOpr* last

Last node of the chain.

MD_u64 count

The number of nodes in the chain.

See Also

MD_ExprBakeOprTableFromList

MD_ExprOprTable

An operator table determines the set of operators that will be understood by the parser. It's exact structure is likely to get rearranged whenever it is upgraded to provide faster operator lookups, so it's contents should all be considered 'internal'.

struct MD_ExprOprTable
{
  // opaque
};

See Also

MD_ExprBakeOprTableFromList

MD_Expr

An expression node used as the output type from the expression parser.

struct MD_Expr
{
  MD_Expr* parent;
  MD_Expr* left;
  MD_Expr* right;
  MD_ExprOpr* op;
  MD_Node* md_node;
};

Members

MD_Expr* parent

The parent node in the expression tree, null for the root node.

MD_Expr* left

The left operand of binary operators - also the operand of unary operators.

MD_Expr* right

The right operand of binary operators - null for unary operators.

If this expression node is an operator this points to the operator's primary data. If this expression node is a leaf then this pointer is null.

MD_Node* md_node

A pointer to the metadesk node directly responsible for generating this node of the expression.

MD_ExprParseResult

The expression parser returns this, a combined expression node tree and a list of error messages.

struct MD_ExprParseResult
{
  MD_Expr* expr;
  MD_MessageList errors;
};

Members

MD_Expr* expr

The root of the expression tree.

The list of parser errors.

MD_ExprParseCtx

The parse context used in expression parsing. Currently considered entirely internal.

struct MD_ExprParseCtx
{
  // opaque
};

MD_ExprOprPush

Pushes a new operator onto the back of an operator list. All of the pushes on a list should be allocated on the same arena.

void MD_ExprOprPush(MD_Arena* arena, MD_ExprOprList* list, MD_ExprOprKind kind, MD_u64 precedence, MD_String8 op_string, MD_u32 op_id, void* op_ptr);

Parameters

The list accumulating the operators.

This operator's association rule.

MD_u64 precedence

This precedence level. Higher precedence means 'more tightly binding'.

MD_String8 op_string

The string for this operator. It should parse as a single Metadesk token, either a symbol token or an identifier token.

MD_u32 op_id

User data. Intended for statically allocated ids like enums for operator switches.

void* op_ptr

User data. Intended for dynamically allocated ids like pointers to some other structure.

See Also

MD_ExprOprList, MD_ExprOprKind

MD_ExprBakeOprTableFromList

Convert a simple list of operators into an operator table - and performing correctness checks along the way.

Parameters

The list of operators to bake into a table.

See Also

MD_ExprOprList

MD_ExprOprFromKindString

Get an operator info pointer from an operator table by looking up it's operator kind and name.

Parameters

The table of operators to look into.

Which kind of operator to find. If this is MD_ExprOprKind_Null then any kind of operator can match.

The name of the operator to find.

MD_ExprParse

Create an expression tree from a range of Metadesk nodes.

MD_ExprParseResult MD_ExprParse(MD_Arena* arena, MD_ExprOprTable* op_table, MD_Node* first, MD_Node* one_past_last);

Parameters

MD_ExprOprTable* op_table

The operator table that controls the parse.

MD_Node* first

The first Metadesk node in the range to parse.

MD_Node* one_past_last

The last Metadesk node in the range to parse.

MD_Expr_NewLeaf

Allocates and initializes a leaf expression node. Currently considered entirely internal.

MD_Expr_NewOpr

Allocates and initializes an operator expression node. Currently considered entirely internal.

MD_ExprParse_MakeContext

Initializes an expression parser context. Currently considered entirely internal.

MD_ExprParse_TopLevel

Parser helper: The root call for a parse of a range of metadesk nodes. Currently considered entirely internal.

MD_ExprParse_OprConsume

Parse helper: Tries to consume the next node as an operator and return the operator's primary info pointer. Currently considered entirely internal.

MD_ExprParse_Atom

Parse helper: Handles leaves, prefix operators, and parentheses. Currently considered entirely internal.

MD_ExprParse_MinPrecedence

Parse helper: Core of the parsing loop, puts together binary operators, does precedence checking, etc. Currently considered entirely internal.

Command Line Helper

MD_CmdLineOption

A type used to encode parsed command line options, that can have values associated with them.

Members

A pointer to the next option, if this is within a chain of options. Will be 0 if this is the last option in a chain.

MD_String8 name

The name of this option.

The values associated with this option.

See Also

MD_CmdLine, MD_MakeCmdLineFromOptions

MD_CmdLine

The type encoding a fully parsed set of command line options.

struct MD_CmdLine
{
  MD_String8List inputs;
  MD_CmdLineOption* first_option;
  MD_CmdLineOption* last_option;
};

Members

The list of all command line arguments that were not parsed as flags with optional values. Can be used as a list of unstructured input strings; for example, to be considered as input file paths.

MD_CmdLineOption* first_option

The first option that was parsed, forming the head of a chain of options.

MD_CmdLineOption* last_option

The last option that was parsed.

See Also

MD_MakeCmdLineFromOptions

MD_StringListFromArgCV

Converts a traditional C-style argc, argv pair into an MD_String8List.

MD_String8List MD_StringListFromArgCV(MD_Arena* arena, int argument_count, char** arguments);

Parameters

MD_Arena* arena

The arena to allocate with.

int argument_count

The number of command line arguments. Traditionally referred to as argc.

char** arguments

A pointer to the command line arguments. Traditionally referred to as argv.

See Also

MD_MakeCmdLineFromOptions

MD_MakeCmdLineFromOptions

Parses an MD_String8List as a set of command line options.

Parameters

MD_Arena* arena

The arena to allocate with.

MD_String8List options

An MD_String8List encoding the list of command line arguments. Can be produced from a traditional argc and argv pair using MD_StringListFromArgCV.

See Also

MD_CmdLine, MD_StringListFromArgCV, MD_CmdLineValuesFromString, MD_CmdLineB32FromString

MD_CmdLineValuesFromString

Gets the list of values associated with name in the parsed command line arguments.

Parameters

MD_CmdLine cmdln

Parsed command line data from MD_MakeCmdLineFromOptions.

MD_String8 name

The name of the command line option.

See Also

MD_CmdLine, MD_MakeCmdLineFromOptions, MD_CmdLineB32FromString, MD_CmdLineI64FromString

MD_CmdLineB32FromString

Determines whether a command line argument explicitly passed an option matching name.

Parameters

MD_CmdLine cmdln

Parsed command line data from MD_MakeCmdLineFromOptions.

MD_String8 name

The name of the command line option.

See Also

MD_CmdLine, MD_MakeCmdLineFromOptions, MD_CmdLineB32FromString, MD_CmdLineValuesFromString

MD_CmdLineI64FromString

Gets the list of values associated with name in the parsed command line arguments, treats them as a string representation of a 64-bit signed integer value, and returns that integer value.

Parameters

MD_CmdLine cmdln

Parsed command line data from MD_MakeCmdLineFromOptions.

MD_String8 name

The name of the command line option.

See Also

MD_MakeCmdLineFromOptions, MD_CmdLineValuesFromString, MD_CmdLineB32FromString

File System Helper

MD_FileFlags

Flags encoding certain properties of a file.

typedef MD_u32 MD_FileFlags;
enum
{
  MD_FileFlag_Directory          = (1<<0),
};

Values

MD_FileFlag_Directory

The associated file is a directory.

See Also

MD_FileInfo, MD_FileIterBegin, MD_FileIterNext, MD_FileIterEnd

MD_FileInfo

Encodes general metadata about a file.

struct MD_FileInfo
{
  MD_FileFlags flags;
  MD_String8 filename;
  MD_u64 file_size;
};

Members

MD_String8 filename

The name of the file. This includes the extension of the file, but does not include the directory in which the file is stored.

MD_u64 file_size

The size of the file, in bytes.

See Also

MD_FileFlags, MD_FileIterBegin, MD_FileIterNext, MD_FileIterEnd

MD_FileIter

An opaque iterator type used to store operating-system-specific state, when iterating files.

struct MD_FileIter
{
  // opaque
};

See Also

MD_FileIterBegin, MD_FileIterNext, MD_FileIterEnd

MD_LoadEntireFile

Uses the C standard library to load the contents of the file with filename into an MD_String8.

Parameters

MD_Arena* arena

The arena to use for allocating.

MD_String8 filename

The filename of the file that is to be loaded.

MD_FileIterBegin

Uses lower level operating system APIs to begin iterating a file-system directory. Initializes the opaque structure it to do so.

See Also

MD_FileIter, MD_FileIterEnd, MD_FileIterNext

MD_FileIterNext

Uses lower level operating system APIs to retrieve the next file in a file-system directory, and advance to the next one, with state being stored in it. Requires calling MD_FileIterBegin on it first. Returns the iterated file's information.

See Also

MD_FileIter, MD_FileIterBegin, MD_FileIterEnd

MD_FileIterEnd

Uses lower level operating system APIs to end iterating a file-system directory. Call once it is done being used.