packages feed

ipldm (empty) → 1.0.0.0

raw patch · 22 files changed

+3061/−0 lines, 22 filesdep +arraydep +basedep +basesystems

Dependencies added: array, base, basesystems, bytestring, containers, deepseq, mfmts, parallel, text, xcodec

Files

+ CHANGELOG.md view
@@ -0,0 +1,21 @@+[`ipldm`](http://hackage.haskell.org/package/ipldm) change log:+=================================================================++Major release 1.0+-----------------++## Version 1.0.0.0 (07-09-2026)++This version introduces `ipldm` to hackage! This project provides the interfaces+and functionality for working with various kinds of [InterPlanetary Linked+Data](https://ipld.io/) formats.++The `IPLD.DM*` modules provide interfaces for defining codecs for the IPLD data+model. Specifically, it defines a tagged-union of the IPLD [kinds](+https://ipld.io/docs/data-model/kinds/) and two type-classes for encoding and+decoding binary formats to/from the data model.++The `IPLD.DagCBOR*` modules are the first example of an implementation of the+`IPLD.DM.Decoder` and `IPLD.DM.Encoder` for the [DAG-CBOR](+https://ipld.io/docs/codecs/known/dag-cbor/) codec in `IPLD.DagCBOR.Decoder`+and `IPLD.DagCBOR.Encoder`.
+ LICENSE.txt view
@@ -0,0 +1,661 @@+                    GNU AFFERO GENERAL PUBLIC LICENSE+                       Version 3, 19 November 2007++ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>+ Everyone is permitted to copy and distribute verbatim copies+ of this license document, but changing it is not allowed.++                            Preamble++  The GNU Affero General Public License is a free, copyleft license for+software and other kinds of works, specifically designed to ensure+cooperation with the community in the case of network server software.++  The licenses for most software and other practical works are designed+to take away your freedom to share and change the works.  By contrast,+our General Public Licenses are intended to guarantee your freedom to+share and change all versions of a program--to make sure it remains free+software for all its users.++  When we speak of free software, we are referring to freedom, not+price.  Our General Public Licenses are designed to make sure that you+have the freedom to distribute copies of free software (and charge for+them if you wish), that you receive source code or can get it if you+want it, that you can change the software or use pieces of it in new+free programs, and that you know you can do these things.++  Developers that use our General Public Licenses protect your rights+with two steps: (1) assert copyright on the software, and (2) offer+you this License which gives you legal permission to copy, distribute+and/or modify the software.++  A secondary benefit of defending all users' freedom is that+improvements made in alternate versions of the program, if they+receive widespread use, become available for other developers to+incorporate.  Many developers of free software are heartened and+encouraged by the resulting cooperation.  However, in the case of+software used on network servers, this result may fail to come about.+The GNU General Public License permits making a modified version and+letting the public access it on a server without ever releasing its+source code to the public.++  The GNU Affero General Public License is designed specifically to+ensure that, in such cases, the modified source code becomes available+to the community.  It requires the operator of a network server to+provide the source code of the modified version running there to the+users of that server.  Therefore, public use of a modified version, on+a publicly accessible server, gives the public access to the source+code of the modified version.++  An older license, called the Affero General Public License and+published by Affero, was designed to accomplish similar goals.  This is+a different license, not a version of the Affero GPL, but Affero has+released a new version of the Affero GPL which permits relicensing under+this license.++  The precise terms and conditions for copying, distribution and+modification follow.++                       TERMS AND CONDITIONS++  0. Definitions.++  "This License" refers to version 3 of the GNU Affero General Public License.++  "Copyright" also means copyright-like laws that apply to other kinds of+works, such as semiconductor masks.++  "The Program" refers to any copyrightable work licensed under this+License.  Each licensee is addressed as "you".  "Licensees" and+"recipients" may be individuals or organizations.++  To "modify" a work means to copy from or adapt all or part of the work+in a fashion requiring copyright permission, other than the making of an+exact copy.  The resulting work is called a "modified version" of the+earlier work or a work "based on" the earlier work.++  A "covered work" means either the unmodified Program or a work based+on the Program.++  To "propagate" a work means to do anything with it that, without+permission, would make you directly or secondarily liable for+infringement under applicable copyright law, except executing it on a+computer or modifying a private copy.  Propagation includes copying,+distribution (with or without modification), making available to the+public, and in some countries other activities as well.++  To "convey" a work means any kind of propagation that enables other+parties to make or receive copies.  Mere interaction with a user through+a computer network, with no transfer of a copy, is not conveying.++  An interactive user interface displays "Appropriate Legal Notices"+to the extent that it includes a convenient and prominently visible+feature that (1) displays an appropriate copyright notice, and (2)+tells the user that there is no warranty for the work (except to the+extent that warranties are provided), that licensees may convey the+work under this License, and how to view a copy of this License.  If+the interface presents a list of user commands or options, such as a+menu, a prominent item in the list meets this criterion.++  1. Source Code.++  The "source code" for a work means the preferred form of the work+for making modifications to it.  "Object code" means any non-source+form of a work.++  A "Standard Interface" means an interface that either is an official+standard defined by a recognized standards body, or, in the case of+interfaces specified for a particular programming language, one that+is widely used among developers working in that language.++  The "System Libraries" of an executable work include anything, other+than the work as a whole, that (a) is included in the normal form of+packaging a Major Component, but which is not part of that Major+Component, and (b) serves only to enable use of the work with that+Major Component, or to implement a Standard Interface for which an+implementation is available to the public in source code form.  A+"Major Component", in this context, means a major essential component+(kernel, window system, and so on) of the specific operating system+(if any) on which the executable work runs, or a compiler used to+produce the work, or an object code interpreter used to run it.++  The "Corresponding Source" for a work in object code form means all+the source code needed to generate, install, and (for an executable+work) run the object code and to modify the work, including scripts to+control those activities.  However, it does not include the work's+System Libraries, or general-purpose tools or generally available free+programs which are used unmodified in performing those activities but+which are not part of the work.  For example, Corresponding Source+includes interface definition files associated with source files for+the work, and the source code for shared libraries and dynamically+linked subprograms that the work is specifically designed to require,+such as by intimate data communication or control flow between those+subprograms and other parts of the work.++  The Corresponding Source need not include anything that users+can regenerate automatically from other parts of the Corresponding+Source.++  The Corresponding Source for a work in source code form is that+same work.++  2. Basic Permissions.++  All rights granted under this License are granted for the term of+copyright on the Program, and are irrevocable provided the stated+conditions are met.  This License explicitly affirms your unlimited+permission to run the unmodified Program.  The output from running a+covered work is covered by this License only if the output, given its+content, constitutes a covered work.  This License acknowledges your+rights of fair use or other equivalent, as provided by copyright law.++  You may make, run and propagate covered works that you do not+convey, without conditions so long as your license otherwise remains+in force.  You may convey covered works to others for the sole purpose+of having them make modifications exclusively for you, or provide you+with facilities for running those works, provided that you comply with+the terms of this License in conveying all material for which you do+not control copyright.  Those thus making or running the covered works+for you must do so exclusively on your behalf, under your direction+and control, on terms that prohibit them from making any copies of+your copyrighted material outside their relationship with you.++  Conveying under any other circumstances is permitted solely under+the conditions stated below.  Sublicensing is not allowed; section 10+makes it unnecessary.++  3. Protecting Users' Legal Rights From Anti-Circumvention Law.++  No covered work shall be deemed part of an effective technological+measure under any applicable law fulfilling obligations under article+11 of the WIPO copyright treaty adopted on 20 December 1996, or+similar laws prohibiting or restricting circumvention of such+measures.++  When you convey a covered work, you waive any legal power to forbid+circumvention of technological measures to the extent such circumvention+is effected by exercising rights under this License with respect to+the covered work, and you disclaim any intention to limit operation or+modification of the work as a means of enforcing, against the work's+users, your or third parties' legal rights to forbid circumvention of+technological measures.++  4. Conveying Verbatim Copies.++  You may convey verbatim copies of the Program's source code as you+receive it, in any medium, provided that you conspicuously and+appropriately publish on each copy an appropriate copyright notice;+keep intact all notices stating that this License and any+non-permissive terms added in accord with section 7 apply to the code;+keep intact all notices of the absence of any warranty; and give all+recipients a copy of this License along with the Program.++  You may charge any price or no price for each copy that you convey,+and you may offer support or warranty protection for a fee.++  5. Conveying Modified Source Versions.++  You may convey a work based on the Program, or the modifications to+produce it from the Program, in the form of source code under the+terms of section 4, provided that you also meet all of these conditions:++    a) The work must carry prominent notices stating that you modified+    it, and giving a relevant date.++    b) The work must carry prominent notices stating that it is+    released under this License and any conditions added under section+    7.  This requirement modifies the requirement in section 4 to+    "keep intact all notices".++    c) You must license the entire work, as a whole, under this+    License to anyone who comes into possession of a copy.  This+    License will therefore apply, along with any applicable section 7+    additional terms, to the whole of the work, and all its parts,+    regardless of how they are packaged.  This License gives no+    permission to license the work in any other way, but it does not+    invalidate such permission if you have separately received it.++    d) If the work has interactive user interfaces, each must display+    Appropriate Legal Notices; however, if the Program has interactive+    interfaces that do not display Appropriate Legal Notices, your+    work need not make them do so.++  A compilation of a covered work with other separate and independent+works, which are not by their nature extensions of the covered work,+and which are not combined with it such as to form a larger program,+in or on a volume of a storage or distribution medium, is called an+"aggregate" if the compilation and its resulting copyright are not+used to limit the access or legal rights of the compilation's users+beyond what the individual works permit.  Inclusion of a covered work+in an aggregate does not cause this License to apply to the other+parts of the aggregate.++  6. Conveying Non-Source Forms.++  You may convey a covered work in object code form under the terms+of sections 4 and 5, provided that you also convey the+machine-readable Corresponding Source under the terms of this License,+in one of these ways:++    a) Convey the object code in, or embodied in, a physical product+    (including a physical distribution medium), accompanied by the+    Corresponding Source fixed on a durable physical medium+    customarily used for software interchange.++    b) Convey the object code in, or embodied in, a physical product+    (including a physical distribution medium), accompanied by a+    written offer, valid for at least three years and valid for as+    long as you offer spare parts or customer support for that product+    model, to give anyone who possesses the object code either (1) a+    copy of the Corresponding Source for all the software in the+    product that is covered by this License, on a durable physical+    medium customarily used for software interchange, for a price no+    more than your reasonable cost of physically performing this+    conveying of source, or (2) access to copy the+    Corresponding Source from a network server at no charge.++    c) Convey individual copies of the object code with a copy of the+    written offer to provide the Corresponding Source.  This+    alternative is allowed only occasionally and noncommercially, and+    only if you received the object code with such an offer, in accord+    with subsection 6b.++    d) Convey the object code by offering access from a designated+    place (gratis or for a charge), and offer equivalent access to the+    Corresponding Source in the same way through the same place at no+    further charge.  You need not require recipients to copy the+    Corresponding Source along with the object code.  If the place to+    copy the object code is a network server, the Corresponding Source+    may be on a different server (operated by you or a third party)+    that supports equivalent copying facilities, provided you maintain+    clear directions next to the object code saying where to find the+    Corresponding Source.  Regardless of what server hosts the+    Corresponding Source, you remain obligated to ensure that it is+    available for as long as needed to satisfy these requirements.++    e) Convey the object code using peer-to-peer transmission, provided+    you inform other peers where the object code and Corresponding+    Source of the work are being offered to the general public at no+    charge under subsection 6d.++  A separable portion of the object code, whose source code is excluded+from the Corresponding Source as a System Library, need not be+included in conveying the object code work.++  A "User Product" is either (1) a "consumer product", which means any+tangible personal property which is normally used for personal, family,+or household purposes, or (2) anything designed or sold for incorporation+into a dwelling.  In determining whether a product is a consumer product,+doubtful cases shall be resolved in favor of coverage.  For a particular+product received by a particular user, "normally used" refers to a+typical or common use of that class of product, regardless of the status+of the particular user or of the way in which the particular user+actually uses, or expects or is expected to use, the product.  A product+is a consumer product regardless of whether the product has substantial+commercial, industrial or non-consumer uses, unless such uses represent+the only significant mode of use of the product.++  "Installation Information" for a User Product means any methods,+procedures, authorization keys, or other information required to install+and execute modified versions of a covered work in that User Product from+a modified version of its Corresponding Source.  The information must+suffice to ensure that the continued functioning of the modified object+code is in no case prevented or interfered with solely because+modification has been made.++  If you convey an object code work under this section in, or with, or+specifically for use in, a User Product, and the conveying occurs as+part of a transaction in which the right of possession and use of the+User Product is transferred to the recipient in perpetuity or for a+fixed term (regardless of how the transaction is characterized), the+Corresponding Source conveyed under this section must be accompanied+by the Installation Information.  But this requirement does not apply+if neither you nor any third party retains the ability to install+modified object code on the User Product (for example, the work has+been installed in ROM).++  The requirement to provide Installation Information does not include a+requirement to continue to provide support service, warranty, or updates+for a work that has been modified or installed by the recipient, or for+the User Product in which it has been modified or installed.  Access to a+network may be denied when the modification itself materially and+adversely affects the operation of the network or violates the rules and+protocols for communication across the network.++  Corresponding Source conveyed, and Installation Information provided,+in accord with this section must be in a format that is publicly+documented (and with an implementation available to the public in+source code form), and must require no special password or key for+unpacking, reading or copying.++  7. Additional Terms.++  "Additional permissions" are terms that supplement the terms of this+License by making exceptions from one or more of its conditions.+Additional permissions that are applicable to the entire Program shall+be treated as though they were included in this License, to the extent+that they are valid under applicable law.  If additional permissions+apply only to part of the Program, that part may be used separately+under those permissions, but the entire Program remains governed by+this License without regard to the additional permissions.++  When you convey a copy of a covered work, you may at your option+remove any additional permissions from that copy, or from any part of+it.  (Additional permissions may be written to require their own+removal in certain cases when you modify the work.)  You may place+additional permissions on material, added by you to a covered work,+for which you have or can give appropriate copyright permission.++  Notwithstanding any other provision of this License, for material you+add to a covered work, you may (if authorized by the copyright holders of+that material) supplement the terms of this License with terms:++    a) Disclaiming warranty or limiting liability differently from the+    terms of sections 15 and 16 of this License; or++    b) Requiring preservation of specified reasonable legal notices or+    author attributions in that material or in the Appropriate Legal+    Notices displayed by works containing it; or++    c) Prohibiting misrepresentation of the origin of that material, or+    requiring that modified versions of such material be marked in+    reasonable ways as different from the original version; or++    d) Limiting the use for publicity purposes of names of licensors or+    authors of the material; or++    e) Declining to grant rights under trademark law for use of some+    trade names, trademarks, or service marks; or++    f) Requiring indemnification of licensors and authors of that+    material by anyone who conveys the material (or modified versions of+    it) with contractual assumptions of liability to the recipient, for+    any liability that these contractual assumptions directly impose on+    those licensors and authors.++  All other non-permissive additional terms are considered "further+restrictions" within the meaning of section 10.  If the Program as you+received it, or any part of it, contains a notice stating that it is+governed by this License along with a term that is a further+restriction, you may remove that term.  If a license document contains+a further restriction but permits relicensing or conveying under this+License, you may add to a covered work material governed by the terms+of that license document, provided that the further restriction does+not survive such relicensing or conveying.++  If you add terms to a covered work in accord with this section, you+must place, in the relevant source files, a statement of the+additional terms that apply to those files, or a notice indicating+where to find the applicable terms.++  Additional terms, permissive or non-permissive, may be stated in the+form of a separately written license, or stated as exceptions;+the above requirements apply either way.++  8. Termination.++  You may not propagate or modify a covered work except as expressly+provided under this License.  Any attempt otherwise to propagate or+modify it is void, and will automatically terminate your rights under+this License (including any patent licenses granted under the third+paragraph of section 11).++  However, if you cease all violation of this License, then your+license from a particular copyright holder is reinstated (a)+provisionally, unless and until the copyright holder explicitly and+finally terminates your license, and (b) permanently, if the copyright+holder fails to notify you of the violation by some reasonable means+prior to 60 days after the cessation.++  Moreover, your license from a particular copyright holder is+reinstated permanently if the copyright holder notifies you of the+violation by some reasonable means, this is the first time you have+received notice of violation of this License (for any work) from that+copyright holder, and you cure the violation prior to 30 days after+your receipt of the notice.++  Termination of your rights under this section does not terminate the+licenses of parties who have received copies or rights from you under+this License.  If your rights have been terminated and not permanently+reinstated, you do not qualify to receive new licenses for the same+material under section 10.++  9. Acceptance Not Required for Having Copies.++  You are not required to accept this License in order to receive or+run a copy of the Program.  Ancillary propagation of a covered work+occurring solely as a consequence of using peer-to-peer transmission+to receive a copy likewise does not require acceptance.  However,+nothing other than this License grants you permission to propagate or+modify any covered work.  These actions infringe copyright if you do+not accept this License.  Therefore, by modifying or propagating a+covered work, you indicate your acceptance of this License to do so.++  10. Automatic Licensing of Downstream Recipients.++  Each time you convey a covered work, the recipient automatically+receives a license from the original licensors, to run, modify and+propagate that work, subject to this License.  You are not responsible+for enforcing compliance by third parties with this License.++  An "entity transaction" is a transaction transferring control of an+organization, or substantially all assets of one, or subdividing an+organization, or merging organizations.  If propagation of a covered+work results from an entity transaction, each party to that+transaction who receives a copy of the work also receives whatever+licenses to the work the party's predecessor in interest had or could+give under the previous paragraph, plus a right to possession of the+Corresponding Source of the work from the predecessor in interest, if+the predecessor has it or can get it with reasonable efforts.++  You may not impose any further restrictions on the exercise of the+rights granted or affirmed under this License.  For example, you may+not impose a license fee, royalty, or other charge for exercise of+rights granted under this License, and you may not initiate litigation+(including a cross-claim or counterclaim in a lawsuit) alleging that+any patent claim is infringed by making, using, selling, offering for+sale, or importing the Program or any portion of it.++  11. Patents.++  A "contributor" is a copyright holder who authorizes use under this+License of the Program or a work on which the Program is based.  The+work thus licensed is called the contributor's "contributor version".++  A contributor's "essential patent claims" are all patent claims+owned or controlled by the contributor, whether already acquired or+hereafter acquired, that would be infringed by some manner, permitted+by this License, of making, using, or selling its contributor version,+but do not include claims that would be infringed only as a+consequence of further modification of the contributor version.  For+purposes of this definition, "control" includes the right to grant+patent sublicenses in a manner consistent with the requirements of+this License.++  Each contributor grants you a non-exclusive, worldwide, royalty-free+patent license under the contributor's essential patent claims, to+make, use, sell, offer for sale, import and otherwise run, modify and+propagate the contents of its contributor version.++  In the following three paragraphs, a "patent license" is any express+agreement or commitment, however denominated, not to enforce a patent+(such as an express permission to practice a patent or covenant not to+sue for patent infringement).  To "grant" such a patent license to a+party means to make such an agreement or commitment not to enforce a+patent against the party.++  If you convey a covered work, knowingly relying on a patent license,+and the Corresponding Source of the work is not available for anyone+to copy, free of charge and under the terms of this License, through a+publicly available network server or other readily accessible means,+then you must either (1) cause the Corresponding Source to be so+available, or (2) arrange to deprive yourself of the benefit of the+patent license for this particular work, or (3) arrange, in a manner+consistent with the requirements of this License, to extend the patent+license to downstream recipients.  "Knowingly relying" means you have+actual knowledge that, but for the patent license, your conveying the+covered work in a country, or your recipient's use of the covered work+in a country, would infringe one or more identifiable patents in that+country that you have reason to believe are valid.++  If, pursuant to or in connection with a single transaction or+arrangement, you convey, or propagate by procuring conveyance of, a+covered work, and grant a patent license to some of the parties+receiving the covered work authorizing them to use, propagate, modify+or convey a specific copy of the covered work, then the patent license+you grant is automatically extended to all recipients of the covered+work and works based on it.++  A patent license is "discriminatory" if it does not include within+the scope of its coverage, prohibits the exercise of, or is+conditioned on the non-exercise of one or more of the rights that are+specifically granted under this License.  You may not convey a covered+work if you are a party to an arrangement with a third party that is+in the business of distributing software, under which you make payment+to the third party based on the extent of your activity of conveying+the work, and under which the third party grants, to any of the+parties who would receive the covered work from you, a discriminatory+patent license (a) in connection with copies of the covered work+conveyed by you (or copies made from those copies), or (b) primarily+for and in connection with specific products or compilations that+contain the covered work, unless you entered into that arrangement,+or that patent license was granted, prior to 28 March 2007.++  Nothing in this License shall be construed as excluding or limiting+any implied license or other defenses to infringement that may+otherwise be available to you under applicable patent law.++  12. No Surrender of Others' Freedom.++  If conditions are imposed on you (whether by court order, agreement or+otherwise) that contradict the conditions of this License, they do not+excuse you from the conditions of this License.  If you cannot convey a+covered work so as to satisfy simultaneously your obligations under this+License and any other pertinent obligations, then as a consequence you may+not convey it at all.  For example, if you agree to terms that obligate you+to collect a royalty for further conveying from those to whom you convey+the Program, the only way you could satisfy both those terms and this+License would be to refrain entirely from conveying the Program.++  13. Remote Network Interaction; Use with the GNU General Public License.++  Notwithstanding any other provision of this License, if you modify the+Program, your modified version must prominently offer all users+interacting with it remotely through a computer network (if your version+supports such interaction) an opportunity to receive the Corresponding+Source of your version by providing access to the Corresponding Source+from a network server at no charge, through some standard or customary+means of facilitating copying of software.  This Corresponding Source+shall include the Corresponding Source for any work covered by version 3+of the GNU General Public License that is incorporated pursuant to the+following paragraph.++  Notwithstanding any other provision of this License, you have+permission to link or combine any covered work with a work licensed+under version 3 of the GNU General Public License into a single+combined work, and to convey the resulting work.  The terms of this+License will continue to apply to the part which is the covered work,+but the work with which it is combined will remain governed by version+3 of the GNU General Public License.++  14. Revised Versions of this License.++  The Free Software Foundation may publish revised and/or new versions of+the GNU Affero General Public License from time to time.  Such new versions+will be similar in spirit to the present version, but may differ in detail to+address new problems or concerns.++  Each version is given a distinguishing version number.  If the+Program specifies that a certain numbered version of the GNU Affero General+Public License "or any later version" applies to it, you have the+option of following the terms and conditions either of that numbered+version or of any later version published by the Free Software+Foundation.  If the Program does not specify a version number of the+GNU Affero General Public License, you may choose any version ever published+by the Free Software Foundation.++  If the Program specifies that a proxy can decide which future+versions of the GNU Affero General Public License can be used, that proxy's+public statement of acceptance of a version permanently authorizes you+to choose that version for the Program.++  Later license versions may give you additional or different+permissions.  However, no additional obligations are imposed on any+author or copyright holder as a result of your choosing to follow a+later version.++  15. Disclaimer of Warranty.++  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.++  16. Limitation of Liability.++  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF+SUCH DAMAGES.++  17. Interpretation of Sections 15 and 16.++  If the disclaimer of warranty and limitation of liability provided+above cannot be given local legal effect according to their terms,+reviewing courts shall apply local law that most closely approximates+an absolute waiver of all civil liability in connection with the+Program, unless a warranty or assumption of liability accompanies a+copy of the Program in return for a fee.++                     END OF TERMS AND CONDITIONS++            How to Apply These Terms to Your New Programs++  If you develop a new program, and you want it to be of the greatest+possible use to the public, the best way to achieve this is to make it+free software which everyone can redistribute and change under these terms.++  To do so, attach the following notices to the program.  It is safest+to attach them to the start of each source file to most effectively+state the exclusion of warranty; and each file should have at least+the "copyright" line and a pointer to where the full notice is found.++    <one line to give the program's name and a brief idea of what it does.>+    Copyright (C) <year>  <name of author>++    This program is free software: you can redistribute it and/or modify+    it under the terms of the GNU Affero General Public License as published by+    the Free Software Foundation, either version 3 of the License, or+    (at your option) any later version.++    This program is distributed in the hope that it will be useful,+    but WITHOUT ANY WARRANTY; without even the implied warranty of+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the+    GNU Affero General Public License for more details.++    You should have received a copy of the GNU Affero General Public License+    along with this program.  If not, see <http://www.gnu.org/licenses/>.++Also add information on how to contact you by electronic and paper mail.++  If your software can interact with users remotely through a computer+network, you should also make sure that it provides a way for users to+get its source.  For example, if your program is a web application, its+interface could display a "Source" link that leads users to an archive+of the code.  There are many ways you could offer source, and different+solutions will be better for different programs; see section 13 for the+specific requirements.++  You should also get your employer (if you work as a programmer) or school,+if any, to sign a "copyright disclaimer" for the program, if necessary.+For more information on this, and how to apply and follow the GNU AGPL, see+<http://www.gnu.org/licenses/>.
+ README.md view
@@ -0,0 +1,39 @@+ipldm [![builds.sr.ht status](+https://builds.sr.ht/~z0/ipldm/commits/main/ipfshs-ci.yml.svg)](+https://builds.sr.ht/~z0/ipldm/commits/main/ipfshs-ci.yml?)+----------------------------------------------------------------++The `ipldm` library provides methods for working with the [IPLD data model](+https://ipld.io/docs/data-model/) (DM) in Haskell. Disclaimer that this project+is still in alpha, and not ready to be used in a production system.++Currently, the project has the following functionalities:++- Represeting the DM with [nodes](https://ipld.io/docs/data-model/node/) of+some [kind](https://ipld.io/docs/data-model/kinds/) including [CIDs](+https://github.com/multiformats/cid) provided by the [`mfmts`](+https://hackage.haskell.org/package/mfmts) package.+- A type-class interface for implementing generic encoders and decoders for the+DM using [Alternatives](+https://hackage.haskell.org/package/base/docs/Control-Applicative.html#t:Applicative).+- Implements codec for [DAG-CBOR](https://ipld.io/docs/codecs/known/dag-cbor/)+with encoder/decoder instances that work with [CBOR](https://cbor.io/) encoded+bytestrings and provides exeptions for formatting errors and IPLD's extra+constraints.++Development+-----------++Unit tests are provided on the main [ipfshs repo](https://git.sr.ht/~z0/ipfshs),+and bugs can be reported on [ipfshs ticket tracker](+https://todo.sr.ht/~z0/ipfshs).++Licensing+---------++The `ipldm` project and its modules are free software and licensed under the+[AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) license. See+[LICENSE.txt](LICENSE.txt).++Copyright © 2026 Zoey McBride | [zoeymcbride@mailbox.org](+mailto:zoeymcbride@mailbox.org)
+ dagcbor/IPLD/DagCBOR.hs view
@@ -0,0 +1,26 @@+-- | Module      : IPLD.DagCBOR+--   Description : DagCBOR general utilities+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR (decodeFile) where++import Data.ByteString.Lazy qualified as LBS+import Data.XCodec.BinaryTranscoder qualified as BXC+import IPLD.DM qualified as DM+import IPLD.DM.Decoder qualified as DM+import IPLD.DagCBOR.Decoder qualified as DagCBOR+import IPLD.DagCBOR.Decoder.Errors++-- | Reads a DAG-CBOR encoded file at filepath and gives back the root node.+decodeFile :: FilePath -> IO (Okay DM.Node)+decodeFile filepath = do+  contents <- LBS.readFile filepath+  return $+    -- Applies the DM decoder as the DagCBOR decoderMethod+    case DagCBOR.decoderMethod DM.decoder contents of+      Left err -> Left err+      Right (Result node trailing)+        | not (BXC.null trailing) -> Left TrailingBytes+        | otherwise -> Right node
+ dagcbor/IPLD/DagCBOR/Decoder.hs view
@@ -0,0 +1,180 @@+-- | Module      : IPLD.DagCBOR.Decoder+--   Description : Implements DM.Decoder for DAG-CBOR+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Decoder+  ( -- * Implements `DM.Decoder` for DAG-CBOR.+    DagCBOR (decoderMethod),++    -- * Evaluates the major parts of CBOR data.+    evalMajorType,+    evalMajorId,++    -- * Evaulating DAG-CBOR binaries into `DM.Node`.+    evalNode,++    -- * Implements each `DM.Kind` for the decoder.+    evalNullKind,+    evalBoolKind,+    evalIntKind,+    evalFloatKind,+    evalBytesKind,+    evalStringKind,+    evalResourceKind,+    evalListKind,+    evalMapKind,+  )+where++import Control.Applicative (Alternative (..))+import Control.Monad ((>=>))+import Data.Bifunctor (Bifunctor (first))+import Data.XCodec.BinaryTranscoder (BinaryTranscoder)+import IPLD.DM qualified as DM+import IPLD.DM.Decoder qualified as DM+import IPLD.DagCBOR.Decoder.Errors+import IPLD.DagCBOR.Decoder.MajorTypes+import IPLD.DagCBOR.Decoder.Objects++-- | Implements `DM.Decoder` for DAG-CBOR binaries.+newtype DagCBOR bxc item = DagCBOR+  { -- | Provides the `DecoderMethod` for the `item` type.+    decoderMethod :: DecoderMethod item bxc+  }++-- | Evaluates the first byte's major-type in the given transcoder.+evalMajorType :: (BinaryTranscoder bxc) => MajorId -> DagCBOR bxc MajorType+evalMajorType typeid = DagCBOR decodeMajorType >>= matchTypeId+  where+    -- Fails with `EmptyAlternative` if the `MajorType` doesn't have the correct+    -- `MajorId`.+    matchTypeId majortype+      | majorTypeId majortype /= typeid = pure majortype+      | otherwise = empty++-- | Evaluates a well-formed CBOR binary object into the IPLD data model and+-- removes it from the transcoder.+evalNode :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalNode = DagCBOR decodeObject++-- | Evaluates a `DM.Node` from DAG-CBOR when the major ID in the transcoder+-- matches the given param, and then removes the object from the binary.+-- Otherwise it fails with `EmptyAlternative`.+evalMajorId :: (BinaryTranscoder bxc) => MajorId -> DagCBOR bxc DM.Node+evalMajorId idtype = evalMajorType idtype >> evalNode++-- | Evaluates a `DM.IntKind` from DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalIntKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalIntKind = evalMajorId idPositive <|> evalMajorId idNegative++-- | Evaluates a `DM.BytesKind` from DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalBytesKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalBytesKind = evalMajorId idBytes++-- | Evaluates a `DM.StringKind` from DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalStringKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalStringKind = evalMajorId idUTF8++-- | Evaluates a `DM.ListKind` from DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalListKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalListKind = evalMajorId idList++-- | Evaluates a `DM.MapKind` from DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalMapKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalMapKind = evalMajorId idMap++-- | Evaluates a `DM.ResourceKind` from DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalResourceKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalResourceKind = evalMajorId idResource++-- | Evaluates a `DM.FloatKind` from DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalFloatKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalFloatKind = evalMajorId idFloat >>= matchFloatKind+  where+    -- Fails with `EmptyAlternative` if the node isn't `DM.FloatKind`.+    matchFloatKind node@(DM.FloatKind _) = pure node+    matchFloatKind _ = empty++-- | Evaluates a `DM.BoolKind` from a DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalBoolKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalBoolKind = evalMajorId idBool >>= matchBoolKind+  where+    -- Fails with `EmptyAlternative` if the node isn't `DM.BoolKind`.+    matchBoolKind node@(DM.BoolKind _) = pure node+    matchBoolKind _ = empty++-- | Evaluates a `DM.NullKind` from a DAG-CBOR. Fails with `EmptyAlternative`+-- when the binary doesn't contain the correct `DM.Kind`.+evalNullKind :: (BinaryTranscoder bxc) => DagCBOR bxc DM.Node+evalNullKind = evalMajorId idNull >>= matchNullKind+  where+    -- Fails with `EmptyAlternative` if the node isn't `DM.NullKind`.+    matchNullKind node@DM.NullKind = pure node+    matchNullKind _ = empty++-- | Parses the DM from some DAG-CBOR encoded bytestring.+-- https://ipld.io/specs/codecs/dag-cbor/spec/+instance (BinaryTranscoder bxc) => DM.Decoder (DagCBOR bxc) where+  intKind = evalIntKind+  bytesKind = evalBytesKind+  stringKind = evalStringKind+  listKind = evalListKind+  mapKind = evalMapKind+  resourceKind = evalResourceKind+  floatKind = evalFloatKind+  boolKind = evalBoolKind+  nullKind = evalNullKind++-- | Implements function injection (fmap) into some decoder process.+instance (BinaryTranscoder bxc) => Functor (DagCBOR bxc) where+  -- Decode the result and apply f to the first item in the struct+  fmap f (DagCBOR decoder) = DagCBOR $ decoder >=> pure . first f++-- | Implements value injection in decoder context (pure) and applying some+-- process derived from parsing (<*>).+instance (BinaryTranscoder bxc) => Applicative (DagCBOR bxc) where+  -- Push the value into the functor, keeping the original bytestring+  pure value = DagCBOR $ pure . Result value++  -- Composing functor wrapped functions+  (DagCBOR step1) <*> (DagCBOR step2) =+    DagCBOR $ \bytes -> do+      -- Perform the 2 steps on the data+      Result funcpart inner <- step1 bytes+      Result datapart rest <- step2 inner+      -- Apply the function and return the values from step2+      Right $ Result (funcpart datapart) rest++-- | Binds next operation (>>=) in the DagCBOR context.+instance (BinaryTranscoder bxc) => Monad (DagCBOR bxc) where+  (DagCBOR step1) >>= next =+    DagCBOR $ \bytes -> do+      Result input rest <- step1 bytes+      let (DagCBOR step2) = next input+      step2 rest++-- | Defines alternative code paths (<|>) and default failure element (empty).+instance (BinaryTranscoder bxc) => Alternative (DagCBOR bxc) where+  -- Returns the special value marking a functor as an invalid code path+  empty = DagCBOR $ const (Left EmptyAlternative)++  -- Implements code branch selection+  (DagCBOR step1) <|> (DagCBOR step2) =+    DagCBOR $ \bytes ->+      case step1 bytes of+        -- Try the other branch if empty is called+        Left EmptyAlternative -> step2 bytes+        -- For other errors, return them to the caller+        Left err -> Left err+        -- Return the result if the first code branch works+        Right result -> Right result
+ dagcbor/IPLD/DagCBOR/Decoder/Arguments.hs view
@@ -0,0 +1,265 @@+-- | Module      : IPLD.DagCBOR.Decoder.Arguments+--   Description : Provides arguments for the major types in CBOR+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Decoder.Arguments+  ( -- * Type class for resolving argument types.+    Argument (decodeArg),++    -- * Implements Argument for Integer types+    Ints (..),+    intsSizeOf,++    -- * Stores read CBOR integers+    IntData,+    downcastIntData,++    -- * Implements Arguments for special items (Booleans, Floats, etc)+    Simple (..),++    -- * Stores read CBOR simple types+    SimpleData (..),+    simpleSizeOf,++    -- * Implements Argument for Collections (Arrays, Maps, Strings, etc)+    Collection (..),++    -- * Implements Arguments for CID tags.+    Tag (..),++    -- * DecoderMethod utilities+    extractByte,+    extractBytes,+    extractIntData,+    dropBytes,+    removeOctet,++    -- * Extracts major identifiers and major parameters from raw bytes.+    maskMajorID,+    maskMajorArg,+  )+where++import Data.Bits ((.&.), (.>>.))+import Data.Word (Word64, Word8)+import Data.XCodec.BinaryTranscoder (BinaryTranscoder, Octet)+import Data.XCodec.BinaryTranscoder qualified as BXC+import IPLD.DM qualified as DM+import IPLD.DagCBOR.Decoder.Errors++-- | Extracts a single byte from the transcoder data.+{-# INLINEABLE extractByte #-}+extractByte :: (BinaryTranscoder bxc) => DecoderMethod Word8 bxc+extractByte bytes =+  case BXC.uncons bytes of+    Nothing -> Left UnexpectedStop+    Just (byte, rest) -> byte `seq` Right $ Result byte rest++-- | Extracts multiple bytes from a transcoder.+{-# INLINEABLE extractBytes #-}+extractBytes :: (BinaryTranscoder bxc) => Int -> DecoderMethod bxc bxc+extractBytes pos bytes =+  case BXC.splitOffset pos bytes of+    (top, rest)+      | BXC.totalOctets top < pos -> Left UnexpectedStop+      | otherwise -> Right $ Result top rest++-- | Extracts an Integer value given the rule.+{-# INLINEABLE extractIntData #-}+extractIntData :: (BinaryTranscoder bxc) => Ints -> DecoderMethod IntData bxc+extractIntData ints bytes =+  case ints of+    Ints5Bits param -> convIntData param bytes+    _IntsLarger -> do+      Result intdata rest <- extractBytes (intsSizeOf ints) bytes+      convIntData (BXC.unpackValueBE intdata) rest+  where+    -- Converts the value into IntData and strictly evaluates it+    convIntData intdata rest =+      let value = fromIntegral intdata+       in value `seq` Right $ Result value rest++-- | Extracts some number of bytes from the transcoder data.+{-# INLINEABLE dropBytes #-}+dropBytes :: (BinaryTranscoder bxc) => IntData -> DecoderRoutine bxc+dropBytes pos bytes = do+  ipos <- downcastIntData pos+  case BXC.splitOffset ipos bytes of+    (top, rest)+      | BXC.totalOctets top < ipos -> Left UnexpectedStop+      | otherwise -> Right $ Finish rest++-- | Removes some value and only suceeds when it matches its first octet in the+-- transcoder.+{-# INLINEABLE removeOctet #-}+removeOctet :: (BinaryTranscoder bxc) => Octet -> DecoderRoutine bxc+removeOctet value bytes = do+  Result tag rest <- extractByte bytes+  if tag /= value+    then Left UnexpectedValue+    else Right $ Finish rest++-- Extracts the major-type's id from a byte.+{-# INLINE maskMajorID #-}+maskMajorID :: Word8 -> Word8+maskMajorID byte = (byte .&. 0b11100000) .>>. 5++-- Extracts the major-type's param from a byte.+{-# INLINE maskMajorArg #-}+maskMajorArg :: Word8 -> Word8+maskMajorArg byte = byte .&. 0b00011111++-- | Type-class for parsing argument types.+class Argument a where+  -- | Decodes type `a` from parameter id.+  decodeArg :: Word8 -> Okay a++-- | Represents the possible 5-bits following the 3-bit major for an integer+-- value (signed or unsigned). Encodes how to interpret the following bytes or+-- the current argument.+data Ints+  = -- | For values < 24 we can store in the lower 5 bits of the byte+    Ints5Bits Word8+  | -- | For 8-bit values >= 24, we use the next byte following the idenitfier.+    Ints8Bits+  | -- | For 16-bit values we use the next 2 bytes following the identifier.+    Ints16Bits+  | -- | For 32-bit values we use the next 4 bytes following the identifier.+    Ints32Bits+  | -- | For 64-bit values we use the next 8 bytes following the identifier.+    Ints64Bits+  deriving (Show, Eq)++-- | Implements the section from:+-- https://datatracker.ietf.org/doc/html/rfc8949#section-3-2+instance Argument Ints where+  {-# INLINEABLE decodeArg #-}+  decodeArg arg =+    case maskMajorArg arg of+      param+        | param == 27 -> Right Ints64Bits+        | param == 26 -> Right Ints32Bits+        | param == 25 -> Right Ints16Bits+        | param == 24 -> Right Ints8Bits+        | param <= 23 -> Right (Ints5Bits param)+        | otherwise -> Left ReservedParam++-- | Returns the #bytes a `Ints` type occupies after its argument.+{-# INLINE intsSizeOf #-}+intsSizeOf :: Ints -> Int+intsSizeOf ints =+  case ints of+    Ints5Bits _ -> 0+    Ints8Bits -> 1+    Ints16Bits -> 2+    Ints32Bits -> 4+    Ints64Bits -> 8++-- | Type-alias for `Word64` for CBOR integer data.+type IntData = Word64++-- | For converting `IntData` into smaller types such as `Int`.+{-# INLINE downcastIntData #-}+downcastIntData :: forall a. (Integral a, Bounded a) => IntData -> Okay a+downcastIntData intdata+  | intdata > fromIntegral (maxBound :: a) = Left DowncastFailed+  | otherwise =+      -- Convert the intdata and strictly evaluate it+      let int = fromIntegral intdata+       in int `seq` Right int++-- | Represents the possible 5-bits following the 3-bit major for byte strings,+-- text, arrays and mappings.+data Collection+  = -- | Provides the length for some grouping of data within the same format as+    -- integers' arguments.+    CollectionsLength Ints+  | -- | Indefinite length groupings. Unsupported in DAG-CBOR.+    CollectionsIndefinite+  deriving (Show, Eq)++-- | Implements the section from:+-- https://datatracker.ietf.org/doc/html/rfc8949#section-3-3.8+instance Argument Collection where+  {-# INLINEABLE decodeArg #-}+  decodeArg arg =+    case maskMajorArg arg of+      param+        -- All set 5-bits marks grouping to indefinite.+        | param == 31 -> Left Indefinite+        -- Otherwise, interpret the argument as an int value.+        | otherwise -> CollectionsLength <$> decodeArg param++-- | Represents a tag for marking special data. DAG-CBOR only supports tagging+-- for CID data.+data Tag = Tag deriving (Show, Eq)++-- | Implements tags for DAG-CBOR, see:+-- https://ipld.io/specs/codecs/dag-cbor/spec/#strictness+instance Argument Tag where+  {-# INLINEABLE decodeArg #-}+  decodeArg arg =+    case decodeArg (maskMajorArg arg) of+      -- Valid tags expect an 8-bit value+      Right Ints8Bits -> Right Tag+      -- Report the unsupported param+      Right _gt8bits -> Left InvalidTag+      -- Otherwise, pass the error when given+      Left err -> Left err++-- | Represents the possible arguments following a "simple" (here, special)+-- major type. Used to store floats and some familiar JSON primatives.+data Simple+  = -- | Represents true + false.+    SimpleBool Bool+  | -- | Represents JSON style null.+    SimpleNull+  | -- | Represents JSON style undefined.+    SimpleUndefined+  | -- | For 16-bit half floats in the next 2 bytes.+    FloatHalf+  | -- | For 32-bit single floats in the next 4 bytes.+    FloatSingle+  | -- | For 64-bit double floats in the next 8 bytes.+    FloatDouble+  | -- | Marks the end of an indefinite grouping. Unsupported in DAG-CBOR.+    StopCollection+  deriving (Show, Eq)++-- | Implements the section from:+-- https://datatracker.ietf.org/doc/html/rfc8949#section-3.3+-- And the constraints from:+-- https://ipld.io/specs/codecs/dag-cbor/spec/#strictness+instance Argument Simple where+  {-# INLINEABLE decodeArg #-}+  decodeArg arg =+    case maskMajorArg arg of+      param+        | param == 31 -> Left Indefinite+        | param == 27 -> Right FloatDouble+        | param == 26 -> Right FloatSingle+        | param == 25 -> Right FloatHalf+        | param == 23 -> Left NotDefined+        | param == 22 -> Right SimpleNull+        | param == 21 -> Right (SimpleBool True)+        | param == 20 -> Right (SimpleBool False)+        | otherwise -> Left ReservedParam++-- | Returns the #bytes a `Simple` type occupies after its argument.+{-# INLINE simpleSizeOf #-}+simpleSizeOf :: Simple -> Int+simpleSizeOf simple =+  case simple of+    FloatHalf -> 2+    FloatSingle -> 4+    FloatDouble -> 8+    _SimpleOther -> 0++-- | Stores values from Special arguments.+data SimpleData+  = FloatData DM.FloatData+  | BoolData Bool+  | NullData+  deriving (Show, Eq)
+ dagcbor/IPLD/DagCBOR/Decoder/Errors.hs view
@@ -0,0 +1,93 @@+-- | Module      : IPLD.DagCBOR.Decoder.Errors+--   Description : Invalid states for DAG-CBOR Decoder+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Decoder.Errors+  ( -- * Functor for wrapping results w/ error.+    Okay,++    -- * Error constructors+    Error (..),++    -- * For resolving items and changing decoder data.+    DecoderMethod,+    DecoderRoutine,++    -- * Results from running DecoderMethods+    Result (Result),+    pattern Finish,+  )+where++import Control.DeepSeq (NFData (..))+import Data.Bifunctor (Bifunctor (bimap))+import IPLD.DM.Decoder qualified as DM+import MultiFormats.CID.Errors qualified as CID++-- | The Result value `obj` and the remaining input tokens.+data Result obj bxc = Result obj bxc deriving (Show, Eq)++instance Functor (Result obj) where+  fmap f (Result a b) = Result a (f b)++instance Bifunctor Result where+  bimap f g (Result a b) = Result (f a) (g b)++-- | Short hand for data model DecoderMethod in DagCBOR.+type DecoderMethod item bxc = DM.DecoderMethod item bxc Okay Result++-- | Short hand for a `DecoderMethod` with a Null `Result` item.+type DecoderRoutine bxc = DecoderMethod () bxc++-- | Pattern synonym for routine bytes results.+pattern Finish :: forall bxc. bxc -> Result () bxc+pattern Finish bxc = Result () bxc++-- | Type-alias for erroring results.+type Okay = Either Error++-- | Provides errors for parsing major-type arguments.+data Error+  = -- | Used to implement the empty in `Alternative`.+    EmptyAlternative+  | -- | When the file was parsed with trailing bytes.+    TrailingBytes+  | -- | When a collection is marked indefinite.+    Indefinite+  | -- | When the undefined simple value is given.+    NotDefined+  | -- | When an invalid tag id is given.+    InvalidTag+  | -- | When -∞, ∞, or NaN is encountered, these are not supported.+    InvalidIEEE754+  | -- | For parameters marked reserved in RFC-8949.+    ReservedParam+  | -- | When a section of data expects more, but there is none, leaving gaps.+    Fragmented+  | -- | When the decoder finished unexpectedly.+    UnexpectedStop+  | -- | When some identifier is expected, but another is found.+    UnexpectedValue+  | -- | When converting CBOR IntData to smaller values fail.+    DowncastFailed+  | -- | For integers that aren't minimally encoded.+    NotMinimal+  | -- | When the major-type for a map isn't a string. IPLD forbids this.+    NotStringKey+  | -- | When two or more of the keys in a CBOR map are not unique.+    NotUniqueKey+  | -- | IPLD forbids maps with non-lexographically sorted strings.+    NotSortedMap+  | -- | Passes CID operation errors.+    CIDError CID.Error+  | -- | Marks unimplemented feature of DAG-CBOR and developement assertions.+    NotImplemented String+  deriving (Eq, Show)++-- | Fully instantiates an Error object from lazy Haskell object.+instance NFData Error where+  rnf (CIDError ciderr) = rnf ciderr+  rnf (NotImplemented devmsg) = rnf devmsg+  rnf _ = ()
+ dagcbor/IPLD/DagCBOR/Decoder/MajorTypes.hs view
@@ -0,0 +1,256 @@+-- | Module      : IPLD.DagCBOR.Decoder.MajorTypes+--   Description : Type-class of CBOR object functions+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Decoder.MajorTypes+  ( -- * Major types defining the CBOR objects+    MajorType (..),+    majorTypeSize,+    majorTypeId,++    -- * Numeric identifers for CBOR major types+    MajorId,+    idPositive,+    idNegative,+    idBytes,+    idUTF8,+    idList,+    idMap,+    idTag,+    idResource,+    idSimple,+    idFloat,+    idBool,+    idNull,+  )+where++import Data.Function (on)+import Data.Word (Word8)+import Data.XCodec.BinaryTranscoder (BinaryTranscoder)+import IPLD.DagCBOR.Decoder.Arguments+import IPLD.DagCBOR.Decoder.Errors+import MultiFormats.CID.Constants qualified as CID++-- | Represents the identifier for CBOR major-types. It is the 3-bit identifier+-- at the start of each `Argument` byte, and determines how to evaluate the+-- remaining 5-bit parameter and and `Supplemental` data that follows.+type MajorId = Word8++-- | CBOR major-id for positive integers.+idPositive :: MajorId+idPositive = 0++-- | CBOR major-id for negative integers.+idNegative :: MajorId+idNegative = 1++-- | CBOR major-id for bytestring data.+idBytes :: MajorId+idBytes = 2++-- | CBOR major-id for UTF-8 encoded strings.+idUTF8 :: MajorId+idUTF8 = 3++-- | CBOR major-id for list objects.+idList :: MajorId+idList = 4++-- | CBOR major-id for map objects.+idMap :: MajorId+idMap = 5++-- | CBOR major-id for tagged objects (which can only be CID bytestrings in+-- DAG-CBOR).+idTag :: MajorId+idTag = 6++-- | DAG-CBOR major-id for CID resources.+idResource :: MajorId+idResource = idTag++-- | CBOR major-id for simple-types: null objects, booleans, and floats.+idSimple :: MajorId+idSimple = 7++-- | CBOR major-id for floats.+idFloat :: MajorId+idFloat = idSimple++-- | CBOR major-id for booleans.+idBool :: MajorId+idBool = idSimple++-- | CBOR major-id for null objects.+idNull :: MajorId+idNull = idSimple++-- | Gives back the 3-bit identifier for each major-type.+{-# INLINE majorTypeId #-}+majorTypeId :: MajorType -> MajorId+majorTypeId majortype =+  case majortype of+    TypePositive _ -> 0+    TypeNegative _ -> 1+    TypeBytes _ -> 2+    TypeUTF8 _ -> 3+    TypeList _ -> 4+    TypeMap _ -> 5+    TypeTag _ -> 6+    TypeSimple _ -> 7++-- | Implements identitifers for the major-types from CBOR.+-- https://datatracker.ietf.org/doc/html/rfc8949#section-3.2.4+data MajorType+  = -- | Provides major-type for positive integers.+    TypePositive Ints+  | -- | Provides major-type for negative integers.+    TypeNegative Ints+  | -- | Provides major-type for byte strings.+    TypeBytes Collection+  | -- | Provides major-type for UTF-8 strings.+    TypeUTF8 Collection+  | -- | Provides major-type for array objects.+    TypeList Collection+  | -- | Provides major-type for map objects.+    TypeMap Collection+  | -- | Provides major-type for tagged data.+    TypeTag Tag+  | -- | Provides major-type for simple data.+    TypeSimple Simple+  deriving (Show)++-- | Checks if two major-type are equal, disregarding their supplemental values.+instance Eq MajorType where+  {-# INLINE (==) #-}+  (==) = (==) `on` majorTypeId++-- | Orders major-types by their 3-bit identifiers.+instance Ord MajorType where+  {-# INLINE compare #-}+  compare = compare `on` majorTypeId++-- | Parses the major-type from a byte.+instance Argument MajorType where+  {-# INLINE decodeArg #-}+  decodeArg byte =+    -- Matches each major-type number with its type identifier+    case maskMajorID byte of+      0 -> mk TypePositive+      1 -> mk TypeNegative+      2 -> mk TypeBytes+      3 -> mk TypeUTF8+      4 -> mk TypeList+      5 -> mk TypeMap+      6 -> mk TypeTag+      7 -> mk TypeSimple+      _ -> error "unreachable: exceeds 3-bit values"+    where+      -- Decodes the param from the byte and applies the constructor.+      mk constructor = constructor <$> decodeArg byte++-- | Resolves the top CBOR object's size in bytes.+{-# INLINE majorTypeSize #-}+majorTypeSize :: (BinaryTranscoder bxc) => DecoderMethod IntData bxc+majorTypeSize bytes = do+  -- Resolve the major type from the top byte+  Result arg inner <- extractByte bytes+  majortype <- decodeArg arg+  -- Determine size of the supplemental data from major type+  Result supsize rest <-+    case majortype of+      TypePositive ints -> intsSize ints inner+      TypeNegative ints -> intsSize ints inner+      TypeBytes collection -> strSize collection inner+      TypeUTF8 collection -> strSize collection inner+      TypeList collection -> listSize collection inner+      TypeMap collection -> mapSize collection inner+      TypeTag _ -> cidSize inner+      TypeSimple simple -> simpleSize simple inner+  -- Return the total from removing the argument + supplement data+  Right $ Result (supsize + 1) rest++-- | Reformats the bytesize for integer data.+{-# INLINE intsSize #-}+intsSize :: (BinaryTranscoder bxc) => Ints -> DecoderMethod IntData bxc+intsSize ints bytes = do+  let intsize = intsSizeOf ints+      supsize = fromIntegral intsize+  Result _ rest <- dropBytes supsize bytes+  Right $ Result supsize rest++-- | Gets the size of a CBOR simple type.+{-# INLINE simpleSize #-}+simpleSize :: (BinaryTranscoder bxc) => Simple -> DecoderMethod IntData bxc+simpleSize simple bytes = do+  let intsize = simpleSizeOf simple+      supsize = fromIntegral intsize+  Result _ rest <- dropBytes supsize bytes+  Right $ Result supsize rest++-- | Gets the size of Bytes/String data.+{-# INLINE strSize #-}+strSize :: (BinaryTranscoder bxc) => Collection -> DecoderMethod IntData bxc+strSize collection bytes =+  case collection of+    CollectionsIndefinite -> Left Indefinite+    CollectionsLength ints -> do+      -- Get the length of the collection+      Result strsize inner <- extractIntData ints bytes+      -- Remove the string from the bytes and return the result+      Result _ rest <- dropBytes strsize inner+      -- Add the #bytes for size to the size for the total+      let intsize = fromIntegral $ intsSizeOf ints+      Right $ Result (strsize + intsize) rest++-- | Gets the size of List data.+{-# INLINE listSize #-}+listSize :: (BinaryTranscoder bxc) => Collection -> DecoderMethod IntData bxc+listSize collection bytes =+  case collection of+    CollectionsIndefinite -> Left Indefinite+    CollectionsLength ints -> do+      -- Setup list byte length recursion+      Result elems start <- extractIntData ints bytes+      let loop !cursor !listsize !seen+            -- Once the #objects traveled reaches the count, return the total+            | seen >= elems = Right $ Result listsize cursor+            -- Otherwise, read the current list item+            | otherwise = do+                Result objsize rest <- majorTypeSize cursor+                loop rest (listsize + objsize) (seen + 1)+      -- Start the loop offset by the #bytes in the length integer+      let intsoffset = fromIntegral $ intsSizeOf ints+      loop start intsoffset 0++-- | Gets the size of Map data.+{-# INLINE mapSize #-}+mapSize :: (BinaryTranscoder bxc) => Collection -> DecoderMethod IntData bxc+mapSize collection bytes =+  case collection of+    CollectionsIndefinite -> Left Indefinite+    CollectionsLength ints -> do+      -- Setup map byte length recursion+      Result pairs start <- extractIntData ints bytes+      let loop !cursor !mapsize !seen+            -- Once the #seen reaches the #pairs, return the total+            | seen >= pairs = Right $ Result mapsize cursor+            -- Otherwise, read the current map pair+            | otherwise = do+                Result keysize onkey <- majorTypeSize cursor+                Result valsize rest <- majorTypeSize onkey+                loop rest (mapsize + keysize + valsize) (seen + 1)+      -- Start the loop offset by the #bytes in the length integer+      let intsoffset = fromIntegral $ intsSizeOf ints+      loop start intsoffset 0++-- | Gets the size of a CID within CBOR including its tag value.+{-# INLINE cidSize #-}+cidSize :: (BinaryTranscoder bxc) => DecoderMethod IntData bxc+cidSize bytes = do+  Result _ oncid <- removeOctet CID.ipldTagCBOR bytes+  Result size rest <- majorTypeSize oncid+  Right $ Result (size + 1) rest
+ dagcbor/IPLD/DagCBOR/Decoder/Objects.hs view
@@ -0,0 +1,216 @@+-- | Module      : IPLD.DagCBOR.Decoder.Objects+--   Description : Decodes CBOR objects from binary into the IPLD data model+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Decoder.Objects+  ( -- * Instances of major-type data decoded from DAG-CBOR+    Object (..),+    decodeMajorType,+    decodeSupplemental,+    decodeObject,++    -- * Recursively defines object collections for CBOR+    MapData,+    ListData,+  )+where++import Control.DeepSeq (NFData (..), force)+import Control.Parallel.Strategies (parBuffer, rdeepseq, using)+import Data.Array.IArray qualified as Array+import Data.Bifunctor (Bifunctor (first))+import Data.Text (Text)+import Data.XCodec.BinaryTranscoder (BinaryTranscoder)+import Data.XCodec.BinaryTranscoder qualified as BXC+import IPLD.DM qualified as DM+import IPLD.DagCBOR.Decoder.Arguments+import IPLD.DagCBOR.Decoder.Errors+import IPLD.DagCBOR.Decoder.MajorTypes+import IPLD.DagCBOR.Decoder.Supplemental+import MultiFormats.CID (CID)++-- | Stores the data gotten from each major-type+data Object+  = -- | Instance of a CBOR positive integer.+    ObjectPositive IntData+  | -- | Instance of a CBOR negative integer.+    ObjectNegative IntData+  | -- | Instance of a CBOR bytestring.+    ObjectBytes DM.BytesData+  | -- | Instance of a CBOR UTF-8 string.+    ObjectUTF8 Text+  | -- | Instance of a valid IPLD CBOR list object.+    ObjectList ListData+  | -- | Instance of a valid IPLD CBOR map object.+    ObjectMap MapData+  | -- | Instance of a CID following its CBOR tag.+    ObjectTag CID+  | -- | Instance of simple types (null, bool, float).+    ObjectSimple SimpleData+  deriving (Show, Eq)++-- | Resolves the supplemental data from a major type.+instance (BinaryTranscoder bxc) => Supplemental MajorType Object bxc where+  decodeSup arg =+    case arg of+      TypePositive intrule -> mk ObjectPositive intrule+      TypeNegative intrule -> mk ObjectNegative intrule+      TypeBytes bytesrule -> mk ObjectBytes bytesrule+      TypeUTF8 utf8rule -> mk ObjectUTF8 utf8rule+      TypeList listrule -> mk ObjectList listrule+      TypeMap maprule -> mk ObjectMap maprule+      TypeTag tagrule -> mk ObjectTag tagrule+      TypeSimple simplerule -> mk ObjectSimple simplerule+    where+      -- Creates the DecoderMethod that reads the object using the given rule+      {-# INLINE mk #-}+      mk constructor rule =+        pure $ \bytes -> do+          sup <- decodeSup rule+          Result supdata rest <- sup bytes+          pure $ Result (constructor supdata) rest++-- | Translates the CBOR MajorObject into the IPLD data model.+{-# INLINE objectNode #-}+objectNode :: Object -> DM.Node+objectNode obj =+  -- Strictly evaluate the entire converted object+  force convObject+  where+    -- Points to the conversion of the object into a DM.Node+    {-# NOINLINE convObject #-}+    convObject =+      case obj of+        ObjectSimple NullData -> DM.NullKind+        ObjectSimple (BoolData bool) -> DM.BoolKind bool+        ObjectSimple (FloatData float) -> DM.FloatKind float+        ObjectBytes bytes -> DM.BytesKind bytes+        ObjectUTF8 text -> DM.StringKind text+        ObjectTag cid -> DM.ResourceKind cid+        ObjectList (ListData listdata) -> DM.ListKind listdata+        ObjectMap (MapData mapdata) -> DM.MapKind mapdata+        -- Convert the raw intdata into Haskell Integer (including zero)+        ObjectPositive intdata -> DM.IntKind (fromIntegral intdata)+        -- Adjust negative values for extra digit from not having zero+        ObjectNegative intdata -> DM.IntKind (-(fromIntegral intdata) - 1)++-- | Decodes the CBOR major-type for the first transcoder byte and keeps it in+-- place.+decodeMajorType :: (BinaryTranscoder bxc) => DecoderMethod MajorType bxc+decodeMajorType bytes = do+  Result top _ <- extractByte bytes+  mt <- decodeArg top+  Right $ Result mt bytes++-- | Decodes a major-type's supplemental data from the CBOR object binary and+-- removes it.+decodeSupplemental ::+  (BinaryTranscoder bxc) =>+  MajorType ->+  DecoderMethod Object bxc+decodeSupplemental mt bytes = do+  sup <- decodeSup mt+  sup bytes++-- | Decodes the MajorType and it's Supplemental data from the transcoder and+-- removes both.+decodeObject :: (BinaryTranscoder bxc) => DecoderMethod DM.Node bxc+decodeObject bytes = do+  Result mt _ <- decodeMajorType bytes+  Result _ inner <- extractByte bytes+  first objectNode <$> decodeSupplemental mt inner++-- | Decodes list/map subobjects in parallel using the given decoder function.+decodeSubObjects ::+  (Monoid x, NFData y) =>+  IntData ->+  Int ->+  (x -> Okay y) ->+  [x] ->+  Okay [y]+decodeSubObjects size count decoder bxcs+  -- Run the subdecoders in parallel, and join the objects in sequence on+  -- success, and fully evaluates the subobject w/ deepseq.+  | mtenabled = sequence (mapdecoder `using` parBuffer numsparks rdeepseq)+  -- Otherwise, use single-threading.+  | otherwise =  sequence mapdecoder+  where+    -- Minimum #items and #bytes to qualify for requesting spark threads+    mtenabled = count > 1 && (count > minsparks || size > 4096)+    -- Sets the #sparks, which becomes an enqueued thread to run or become GC'd+    numsparks = max minsparks (min maxsparks count)+    -- Maps the decoder onto the list of binary CBOR objects+    mapdecoder = map decoder bxcs+    -- Maximum #sparks to request from the RTS+    maxsparks = 128+    -- Minimum #sparks to request from the RTS+    minsparks = 16++-- | Provides ListData from DM for DAG-CBOR list object.+newtype ListData = ListData (DM.ListData DM.Node) deriving (Show, Eq)++-- | Implements reading list objects from CBOR.+instance (BinaryTranscoder bxc) => Supplemental Collection ListData bxc where+  decodeSup arg = do+    case arg of+      CollectionsIndefinite -> Left Indefinite+      CollectionsLength ints ->+        Right $ \bytes -> do+          -- Read the list of binary CBOR objects and decode them+          sup <- decodeSup arg :: Okay (DecoderMethod (ListObj bxc) bxc)+          Result (size, chunks) following <- sup bytes+          -- Read the #elements in the list from the top of the bytes+          Result elems _ <- extractIntData ints bytes+          ielems <- downcastIntData elems+          -- Decode the subobjects of the list+          objs <- decodeSubObjects size ielems decodeElem chunks+          let listarray = Array.listArray (0, ielems - 1) objs+          Right $ Result (ListData listarray) following+    where+      -- Decodes single CBOR list element from binary+      {-# NOINLINE decodeElem #-}+      decodeElem bin = do+        Result obj after <- decodeObject bin+        if not (BXC.null after)+          then Left Fragmented+          else return obj++-- | Provides ListData from DM for DAG-CBOR list object.+newtype MapData = MapData (DM.MapData DM.Node DM.Node) deriving (Show, Eq)++-- | Implements reading map objects from CBOR.+instance (BinaryTranscoder bxc) => Supplemental Collection MapData bxc where+  decodeSup arg = do+    case arg of+      CollectionsIndefinite -> Left Indefinite+      CollectionsLength ints ->+        Right $ \bytes -> do+          -- Read the map of binary CBOR objects pairs and decode them+          sup <- decodeSup arg :: Okay (DecoderMethod (MapObj bxc) bxc)+          Result (size, chunks) following <- sup bytes+          -- Read the #elements in the list from the top of the bytes+          Result pairs _ <- extractIntData ints bytes+          ipairs <- downcastIntData pairs+          -- Decode the subobjects of the map+          objs <- decodeSubObjects size ipairs decodePair chunks+          let maparray = Array.listArray (0, ipairs - 1) objs+          Right $ Result (MapData maparray) following+    where+      -- Decodes single CBOR map pair from binary tuple+      {-# NOINLINE decodePair #-}+      decodePair (bin1, bin2) = do+        -- Read the key and value binary objects+        Result key afterkey <- decodeObject bin1+        Result val afterval <- decodeObject bin2+        -- Verify parsing the map succeeded+        case (key, val) of+          ypair+            | not (BXC.null afterkey && BXC.null afterval) -> Left Fragmented+            | not (isKeyValidDAGCBOR key) -> Left NotStringKey+            | otherwise -> Right ypair+      -- Gives true if the key object for the map is a string type+      {-# INLINE isKeyValidDAGCBOR #-}+      isKeyValidDAGCBOR (DM.StringKind _) = True+      isKeyValidDAGCBOR _OtherKinds = False
+ dagcbor/IPLD/DagCBOR/Decoder/Supplemental.hs view
@@ -0,0 +1,284 @@+-- | Module      : IPLD.DagCBOR.Decoder.Supplemental+--   Description : Parsing additional data from argument types.+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Decoder.Supplemental+  ( -- * Type-class for implementing Supplements for Arguments.+    Supplemental (decodeSup),++    -- * Implements CBOR simple values (Bools, Nulls, FloatData)+    SimpleData (..),++    -- * Types for working with CBOR binary objects+    ListObj,+    MapObj,++    -- * DecoderMethods for supplementals+    supplementIntData,+  )+where++import Data.Bifunctor (Bifunctor (bimap, first))+import Data.Bits ((.<<.), (.|.))+import Data.ByteString qualified as LBS+import Data.ByteString.Builder qualified as Builder+import Data.Text (Text)+import Data.Text.Encoding qualified as Text+import Data.XCodec.BinaryTranscoder (BinaryTranscoder)+import Data.XCodec.BinaryTranscoder qualified as BXC+import IPLD.DM qualified as DM+import IPLD.DagCBOR.Decoder.Arguments+import IPLD.DagCBOR.Decoder.Errors+import IPLD.DagCBOR.Decoder.MajorTypes+import MultiFormats.CID (CID)+import MultiFormats.CID.Constants qualified as CID+import MultiFormats.CID.Extractor qualified as CID+import Unsafe.Coerce (unsafeCoerce)++-- | Defines arguments which have additional data after the parameter.+class (Argument a, BinaryTranscoder b) => Supplemental a t b where+  -- | Provides function for reading argument data from argument type.+  decodeSup :: a -> Okay (DecoderMethod t b)++-- | Gives back the bytes converted into `a` when minimally encoded.+supplementIntData :: (BinaryTranscoder bxc) => Int -> DecoderMethod IntData bxc+supplementIntData sizeof bytes = do+  -- Load the #bytes for the integer+  Result intdata rest <- extractBytes sizeof bytes+  -- Build the data from big-endian encoded CBOR+  let value = fromIntegral $ BXC.unpackValueBE intdata+      result = Result value rest+  -- Match the size with its minimal encoding check+  case sizeof of+    1 -- Check 8-bit encodings+      | not (minimal8 value) -> Left NotMinimal+      | otherwise -> Right result+    2 -- Check 16-bit encodings+      | not (minimal16 value) -> Left NotMinimal+      | otherwise -> Right result+    4 -- Check 32-bit encodings+      | not (minimal32 value) -> Left NotMinimal+      | otherwise -> Right result+    8 -- Check 64-bit minimal encoding+      | not (minimal64 value) -> Left NotMinimal+      | otherwise -> Right result+    _ -> error "supplementIntData: sizeof invariant failed"+  where+    -- Valid minimal-encoding ranges for different byte-sized integers+    minimal8 r = 0 <= r && r <= 0xFF+    minimal16 r = 0xFF < r && r <= 0xFFFF+    minimal32 r = 0xFFFF < r && r <= 0xFFFFFFFF+    minimal64 r = 0xFFFFFFFF < r && r <= 0xFFFFFFFFFFFFFFFF++-- | Implements reading a Number after an Ints argument. All numbers get stored+-- in a 64-bit integer for performance.+instance (BinaryTranscoder bxc) => Supplemental Ints IntData bxc where+  decodeSup arg =+    case arg of+      Ints5Bits value -> Right $ paramIntData value+      Ints8Bits -> Right $ supplementIntData 1+      Ints16Bits -> Right $ supplementIntData 2+      Ints32Bits -> Right $ supplementIntData 4+      Ints64Bits -> Right $ supplementIntData 8+    where+      -- Creates a Result from a 5-bit int parameter.+      paramIntData value bytes =+        Right $ Result (fromIntegral value :: IntData) bytes++-- | Implements reading a Supplemental collection of binary transcoder data.+instance (BinaryTranscoder b) => Supplemental Collection b b where+  decodeSup arg =+    case arg of+      CollectionsIndefinite -> Left Indefinite+      CollectionsLength ints ->+        Right $ \bytes -> do+          -- Get the function for reading the int+          intdata <- decodeSup ints :: Okay (DecoderMethod IntData b)+          -- Read the #bytes from the IntData+          Result count rest <- intdata bytes+          extractBytes (fromIntegral count) rest++-- | Implements reading a Supplemental CBOR bytestring data.+instance (BinaryTranscoder b) => Supplemental Collection DM.BytesData b where+  decodeSup arg =+    Right $ \bytes -> do+      -- Read the bytes from the transcoder data+      readbytes <- decodeSup arg :: Okay (DecoderMethod b b)+      Result bytesdata rest <- readbytes bytes+      -- Serialize the binary value into Builder+      let builder = BXC.unpackSerial bytesdata+          len = BXC.totalOctets bytesdata+      Right $ Result (DM.BytesData builder len) rest++-- | Implements reading a Supplemental collection of UTF-8 text.+instance (BinaryTranscoder bxc) => Supplemental Collection Text bxc where+  decodeSup arg =+    Right $ \bytes -> do+      -- Get the method for reading ByteStrings+      readbytes <- decodeSup arg :: Okay (DecoderMethod DM.BytesData bxc)+      -- Read the decoder result+      Result bytesdata rest <- readbytes bytes+      -- Decode the result+      Right $ Result (decodeUtf8 bytesdata) rest+    where+      -- Instansiates the Builder into a strict ByteString for Text.decodeUtf8+      decodeUtf8 (DM.BytesData builder _) =+        Text.decodeUtf8 $ LBS.toStrict (Builder.toLazyByteString builder)++-- | Iterates some monadic action `f` on the pure `a` value at most `n` times.+iterateTakeM :: (Monad m) => Int -> (a -> m a) -> a -> m [a]+iterateTakeM n f = sequence . take n . drop 1 . iterate (f =<<) . pure++-- | Stores length information for a parsed CBOR object.+data Obj bxc = Obj IntData bxc++-- | Removes the CBOR object from the bytes.+nextObj :: (BinaryTranscoder bxc) => bxc -> Okay (Obj bxc, bxc)+nextObj bytes = do+  Result size _ <- majorTypeSize bytes+  isize <- downcastIntData size+  let (hi, lo) = BXC.splitOffset isize bytes+  Right (Obj size hi, lo)++-- | Folds the resulting list of CBOR objects from the iteration list.+foldObjs :: bxc -> [(Obj a, bxc)] -> Result (ListObj a) bxc+foldObjs start = foldr buildResult (Result (0, []) start)+  where+    -- Returns true if the result is the initial accumulator to foldr+    isInitial (Result (size, _) _) = size == 0+    -- Builds the Result from the (Obj a, bxc) list fold.+    buildResult (Obj len bxc, afterobjs) res+      -- If this is the first item, this is the bytestring with all the objects+      -- removed, so update the pointer in the second item in Result.+      | isInitial res = bimap (bimap (len +) (bxc :)) (const afterobjs) res+      -- Otherwise, only update the length and list of BXCs+      | otherwise = first (bimap (len +) (bxc :)) res++-- | Stores a list of CBOR binary objects + length.+type ListObj bxc = (IntData, [bxc])++-- | Chunks DAG-CBOR Lists into list of encoded binary CBOR objects.+instance (BinaryTranscoder b) => Supplemental Collection (ListObj b) b where+  decodeSup arg =+    case arg of+      CollectionsIndefinite -> Left Indefinite+      CollectionsLength ints ->+        Right $ \bytes -> do+          -- Read the list length data+          Result elemcount start <- extractIntData ints bytes+          ielems <- downcastIntData elemcount+          -- Iterate through CBOR list members for the #elements+          foldObjs start <$> iterateTakeM ielems nextElem (Obj 0 mempty, start)+    where+      -- Extracts the next element from the list with iterate splitAt+      nextElem (Obj total _, bytes) = do+        (Obj len obj, rest) <- nextObj bytes+        return (Obj (len + total) obj, rest)++-- | Stores key-value CBOR binary object pairs + length.+type MapObj bxc = ListObj (bxc, bxc)++-- | Chunks DAG-CBOR Map into list of encoded binary CBOR key-value pairs.+instance (BinaryTranscoder b) => Supplemental Collection (MapObj b) b where+  decodeSup arg =+    case arg of+      CollectionsIndefinite -> Left Indefinite+      CollectionsLength ints ->+        Right $ \bytes -> do+          -- Read the number of pairs for the map data+          Result len start <- extractIntData ints bytes+          ipairs <- downcastIntData len+          -- Iterate through CBOR list members for the #pairs+          foldObjs start <$> iterateTakeM ipairs nextPair (mkIterObj start)+    where+      -- Initializes the iterator for collecting key value pairs+      mkIterObj start = (Obj 0 (mempty, mempty), start)+      -- Extracts the next pair from the map with iterate splitAt+      nextPair (Obj total _, bytes) = do+        (Obj l1 key, onval) <- nextObj bytes+        (Obj l2 val, rest) <- nextObj onval+        return (Obj (total + l1 + l2) (key, val), rest)++-- | Implements reading a Supplemental CID from the matching tag, see:+-- https://github.com/ipld/cid-cbor/+-- https://ipld.io/specs/codecs/dag-cbor/spec/#links+instance (BinaryTranscoder bxc) => Supplemental Tag CID bxc where+  decodeSup Tag =+    Right $ \bytes -> do+      -- Remove the CID tag identifier+      Result _ inner1 <- removeOctet CID.ipldTagCBOR bytes+      -- Decode the arg from the first byte and get the decoder rule+      Result arg inner2 <- extractByte inner1+      -- Get the rule for reading in the CID data bytestring.+      bytesrule <- decodeArg arg :: Okay Collection+      bytesread <- decodeSup bytesrule :: Okay (DecoderMethod bxc bxc)+      -- Remove and verify the multibase 0 prefix and extract the CID result.+      Result cidtop final <- bytesread inner2+      Result _ ciddata <- removeOctet 0 cidtop+      case CID.extractor ciddata of+        Left err -> Left $ CIDError err+        Right (cid, fragmented)+          | BXC.totalOctets fragmented > 0 -> Left Fragmented+          | otherwise -> Right $ Result cid final++-- | Reads simple values. For floating points, it does:+-- 1. Takes n number bytes from the ByteString+-- 2. Validates bytes taken to matches the FloatData type size.+-- 3. Copy those bytes to a corresponding sized Word type+-- 4. Check if they are a valid IPLD Float (Not -∞, ∞, or NaN)+-- 5. Updates the bytes to remove the floating point bytes.+-- Otherwise, it packages the simple value and leaves the bytes unmodified.+instance (BinaryTranscoder bxc) => Supplemental Simple SimpleData bxc where+  decodeSup arg =+    case arg of+      -- Floating point values+      FloatHalf -> Right $ float DM.HalfPrecision 2+      FloatSingle -> Right $ float DM.SinglePrecision 4+      FloatDouble -> Right $ float DM.DoublePrecision 8+      -- Simple supported values+      SimpleNull -> Right $ simple NullData+      SimpleBool bool -> Right $ simple (BoolData bool)+      -- Simple unsupported values+      SimpleUndefined -> Left NotDefined+      StopCollection -> Left Indefinite+    where+      -- Returns the simple value without changing the bytes.+      simple value bytes = Right $ Result value bytes+      -- Copys and constructs a floating point number from n bytes.+      -- TODO: I want to be able to relax the validation with an ifdef+      float mk n bytes = do+        -- Take the first n bytes from the ByteString+        Result taken rest <- extractBytes n bytes+        -- Convert the value from network order to CPU's format.+        value <- copyBEtoCPU taken+        -- Validate its IEEE754 representation. Use `unsafeCoerce` to change+        -- the bit interpretation from Word to Float/Double.+        case (unsafeCoerce value, unsafeCoerce value) of+          (as32, as64)+            -- NOTE: 16-bit floating point numbers aren't part of Haskell.+            | n == 2 -> Left $ NotImplemented "decodeSup: 16-bit float"+            -- Validate 32-bit single floats+            | n == 4 && invalidSingle as32 -> Left InvalidIEEE754+            -- Validate 64-bit double floats+            | n == 8 && invalidDouble as64 -> Left InvalidIEEE754+            -- Success: return the constructed value+            | otherwise -> Right $ Result (FloatData $ mk value) rest+        where+          -- Copys from BE format to CPU format+          -- WARN: only supports little-endian CPUs.+          -- TODO: there should be a way to convert endianness in XCodec+          copyBEtoCPU = copyW8s 0 0 . BXC.unpackOctets . BXC.swapOrder+          -- Bitwise-or each byte from the number into the Word type. Fail when+          -- iteration exceeds bytes or doesn't read the correct #bytes.+          copyW8s !i !acc (!w8 : ws)+            | i < n = copyW8s (i + 1) (acc .<<. 8 .|. fromIntegral w8) ws+            | otherwise = Left UnexpectedStop+          copyW8s !i !acc []+            | i == n = Right acc+            | otherwise = Left UnexpectedStop+          -- True if invalid 32-bit value+          invalidSingle (single :: Float) = isNaN single || isInfinite single+          -- True if invalid 64-bit value+          invalidDouble (double :: Double) = isNaN double || isInfinite double
+ dagcbor/IPLD/DagCBOR/Encoder.hs view
@@ -0,0 +1,222 @@+-- | Module      : IPLD.DagCBOR.Encoder+--   Description : Implements DM.Encoder for DAG-CBOR+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder+  ( -- * Encoder output+    DagCBOR,++    -- * Implements `DM.Encoder` class+    Encoder,++    -- * List CBOR encoding+    encodeListKind,+    majorList,++    -- * Key-value pair CBOR encoding+    encodeMapKind,+    majorMap,++    -- * Encoder utilities+    toByteString,+    toDigits,+    toHex,++    -- * Implementing methods+    module IPLD.DM.Encoder,+  )+where++import Control.Applicative (Alternative (..))+import Data.BaseSystems.Lazy (BaseSystem, base16lower)+import Data.BaseSystems.Lazy qualified as Bases+import Data.ByteString.Builder (Builder)+import Data.ByteString.Builder qualified as BSB+import Data.ByteString.Lazy (LazyByteString)+import Data.Text (Text)+import IPLD.DM (Kind (..), ListData, MapData)+import IPLD.DM.Encoder hiding (Encoder)+import IPLD.DM.Encoder qualified as DM+import IPLD.DagCBOR.Encoder.Arguments+import IPLD.DagCBOR.Encoder.CID+import IPLD.DagCBOR.Encoder.Errors+import IPLD.DagCBOR.Encoder.Floats+import IPLD.DagCBOR.Encoder.Ints+import IPLD.DagCBOR.Encoder.SimpleTypes+import IPLD.DagCBOR.Encoder.Strings++-- | Method results from `DM.Encoder`.+type DagCBOR = Encoder Builder++toByteString :: DagCBOR -> Okay LazyByteString+toByteString dagcbor =+  case dagcbor of+    EncoderError err -> Left err+    EncoderValue result -> Right (BSB.toLazyByteString result)++-- | Encodes DagCBOR to a digit string in the provided `BaseSystem`.+toDigits :: (BaseSystem system) => system -> DagCBOR -> Okay Text+toDigits base dagcbor =+  case conv <$> dagcbor of+    EncoderError err -> Left err+    EncoderValue result -> Right result+  where+    conv = Bases.encoder base . BSB.toLazyByteString++-- | Encodes DagCBOR to hexadecimal string.+toHex :: DagCBOR -> Okay Text+toHex = toDigits base16lower++-- | Provides a Encoder implementation for DAG-CBOR.+data Encoder encoded+  = -- | An encoded value result.+    EncoderValue encoded+  | -- | For the `empty` object in the `Alternative` class.+    EncoderError Error+  deriving (Show, Eq)++-- | Pattern synonym for the `Alternative` `empty` object.+pattern EncoderEmpty :: forall encoded. Encoder encoded+pattern EncoderEmpty = EncoderError EmptyAlternative++-- | Converts `Okay` functor into `Encoder` functor.+{-# INLINE okay #-}+okay :: Okay t -> Encoder t+okay = either EncoderError EncoderValue++-- | Encodes the given IPLD node into DAG-CBOR binary format.+-- https://ipld.io/specs/codecs/dag-cbor/spec/+instance DM.Encoder Encoder where+  intKind (IntKind int) = okay (encodeIntKind int)+  intKind _ = empty++  bytesKind (BytesKind bytes) = okay (encodeBytesKind bytes)+  bytesKind _ = empty++  stringKind (StringKind string) = okay (encodeStringKind string)+  stringKind _ = empty++  listKind (ListKind list) = encodeListKind list+  listKind _ = empty++  mapKind (MapKind dict) = encodeMapKind dict+  mapKind _ = empty++  resourceKind (ResourceKind cid) = okay (encodeResourceKind cid)+  resourceKind _ = empty++  floatKind (FloatKind float) = pure (encodeFloatKind float)+  floatKind _ = empty++  boolKind (BoolKind bool) = pure (encodeBoolKind bool)+  boolKind _ = empty++  nullKind NullKind = pure encodeNullKind+  nullKind _ = empty++-- | Implements function injection (fmap) into some encoder process.+instance Functor Encoder where+  -- Applies `f` to the encoded value if it exists+  {-# INLINE fmap #-}+  f `fmap` EncoderValue value = pure (f value)+  _ `fmap` EncoderError err = EncoderError err++-- | Implements value injection in encoder context (pure) and applying some+-- process derived from encoding (<*>).+instance Applicative Encoder where+  -- Wraps a Haskell type into an EncoderValue.+  {-# INLINE pure #-}+  pure = EncoderValue++  -- Resolve an encoded function and encoded value and apply the function to the+  -- value.+  {-# INLINE (<*>) #-}+  -- Extract the function from its context and apply it in value's context+  EncoderValue func <*> value = func <$> value+  EncoderError err <*> _ = EncoderError err++-- | Implements chaining encoders together in steps using binds (>>=).+instance Monad Encoder where+  {-# INLINE (>>=) #-}+  (EncoderValue value) >>= next = next value+  (EncoderError err) >>= _ = EncoderError err++-- | Defines alternative code paths (<|>) and default failure element (empty).+instance Alternative Encoder where+  -- For inputs that don't have the expected node type.+  empty = EncoderEmpty++  -- Tries the second code branch if the first fails+  {-# INLINE (<|>) #-}+  -- If the first branch is Just, return it+  EncoderValue ok1 <|> _ = pure ok1+  -- If the first branch is empty, return the second branch+  EncoderEmpty <|> EncoderValue ok2 = pure ok2+  -- If both branches are Nothing, return empty+  EncoderEmpty <|> EncoderEmpty = empty+  -- Otherwise, report the error that happened.+  _ <|> EncoderError err = EncoderError err+  EncoderError err <|> _ = EncoderError err++-- | Implements joining the results of two Encoders via semigroup adding (<>),+-- for Builders this would be concatinating the two bytestring contents.+instance (Semigroup s) => Semigroup (Encoder s) where+  -- This should only return an empty value when both the results are empty.+  {-# INLINE (<>) #-}+  -- Concat the values within DagCBOR context+  EncoderValue v1 <> EncoderValue v2 = pure (v1 <> v2)+  EncoderValue v1 <> EncoderEmpty = pure v1+  EncoderEmpty <> EncoderValue v2 = pure v2+  EncoderEmpty <> EncoderEmpty = empty+  -- Otherwise, report the error that happened+  _ <> EncoderError err = EncoderError err+  EncoderError err <> _ = EncoderError err++-- | Provides zero element `mempty` for encoder concatination. Applying (<>) to+-- this value will result an identity function.+instance (Semigroup s) => Monoid (Encoder s) where+  mempty = empty++-- | Major id for CBOR lists.+majorList :: MajorArg+majorList = 4++-- | Recursively encodes the list of CBOR objects.+{-# INLINE encodeListKind #-}+encodeListKind :: ListData Kind -> Encoder Builder+encodeListKind listdata =+  let -- Get the #elements in the list+      len = length listdata+      -- Encode the argument with the with the list's length+      arg = encodeIntArgument majorList len+      -- Initializes a Builder in the Encoder Monoid+      initobj = pure mempty+      -- Recursively encode the elements of the arguments+      objs = foldr (\item acc -> DM.encoder item <> acc) initobj listdata+   in -- Concat arg as DAG-CBOR data and the CBOR list objects+      okay arg <> objs++-- | Major id for CBOR maps.+majorMap :: MajorArg+majorMap = 5++-- | Recursively encodes the key-value pairs of CBOR objects.+{-# INLINE encodeMapKind #-}+encodeMapKind :: MapData Kind Kind -> Encoder Builder+encodeMapKind mapdata =+  let -- Get the #keys in the map+      len = length mapdata+      -- Encode the argument with only the #keys (#values is implied)+      arg = encodeIntArgument majorMap len+      -- Initializes a Builder in the Encoder Monoid+      initobj = pure mempty+      -- Recursively encode each key/value pair in the map.+      objs = foldr (\pair acc -> encodeMapPair pair <> acc) initobj mapdata+   in -- Concat the arg as DAG-CBOR and concat the encoded map.+      okay arg <<>> objs+  where+    -- Encodes a single map pair from tuple into Builder.+    {-# INLINE encodeMapPair #-}+    encodeMapPair (key, val) = DM.encoder key <> DM.encoder val
+ dagcbor/IPLD/DagCBOR/Encoder/Arguments.hs view
@@ -0,0 +1,34 @@+-- | Module      : IPLD.DagCBOR.Encoder.Arguments+--   Description : Functions for encoding CBOR major-type information.+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder.Arguments+  ( -- * Encodes CBOR type argument configuration into a byte.+    MajorArg,+    ParamArg,+    encodeArgument,+  )+where++import Data.Bits ((.<<.), (.|.))+import Data.ByteString.Builder (Builder)+import Data.ByteString.Builder qualified as BSB+import Data.Word (Word8)++-- | 3-bit identifier for idenitifying the major data types of CBOR.+type MajorArg = Word8++-- | 5-bit identifier that configures the data-type parameters for CBOR objects.+type ParamArg = Word8++-- | Encodes and validates the major type id and the parameter data.+{-# INLINE encodeArgument #-}+encodeArgument :: MajorArg -> ParamArg -> Builder+encodeArgument major param+  | major > 0b111 = error "major overflow"+  | param > 0b11111 = error "param overflow"+  | otherwise = BSB.word8 $ majorbits .|. param+  where+    majorbits = fromIntegral (fromEnum major .<<. 5)
+ dagcbor/IPLD/DagCBOR/Encoder/CID.hs view
@@ -0,0 +1,44 @@+-- | Module      : IPLD.DagCBOR.Encoder.CID+--   Description : Implements encoding CIDs within DAG-CBOR+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder.CID+  ( -- * DAG-CBOR CID encoder implementation+    encodeResourceKind,++    -- * CBOR tag major id+    majorTag,+  )+where++import Data.ByteString.Builder (Builder)+import Data.ByteString.Builder qualified as Builder+import IPLD.DagCBOR.Encoder.Arguments+import IPLD.DagCBOR.Encoder.Errors+import IPLD.DagCBOR.Encoder.Ints+import IPLD.DagCBOR.Encoder.Strings+import MultiFormats.CID (CID)+import MultiFormats.CID qualified as CID+import MultiFormats.CID.Constants qualified as CID+import MultiFormats.CID.Serializer qualified as CID++-- | Major id for tagged CBOR objects.+majorTag :: MajorArg+majorTag = 6++-- | Implements encoding CID data into DAG-CBOR.+encodeResourceKind :: CID -> Okay Builder+encodeResourceKind resource = cbortag <<>> bytesobj <<>> ciddata+  where+    -- Encodes the CBOR tag identifying IPLD CIDs+    cbortag = encodeIntArgument majorTag CID.ipldTagCBOR+    -- Encodes the #bytes + the single byte for the identity multibase+    bytesobj = encodeIntArgument majorBytes (CID.cidSizeOf resource + 1)+    -- Encodes the CID within its own Okay functor+    cidserial = CID.serializer resource+    -- Encodes required the identity multibase byte+    cidmultibase = Builder.word8 0+    -- Encodes the CID or wraps the given error+    ciddata = either (Left . CIDError) (Right . (cidmultibase <>)) cidserial
+ dagcbor/IPLD/DagCBOR/Encoder/Errors.hs view
@@ -0,0 +1,27 @@+-- | Module      : IPLD.DagCBOR.Encoder.Errors+--   Description : Errors for DAG-CBOR encoding+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder.Errors (Okay, Error (..), (<<>>)) where++import MultiFormats.CID.Errors qualified as CID++-- | Defines the DAG-CBOR encoder errors.+data Error+  = -- | For implementing `Alternative` class.+    EmptyAlternative+  | -- | When the provided DM.IntKind exceeds 64-bits+    OverflowIntKind+  | -- | When CID encoding fails.+    CIDError CID.Error+  deriving (Show, Eq)++-- | Functor for encoder error results.+type Okay t = Either Error t++-- | Concatenates two monoids `m` within the same context `a`.+{-# INLINE (<<>>) #-}+(<<>>) :: (Applicative a, Monoid m) => a m -> a m -> a m+(<<>>) = liftA2 (<>)
+ dagcbor/IPLD/DagCBOR/Encoder/Floats.hs view
@@ -0,0 +1,55 @@+-- | Module      : IPLD.DagCBOR.Encoder.Floats+--   Description : Implements encoders for float simple types in DAG-CBOR+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder.Floats+  ( -- * CBOR floating point encoders+    encodeFloatKind,++    -- * Constants for working with CBOR floats+    paramDouble,+    paramSingle,+    paramHalf,+  )+where++import Data.ByteString.Builder (Builder)+import Data.ByteString.Builder qualified as BSB+import IPLD.DM qualified as DM+import IPLD.DagCBOR.Encoder.Arguments+import IPLD.DagCBOR.Encoder.SimpleTypes (majorSimple)++-- | Parameter for encoding 64-bit IEEE754 double precision data.+paramDouble :: ParamArg+paramDouble = 27++-- | Parameter for encoding 32-bit IEEE754 single precision data.+paramSingle :: ParamArg+paramSingle = 26++-- | Parameter for encoding 16-bit IEEE754 half precision data.+paramHalf :: ParamArg+paramHalf = 25++-- TODO:+-- encodeFloat :: forall bxc. (BinaryTranscoder bxc) => Float -> bxc+-- encodeDouble :: forall bxc. (BinaryTranscoder bxc) => Double -> bxc+-- NOTE: the encoder does no validation currently.++-- | Encodes a float from IPLD floating data.+{-# INLINE encodeFloatKind #-}+encodeFloatKind :: DM.FloatData -> Builder+encodeFloatKind (DM.DoublePrecision double) =+  -- Encodes 64-bit IEEE754 to CBOR simple doubles+  let arg64 = encodeArgument majorSimple paramDouble+   in arg64 <> BSB.word64BE double+encodeFloatKind (DM.SinglePrecision single) =+  -- Encodes 32-bit IEEE754 to CBOR simple floats+  let arg32 = encodeArgument majorSimple paramSingle+   in arg32 <> BSB.word32BE single+encodeFloatKind (DM.HalfPrecision half) =+  -- Encodes 16-bit IEEE754 to CBOR simple halfs+  let arg16 = encodeArgument majorSimple paramHalf+   in arg16 <> BSB.word16BE half
+ dagcbor/IPLD/DagCBOR/Encoder/Ints.hs view
@@ -0,0 +1,132 @@+-- | Module      : IPLD.DagCBOR.Encoder.Ints+--   Description : Implements encoder for DAG-CBOR integer data+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder.Ints+  ( -- * CBOR encoder for IPLD Integer kind+    encodeIntKind,++    -- * Generates an argument with an attached CBOR value+    encodeIntArgument,++    -- * CBOR integer constants+    majorIntPositive,+    majorIntNegative,+    majorIntSign,+    paramInt8,+    paramInt16,+    paramInt32,+    paramInt64,+  )+where++import Data.ByteString.Builder (Builder)+import Data.ByteString.Builder qualified as BSB+import Data.Word (Word16, Word32, Word64, Word8)+import IPLD.DagCBOR.Encoder.Arguments+import IPLD.DagCBOR.Encoder.Errors++-- | Major id for positive integer values in CBOR.+majorIntPositive :: MajorArg+majorIntPositive = 0++-- | Major id for negative integer values in CBOR.+majorIntNegative :: MajorArg+majorIntNegative = 1++-- | Provides the `MajorArg` associated with a number's sign (+: 0/-: 1).+{-# INLINE majorIntSign #-}+majorIntSign :: (Integral a, Integral b) => a -> b+majorIntSign value = fromIntegral $ fromEnum (value < 0)++-- | Parameter value for 1-byte CBOR integer encodings.+paramInt8 :: ParamArg+paramInt8 = 24++-- | Parameter value for 2-byte CBOR integer encodings.+paramInt16 :: ParamArg+paramInt16 = 25++-- | Parameter value for 4-byte CBOR integer encodings.+paramInt32 :: ParamArg+paramInt32 = 26++-- | Parameter value for 8-byte CBOR integer encodings.+paramInt64 :: ParamArg+paramInt64 = 27++-- | Encodes a CBOR argument with an integer value attached with for the+-- provided major type.+{-# INLINE encodeIntArgument #-}+encodeIntArgument :: forall a. (Integral a) => MajorArg -> a -> Okay Builder+encodeIntArgument major value+  -- Encode 5-bit values+  | 0 <= normal && normal <= max5 = Right $ encode5bit major value+  -- Encode 8-bit values+  | max5 < normal && normal <= max8 = Right $ encode8bit major value+  -- Encode 16-bit values+  | max8 < normal && normal <= max16 = Right $ encode16bit major value+  -- Encode 32-bit values+  | max16 < normal && normal <= max32 = Right $ encode32bit major value+  -- Encode 64-bit values+  | max32 < normal && normal <= max64 = Right $ encode64bit major value+  -- Otherwise, the Integer is too large for CBOR+  | otherwise = Left OverflowIntKind+  where+    -- Normalizes the value for positive/negative encodings+    normal = normalize value :: a+    -- Upper bounds for supported bitwidths+    max64 = fromIntegral (maxBound :: Word64)+    max32 = fromIntegral (maxBound :: Word32)+    max16 = fromIntegral (maxBound :: Word16)+    max8 = fromIntegral (maxBound :: Word8)+    max5 = 23 -- values > 23 are parameter reserved++-- | Encodes `Integral` values to a CBOR bytestring builder.+{-# INLINE encodeIntKind #-}+encodeIntKind :: forall a. (Integral a) => a -> Okay Builder+encodeIntKind value = encodeIntArgument (majorIntSign value) value++-- | Normalizes the value in `a` and fits the bits to type `b`.+{-# INLINE normalize #-}+normalize :: (Integral a, Integral b) => a -> b+normalize v = fromIntegral $ abs v - majorIntSign v++-- | Encodes a 5-bit CBOR value into argument parmeter data.+{-# INLINE encode5bit #-}+encode5bit :: (Integral a) => MajorArg -> a -> Builder+encode5bit major value = encodeArgument major (normalize value)++-- | Encodes a 8-bit CBOR value.+{-# INLINE encode8bit #-}+encode8bit :: (Integral a) => MajorArg -> a -> Builder+encode8bit major value =+  encodeArgument major paramInt8 <> BSB.word8 normal+  where+    normal = normalize value++-- | Encodes a 16-bit CBOR value.+{-# INLINE encode16bit #-}+encode16bit :: (Integral a) => MajorArg -> a -> Builder+encode16bit major value =+  encodeArgument major paramInt16 <> BSB.word16BE normal+  where+    normal = normalize value++-- | Encodes a 32-bit CBOR value.+{-# INLINE encode32bit #-}+encode32bit :: (Integral a) => MajorArg -> a -> Builder+encode32bit major value =+  encodeArgument major paramInt32 <> BSB.word32BE normal+  where+    normal = normalize value++-- | Encodes a 64-bit CBOR value.+{-# INLINE encode64bit #-}+encode64bit :: (Integral a) => MajorArg -> a -> Builder+encode64bit major value =+  encodeArgument major paramInt64 <> BSB.word64BE normal+  where+    normal = normalize value
+ dagcbor/IPLD/DagCBOR/Encoder/SimpleTypes.hs view
@@ -0,0 +1,48 @@+-- | Module      : IPLD.DagCBOR.Encoder.SimpleTypes+--   Description : Implements booleans and null for DAG-CBOR+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder.SimpleTypes+  ( -- * CBOR simple value encoders+    encodeNullKind,+    encodeBoolKind,++    -- * Constants for working with CBOR simple value types+    majorSimple,+    paramFalse,+    paramTrue,+    paramNull,+  )+where++import Data.ByteString.Builder (Builder)+import IPLD.DagCBOR.Encoder.Arguments++-- | Major id for CBOR simple value objects.+majorSimple :: MajorArg+majorSimple = 7++-- | Parameter for encoding boolean false CBOR data.+paramFalse :: ParamArg+paramFalse = 20++-- | Parameter for encoding boolean true CBOR.+paramTrue :: ParamArg+paramTrue = 21++-- | Parameter for encoding null CBOR object.+paramNull :: ParamArg+paramNull = 22++-- | Encodes the DAG-CBOR value for True/False into the BinaryTranscoder `bxc`.+{-# INLINE encodeBoolKind #-}+encodeBoolKind :: Bool -> Builder+encodeBoolKind True = encodeArgument majorSimple paramTrue+encodeBoolKind False = encodeArgument majorSimple paramFalse++-- | Encodes the DAG-CBOR representation of null into `bxc`.+{-# INLINE encodeNullKind #-}+encodeNullKind :: Builder+encodeNullKind = encodeArgument majorSimple paramNull
+ dagcbor/IPLD/DagCBOR/Encoder/Strings.hs view
@@ -0,0 +1,56 @@+-- | Module      : IPLD.DagCBOR.Encoder.Strings+--   Description : DAG-CBOR encoders for strings, bytes, lists and maps+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DagCBOR.Encoder.Strings+  ( -- * DAG-CBOR encoder for bytestrings+    encodeBytesKind,+    majorBytes,++    -- * DAG-CBOR encoder for UTF-8 strings+    encodeStringKind,+    majorString,+  )+where++import Data.ByteString qualified as Bytes+import Data.ByteString.Builder (Builder)+import Data.ByteString.Builder qualified as BSB+import Data.Text (Text)+import Data.Text.Encoding qualified as Text+import IPLD.DM qualified as DM+import IPLD.DagCBOR.Encoder.Arguments+import IPLD.DagCBOR.Encoder.Errors+import IPLD.DagCBOR.Encoder.Ints++-- | Major id for CBOR bytestrings.+majorBytes :: MajorArg+majorBytes = 2++-- | Encodes a CBOR bytesring.+{-# INLINE encodeBytesKind #-}+encodeBytesKind :: DM.BytesData -> Okay Builder+encodeBytesKind (DM.BytesData bsb len) =+  let -- Get the argument builder for CBOR bytestrings+      arg = encodeIntArgument majorBytes len+   in -- Concat the argument and the bytestring builder+      arg <<>> pure bsb++-- | Major id for CBOR UTF-8 strings.+majorString :: MajorArg+majorString = 3++-- | Encodes a CBOR UTF-8 string.+{-# INLINE encodeStringKind #-}+encodeStringKind :: Text -> Okay Builder+encodeStringKind text =+  let -- Generates a UTF-8 encoded bytestring and get the builder and length+      utf = Text.encodeUtf8 text+      bsb = BSB.byteString utf+      len = Bytes.length utf+      -- Get the argument builder for CBOR UTF-8 strings+      arg = encodeIntArgument majorString len+   in -- Concat the argument and the bytestring builder+      arg <<>> pure bsb
+ ipld/IPLD/DM.hs view
@@ -0,0 +1,127 @@+-- | Module      : IPLD.DM+--   Description : Provides Node and Kind types for IPLD+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DM+  ( -- * Kinds are the data types of the IPLD data model+    Kind (..),++    -- * Node objects within a DM graph+    Node,++    -- * Implementing the IPLD bytesring+    BytesData (..),++    -- * Implementing the IPLD map type+    MapData,++    -- * Implementing the IPLD list type+    ListData,++    -- * Stores raw IEEE-754 floating point data.+    FloatData (..),+  )+where++import Control.DeepSeq (NFData (..))+import Data.Array (Array)+import Data.ByteString.Builder (Builder)+import Data.ByteString.Builder qualified as Builder+import Data.Text (Text)+import Data.Word (Word16, Word32, Word64)+import MultiFormats.CID (CID)++-- | All nodes within the DM have a kind with their, and this is part of the+-- Kind sum-type, so this is just a type-alias.+type Node = Kind++-- | Implements sum type for Kind, the representable data in IPLD.+-- https://ipld.io/docs/data-model/kinds/+-- https://ipld.io/docs/data-model/node/+data Kind+  = -- | Null can only have the value `Null`.+    -- https://ipld.io/docs/data-model/kinds/#null-kind+    NullKind+  | -- | True or False.+    -- https://ipld.io/docs/data-model/kinds/#boolean-kind+    BoolKind Bool+  | -- | AKA: Integer. IPLD suggests to use an unlimited size number+    -- representation when available, so we use integer. It will be up to the+    -- implementer of DataModel whether to use this space or not.+    -- https://ipld.io/docs/data-model/kinds/#integer-kind+    -- https://ipld.io/design/tricky-choices/numeric-domain/#integers+    IntKind Integer+  | -- | AKA: Float. This is how we represent decimal numbers with Kind.+    -- https://ipld.io/docs/data-model/kinds/#float-kind+    -- https://ipld.io/design/tricky-choices/numeric-domain/#floating-point+    FloatKind FloatData+  | -- | IPLD recommends UTF-8 support, so Text is used.+    -- https://ipld.io/docs/data-model/kinds/#string-kind+    StringKind Text+  | -- | Stores arbitrary bytes of any length.+    -- https://ipld.io/docs/data-model/kinds/#bytes-kind+    BytesKind BytesData+  | -- | AKA: Link, IPLD links data together using Multiformat's Content ID/CID.+    -- Using links, we can point to data in another IPLD block.+    -- https://ipld.io/docs/data-model/kinds/#link-kind+    ResourceKind CID+  | -- | Recursive type: List of Nodes.+    -- https://ipld.io/docs/data-model/kinds/#list-kind+    ListKind (ListData Node)+  | -- | Recursive type: Map of Nodes.+    -- https://ipld.io/docs/data-model/kinds/#map-kind+    MapKind (MapData Node Node)+  deriving (Show, Eq)++-- | Fully instantiates a Kind object from lazy Haskell object.+instance NFData Kind where+  rnf NullKind = ()+  rnf (BoolKind bool) = rnf bool+  rnf (IntKind int) = rnf int+  rnf (FloatKind float) = rnf float+  rnf (BytesKind bytesdata) = rnf bytesdata+  rnf (StringKind text) = rnf text+  rnf (ResourceKind cid) = rnf cid+  rnf (ListKind list) = rnf list+  rnf (MapKind kvs) = rnf kvs++-- | New-type for `Builder` for the bytestring type IPLD in data model.+data BytesData = BytesData+  { bytesDataBuilder :: Builder,+    bytesDataLength :: Int+  }+  deriving (Show)++-- | Fully instantiates a BytesData object from lazy Haskell object.+instance NFData BytesData where+  rnf (BytesData builder len) = builder `seq` len `seq` ()++-- | Implements `Eq` on `BytesData` by executing `Builder.toLazyByteString` on+-- both inputs.+instance Eq BytesData where+  (BytesData b1 l1) == (BytesData b2 l2) =+    l1 == l2 && Builder.toLazyByteString b1 == Builder.toLazyByteString b2++-- | Type-alias for storing the map type in the IPLD data model.+type ListData t = Array Int t++-- | Type-alias for storing the map type in the IPLD data model.+type MapData k v = Array Int (k, v)++-- | FloatData stores float types for different sizes.+data FloatData+  = -- | Raw IEEE754 half precision data. This doesn't have a Haskell type.+    HalfPrecision Word16+  | -- | Raw IEEE754 single precision data. Corresponds to Haskell `Float`.+    SinglePrecision Word32+  | -- | Raw IEEE754 double precision data. Corresponds to Haskell `Double`.+    DoublePrecision Word64+  deriving (Show, Eq)++-- | Fully instantiates a FloatData object from lazy Haskell object.+instance NFData FloatData where+  rnf (HalfPrecision w16) = rnf w16 `seq` ()+  rnf (SinglePrecision w32) = rnf w32 `seq` ()+  rnf (DoublePrecision w64) = rnf w64 `seq` ()
+ ipld/IPLD/DM/Decoder.hs view
@@ -0,0 +1,66 @@+-- | Module      : IPLD.DM.Decoder+--   Description : Type-class of IPLD data model decoders+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DM.Decoder+  ( -- * Class of data model decoders.+    Decoder (..),++    -- * Method signature for decoder implementers.+    DecoderMethod,+  )+where++import Control.Applicative (Alternative (..))+import IPLD.DM qualified as DM++-- | Method signature for DM decoders. Decodes some `item` from `tokens` into+-- the `ok` functor and the `result` bifunctor, storing the decoded item with+-- the remaining tokens.+type DecoderMethod item tokens ok result = tokens -> ok (result item tokens)++-- | Abstract class for developing DM decoders within some `codec`. Expects+-- implementations for each IPLD Kind, and provides a concrete method for+-- parsing a whole data model with the `decoder` method into a Node.+class (Alternative codec) => Decoder codec where+  -- | Decodes a object into the IPLD data model.+  mapKind :: codec DM.Node++  -- | Decodes a list object into the IPLD data model.+  listKind :: codec DM.Node++  -- | Decodes a ResourceKind aka link kind in IPLD.+  resourceKind :: codec DM.Node++  -- | Decodes a UTF-8 Text into IPLD data model.+  stringKind :: codec DM.Node++  -- | Decodes a ByteString into IPLD data model.+  bytesKind :: codec DM.Node++  -- | Decodes Integer values into IPLD whole-numbers.+  intKind :: codec DM.Node++  -- | Decodes a IEEE754 value into a valid IPLD floating point number.+  floatKind :: codec DM.Node++  -- | Decodes IPLD booleans.+  boolKind :: codec DM.Node++  -- | Decodes IPLD null values.+  nullKind :: codec DM.Node++  -- | Decodes DAG from the format.+  decoder :: codec DM.Node+  decoder =+    mapKind+      <|> listKind+      <|> resourceKind+      <|> bytesKind+      <|> stringKind+      <|> floatKind+      <|> intKind+      <|> boolKind+      <|> nullKind
+ ipld/IPLD/DM/Encoder.hs view
@@ -0,0 +1,118 @@+-- | Module      : IPLD.DM.Encoder+--   Description : Type-class of IPLD data model encoders+--   Copyright   : Zoey McBride (c) 2026+--   License     : AGPL-3.0-or-later+--   Maintainer  : zoeymcbride@mailbox.org+--   Stability   : experimental+module IPLD.DM.Encoder+  ( -- * Class of data model encoders.+    Encoder (..),+  )+where++import Control.Applicative (Alternative (..))+import Data.ByteString.Builder (Builder)+import Data.Text (Text)+import Data.Text qualified as Text+import Data.XCodec.BinaryTranscoder (BinaryTranscoder)+import Data.XCodec.BinaryTranscoder qualified as BXC+import IPLD.DM qualified as DM+import MultiFormats.CID (CID)+import Unsafe.Coerce (unsafeCoerce)++-- | Class of functions implementing `encoder` for `codec` in the IPLD data+-- model. Each abstract method takes a Node and produces a bytestring Builder+-- containing the CBOR object for that IPLD kind.+class (Alternative codec) => Encoder codec where+  -- | Encodes DAG from the `codec` format.+  encoder :: DM.Node -> codec Builder+  encoder node =+    mapKind node+      <|> listKind node+      <|> resourceKind node+      <|> bytesKind node+      <|> stringKind node+      <|> floatKind node+      <|> intKind node+      <|> boolKind node+      <|> nullKind node++  -- | Encodes a object into the IPLD data model.+  mapKind :: DM.Node -> codec Builder++  -- | Encodes a list object into the IPLD data model.+  listKind :: DM.Node -> codec Builder++  -- | Encodes a ResourceKind aka link kind in IPLD.+  resourceKind :: DM.Node -> codec Builder++  -- | Encodes a UTF-8 Text into IPLD data model.+  stringKind :: DM.Node -> codec Builder++  -- | Encodes a ByteString into IPLD data model.+  bytesKind :: DM.Node -> codec Builder++  -- | Encodes Integer values into IPLD whole-numbers.+  intKind :: DM.Node -> codec Builder++  -- | Encodes a IEEE754 value into a valid IPLD floating point number.+  floatKind :: DM.Node -> codec Builder++  -- | Encodes IPLD booleans.+  boolKind :: DM.Node -> codec Builder++  -- | Encodes IPLD null values.+  nullKind :: DM.Node -> codec Builder++  -- | Encodes a Text string directly into a StringKind node.+  encodeText :: Text -> codec Builder+  encodeText = stringKind . DM.StringKind++  -- | Encodes a Haskell String directly into a StringKind node.+  encodeString :: String -> codec Builder+  encodeString = encodeText . Text.pack++  -- | Encodes BinaryTranscoder class directly into a BytesKind node.+  encodeBytes :: (BinaryTranscoder bxc) => bxc -> codec Builder+  encodeBytes bxc = bytesKind $ DM.BytesKind (DM.BytesData builder len)+    where+      builder = BXC.unpackSerial bxc+      len = BXC.totalOctets bxc++  -- | Encodes CID into the ResourceKind node.+  encodeResource :: CID -> codec Builder+  encodeResource = resourceKind . DM.ResourceKind++  -- | Encodes an Integral value into the data model.+  encodeIntValue :: (Integral a) => a -> codec Builder+  encodeIntValue = intKind . DM.IntKind . fromIntegral++  -- | Encodes a Haskell Float into the data model for convenience. This+  -- function crashes for invalid inputs, so use `encodeFloatKind` for input+  -- data.+  encodeFloatValue :: Float -> codec Builder+  encodeFloatValue value+    | isNaN value || isInfinite value = error "encodeFloat: Invalid IPLD"+    | otherwise = floatKind $ DM.FloatKind single+    where+      -- Get the binary value of the floating point+      single = DM.SinglePrecision $ unsafeCoerce value++  -- | Encodes a Haskell Double into the data model for convenience. This+  -- function crashes for invalid inputs, so use `encodeFloatKind` for input+  -- data.+  encodeDoubleValue :: Double -> codec Builder+  encodeDoubleValue value+    | isNaN value || isInfinite value = error "encodeFloat: Invalid IPLD"+    | otherwise = floatKind $ DM.FloatKind double+    where+      -- Get the binary value of the floating point+      double = DM.DoublePrecision $ unsafeCoerce value++  -- | Encodes a Haskell boolean into the data model format.+  encodeBool :: Bool -> codec Builder+  encodeBool = boolKind . DM.BoolKind++  -- | Encodes the null data model+  encodeNull :: codec Builder+  encodeNull = nullKind DM.NullKind
+ ipldm.cabal view
@@ -0,0 +1,91 @@+cabal-version:   3.0+version:         1.0.0.0+name:            ipldm+build-type:      Simple+author:          Zoey McBride+maintainer:      zoeymcbride@mailbox.org+license:         AGPL-3.0-or-later+license-file:    LICENSE.txt+extra-doc-files: README.md, CHANGELOG.md+category:        Network+synopsis:        The InterPlanetary Linked Data Model and codec formats.+description:+    Provides the IPLD data model in an abstract form with the different IPLD+    data kinds. Also codecs for decoding these kinds from serialized formats+    such as DAG-CBOR, and encoding the abstract data model back into binary+    formats.+tested-with:+    GHC == 9.6.7++source-repository head {+    type: git+    location: https://git.sr.ht/~z0/ipldm+}+++common HaskellConfig {+    hs-source-dirs: ipld dagcbor+    default-language: GHC2021+    default-extensions: StrictData PatternSynonyms+}++common Depends {+    build-depends:+        base >= 4.18 && < 5,+        xcodec ^>= 1.1,+        basesystems ^>= 1.2,+        mfmts ^>= 1.2,+        array ^>= 0.5,+        bytestring ^>= 0.12,+        containers ^>= 0.7,+        text ^>= 2.1,+        parallel ^>= 3.3,+        deepseq ^>= 1.4+}++common BuildUser {+    import: Depends+    ghc-options: -Wall -Wextra -Wno-unused-top-binds -threaded+}++common BuildCI {+    import: Depends+    ghc-options: -Wall -Wextra -Werror -Wno-unused-top-binds -threaded+}++flag CI {+    Description: CI Build options+    Default: False+    Manual: True+}++library {+    import: HaskellConfig+    if flag(CI) { import: BuildCI }+    else { import: BuildUser }+    exposed-modules:+        -- * Provides sum-type for different data model kinds+        IPLD.DM+        -- * Type-class of IPLD data model encoders+        IPLD.DM.Encoder+        -- * Type-class of IPLD data model decoders+        IPLD.DM.Decoder+        -- * NOTE: changing file+        IPLD.DagCBOR+        -- * Implements DM.Decoder for DAG-CBOR+        IPLD.DagCBOR.Decoder+        IPLD.DagCBOR.Decoder.Errors+        IPLD.DagCBOR.Decoder.Arguments+        IPLD.DagCBOR.Decoder.Objects+        IPLD.DagCBOR.Decoder.MajorTypes+        IPLD.DagCBOR.Decoder.Supplemental+        -- * Implements DM.Encoder for DAG-CBOR+        IPLD.DagCBOR.Encoder+        IPLD.DagCBOR.Encoder.Arguments+        IPLD.DagCBOR.Encoder.Errors+        IPLD.DagCBOR.Encoder.Strings+        IPLD.DagCBOR.Encoder.Floats+        IPLD.DagCBOR.Encoder.Ints+        IPLD.DagCBOR.Encoder.CID+        IPLD.DagCBOR.Encoder.SimpleTypes+}