{"id":15514631,"url":"https://github.com/fgasper/p5-cbor-free","last_synced_at":"2025-04-11T00:51:53.446Z","repository":{"id":56832687,"uuid":"182457743","full_name":"FGasper/p5-CBOR-Free","owner":"FGasper","description":"CPAN’s CBOR::Free","archived":false,"fork":false,"pushed_at":"2022-06-02T14:49:29.000Z","size":420,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T00:51:47.667Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FGasper.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-20T21:51:48.000Z","updated_at":"2023-12-17T15:13:44.000Z","dependencies_parsed_at":"2022-09-08T05:11:24.810Z","dependency_job_id":null,"html_url":"https://github.com/FGasper/p5-CBOR-Free","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-CBOR-Free","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-CBOR-Free/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-CBOR-Free/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-CBOR-Free/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FGasper","download_url":"https://codeload.github.com/FGasper/p5-CBOR-Free/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322609,"owners_count":21084336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T10:00:18.752Z","updated_at":"2025-04-11T00:51:53.432Z","avatar_url":"https://github.com/FGasper.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nCBOR::Free - Fast CBOR for everyone\n\n# SYNOPSIS\n\n    $cbor = CBOR::Free::encode( $some_data_structure );\n\n    $thing = CBOR::Free::decode( $cbor )\n\n    my $tagged = CBOR::Free::tag( 1, '2019-01-02T00:01:02Z' );\n\nAlso see [CBOR::Free::Decoder](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ADecoder) for an object-oriented interface\nto the decoder.\n\n# DESCRIPTION\n\n\u003cdiv\u003e\n    \u003ca href='https://coveralls.io/github/FGasper/p5-CBOR-Free?branch=master'\u003e\u003cimg src='https://coveralls.io/repos/github/FGasper/p5-CBOR-Free/badge.svg?branch=master' alt='Coverage Status' /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\nThis library implements [CBOR](https://tools.ietf.org/html/rfc7049)\nvia XS under a license that permits commercial usage with no “strings\nattached”.\n\n# STATUS\n\nThis distribution is an experimental effort. Its interface is still\nsubject to change. If you decide to use CBOR::Free in your project,\nplease always check the changelog before upgrading.\n\n# FUNCTIONS\n\n## $cbor = encode( $DATA, %OPTS )\n\nEncodes a data structure or non-reference scalar to CBOR.\nThe encoder recognizes and encodes integers, floats, byte and character\nstrings, array and hash references, [CBOR::Free::Tagged](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ATagged) instances,\n[Types::Serialiser](https://metacpan.org/pod/Types%3A%3ASerialiser) booleans, and undef (encoded as null).\n\nThe encoder currently does not handle any other blessed references.\n\n%OPTS may be:\n\n- `canonical` - A boolean that makes the encoder output\nCBOR in [canonical form](https://tools.ietf.org/html/rfc7049#section-3.9).\n- `string_encode_mode` - Decides the logic to use for\nCBOR encoding of strings and hash keys. (The word “string”\nin the below descriptions applies equally to hash keys.)\n\n    Takes one of:\n\n    - `sv`: The default mode of operation. If the string’s internal\n    UTF8 flag is set, it will become a CBOR text string; otherwise, it will be\n    CBOR binary. This is good for IPC with other Perl code but isn’t a very\n    friendly default for working with other languages that probably expect more\n    reliably-typed strings.\n\n        This is (currently) the only way to output text and binary strings in a\n        single CBOR document. Unfortunately, because Perl itself doesn’t reliably\n        distinguish between text and binary strings, neither can CBOR::Free. If you\n        want to try, though:\n\n        - Be sure to use character-decoding logic that always\n        sets the string’s UTF8 flag, even if the input is plain ASCII.\n        (As of this writing, [Encode](https://metacpan.org/pod/Encode) and [Unicode::UTF8](https://metacpan.org/pod/Unicode%3A%3AUTF8) work this way.)\n        - Whatever consumes your Perl-sourced CBOR should probably accept\n        “mis-typed” strings.\n\n    - `encode_text`: Treats all strings as unencoded characters.\n    All CBOR strings will be text.\n\n        This is probably what you want if you\n        follow the receive-decode-process-encode-output workflow that\n        [perlunitut](https://metacpan.org/pod/perlunitut) recommends (which you might be doing via `use utf8`)\n        **AND** if you intend for your CBOR to contain exclusively text.\n\n        Think of this option as: “All my strings are decoded.”\n\n        (Perl internals note: if !SvUTF8, the CBOR will be the UTF8-upgraded\n        version.)\n\n    - `as_text`: Treats all strings as octets of UTF-8.\n    Wide characters (i.e., code points above 255) are thus invalid input.\n    All CBOR strings will be text.\n\n        This is probably what you want if you forgo character decoding (and encoding),\n        treating all input as octets, **BUT** you still intend for your CBOR to\n        contain exclusively text.\n\n        Think of this option as: “I’ve encoded all my strings as UTF-8.”\n\n        (Perl internals note: if SvUTF8, the CBOR will be the downgraded version.)\n\n    - `as_binary`: Like `as_text`, but outputs CBOR binary\n    instead of text.\n\n        This is probably what you want if your application is “all binary,\n        all the time”.\n\n        Think of this option as: “Just the bytes, ma’am.”\n\n- `preserve_references` - A boolean that makes the encoder encode\nmulti-referenced values via [CBOR’s “shared references” tags](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml). This allows encoding of shared\nand circular references. It also incurs a performance penalty.\n\n    (Take care that any circular references in your application don’t cause\n    memory leaks!)\n\n- `scalar_references` - A boolean that makes the encoder accept\nscalar references\n(rather than reject them) and encode them via\n[CBOR’s “indirection” tag](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml).\nMost languages don’t use references as Perl does, so this option seems of\nlittle use outside all-Perl IPC contexts; it is arguably more useful, then,\nfor general use to have the encoder reject data structures that most other\nlanguages cannot represent.\n\nNotes on mapping Perl to CBOR:\n\n- The internal state of a Perl scalar (e.g., whether it’s an\ninteger, float, string, etc.) determines its CBOR encoding.\n- Perl doesn’t currently provide reliable binary/character string types.\nThe various `string_encode_mode` options (described above) provide ways to\ndeal with this problem.\n- The above applies also to strings vs. numbers: whatever consumes\nyour Perl-sourced CBOR **MUST** account for the prospect of numbers that\nare in CBOR as strings, or vice-versa.\n- Perl hash keys are serialized as strings, either binary or text\n(according to the `string_encode_mode`).\n- [Types::Serialiser](https://metacpan.org/pod/Types%3A%3ASerialiser) booleans are encoded as CBOR booleans.\nPerl undef is encoded as CBOR null. (NB: No Perl value encodes as CBOR\nundefined.)\n- Scalar references (including references to other references) are\nunhandled by default, which makes them trigger an exception. You can\noptionally tell CBOR::Free to encode them via the `scalar_references` flag.\n- Via the optional `preserve_references` flag, circular and shared\nreferences may be preserved. Without this flag, circular references cause an\nexception, and other shared references are not preserved.\n- Instances of [CBOR::Free::Tagged](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ATagged) are encoded as tagged values.\n\nAn error is thrown on excess recursion or an unrecognized object.\n\n## $data = decode( $CBOR )\n\nDecodes a data structure from CBOR. Errors are thrown to indicate\ninvalid CBOR. A warning is thrown if $CBOR is longer than is needed\nfor $data.\n\nNotes on mapping CBOR to Perl:\n\n- `decode()` decodes CBOR text strings as UTF-8-decoded Perl strings.\nCBOR binary strings become undecoded Perl strings.\n\n    (See [CBOR::Free::Decoder](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ADecoder) and [CBOR::Free::SequenceDecoder](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ASequenceDecoder) for more\n    character-decoding options.)\n\n    Notes:\n\n    - Invalid UTF-8 in a CBOR text string is usually considered\n    invalid input and will thus prompt a thrown exception. (See\n    [CBOR::Free::Decoder](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ADecoder) and [CBOR::Free::SequenceDecoder](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ASequenceDecoder) if you want\n    to tolerate invalid UTF-8.)\n    - You can reliably use `utf8::is_utf8()` to determine if a given Perl\n    string came from CBOR text or binary, but **ONLY** if you test the scalar as\n    it appears in the newly-decoded data structure itself. Generally Perl code\n    should avoid `is_utf8()`, but with CBOR::Free-created strings this limited\n    use case is legitimate and potentially gainful.\n\n- The only map keys that `decode()` accepts are integers and strings.\nAn exception is thrown if the decoder finds anything else as a map key.\nNote that, because Perl does not distinguish between binary and text strings,\nif two keys of the same map contain the same bytes, Perl will consider these\na duplicate key and prefer the latter.\n- CBOR booleans become the corresponding [Types::Serialiser](https://metacpan.org/pod/Types%3A%3ASerialiser) values.\nBoth CBOR null and undefined become Perl undef.\n- [CBOR’s “indirection” tag](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml) is interpreted as a scalar reference. This behavior is always\nactive; unlike with the encoder, there is no need to enable it manually.\n- `preserve_references()` mode complements the same flag\ngiven to the encoder.\n- This function does not interpret any other tags. If you need to\ndecode other tags, look at [CBOR::Free::Decoder](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3ADecoder). Any unhandled tags that\nthis function sees prompt a warning but are otherwise ignored.\n\n## $obj = tag( $NUMBER, $DATA )\n\nTags an item for encoding so that its CBOR encoding will preserve the\ntag number. (Include $obj, not $DATA, in the data structure that\n`encode()` receives.)\n\n# BOOLEANS\n\n`CBOR::Free::true()` and `CBOR::Free::false()` are defined as\nconvenience aliases for the equivalent [Types::Serialiser](https://metacpan.org/pod/Types%3A%3ASerialiser) functions.\n(Note that there are no equivalent scalar aliases.)\n\n# FRACTIONAL (FLOATING-POINT) NUMBERS\n\nFloating-point numbers are encoded in CBOR as IEEE 754 half-, single-,\nor double-precision. If your Perl is compiled to use anything besides\nIEEE 754 double-precision to represent floating-point values (e.g.,\n“long double” or “quadmath” compilation options), you may see rounding\nerrors when converting to/from CBOR. If that’s a problem for you, append\nan empty string to your floating-point numbers, which will cause CBOR::Free\nto encode them as strings.\n\n# INTEGER LIMITS\n\nCBOR handles up to 64-bit positive and negative integers. Most Perls\nnowadays can handle 64-bit integers, but if yours can’t then you’ll\nget an exception whenever trying to parse an integer that can’t be\nrepresented with 32 bits. This means:\n\n- Anything greater than 0xffff\\_ffff (4,294,967,295)\n- Anything less than -0x8000\\_0000 (2,147,483,648)\n\nNote that even 64-bit Perls can’t parse negatives that are less than\n\\-0x8000\\_0000\\_0000\\_0000 (-9,223,372,036,854,775,808); these also prompt an\nexception since Perl can’t handle them. (It would be possible to load\n[Math::BigInt](https://metacpan.org/pod/Math%3A%3ABigInt) to handle these; if that’s desirable for you,\nfile a feature request.)\n\n# ERROR HANDLING\n\nMost errors are represented via instances of subclasses of\n[CBOR::Free::X](https://metacpan.org/pod/CBOR%3A%3AFree%3A%3AX), which subclasses [X::Tiny::Base](https://metacpan.org/pod/X%3A%3ATiny%3A%3ABase).\n\n# SPEED\n\nCBOR::Free is pretty snappy. I find that it keeps pace with or\nsurpasses [CBOR::XS](https://metacpan.org/pod/CBOR%3A%3AXS), [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel%3A%3AJSON%3A%3AXS), [JSON::XS](https://metacpan.org/pod/JSON%3A%3AXS), [Sereal](https://metacpan.org/pod/Sereal),\nand [Data::MessagePack](https://metacpan.org/pod/Data%3A%3AMessagePack).\n\nIt’s also quite light. Its only “heavy” dependency is\n[Types::Serialiser](https://metacpan.org/pod/Types%3A%3ASerialiser), which is only loaded when you actually need it.\nThis keeps memory usage low for when, e.g., you’re using CBOR for\nIPC between Perl processes and have no need for true booleans.\n\n# AUTHOR\n\n[Gasper Software Consulting](http://gaspersoftware.com) (FELIPE)\n\n# LICENSE\n\nThis code is licensed under the same license as Perl itself.\n\n# SEE ALSO\n\n[CBOR::PP](https://metacpan.org/pod/CBOR%3A%3APP) is a pure-Perl CBOR library.\n\n[CBOR::XS](https://metacpan.org/pod/CBOR%3A%3AXS) is an older CBOR module on CPAN. It’s got more bells and\nwhistles, so check it out if CBOR::Free lacks a feature you’d like.\nNote that [its maintainer has abandoned support for Perl versions from 5.22\nonward](http://blog.schmorp.de/2015-06-06-stableperl-faq.html), though,\nand its GPL license limits its usefulness in\ncommercial [perlcc](https://metacpan.org/pod/distribution/B-C/script/perlcc.PL)\napplications.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-cbor-free","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgasper%2Fp5-cbor-free","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-cbor-free/lists"}