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

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

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

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

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

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

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

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

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

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

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

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

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

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

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_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_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

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

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

MD_S8Prefix

Returns a prefix of the passed MD_String8.

MD_String8 MD_S8Prefix(MD_String8 str, MD_u64 size);

Parameters

MD_S8Suffix

Returns a suffix of the passed MD_String8.

MD_String8 MD_S8Suffix(MD_String8 str, MD_u64 size);

Parameters

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.

MD_b32 MD_S8Match(MD_String8 a, MD_String8 b, MD_MatchFlags flags);

Parameters

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

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_String8 MD_S8Copy(MD_Arena* arena, MD_String8 string);

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.

void MD_S8ListConcat(MD_String8List* list, MD_String8List* to_push);

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

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.

MD_String8 MD_S8ListJoin(MD_Arena* arena, MD_String8List list, MD_StringJoin* 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.

MD_String8 MD_S8Stylize(MD_Arena* arena, MD_String8 string, MD_IdentifierStyle style, MD_String8 separator);

Parameters

See Also

MD_IdentifierStyle

MD_DecodeCodepointFromUtf8

MD_DecodedCodepoint MD_DecodeCodepointFromUtf8(MD_u8 str, MD_u64 max);

MD_DecodeCodepointFromUtf16

MD_DecodedCodepoint MD_DecodeCodepointFromUtf16(MD_u16* str, MD_u64 max);

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.

MD_String8 MD_S8FromS16(MD_Arena* arena, MD_String16 str);

Parameters

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.

MD_String16 MD_S16FromS8(MD_Arena* arena, MD_String8 str);

Parameters

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.

MD_String8 MD_S8FromS32(MD_Arena* arena, MD_String32 str);

Parameters

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.

MD_String32 MD_S32FromS8(MD_Arena* arena, MD_String8 str);

Parameters

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.

MD_String8 MD_PathChopLastPeriod(MD_String8 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.

MD_String8 MD_PathSkipLastSlash(MD_String8 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.

MD_String8 MD_PathSkipLastPeriod(MD_String8 string);

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.

MD_String8 MD_PathChopLastSlash(MD_String8 string);

See Also

MD_PathSkipLastPeriod, MD_S8Prefix, MD_S8Substring, MD_S8Skip

MD_S8SkipWhitespace

Returns the equivalent of string with all leading whitespace skipped.

MD_String8 MD_S8SkipWhitespace(MD_String8 string);

See Also

MD_S8Substring, MD_S8ChopWhitespace, MD_S8Skip, MD_S8Chop

MD_S8ChopWhitespace

Returns the equivalent of string with all trailing whitespace chopped.

MD_String8 MD_S8ChopWhitespace(MD_String8 string);

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_b32 MD_StringIsCStyleInt(MD_String8 string);

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_i64 MD_CStyleIntFromString(MD_String8 string);

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

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

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.

MD_Arena* MD_ArenaAlloc();

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

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

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

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

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

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

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

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.

MD_ArenaTemp MD_ArenaBeginTemp(MD_Arena* arena);

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.

void MD_ArenaEndTemp(MD_ArenaTemp temp);

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

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

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_TokenFromString

Produces a single token, given some input string.

MD_Token MD_TokenFromString(MD_String8 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_Message

This type encodes information about messages.

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

Members

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_ParseSetRule

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

enum MD_ParseSetRule
{
  MD_ParseSetRule_EndOnDelimiter,
  MD_ParseSetRule_Global,
};

Values

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

See Also

MD_ParseWholeFile, MD_ParseWholeString, MD_ParseOneNode, MD_ParseNodeSet

MD_ParseResultZero

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

MD_ParseResult MD_ParseResultZero();

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

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_ParseWholeString

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

MD_ParseResult MD_ParseWholeString(MD_Arena* arena, MD_String8 filename, MD_String8 contents);

Parameters

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.

MD_ParseResult MD_ParseWholeFile(MD_Arena* arena, MD_String8 filename);

Parameters

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

See Also

MD_MakeNode, MD_MakeNodeError

MD_MakeNodeError

Allocates and initializes an MD_Message associated with a particular MD_Node.

MD_Message* MD_MakeNodeError(MD_Arena* arena, MD_Node* node, MD_MessageKind kind, MD_String8 str);

Parameters

See Also

MD_Message

MD_MakeDetachedError

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

MD_Message* MD_MakeDetachedError(MD_Arena* arena, MD_Node* node, MD_MessageKind kind, MD_String8 str);

Parameters

See Also

MD_Message

MD_MakeTokenError

Allocates and initializes an MD_Message associated with a particular MD_Token.

MD_Message* MD_MakeTokenError(MD_Arena* arena, MD_String8 parse_contents, MD_Token token, MD_MessageKind kind, MD_String8 str);

Parameters

See Also

MD_Message

MD_MessageListPush

Pushes a constructed MD_Message into an MD_MessageList.

void MD_MessageListPush(MD_MessageList* list, MD_Message* error);

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.

void MD_MessageListConcat(MD_MessageList* list, MD_MessageList* to_push);

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_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

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_StringFromNodeKind

Returns a string that contains a name matching kind.

MD_String8 MD_StringFromNodeKind(MD_NodeKind 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_String8List MD_StringListFromNodeFlags(MD_Arena* arena, MD_NodeFlags flags);

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.

MD_Node* MD_NilNode();

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_Node* MD_PushNewReference(MD_Node* list, MD_Node* target);

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.

MD_Node* MD_FirstNodeWithString(MD_Node* first, MD_String8 string, MD_MatchFlags flags);

Parameters

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

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.

MD_Node* MD_FirstNodeWithFlags(MD_Node* first, MD_NodeFlags flags);

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.

int MD_IndexFromNode(MD_Node* node);

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.

MD_Node* MD_RootFromNode(MD_Node* node);

Parameters

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.

MD_Node* MD_ChildFromString(MD_Node* node, MD_String8 child_string, MD_MatchFlags flags);

Parameters

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.

MD_Node* MD_TagFromString(MD_Node* node, MD_String8 tag_string, MD_MatchFlags flags);

Parameters

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.

MD_Node* MD_ChildFromIndex(MD_Node* node, int n);

Parameters

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.

MD_Node* MD_TagFromIndex(MD_Node* node, int n);

Parameters

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

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

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

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

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_i64 MD_ChildCountFromNode(MD_Node* node);

MD_TagCountFromNode

Returns the number of tags on node.

MD_i64 MD_TagCountFromNode(MD_Node* node);

MD_ResolveNodeFromReference

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

MD_Node* MD_ResolveNodeFromReference(MD_Node* node);

MD_NodeNextWithLimit

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

MD_Node* MD_NodeNextWithLimit(MD_Node* node, MD_Node* opl);

See Also

MD_NilNode

MD_PrevCommentFromNode

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

MD_String8 MD_PrevCommentFromNode(MD_Node* node);

MD_NextCommentFromNode

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

MD_String8 MD_NextCommentFromNode(MD_Node* node);

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

MD_StringFromMessageKind

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

MD_String8 MD_StringFromMessageKind(MD_MessageKind kind);

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.

MD_String8 MD_FormatMessage(MD_Arena* arena, MD_CodeLoc loc, MD_MessageKind kind, MD_String8 string);

Parameters

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

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

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

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.

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

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_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.

MD_CodeLoc MD_CodeLocFromNode(MD_Node* 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_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_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

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_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_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.

MD_Map MD_MapMake(MD_Arena* arena);

See Also

MD_MapMakeBucketCount

MD_MapKeyStr

Forms an MD_Map key from a string.

MD_MapKey MD_MapKeyStr(MD_String8 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.

MD_MapSlot* MD_MapLookup(MD_Map* map, MD_MapKey key);

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.

MD_MapSlot* MD_MapScan(MD_MapSlot* first_slot, MD_MapKey key);

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_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

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

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_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_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

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.

MD_ExprOprTable MD_ExprBakeOprTableFromList(MD_Arena* arena, MD_ExprOprList* list);

Parameters

See Also

MD_ExprOprList

MD_ExprOprFromKindString

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

MD_ExprOpr* MD_ExprOprFromKindString(MD_ExprOprTable* table, MD_ExprOprKind kind, MD_String8 s);

Parameters

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_Expr_NewLeaf

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

void MD_Expr_NewLeaf();

MD_Expr_NewOpr

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

void MD_Expr_NewOpr();

MD_ExprParse_MakeContext

Initializes an expression parser context. Currently considered entirely internal.

void MD_ExprParse_MakeContext();

MD_ExprParse_TopLevel

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

void MD_ExprParse_TopLevel();

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.

void MD_ExprParse_OprConsume();

MD_ExprParse_Atom

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

void MD_ExprParse_Atom();

MD_ExprParse_MinPrecedence

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

void MD_ExprParse_MinPrecedence();

Command Line Helper

MD_CmdLineOption

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

struct MD_CmdLineOption
{
  MD_CmdLineOption* next;
  MD_String8 name;
  MD_String8List values;
};

Members

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

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

See Also

MD_MakeCmdLineFromOptions

MD_MakeCmdLineFromOptions

Parses an MD_String8List as a set of command line options.

MD_CmdLine MD_MakeCmdLineFromOptions(MD_Arena* arena, MD_String8List options);

Parameters

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.

MD_String8List MD_CmdLineValuesFromString(MD_CmdLine cmdln, MD_String8 name);

Parameters

See Also

MD_CmdLine, MD_MakeCmdLineFromOptions, MD_CmdLineB32FromString, MD_CmdLineI64FromString

MD_CmdLineB32FromString

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

MD_b32 MD_CmdLineB32FromString(MD_CmdLine cmdln, MD_String8 name);

Parameters

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.

MD_i64 MD_CmdLineI64FromString(MD_CmdLine cmdln, MD_String8 name);

Parameters

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

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

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.

MD_String8 MD_LoadEntireFile(MD_Arena* arena, MD_String8 filename);

Parameters

MD_FileIterBegin

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

void MD_FileIterBegin(MD_FileIter* it, MD_String8 path);

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.

MD_FileInfo MD_FileIterNext(MD_Arena* arena, MD_FileIter* it);

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.

void MD_FileIterEnd(MD_FileIter* it);