Tag utilities

Classes
struct	c4::yml::TagCache::Entry
struct	c4::yml::TagCache::LookupResult
struct	c4::yml::TagCache
	Accelerator structure to reduce memory requirements by enabling reuse of resolved tags. More...
struct	c4::yml::TagDirective
struct	c4::yml::TagDirectiveRange
struct	c4::yml::TagDirectives

Macros
#define	RYML_MAX_TAG_DIRECTIVES   4
	the maximum number of tag directives in a Tree More...

Typedefs
using	c4::yml::tag_bits = uint16_t
	the integral type necessary to cover all the bits marking node tags More...

Enumerations
enum	c4::yml::YamlTag_e : tag_bits {   c4::yml::TAG_NONE = 0, c4::yml::TAG_MAP = 1, c4::yml::TAG_OMAP = 2, c4::yml::TAG_PAIRS = 3,   c4::yml::TAG_SET = 4, c4::yml::TAG_SEQ = 5, c4::yml::TAG_BINARY = 6, c4::yml::TAG_BOOL = 7,   c4::yml::TAG_FLOAT = 8, c4::yml::TAG_INT = 9, c4::yml::TAG_MERGE = 10, c4::yml::TAG_NULL = 11,   c4::yml::TAG_STR = 12, c4::yml::TAG_TIMESTAMP = 13, c4::yml::TAG_VALUE = 14, c4::yml::TAG_YAML = 15 }
	a bit mask for marking tags for types More...

Functions
YamlTag_e	c4::yml::to_tag (csubstr tag)
csubstr	c4::yml::from_tag (YamlTag_e tag)
csubstr	c4::yml::from_tag_long (YamlTag_e tag)
csubstr	c4::yml::normalize_tag (csubstr tag)
csubstr	c4::yml::normalize_tag_long (csubstr tag)
csubstr	c4::yml::normalize_tag_long (csubstr tag, substr output)
bool	c4::yml::is_custom_tag (csubstr tag)
	is a tag of the form !handle!tag? More...
bool	c4::yml::is_valid_tag_handle (csubstr handle)
size_t	c4::yml::transform_tag (substr output, csubstr handle, csubstr prefix, csubstr tag, Callbacks const &callbacks, Location const &ymlloc={}, bool with_brackets=true)
	returns the length of the transformed tag, or 0 to signal that the tag is local and cannot be resolved More...

Detailed Description

See also

sample_tags()

Macro Definition Documentation

#define RYML_MAX_TAG_DIRECTIVES   4

the maximum number of tag directives in a Tree

Definition at line 26 of file tag.hpp.

Referenced by c4::yml::TagDirectives::add(), c4::yml::TagDirectives::lookup(), c4::yml::TagDirectives::lookup_range(), and c4::yml::TagDirectives::size().

Typedef Documentation

using c4::yml::tag_bits = typedef uint16_t

the integral type necessary to cover all the bits marking node tags

Definition at line 30 of file tag.hpp.

Enumeration Type Documentation

enum c4::yml::YamlTag_e : tag_bits

a bit mask for marking tags for types

Enumerator
TAG_NONE
TAG_MAP	!!map Unordered set of key: value pairs without duplicates. See also https://yaml.org/type/map.html
TAG_OMAP	!!omap Ordered sequence of key: value pairs without duplicates. See also https://yaml.org/type/omap.html
TAG_PAIRS	!!pairs Ordered sequence of key: value pairs allowing duplicates. See also https://yaml.org/type/pairs.html
TAG_SET	!!set Unordered set of non-equal values. See also https://yaml.org/type/set.html
TAG_SEQ	!!seq Sequence of arbitrary values. See also https://yaml.org/type/seq.html
TAG_BINARY	!!binary A sequence of zero or more octets (8 bit values). See also https://yaml.org/type/binary.html
TAG_BOOL	!!bool Mathematical Booleans. See also https://yaml.org/type/bool.html
TAG_FLOAT	!!float Floating-point approximation to real numbers. https://yaml.org/type/float.html
TAG_INT	!!float Mathematical integers. https://yaml.org/type/int.html
TAG_MERGE	!!merge Specify one or more mapping to be merged with the current one. https://yaml.org/type/merge.html
TAG_NULL	!!null Devoid of value. https://yaml.org/type/null.html
TAG_STR	!!str A sequence of zero or more Unicode characters. https://yaml.org/type/str.html
TAG_TIMESTAMP	!!timestamp A point in time https://yaml.org/type/timestamp.html
TAG_VALUE	!!value Specify the default value of a mapping https://yaml.org/type/value.html
TAG_YAML	!!yaml Specify the default value of a mapping https://yaml.org/type/yaml.html

Definition at line 33 of file tag.hpp.

             : tag_bits { // NOLINT
    TAG_NONE      =  0,
    // container types
    TAG_MAP       =  1, /**< !!map   Unordered set of key: value pairs without duplicates. @see https://yaml.org/type/map.html */
    TAG_OMAP      =  2, /**< !!omap  Ordered sequence of key: value pairs without duplicates. @see https://yaml.org/type/omap.html */
    TAG_PAIRS     =  3, /**< !!pairs Ordered sequence of key: value pairs allowing duplicates. @see https://yaml.org/type/pairs.html */
    TAG_SET       =  4, /**< !!set   Unordered set of non-equal values. @see https://yaml.org/type/set.html */
    TAG_SEQ       =  5, /**< !!seq   Sequence of arbitrary values. @see https://yaml.org/type/seq.html */
    // scalar types
    TAG_BINARY    =  6, /**< !!binary A sequence of zero or more octets (8 bit values). @see https://yaml.org/type/binary.html */
    TAG_BOOL      =  7, /**< !!bool   Mathematical Booleans. @see https://yaml.org/type/bool.html */
    TAG_FLOAT     =  8, /**< !!float  Floating-point approximation to real numbers. https://yaml.org/type/float.html */
    TAG_INT       =  9, /**< !!float  Mathematical integers. https://yaml.org/type/int.html */
    TAG_MERGE     = 10, /**< !!merge  Specify one or more mapping to be merged with the current one. https://yaml.org/type/merge.html */
    TAG_NULL      = 11, /**< !!null   Devoid of value. https://yaml.org/type/null.html */
    TAG_STR       = 12, /**< !!str    A sequence of zero or more Unicode characters. https://yaml.org/type/str.html */
    TAG_TIMESTAMP = 13, /**< !!timestamp A point in time https://yaml.org/type/timestamp.html */
    TAG_VALUE     = 14, /**< !!value  Specify the default value of a mapping https://yaml.org/type/value.html */
    TAG_YAML      = 15, /**< !!yaml   Specify the default value of a mapping https://yaml.org/type/yaml.html */
} YamlTag_e;

Function Documentation

YamlTag_e c4::yml::to_tag

(

csubstr

tag

)

Definition at line 68 of file tag.cpp.

Referenced by c4::yml::normalize_tag(), c4::yml::normalize_tag_long(), c4::yml::TagDirectives::resolve(), and sample_tags().

{
    if(tag.begins_with("!<"))
        tag = tag.sub(1);
    if(tag.begins_with("!!"))
    {
        tag = tag.sub(2);
    }
    else if(tag.begins_with('!'))
    {
        return TAG_NONE;
    }
    else
    {
        csubstr pfx = "<tag:yaml.org,2002:";
        csubstr pfx2 = pfx.sub(1);
        if(tag.begins_with(pfx2))
        {
            tag = tag.sub(pfx2.len);
        }
        else if(tag.begins_with(pfx))
        {
            tag = tag.sub(pfx.len);
            if(!tag.len)
                return TAG_NONE;
            tag = tag.offs(0, 1);
        }
    }
    if(tag == "map")
        return TAG_MAP;
    else if(tag == "omap")
        return TAG_OMAP;
    else if(tag == "pairs")
        return TAG_PAIRS;
    else if(tag == "set")
        return TAG_SET;
    else if(tag == "seq")
        return TAG_SEQ;
    else if(tag == "binary")
        return TAG_BINARY;
    else if(tag == "bool")
        return TAG_BOOL;
    else if(tag == "float")
        return TAG_FLOAT;
    else if(tag == "int")
        return TAG_INT;
    else if(tag == "merge")
        return TAG_MERGE;
    else if(tag == "null")
        return TAG_NULL;
    else if(tag == "str")
        return TAG_STR;
    else if(tag == "timestamp")
        return TAG_TIMESTAMP;
    else if(tag == "value")
        return TAG_VALUE;
    else if(tag == "yaml")
        return TAG_YAML;

    return TAG_NONE;
}

csubstr c4::yml::from_tag

(

YamlTag_e

tag

)

Definition at line 170 of file tag.cpp.

Referenced by c4::yml::normalize_tag(), and sample_tags().

{
    switch(tag)
    {
    case TAG_MAP:
        return {"!!map"};
    case TAG_OMAP:
        return {"!!omap"};
    case TAG_PAIRS:
        return {"!!pairs"};
    case TAG_SET:
        return {"!!set"};
    case TAG_SEQ:
        return {"!!seq"};
    case TAG_BINARY:
        return {"!!binary"};
    case TAG_BOOL:
        return {"!!bool"};
    case TAG_FLOAT:
        return {"!!float"};
    case TAG_INT:
        return {"!!int"};
    case TAG_MERGE:
        return {"!!merge"};
    case TAG_NULL:
        return {"!!null"};
    case TAG_STR:
        return {"!!str"};
    case TAG_TIMESTAMP:
        return {"!!timestamp"};
    case TAG_VALUE:
        return {"!!value"};
    case TAG_YAML:
        return {"!!yaml"};
    case TAG_NONE:
    default:
        return {""};
    }
}

csubstr c4::yml::from_tag_long

(

YamlTag_e

tag

)

Definition at line 130 of file tag.cpp.

Referenced by c4::yml::normalize_tag_long(), c4::yml::TagDirectives::resolve(), and sample_tags().

{
    switch(tag)
    {
    case TAG_MAP:
        return {"<tag:yaml.org,2002:map>"};
    case TAG_OMAP:
        return {"<tag:yaml.org,2002:omap>"};
    case TAG_PAIRS:
        return {"<tag:yaml.org,2002:pairs>"};
    case TAG_SET:
        return {"<tag:yaml.org,2002:set>"};
    case TAG_SEQ:
        return {"<tag:yaml.org,2002:seq>"};
    case TAG_BINARY:
        return {"<tag:yaml.org,2002:binary>"};
    case TAG_BOOL:
        return {"<tag:yaml.org,2002:bool>"};
    case TAG_FLOAT:
        return {"<tag:yaml.org,2002:float>"};
    case TAG_INT:
        return {"<tag:yaml.org,2002:int>"};
    case TAG_MERGE:
        return {"<tag:yaml.org,2002:merge>"};
    case TAG_NULL:
        return {"<tag:yaml.org,2002:null>"};
    case TAG_STR:
        return {"<tag:yaml.org,2002:str>"};
    case TAG_TIMESTAMP:
        return {"<tag:yaml.org,2002:timestamp>"};
    case TAG_VALUE:
        return {"<tag:yaml.org,2002:value>"};
    case TAG_YAML:
        return {"<tag:yaml.org,2002:yaml>"};
    case TAG_NONE:
    default:
        return {""};
    }
}

csubstr c4::yml::normalize_tag

(

csubstr

tag

)

Definition at line 19 of file tag.cpp.

Referenced by sample_tags().

{
    YamlTag_e t = to_tag(tag);
    if(t != TAG_NONE)
        return from_tag(t);
    if(tag.begins_with("!<"))
        tag = tag.sub(1);
    if(tag.begins_with("<!"))
        return tag;
    return tag;
}

csubstr c4::yml::normalize_tag_long

(

csubstr

tag

)

Definition at line 31 of file tag.cpp.

Referenced by c4::yml::normalize_tag_long(), and sample_tags().

{
    YamlTag_e t = to_tag(tag);
    if(t != TAG_NONE)
        return from_tag_long(t);
    if(tag.begins_with("!<"))
        tag = tag.sub(1);
    if(tag.begins_with("<!"))
        return tag;
    return tag;
}

csubstr c4::yml::normalize_tag_long	(	csubstr	tag,
		substr	output
	)

Definition at line 43 of file tag.cpp.

{
    csubstr result = normalize_tag_long(tag);
    if(result.begins_with("!!"))
    {
        RYML_CHECK_BASIC_(!output.overlaps(tag));
        tag = tag.sub(2);
        const csubstr pfx = "<tag:yaml.org,2002:";
        const size_t len = pfx.len + tag.len + 1;
        if(len <= output.len)
        {
            memcpy(output.str          , pfx.str, pfx.len);
            memcpy(output.str + pfx.len, tag.str, tag.len);
            output[pfx.len + tag.len] = '>';
            result = output.first(len);
        }
        else
        {
            result.str = nullptr;
            result.len = len;
        }
    }
    return result;
}

bool c4::yml::is_custom_tag

(

csubstr

tag

)

is a tag of the form !handle!tag?

Definition at line 9 of file tag.cpp.

Referenced by c4::yml::TagDirectives::lookup(), and c4::yml::TagDirectives::resolve().

{
    if((tag.len > 2) && (tag.str[0] == '!'))
    {
        size_t pos = tag.find('!', 1);
        return pos != npos && pos > 1 && tag.str[1] != '<';
    }
    return false;
}

bool c4::yml::is_valid_tag_handle

(

csubstr

handle

)

Definition at line 210 of file tag.cpp.

Referenced by c4::yml::Tree::add_tag_directive().

{
    if(handle.begins_with('!') && handle.ends_with('!'))
    {
        _c4dbgpf("handle={}", prs_(handle, true));
        csubstr trimmed = handle.sub(1);
        if(trimmed.ends_with('!'))
            trimmed = trimmed.offs(0, 1);
        _c4dbgpf("handle_trimmed={}", prs_(trimmed, true));
        // https://yaml.org/spec/1.2.2/#rule-ns-word-char
        for(char c : trimmed)
        {
            bool ok = (c >= '0' && c <= '9')
                || (c >= 'a' && c <= 'z')
                || (c >= 'A' && c <= 'Z')
                || c == '-';
            if(!ok)
            {
                _c4dbgpf("invalid handle character: '{}'", _c4prc(c));
                return false;
            }
        }
        return true;
    }
    return false;
}

size_t c4::yml::transform_tag	(	substr	output,
		csubstr	handle,
		csubstr	prefix,
		csubstr	tag,
		Callbacks const &	callbacks,
		Location const &	ymlloc,
		bool	with_brackets
	)

returns the length of the transformed tag, or 0 to signal that the tag is local and cannot be resolved

Definition at line 287 of file tag.cpp.

Referenced by c4::yml::TagDirectives::resolve().

{
    RYML_ASSERT_BASIC_CB_(callbacks, tag.len >= handle.len);
    RYML_ASSERT_BASIC_CB_(callbacks, !output.overlaps(tag));
    RYML_ASSERT_BASIC_CB_(callbacks, prefix.len > 0);
    csubstr rest = tag.sub(handle.len);
    _c4dbgpf("%TAG: rest={}", prs_(rest));
    size_t rpos = 0, wpos = 0;
    auto appendstr = [&](csubstr s) {
        if(s.len && wpos + s.len <= output.len)
            memcpy(output.str + wpos, s.str, s.len);
        wpos += s.len;
    };
    auto appendchar = [&](char c) {
        if(wpos < output.len)
            output.str[wpos] = c;
        ++wpos;
    };
    if(with_brackets)
        appendchar('<');
    appendstr(prefix);
    const char *errmsg = nullptr;
    for(size_t pos = 0; pos < rest.len; ++pos)
    {
        char c = rest.str[pos];
        if C4_LIKELY(is_valid_tag_char(c))
        {
            if(c != '%')
            {
                continue;
            }
            else if(read_hex_char(rest, pos, &c))
            {
                appendstr(rest.range(rpos, pos));
                appendchar(c);
                pos += 2;
                rpos = pos + 1;
                continue;
            }
        }
        errmsg = "invalid tag";
        goto err; // NOLINT
    }
    appendstr(rest.sub(rpos));
    if(with_brackets)
        appendchar('>');
    return wpos;
err:
    if(ymlloc)
    {
        RYML_ERR_PARSE_CB_(callbacks, ymlloc, errmsg);
    }
    else
    {
        RYML_ERR_BASIC_CB_(callbacks, errmsg);
    }
}