diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,1 @@ +See https://github.com/pbrisbin/jsonpatch/releases diff --git a/COPYING b/COPYING new file mode 100644 --- /dev/null +++ b/COPYING @@ -0,0 +1,662 @@ + + GNU AFFERO GENERAL PUBLIC LICENSE + Version 3, 19 November 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + 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. + + + Copyright (C) + + 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 . + +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 +. diff --git a/README.lhs b/README.lhs new file mode 100644 --- /dev/null +++ b/README.lhs @@ -0,0 +1,102 @@ +# jsonpatch + +[![Hackage](https://img.shields.io/hackage/v/jsonpatch.svg?style=flat)](https://hackage.haskell.org/package/jsonpatch) +[![Stackage Nightly](http://stackage.org/package/jsonpatch/badge/nightly)](http://stackage.org/nightly/package/jsonpatch) +[![Stackage LTS](http://stackage.org/package/jsonpatch/badge/lts)](http://stackage.org/lts/package/jsonpatch) +[![CI](https://github.com/pbrisbin/jsonpatch/actions/workflows/ci.yml/badge.svg)](https://github.com/pbrisbin/jsonpatch/actions/workflows/ci.yml) + +Haskell package for parsing and applying [JSON Patches][jsonpatch]. + +[jsonpatch]: https://jsonpatch.com/ + +## Example + + + +Typical use cases need only one import: + +```haskell +import Data.JSON.Patch +``` + +Our example will make use of a few more libraries: + + +```haskell +import Control.Exception (displayException) +import Data.Aeson (Value, Result(..), fromJSON) +import Data.Aeson.Encode.Pretty +import Data.Aeson.QQ (aesonQQ) +import Data.ByteString.Lazy qualified as BSL +``` + +The `FromJSON` instance can be used to build a `[Patch]`: + +```haskell +patch :: [Patch] +patch = fromResult $ fromJSON [aesonQQ| + [ + { "op": "replace", "path": "/baz", "value": "boo" }, + { "op": "add", "path": "/hello", "value": ["world"] }, + { "op": "remove", "path": "/foo" } + ] +|] + + +-- | Unsafe unwrapping for the sake of example +fromResult :: Result a -> a +fromResult (Success a) = a +``` + +The patches can then be applied to a document: + +```haskell +result :: Either PatchError Value +result = applyPatches patch [aesonQQ| + { + "baz": "qux", + "foo": "bar" + } +|] +``` + +The result is in `Either PatchError`, with `displayException` available to get +a user-friendly message. + +```haskell +main :: IO () +main = either (fail . displayException) (BSL.putStr . encodePretty) result +``` + +The above program outputs: + +```json +{ + "baz": "boo", + "hello": ["world"] +} +``` + + +## Quality + +The full test suite from [`json-patch/json-patch-tests`][json-patch-tests] +passes. However, some error cases have poor (or misleading) error messages at +this time. + +[json-patch-tests]: https://github.com/json-patch/json-patch-tests + +## License + +This package is licensed AGPLv3. See [COPYING](./COPYING). diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,102 @@ +# jsonpatch + +[![Hackage](https://img.shields.io/hackage/v/jsonpatch.svg?style=flat)](https://hackage.haskell.org/package/jsonpatch) +[![Stackage Nightly](http://stackage.org/package/jsonpatch/badge/nightly)](http://stackage.org/nightly/package/jsonpatch) +[![Stackage LTS](http://stackage.org/package/jsonpatch/badge/lts)](http://stackage.org/lts/package/jsonpatch) +[![CI](https://github.com/pbrisbin/jsonpatch/actions/workflows/ci.yml/badge.svg)](https://github.com/pbrisbin/jsonpatch/actions/workflows/ci.yml) + +Haskell package for parsing and applying [JSON Patches][jsonpatch]. + +[jsonpatch]: https://jsonpatch.com/ + +## Example + + + +Typical use cases need only one import: + +```haskell +import Data.JSON.Patch +``` + +Our example will make use of a few more libraries: + + +```haskell +import Control.Exception (displayException) +import Data.Aeson (Value, Result(..), fromJSON) +import Data.Aeson.Encode.Pretty +import Data.Aeson.QQ (aesonQQ) +import Data.ByteString.Lazy qualified as BSL +``` + +The `FromJSON` instance can be used to build a `[Patch]`: + +```haskell +patch :: [Patch] +patch = fromResult $ fromJSON [aesonQQ| + [ + { "op": "replace", "path": "/baz", "value": "boo" }, + { "op": "add", "path": "/hello", "value": ["world"] }, + { "op": "remove", "path": "/foo" } + ] +|] + + +-- | Unsafe unwrapping for the sake of example +fromResult :: Result a -> a +fromResult (Success a) = a +``` + +The patches can then be applied to a document: + +```haskell +result :: Either PatchError Value +result = applyPatches patch [aesonQQ| + { + "baz": "qux", + "foo": "bar" + } +|] +``` + +The result is in `Either PatchError`, with `displayException` available to get +a user-friendly message. + +```haskell +main :: IO () +main = either (fail . displayException) (BSL.putStr . encodePretty) result +``` + +The above program outputs: + +```json +{ + "baz": "boo", + "hello": ["world"] +} +``` + + +## Quality + +The full test suite from [`json-patch/json-patch-tests`][json-patch-tests] +passes. However, some error cases have poor (or misleading) error messages at +this time. + +[json-patch-tests]: https://github.com/json-patch/json-patch-tests + +## License + +This package is licensed AGPLv3. See [COPYING](./COPYING). diff --git a/jsonpatch.cabal b/jsonpatch.cabal new file mode 100644 --- /dev/null +++ b/jsonpatch.cabal @@ -0,0 +1,178 @@ +cabal-version: 1.18 +name: jsonpatch +version: 0.1.0.0 +license: AGPL-3 +license-file: COPYING +maintainer: Patrick Brisbin +homepage: https://github.com/pbrisbin/jsonpatch#readme +bug-reports: https://github.com/pbrisbin/jsonpatch/issues +synopsis: JSON Patch parsing and application +description: + This is a Haskell library for parsing and applying JSON Patches + . + From : + . + JSON Patch is a format for describing changes to a + [JSON](https://www.json.org/) document. It can be used to avoid sending a + whole document when only a part has changed. When used in combination with the + [HTTP PATCH method](https://datatracker.ietf.org/doc/html/rfc5789/), it allows + partial updates for HTTP APIs in a standards compliant way. + . + The patch documents are themselves JSON documents. + . + JSON Patch is specified in [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902/) from the IETF. + +category: JSON +build-type: Simple +extra-source-files: tests.json +extra-doc-files: + README.md + CHANGELOG.md + +source-repository head + type: git + location: https://github.com/pbrisbin/jsonpatch + +library + exposed-modules: + Data.Aeson.Optics.Ext + Data.JSON.Patch + Data.JSON.Patch.Apply + Data.JSON.Patch.Error + Data.JSON.Patch.Type + Data.JSON.Pointer + Data.JSON.Pointer.Token + Data.Vector.Ext + + hs-source-dirs: src + other-modules: Paths_jsonpatch + default-language: GHC2021 + default-extensions: + DataKinds DeriveAnyClass DerivingStrategies DerivingVia + DuplicateRecordFields GADTs LambdaCase NoFieldSelectors + NoImplicitPrelude NoMonomorphismRestriction NoPostfixOperators + OverloadedRecordDot OverloadedStrings QuasiQuotes TypeFamilies + + ghc-options: + -Weverything -Wno-all-missed-specialisations + -Wno-missed-specialisations -Wno-missing-exported-signatures + -Wno-missing-import-lists -Wno-missing-local-signatures + -Wno-monomorphism-restriction -Wno-safe -Wno-unsafe + + build-depends: + aeson >=2.0.3.0, + aeson-optics >=1.2.0.1, + attoparsec >=0.14.4, + base >=4.16.4.0 && <5, + mtl >=2.2.2, + optics >=0.4.2, + text >=1.2.5.0, + vector >=0.12.3.1 + + if impl(ghc >=9.8) + ghc-options: + -Wno-missing-role-annotations -Wno-missing-poly-kind-signatures + + if impl(ghc >=9.2) + ghc-options: -Wno-missing-kind-signatures + + if impl(ghc >=8.10) + ghc-options: + -Wno-missing-safe-haskell-mode -Wno-prepositive-qualified-module + + if impl(ghc >=8.8) + ghc-options: -fwrite-ide-info + +test-suite readme + type: exitcode-stdio-1.0 + main-is: README.lhs + other-modules: Paths_jsonpatch + default-language: GHC2021 + default-extensions: + DataKinds DeriveAnyClass DerivingStrategies DerivingVia + DuplicateRecordFields GADTs LambdaCase NoFieldSelectors + NoImplicitPrelude NoMonomorphismRestriction NoPostfixOperators + OverloadedRecordDot OverloadedStrings QuasiQuotes TypeFamilies + + ghc-options: + -Weverything -Wno-all-missed-specialisations + -Wno-missed-specialisations -Wno-missing-exported-signatures + -Wno-missing-import-lists -Wno-missing-local-signatures + -Wno-monomorphism-restriction -Wno-safe -Wno-unsafe -pgmL + markdown-unlit + + build-depends: + aeson >=2.0.3.0, + aeson-pretty >=0.8.9, + aeson-qq >=0.8.4, + base >=4.16.4.0 && <5, + bytestring >=0.11.4.0, + jsonpatch, + markdown-unlit >=0.5.1 + + if impl(ghc >=9.8) + ghc-options: + -Wno-missing-role-annotations -Wno-missing-poly-kind-signatures + + if impl(ghc >=9.2) + ghc-options: -Wno-missing-kind-signatures + + if impl(ghc >=8.10) + ghc-options: + -Wno-missing-safe-haskell-mode -Wno-prepositive-qualified-module + + if impl(ghc >=8.8) + ghc-options: -fwrite-ide-info + +test-suite spec + type: exitcode-stdio-1.0 + main-is: Spec.hs + hs-source-dirs: test + other-modules: + Data.Aeson.Optics.ExtSpec + Data.JSON.Patch.PointerSpec + Data.JSON.PatchSpec + Data.Vector.ExtSpec + Paths_jsonpatch + + default-language: GHC2021 + default-extensions: + DataKinds DeriveAnyClass DerivingStrategies DerivingVia + DuplicateRecordFields GADTs LambdaCase NoFieldSelectors + NoImplicitPrelude NoMonomorphismRestriction NoPostfixOperators + OverloadedRecordDot OverloadedStrings QuasiQuotes TypeFamilies + + ghc-options: + -Weverything -Wno-all-missed-specialisations + -Wno-missed-specialisations -Wno-missing-exported-signatures + -Wno-missing-import-lists -Wno-missing-local-signatures + -Wno-monomorphism-restriction -Wno-safe -Wno-unsafe -threaded + -rtsopts -with-rtsopts=-N + + build-depends: + aeson >=2.0.3.0, + aeson-optics >=1.2.0.1, + aeson-pretty >=0.8.9, + aeson-qq >=0.8.4, + base >=4.16.4.0 && <5, + bytestring >=0.11.4.0, + hspec >=2.9.7, + hspec-expectations-json >=1.0.0.7, + jsonpatch, + optics >=0.4.2, + path >=0.9.2, + vector >=0.12.3.1 + + if impl(ghc >=9.8) + ghc-options: + -Wno-missing-role-annotations -Wno-missing-poly-kind-signatures + + if impl(ghc >=9.2) + ghc-options: -Wno-missing-kind-signatures + + if impl(ghc >=8.10) + ghc-options: + -Wno-missing-safe-haskell-mode -Wno-prepositive-qualified-module + + if impl(ghc >=8.8) + ghc-options: -fwrite-ide-info diff --git a/src/Data/Aeson/Optics/Ext.hs b/src/Data/Aeson/Optics/Ext.hs new file mode 100644 --- /dev/null +++ b/src/Data/Aeson/Optics/Ext.hs @@ -0,0 +1,71 @@ +-- | +-- +-- Module : Data.Aeson.Optics.Ext +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.Aeson.Optics.Ext + ( atKey + , atNth + ) where + +import Prelude + +import Data.Aeson (Key, Value (..)) +import Data.Aeson.Key qualified as Key +import Data.Aeson.KeyMap qualified as KeyMap +import Data.Aeson.Optics +import Data.Vector qualified as V +import Data.Vector.Ext qualified as V +import Optics + +-- | Like 'key', but uses 'at' instead of 'ix'. This is handy when adding and +-- removing object keys: +-- +-- >>> "{\"a\": 100, \"b\": 200}" & atKey "a" .~ Nothing +-- "{\"b\":200}" +-- +-- >>> "{\"a\": 100, \"b\": 200}" & atKey "c" ?~ String "300" +-- "{\"a\":100,\"b\":200,\"c\":\"300\"}" +atKey :: Key -> AffineTraversal' Value (Maybe Value) +atKey k = _Object % at k + +-- | Like 'atKey', but for 'Array's +-- +-- Adding shifts all later elements right: +-- +-- >>> ['a', 'b'] & atNth 1 ?~ 'x' +-- ['a', 'x', 'b'] +-- +-- Removing shifts all later elements left: +-- +-- >>> ['a', 'b', 'c'] & atNth 1 .~ Nothing +-- ['a', 'c'] +-- +-- __NOTE__: this function will also index objects, in which case this behaves +-- exactly like 'atKey'. This is necessary for our use-case and probably means +-- we could never upstream this. +-- +-- >>> {"0": 'a', "1": 'b'} & atNth 1 ?~ 'x' +-- {"0": 'a', "1": 'x', "2": 'b'} +atNth :: Int -> AffineTraversal' Value (Maybe Value) +atNth n = atraversal matcher updater + where + matcher :: Value -> Either Value (Maybe Value) + matcher = \case + Object km -> Right $ KeyMap.lookup (Key.fromString $ show n) km + Array vec -> Right $ vec V.!? n + v -> Left v + + updater :: Value -> Maybe Value -> Value + updater nv = \case + Nothing -> case nv of + Object km -> Object $ KeyMap.delete (Key.fromString $ show n) km + Array vec -> Array $ V.deleteAt n vec + v -> v + Just x -> case nv of + Object km -> Object $ KeyMap.insert (Key.fromString $ show n) x km + Array vec -> Array $ V.insertAt n x vec + v -> v diff --git a/src/Data/JSON/Patch.hs b/src/Data/JSON/Patch.hs new file mode 100644 --- /dev/null +++ b/src/Data/JSON/Patch.hs @@ -0,0 +1,16 @@ +-- | +-- +-- Module : Data.JSON.Patch +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.JSON.Patch + ( Patch + , PatchError + , applyPatches + ) where + +import Data.JSON.Patch.Apply +import Data.JSON.Patch.Type diff --git a/src/Data/JSON/Patch/Apply.hs b/src/Data/JSON/Patch/Apply.hs new file mode 100644 --- /dev/null +++ b/src/Data/JSON/Patch/Apply.hs @@ -0,0 +1,121 @@ +-- | +-- +-- Module : Data.JSON.Patch.Apply +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.JSON.Patch.Apply + ( applyPatches + , PatchError (..) + ) where + +import Prelude + +import Control.Monad (unless, void, when) +import Control.Monad.Except (MonadError, runExcept, throwError) +import Control.Monad.State (MonadState, execStateT, gets, modify, put) +import Data.Aeson +import Data.Aeson.KeyMap (KeyMap) +import Data.Aeson.Optics +import Data.Foldable (traverse_) +import Data.JSON.Patch.Error +import Data.JSON.Patch.Type +import Data.JSON.Pointer +import Data.JSON.Pointer.Token +import Data.Vector (Vector) +import Data.Vector qualified as V +import Optics + +applyPatches :: [Patch] -> Value -> Either PatchError Value +applyPatches ps = runExcept . execStateT (traverse_ applyPatch ps) + +applyPatch :: (MonadError PatchError m, MonadState Value m) => Patch -> m () +applyPatch = \case + Add op -> add op.value op.path + Remove op -> remove op.path + Replace op -> remove op.path >> add op.value op.path + Move op -> do + v <- get op.from + remove op.from + add v op.path + Copy op -> flip add op.path =<< get op.from + Test op -> do + v <- get op.path + unless (v == op.value) $ throwError $ TestFailed op.path v op.value + +get :: (MonadError PatchError m, MonadState Value m) => Pointer -> m Value +get = \case + PointerEmpty -> gets id + PointerPath ts t -> assertExists $ ts <> [t] + PointerPathEnd ts -> do + target <- assertExists ts + vec <- assertArray ts target + snd <$> assertUnsnoc ts vec + +add :: (MonadError PatchError m, MonadState Value m) => Value -> Pointer -> m () +add v = \case + PointerEmpty -> put v + PointerPath ts t -> do + target <- assertExists ts + + -- Additional validations based on type of final target + case t of + K _ -> void $ assertObject ts target + N n -> do + case target of + Object {} -> pure () -- n will be used as Key, no bounds check + Array vec -> do + when (n < 0) $ throwError $ IndexOutOfBounds ts n vec + when (n > V.length vec) $ throwError $ IndexOutOfBounds ts n vec + v' -> throwError $ InvalidArrayOperation ts v' + + modify $ tokensL ts % atTokenL t ?~ v + PointerPathEnd ts -> do + target <- assertExists ts + void $ assertArray ts target + modify $ tokensL ts % _Array %~ (<> pure v) + +remove :: (MonadError PatchError m, MonadState Value m) => Pointer -> m () +remove = \case + PointerEmpty -> put Null -- NB. unspecified behavior + PointerPath ts t -> do + void $ assertExists $ ts <> [t] + + -- NB. odd that the tests don't exercise any additional validation (e.g. + -- bounds checking) like we saw with add. + + modify $ tokensL ts % atTokenL t .~ Nothing + PointerPathEnd ts -> do + target <- assertExists ts + vec <- assertArray ts target + (vs, _) <- assertUnsnoc ts vec + modify $ tokensL ts % _Array .~ vs + +assertExists + :: (MonadError PatchError m, MonadState Value m) => [Token] -> m Value +assertExists ts = + gets (preview $ tokensL ts) >>= \case + Nothing -> throwError $ PointerNotFound ts Nothing + Just v -> pure v + +assertObject :: MonadError PatchError m => [Token] -> Value -> m (KeyMap Value) +assertObject ts = \case + Object o -> pure o + v -> throwError $ InvalidObjectOperation ts v + +assertArray :: MonadError PatchError m => [Token] -> Value -> m (Vector Value) +assertArray ts = \case + Array vec -> pure vec + v -> throwError $ InvalidArrayOperation ts v + +assertUnsnoc + :: MonadError PatchError m + => [Token] + -> Vector Value + -> m (Vector Value, Value) +assertUnsnoc ts vec = + case V.unsnoc vec of + Nothing -> throwError $ EmptyArray ts + Just tp -> pure tp diff --git a/src/Data/JSON/Patch/Error.hs b/src/Data/JSON/Patch/Error.hs new file mode 100644 --- /dev/null +++ b/src/Data/JSON/Patch/Error.hs @@ -0,0 +1,66 @@ +-- | +-- +-- Module : Data.JSON.Patch.Error +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.JSON.Patch.Error + ( PatchError (..) + ) where + +import Prelude + +import Control.Exception (Exception (..)) +import Data.Aeson (Value) +import Data.JSON.Pointer +import Data.JSON.Pointer.Token +import Data.Vector (Vector) +import Data.Vector qualified as V + +data PatchError + = ParseError Value String + | PointerNotFound [Token] (Maybe String) + | InvalidObjectOperation [Token] Value + | InvalidArrayOperation [Token] Value + | IndexOutOfBounds [Token] Int (Vector Value) + | EmptyArray [Token] + | TestFailed Pointer Value Value + deriving stock (Show) + +instance Exception PatchError where + displayException = \case + ParseError v msg -> + "Unable to parse Patch(es) from Value: " + <> ("\n error: " <> msg) + <> ("\n input: " <> show v) + PointerNotFound ts mType -> + "Path " + <> tokensToString ts + <> " does not exist" + <> maybe "" (" or is not " <>) mType + InvalidObjectOperation ts v -> + "Cannot perform object operation on non-object at " + <> tokensToString ts + <> ": " + <> show v + InvalidArrayOperation ts v -> + "Cannot perform array operation on non-array at " + <> tokensToString ts + <> ": " + <> show v + IndexOutOfBounds ts n vec -> + "Index " + <> show n + <> " is out of bounds for vector of length " + <> show (V.length vec) + <> " at " + <> tokensToString ts + EmptyArray ts -> + "Cannot perform operation on empty array at " <> tokensToString ts + TestFailed p actual expected -> + "Test failed at " + <> pointerToString p + <> ("\n expected: " <> show expected) + <> ("\n actual: " <> show actual) diff --git a/src/Data/JSON/Patch/Type.hs b/src/Data/JSON/Patch/Type.hs new file mode 100644 --- /dev/null +++ b/src/Data/JSON/Patch/Type.hs @@ -0,0 +1,93 @@ +-- | +-- +-- Module : Data.JSON.Patch.Type +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.JSON.Patch.Type + ( Patch (..) + , AddOp (..) + , RemoveOp (..) + , ReplaceOp (..) + , CopyOp (..) + , MoveOp (..) + , TestOp (..) + ) where + +import Prelude + +import Data.Aeson +import Data.JSON.Pointer +import Data.Text (Text) +import GHC.Generics (Generic) + +data Patch + = Add AddOp + | Remove RemoveOp + | Replace ReplaceOp + | Copy CopyOp + | Move MoveOp + | Test TestOp + deriving stock (Eq, Show) + +instance FromJSON Patch where + parseJSON = withObject "Operation" $ \o -> do + op <- o .: "op" + + case (op :: Text) of + "add" -> Add <$> parseJSON (Object o) + "remove" -> Remove <$> parseJSON (Object o) + "replace" -> Replace <$> parseJSON (Object o) + "copy" -> Copy <$> parseJSON (Object o) + "move" -> Move <$> parseJSON (Object o) + "test" -> Test <$> parseJSON (Object o) + x -> + fail + $ concat + [ "unexpected operation, " + , show x + , ", must be one of add, remove, replace, copy, move, or test" + ] + +data AddOp = AddOp + { path :: Pointer + , value :: Value + } + deriving stock (Eq, Generic, Show) + deriving anyclass (FromJSON) + +newtype RemoveOp = RemoveOp + { path :: Pointer + } + deriving stock (Eq, Generic, Show) + deriving anyclass (FromJSON) + +data ReplaceOp = ReplaceOp + { path :: Pointer + , value :: Value + } + deriving stock (Eq, Generic, Show) + deriving anyclass (FromJSON) + +data CopyOp = CopyOp + { from :: Pointer + , path :: Pointer + } + deriving stock (Eq, Generic, Show) + deriving anyclass (FromJSON) + +data MoveOp = MoveOp + { from :: Pointer + , path :: Pointer + } + deriving stock (Eq, Generic, Show) + deriving anyclass (FromJSON) + +data TestOp = TestOp + { path :: Pointer + , value :: Value + } + deriving stock (Eq, Generic, Show) + deriving anyclass (FromJSON) diff --git a/src/Data/JSON/Pointer.hs b/src/Data/JSON/Pointer.hs new file mode 100644 --- /dev/null +++ b/src/Data/JSON/Pointer.hs @@ -0,0 +1,60 @@ +-- +module Data.JSON.Pointer + ( Pointer (..) + , pointerFromText + , pointerToText + , pointerToString + ) where + +import Prelude + +import Data.Aeson (FromJSON (..), withText) +import Data.Attoparsec.Text +import Data.JSON.Pointer.Token +import Data.List.NonEmpty (nonEmpty) +import Data.List.NonEmpty qualified as NE +import Data.Text (Text, unpack) +import Data.Text qualified as T + +data Pointer + = -- | @""@ means whole-document + PointerEmpty + | -- | @"/[.../]x"@ means path to a key or index @x@ + -- + -- NB. @"/"@ naturally becomes @'PointerPath' [] ('K' "")@ + PointerPath [Token] Token + | -- | @"/[.../]-"@ means path to last element of an array + PointerPathEnd [Token] + deriving stock (Eq, Show) + +instance FromJSON Pointer where + parseJSON = withText "Pointer" $ either fail pure . pointerFromText + +pointerFromText :: Text -> Either String Pointer +pointerFromText = \case + "" -> Right PointerEmpty + "/" -> Right $ PointerPath [] $ K "" + "/-" -> Right $ PointerPathEnd [] + p -> case T.stripSuffix "/-" p of + Nothing -> parseOnly pointerPathP p + Just p' -> parseOnly pointerPathEndP p' + +pointerToText :: Pointer -> Text +pointerToText = \case + PointerEmpty -> "" + PointerPath ts t -> tokensToText $ ts <> [t] + PointerPathEnd ts -> tokensToText ts <> "/-" + +pointerToString :: Pointer -> String +pointerToString = unpack . pointerToText + +pointerPathP :: Parser Pointer +pointerPathP = do + ts <- maybe (fail "") pure . nonEmpty =<< pointerP + pure $ PointerPath (NE.init ts) $ NE.last ts + +pointerPathEndP :: Parser Pointer +pointerPathEndP = PointerPathEnd <$> pointerP + +pointerP :: Parser [Token] +pointerP = char '/' *> tokenP `sepBy1` char '/' <* endOfInput diff --git a/src/Data/JSON/Pointer/Token.hs b/src/Data/JSON/Pointer/Token.hs new file mode 100644 --- /dev/null +++ b/src/Data/JSON/Pointer/Token.hs @@ -0,0 +1,90 @@ +-- | +-- +-- Module : Data.JSON.Pointer.Token +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.JSON.Pointer.Token + ( Token (..) + , tokenP + , tokensToText + , tokensToString + , tokensL + , tokenL + , atTokenL + ) where + +import Prelude + +import Control.Applicative (optional, (<|>)) +import Data.Aeson (Key, Value (..)) +import Data.Aeson.Key qualified as Key +import Data.Aeson.Optics +import Data.Aeson.Optics.Ext +import Data.Attoparsec.Text +import Data.Text (Text, pack, unpack) +import Data.Text qualified as T +import Optics +import Text.Read (readEither) + +data Token = K Key | N Int + deriving stock (Eq, Show) + +tokensToString :: [Token] -> String +tokensToString = unpack . tokensToText + +tokensToText :: [Token] -> Text +tokensToText ts = "/" <> T.intercalate "/" (map tokenToText ts) + +tokenToText :: Token -> Text +tokenToText = \case + K k -> Key.toText k + N n -> pack $ show n + +tokensL :: [Token] -> AffineTraversal' Value Value +tokensL = foldr ((%) . tokenL) $ castOptic simple + +-- | Access a key or array index like 'ix' +tokenL :: Token -> AffineTraversal' Value Value +tokenL t = case t of + K k -> key k + N n -> nth n + +-- | Access a key or array index, but 'at'-like +atTokenL :: Token -> AffineTraversal' Value (Maybe Value) +atTokenL = \case + K k -> atKey k + N n -> atNth n + +tokenP :: Parser Token +tokenP = wtf <|> N <$> indexP <|> K <$> keyP + +-- | +-- +-- The tests love to use this value as an example. I'm clearly confused because +-- I would expect it to fail 'indexP', backtrack, then succeed in 'keyP', but it +-- causes errors with "endOfInput", so we'll special case it for now. +wtf :: Parser Token +wtf = K . Key.fromText <$> string "1e0" + +keyP :: Parser Key +keyP = + Key.fromText + . T.replace "~0" "~" + . T.replace "~1" "/" + <$> takeTill (== '/') + +indexP :: Parser Int +indexP = do + f <- maybe id (const negate) <$> optional (char '-') + f <$> nonzeroP <|> 0 <$ char '0' + +nonzeroP :: Parser Int +nonzeroP = do + ds <- (:) <$> satisfy (inClass "1-9") <*> many' digit + either (err ds) pure $ readEither ds + where + err :: String -> String -> Parser a + err x msg = fail $ "Unable to read integer from " <> x <> ": " <> msg diff --git a/src/Data/Vector/Ext.hs b/src/Data/Vector/Ext.hs new file mode 100644 --- /dev/null +++ b/src/Data/Vector/Ext.hs @@ -0,0 +1,54 @@ +-- | +-- +-- Module : Data.Vector.Ext +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.Vector.Ext + ( deleteAt + , insertAt + ) where + +import Prelude + +import Data.Vector (Vector) +import Data.Vector qualified as V + +-- | Delete from a vector and shift all later elements left +deleteAt :: Int -> Vector a -> Vector a +deleteAt n vec + | n < 0 = vec + | n >= V.length vec = vec + | otherwise = generateFrom $ V.imapMaybe shift vec + where + shift idx a + | idx < n = Just (idx, a) + | idx == n = Nothing + | otherwise = Just (idx - 1, a) + +-- | Insert into a vector and shift all later elements right +insertAt :: Int -> a -> Vector a -> Vector a +insertAt n v vec + | n < 0 = vec + | n > V.length vec = vec + | otherwise = generateFrom $ V.imap shift vec <> pure (n, v) + where + shift idx a + | idx >= n = (idx + 1, a) + | otherwise = (idx, a) + +generateFrom :: Vector (Int, a) -> Vector a +generateFrom indexed = V.generate (length indexed) $ \idx -> + maybe (badIndex idx) snd $ V.find ((== idx) . fst) indexed + where + badIndex idx = + error + $ "Index " + <> show idx + <> " is not present in vector of indexed values: " + <> show indexes + + indexes :: [Int] + indexes = map fst $ V.toList indexed diff --git a/test/Data/Aeson/Optics/ExtSpec.hs b/test/Data/Aeson/Optics/ExtSpec.hs new file mode 100644 --- /dev/null +++ b/test/Data/Aeson/Optics/ExtSpec.hs @@ -0,0 +1,69 @@ +-- | +-- +-- Module : Data.Aeson.Optics.ExtSpec +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.Aeson.Optics.ExtSpec + ( spec + ) where + +import Prelude + +import Data.Aeson.Key qualified as Key +import Data.Aeson.Optics +import Data.Aeson.Optics.Ext +import Data.Aeson.QQ +import Data.Foldable (for_) +import Optics +import Test.Hspec + +spec :: Spec +spec = do + describe "atNth" $ do + it "indexes arrays as expected" $ do + let input = [aesonQQ| ["a", "b"] |] + + input ^? atNth (-1) % _Just `shouldBe` Nothing + input ^? atNth 0 % _Just % _String `shouldBe` Just "a" + input ^? atNth 1 % _Just % _String `shouldBe` Just "b" + input ^? atNth 2 % _Just `shouldBe` Nothing + + it "adds to arrays by shifting elements right" $ do + let input = [aesonQQ| ["a", "b"] |] + + input & atNth (-1) ?~ "x" & (`shouldBe` input) + input & atNth 0 ?~ "x" & (`shouldBe` [aesonQQ| ["x", "a", "b"] |]) + input & atNth 1 ?~ "x" & (`shouldBe` [aesonQQ| ["a", "x", "b"] |]) + input & atNth 2 ?~ "x" & (`shouldBe` [aesonQQ| ["a", "b", "x"] |]) + input & atNth 3 ?~ "x" & (`shouldBe` input) + + it "removes from arrays by shifting elements left" $ do + let input = [aesonQQ| ["a", "b", "c"] |] + + input & atNth (-1) .~ Nothing & (`shouldBe` input) + input & atNth 0 .~ Nothing & (`shouldBe` [aesonQQ| ["b", "c"] |]) + input & atNth 1 .~ Nothing & (`shouldBe` [aesonQQ| ["a", "c"] |]) + input & atNth 2 .~ Nothing & (`shouldBe` [aesonQQ| ["a", "b"] |]) + input & atNth 3 .~ Nothing & (`shouldBe` input) + + context "targeting an Object" $ do + let input = [aesonQQ| {"0":"a", "1":"b", "2":"c"} |] + + for_ [-1 .. 3] $ \n -> do + let + k = Key.fromString $ show n + index l = input ^? l + add l = input & l ?~ "x" + remove l = input & l .~ Nothing + + it ("indexes like atKey for " <> show n) $ do + index (atNth n) `shouldBe` index (atKey k) + + it ("adds like atKey for " <> show n) $ do + add (atNth n) `shouldBe` add (atKey k) + + it ("removes like atKey for " <> show n) $ do + remove (atNth n) `shouldBe` remove (atKey k) diff --git a/test/Data/JSON/Patch/PointerSpec.hs b/test/Data/JSON/Patch/PointerSpec.hs new file mode 100644 --- /dev/null +++ b/test/Data/JSON/Patch/PointerSpec.hs @@ -0,0 +1,53 @@ +-- | +-- +-- Module : Data.JSON.Patch.PointerSpec +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.JSON.Patch.PointerSpec + ( spec + ) where + +import Prelude + +import Data.JSON.Pointer +import Data.JSON.Pointer.Token +import Test.Hspec + +spec :: Spec +spec = do + describe "pointerFromText" $ do + context "success" $ do + it "empty" $ do + pointerFromText "" `shouldBe` Right PointerEmpty + + it "root-only" $ do + pointerFromText "/" `shouldBe` Right (PointerPath [] $ K "") + + it "path" $ do + pointerFromText "/foo/0/bar/1/baz" + `shouldBe` Right + ( PointerPath + [ K "foo" + , N 0 + , K "bar" + , N 1 + ] + $ K "baz" + ) + + it "path end of array" $ do + pointerFromText "/foo/0/bar/1/-" + `shouldBe` Right + ( PointerPathEnd + [ K "foo" + , N 0 + , K "bar" + , N 1 + ] + ) + + it "handles implementation-specific numeric parsing" $ do + pointerFromText "/1e0" `shouldBe` Right (PointerPath [] $ K "1e0") diff --git a/test/Data/JSON/PatchSpec.hs b/test/Data/JSON/PatchSpec.hs new file mode 100644 --- /dev/null +++ b/test/Data/JSON/PatchSpec.hs @@ -0,0 +1,187 @@ +-- | +-- +-- Module : Data.JSON.PatchSpec +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.JSON.PatchSpec + ( spec + ) where + +import Prelude + +import Control.Exception (displayException) +import Control.Monad (unless, zipWithM_) +import Data.Aeson +import Data.Aeson.Encode.Pretty + ( Config (..) + , Indent (..) + , defConfig + , encodePretty' + ) +import Data.ByteString.Lazy qualified as BSL +import Data.ByteString.Lazy.Char8 qualified as BSL8 +import Data.JSON.Patch +import Data.JSON.Patch.Error +import Data.Maybe (fromMaybe) +import GHC.Int (Int64) +import Path +import System.Exit (exitFailure) +import System.IO (hPutStrLn, stderr) +import Test.Hspec hiding (focus) +import Test.Hspec.Expectations.Json + +data PatchTest = PatchTest + { doc :: Value + , patch :: Value + , expected :: Either String Value + , comment :: Maybe String + , disabled :: Bool + , focus :: Bool + } + +instance FromJSON PatchTest where + parseJSON = withObject "PatchTest" $ \o -> do + doc <- o .: "doc" + patch <- o .: "patch" + expected <- toExpected <$> o .:? "expected" <*> o .:? "error" + comment <- o .:? "comment" + disabled <- o .:? "disabled" .!= False + focus <- o .:? "focus" .!= False + pure PatchTest {doc, patch, expected, comment, disabled, focus} + where + toExpected (Just a) Nothing = Right a + toExpected Nothing (Just b) = Left b + toExpected a b = Left $ "invalid test? expected=" <> show a <> ", error=" <> show b + +runPatchTests :: Path b File -> Spec +runPatchTests path = do + tests <- runIO $ decodeFileThrow @[PatchTest] path + zipWithM_ runPatchTest [0 ..] tests + +runPatchTest :: HasCallStack => Int -> PatchTest -> Spec +runPatchTest n t = do + let + it' + | t.disabled = xit + | t.focus = fit + | otherwise = it + + comment = fromMaybe ("test #" <> show n) t.comment + result = case fromJSON t.patch of + Error err -> Left $ ParseError t.patch err + Success patches -> applyPatches patches t.doc + + it' comment $ case (result, t.expected) of + (Left ex, Left e) -> do + unless (maybe False ($ ex) $ lookup e errorsMap) $ do + expectationFailure + $ unlines + [ "Error " <> show e <> " not known or did not pass predicate" + , "Actual message: " <> displayException ex + ] + (Left ex, Right b) -> + expectationFailure + $ unlines + [ "Error: " <> displayException ex + , " Expected:\n" <> indentedPretty 7 b + , " Doc:\n" <> indentedPretty 7 t.doc + , " Patch:\n" <> indentedPretty 7 t.patch + ] + (Right a, Left e) -> + expectationFailure + $ unlines + [ "Expected error: " <> e + , "Instead got:\n" <> indentedPretty 7 a + , " Doc:\n" <> indentedPretty 7 t.doc + , " Patch:\n" <> indentedPretty 7 t.patch + ] + (Right a, Right b) -> a `shouldMatchJson` b + +spec :: Spec +spec = do + context "json-patch-tests main" $ runPatchTests [relfile|tests.json|] + context "json-patch-tests RFC6092" $ runPatchTests [relfile|spec_tests.json|] + +decodeFileThrow :: FromJSON a => Path b File -> IO a +decodeFileThrow file = do + bytes <- BSL.readFile fp + case eitherDecode bytes of + Left ex -> do + hPutStrLn stderr $ "Invalid JSON: " <> fp <> ":\n" <> ex + exitFailure + Right a -> pure a + where + fp = toFilePath file + +indentedPretty :: ToJSON a => Int64 -> a -> String +indentedPretty n = + BSL8.unpack + . BSL8.unlines + . map (indent <>) + . BSL8.lines + . encodePretty' config + where + indent = BSL8.replicate n ' ' + config = defConfig {confIndent = Spaces 2} + +errorsMap :: [(String, PatchError -> Bool)] +errorsMap = + [ ("JSON Pointer should start with a slash", isParseError) + , ("Object operation on array target", isInvalidObjectOperation) + , ("Out of bounds (lower)", isIndexOutOfBounds) + , ("Out of bounds (upper)", isIndexOutOfBounds) + , ("Unrecognized op 'spam'", isParseError) + , ("add op shouldn't add to array with bad number", isInvalidObjectOperation) + , ("add to a non-existent target", isPointerNotFound) + , ("copy op shouldn't work with bad number", isPointerNotFound) + , ("index is greater than number of items in array", isIndexOutOfBounds) + , ("missing 'from' location", isPointerNotFound) + , ("missing 'from' parameter", isParseError) + , ("missing 'path' parameter", isParseError) + , ("missing 'value' parameter", isParseError) + , ("move op shouldn't work with bad number", isPointerNotFound) + , ("null is not valid value for 'path'", isParseError) + , ("number is not equal to string", isTestFailed) + , + ( "path /a does not exist -- missing objects are not created recursively" + , isPointerNotFound + ) + , ("remove op shouldn't remove from array with bad number", isPointerNotFound) + , ("removing a nonexistent field should fail", isPointerNotFound) + , ("removing a nonexistent index should fail", isPointerNotFound) + , ("replace op should fail with missing parent key", isPointerNotFound) + , ("replace op shouldn't replace in array with bad number", isPointerNotFound) + , ("string not equivalent", isTestFailed) + , ("test op should fail", isTestFailed) + , ("test op should reject the array value, it has leading zeros", isParseError) + , ("test op should reject the array value, it has leading zeros", isParseError) + , ("test op shouldn't get array element 1", isPointerNotFound) + ] + +isParseError :: PatchError -> Bool +isParseError = \case + ParseError {} -> True + _ -> False + +isPointerNotFound :: PatchError -> Bool +isPointerNotFound = \case + PointerNotFound {} -> True + _ -> False + +isInvalidObjectOperation :: PatchError -> Bool +isInvalidObjectOperation = \case + InvalidObjectOperation {} -> True + _ -> False + +isIndexOutOfBounds :: PatchError -> Bool +isIndexOutOfBounds = \case + IndexOutOfBounds {} -> True + _ -> False + +isTestFailed :: PatchError -> Bool +isTestFailed = \case + TestFailed {} -> True + _ -> False diff --git a/test/Data/Vector/ExtSpec.hs b/test/Data/Vector/ExtSpec.hs new file mode 100644 --- /dev/null +++ b/test/Data/Vector/ExtSpec.hs @@ -0,0 +1,45 @@ +-- | +-- +-- Module : Data.Vector.ExtSpec +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX +module Data.Vector.ExtSpec + ( spec + ) where + +import Prelude + +import Data.Vector qualified as V +import Data.Vector.Ext qualified as V +import Test.Hspec + +spec :: Spec +spec = do + describe "deleteAt" $ do + let input = V.fromList "abcd" + + it "deletes an element, shifting later elements left" $ do + V.deleteAt 0 input `shouldBe` V.fromList "bcd" + V.deleteAt 1 input `shouldBe` V.fromList "acd" + V.deleteAt 2 input `shouldBe` V.fromList "abd" + V.deleteAt 3 input `shouldBe` V.fromList "abc" + + it "ignores index out of bound" $ do + V.deleteAt (-1) input `shouldBe` input + V.deleteAt 4 input `shouldBe` input + + describe "insertAt" $ do + let input = V.fromList "abc" + + it "inserts an element, shifting later elements right" $ do + V.insertAt 0 'x' input `shouldBe` V.fromList "xabc" + V.insertAt 1 'x' input `shouldBe` V.fromList "axbc" + V.insertAt 2 'x' input `shouldBe` V.fromList "abxc" + V.insertAt 3 'x' input `shouldBe` V.fromList "abcx" + + it "ignores index out of bound" $ do + V.insertAt (-1) 'x' input `shouldBe` input + V.insertAt 4 'x' input `shouldBe` input diff --git a/test/Spec.hs b/test/Spec.hs new file mode 100644 --- /dev/null +++ b/test/Spec.hs @@ -0,0 +1,10 @@ +{-# OPTIONS_GHC -F -pgmF hspec-discover -Wno-missing-export-lists #-} + +-- | +-- +-- Module : Main +-- Copyright : (c) 2025 Patrick Brisbin +-- License : AGPL-3 +-- Maintainer : pbrisbin@gmail.com +-- Stability : experimental +-- Portability : POSIX diff --git a/tests.json b/tests.json new file mode 100644 --- /dev/null +++ b/tests.json @@ -0,0 +1,1788 @@ +[ + { + "comment": "empty list, empty docs", + "doc": {}, + "patch": [], + "expected": {} + }, + { + "comment": "empty patch list", + "doc": { + "foo": 1 + }, + "patch": [], + "expected": { + "foo": 1 + } + }, + { + "comment": "rearrangements OK?", + "doc": { + "foo": 1, + "bar": 2 + }, + "patch": [], + "expected": { + "bar": 2, + "foo": 1 + } + }, + { + "comment": "rearrangements OK? How about one level down ... array", + "doc": [ + { + "foo": 1, + "bar": 2 + } + ], + "patch": [], + "expected": [ + { + "bar": 2, + "foo": 1 + } + ] + }, + { + "comment": "rearrangements OK? How about one level down...", + "doc": { + "foo": { + "foo": 1, + "bar": 2 + } + }, + "patch": [], + "expected": { + "foo": { + "bar": 2, + "foo": 1 + } + } + }, + { + "comment": "add replaces any existing field", + "doc": { + "foo": null + }, + "patch": [ + { + "op": "add", + "path": "/foo", + "value": 1 + } + ], + "expected": { + "foo": 1 + } + }, + { + "comment": "toplevel array", + "doc": [], + "patch": [ + { + "op": "add", + "path": "/0", + "value": "foo" + } + ], + "expected": [ + "foo" + ] + }, + { + "comment": "toplevel array, no change", + "doc": [ + "foo" + ], + "patch": [], + "expected": [ + "foo" + ] + }, + { + "comment": "toplevel object, numeric string", + "doc": {}, + "patch": [ + { + "op": "add", + "path": "/foo", + "value": "1" + } + ], + "expected": { + "foo": "1" + } + }, + { + "comment": "toplevel object, integer", + "doc": {}, + "patch": [ + { + "op": "add", + "path": "/foo", + "value": 1 + } + ], + "expected": { + "foo": 1 + } + }, + { + "comment": "Toplevel scalar values OK?", + "doc": "foo", + "patch": [ + { + "op": "replace", + "path": "", + "value": "bar" + } + ], + "expected": "bar", + "disabled": true + }, + { + "comment": "replace object document with array document?", + "doc": {}, + "patch": [ + { + "op": "add", + "path": "", + "value": [] + } + ], + "expected": [] + }, + { + "comment": "replace array document with object document?", + "doc": [], + "patch": [ + { + "op": "add", + "path": "", + "value": {} + } + ], + "expected": {} + }, + { + "comment": "append to root array document?", + "doc": [], + "patch": [ + { + "op": "add", + "path": "/-", + "value": "hi" + } + ], + "expected": [ + "hi" + ] + }, + { + "comment": "Add, / target", + "doc": {}, + "patch": [ + { + "op": "add", + "path": "/", + "value": 1 + } + ], + "expected": { + "": 1 + } + }, + { + "comment": "Add, /foo/ deep target (trailing slash)", + "doc": { + "foo": {} + }, + "patch": [ + { + "op": "add", + "path": "/foo/", + "value": 1 + } + ], + "expected": { + "foo": { + "": 1 + } + } + }, + { + "comment": "Add composite value at top level", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "add", + "path": "/bar", + "value": [ + 1, + 2 + ] + } + ], + "expected": { + "foo": 1, + "bar": [ + 1, + 2 + ] + } + }, + { + "comment": "Add into composite value", + "doc": { + "foo": 1, + "baz": [ + { + "qux": "hello" + } + ] + }, + "patch": [ + { + "op": "add", + "path": "/baz/0/foo", + "value": "world" + } + ], + "expected": { + "foo": 1, + "baz": [ + { + "qux": "hello", + "foo": "world" + } + ] + } + }, + { + "doc": { + "bar": [ + 1, + 2 + ] + }, + "patch": [ + { + "op": "add", + "path": "/bar/8", + "value": "5" + } + ], + "error": "Out of bounds (upper)" + }, + { + "doc": { + "bar": [ + 1, + 2 + ] + }, + "patch": [ + { + "op": "add", + "path": "/bar/-1", + "value": "5" + } + ], + "error": "Out of bounds (lower)" + }, + { + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "add", + "path": "/bar", + "value": true + } + ], + "expected": { + "foo": 1, + "bar": true + } + }, + { + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "add", + "path": "/bar", + "value": false + } + ], + "expected": { + "foo": 1, + "bar": false + } + }, + { + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "add", + "path": "/bar", + "value": null + } + ], + "expected": { + "foo": 1, + "bar": null + } + }, + { + "comment": "0 can be an array index or object element name", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "add", + "path": "/0", + "value": "bar" + } + ], + "expected": { + "foo": 1, + "0": "bar" + } + }, + { + "doc": [ + "foo" + ], + "patch": [ + { + "op": "add", + "path": "/1", + "value": "bar" + } + ], + "expected": [ + "foo", + "bar" + ] + }, + { + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "add", + "path": "/1", + "value": "bar" + } + ], + "expected": [ + "foo", + "bar", + "sil" + ] + }, + { + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "add", + "path": "/0", + "value": "bar" + } + ], + "expected": [ + "bar", + "foo", + "sil" + ] + }, + { + "comment": "push item to array via last index + 1", + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "add", + "path": "/2", + "value": "bar" + } + ], + "expected": [ + "foo", + "sil", + "bar" + ] + }, + { + "comment": "add item to array at index > length should fail", + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "add", + "path": "/3", + "value": "bar" + } + ], + "error": "index is greater than number of items in array" + }, + { + "comment": "test against implementation-specific numeric parsing", + "doc": { + "1e0": "foo" + }, + "patch": [ + { + "op": "test", + "path": "/1e0", + "value": "foo" + } + ], + "expected": { + "1e0": "foo" + } + }, + { + "comment": "test with bad number should fail", + "doc": [ + "foo", + "bar" + ], + "patch": [ + { + "op": "test", + "path": "/1e0", + "value": "bar" + } + ], + "error": "test op shouldn't get array element 1" + }, + { + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "add", + "path": "/bar", + "value": 42 + } + ], + "error": "Object operation on array target" + }, + { + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "add", + "path": "/1", + "value": [ + "bar", + "baz" + ] + } + ], + "expected": [ + "foo", + [ + "bar", + "baz" + ], + "sil" + ], + "comment": "value in array add not flattened" + }, + { + "doc": { + "foo": 1, + "bar": [ + 1, + 2, + 3, + 4 + ] + }, + "patch": [ + { + "op": "remove", + "path": "/bar" + } + ], + "expected": { + "foo": 1 + } + }, + { + "doc": { + "foo": 1, + "baz": [ + { + "qux": "hello" + } + ] + }, + "patch": [ + { + "op": "remove", + "path": "/baz/0/qux" + } + ], + "expected": { + "foo": 1, + "baz": [ + {} + ] + } + }, + { + "doc": { + "foo": 1, + "baz": [ + { + "qux": "hello" + } + ] + }, + "patch": [ + { + "op": "replace", + "path": "/foo", + "value": [ + 1, + 2, + 3, + 4 + ] + } + ], + "expected": { + "foo": [ + 1, + 2, + 3, + 4 + ], + "baz": [ + { + "qux": "hello" + } + ] + } + }, + { + "doc": { + "foo": [ + 1, + 2, + 3, + 4 + ], + "baz": [ + { + "qux": "hello" + } + ] + }, + "patch": [ + { + "op": "replace", + "path": "/baz/0/qux", + "value": "world" + } + ], + "expected": { + "foo": [ + 1, + 2, + 3, + 4 + ], + "baz": [ + { + "qux": "world" + } + ] + } + }, + { + "doc": [ + "foo" + ], + "patch": [ + { + "op": "replace", + "path": "/0", + "value": "bar" + } + ], + "expected": [ + "bar" + ] + }, + { + "doc": [ + "" + ], + "patch": [ + { + "op": "replace", + "path": "/0", + "value": 0 + } + ], + "expected": [ + 0 + ] + }, + { + "doc": [ + "" + ], + "patch": [ + { + "op": "replace", + "path": "/0", + "value": true + } + ], + "expected": [ + true + ] + }, + { + "doc": [ + "" + ], + "patch": [ + { + "op": "replace", + "path": "/0", + "value": false + } + ], + "expected": [ + false + ] + }, + { + "doc": [ + "" + ], + "patch": [ + { + "op": "replace", + "path": "/0", + "value": null + } + ], + "expected": [ + null + ] + }, + { + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "replace", + "path": "/1", + "value": [ + "bar", + "baz" + ] + } + ], + "expected": [ + "foo", + [ + "bar", + "baz" + ] + ], + "comment": "value in array replace not flattened" + }, + { + "comment": "replace whole document", + "doc": { + "foo": "bar" + }, + "patch": [ + { + "op": "replace", + "path": "", + "value": { + "baz": "qux" + } + } + ], + "expected": { + "baz": "qux" + } + }, + { + "comment": "test replace with missing parent key should fail", + "doc": { + "bar": "baz" + }, + "patch": [ + { + "op": "replace", + "path": "/foo/bar", + "value": false + } + ], + "error": "replace op should fail with missing parent key" + }, + { + "comment": "spurious patch properties", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "test", + "path": "/foo", + "value": 1, + "spurious": 1 + } + ], + "expected": { + "foo": 1 + } + }, + { + "doc": { + "foo": null + }, + "patch": [ + { + "op": "test", + "path": "/foo", + "value": null + } + ], + "expected": { + "foo": null + }, + "comment": "null value should be valid obj property" + }, + { + "doc": { + "foo": null + }, + "patch": [ + { + "op": "replace", + "path": "/foo", + "value": "truthy" + } + ], + "expected": { + "foo": "truthy" + }, + "comment": "null value should be valid obj property to be replaced with something truthy" + }, + { + "doc": { + "foo": null + }, + "patch": [ + { + "op": "move", + "from": "/foo", + "path": "/bar" + } + ], + "expected": { + "bar": null + }, + "comment": "null value should be valid obj property to be moved" + }, + { + "doc": { + "foo": null + }, + "patch": [ + { + "op": "copy", + "from": "/foo", + "path": "/bar" + } + ], + "expected": { + "foo": null, + "bar": null + }, + "comment": "null value should be valid obj property to be copied" + }, + { + "doc": { + "foo": null + }, + "patch": [ + { + "op": "remove", + "path": "/foo" + } + ], + "expected": {}, + "comment": "null value should be valid obj property to be removed" + }, + { + "doc": { + "foo": "bar" + }, + "patch": [ + { + "op": "replace", + "path": "/foo", + "value": null + } + ], + "expected": { + "foo": null + }, + "comment": "null value should still be valid obj property replace other value" + }, + { + "doc": { + "foo": { + "foo": 1, + "bar": 2 + } + }, + "patch": [ + { + "op": "test", + "path": "/foo", + "value": { + "bar": 2, + "foo": 1 + } + } + ], + "expected": { + "foo": { + "foo": 1, + "bar": 2 + } + }, + "comment": "test should pass despite rearrangement" + }, + { + "doc": { + "foo": [ + { + "foo": 1, + "bar": 2 + } + ] + }, + "patch": [ + { + "op": "test", + "path": "/foo", + "value": [ + { + "bar": 2, + "foo": 1 + } + ] + } + ], + "expected": { + "foo": [ + { + "foo": 1, + "bar": 2 + } + ] + }, + "comment": "test should pass despite (nested) rearrangement" + }, + { + "doc": { + "foo": { + "bar": [ + 1, + 2, + 5, + 4 + ] + } + }, + "patch": [ + { + "op": "test", + "path": "/foo", + "value": { + "bar": [ + 1, + 2, + 5, + 4 + ] + } + } + ], + "expected": { + "foo": { + "bar": [ + 1, + 2, + 5, + 4 + ] + } + }, + "comment": "test should pass - no error" + }, + { + "doc": { + "foo": { + "bar": [ + 1, + 2, + 5, + 4 + ] + } + }, + "patch": [ + { + "op": "test", + "path": "/foo", + "value": [ + 1, + 2 + ] + } + ], + "error": "test op should fail" + }, + { + "comment": "Whole document", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "test", + "path": "", + "value": { + "foo": 1 + } + } + ], + "disabled": true + }, + { + "comment": "Empty-string element", + "doc": { + "": 1 + }, + "patch": [ + { + "op": "test", + "path": "/", + "value": 1 + } + ], + "expected": { + "": 1 + } + }, + { + "doc": { + "foo": [ + "bar", + "baz" + ], + "": 0, + "a/b": 1, + "c%d": 2, + "e^f": 3, + "g|h": 4, + "i\\j": 5, + "k\"l": 6, + " ": 7, + "m~n": 8 + }, + "patch": [ + { + "op": "test", + "path": "/foo", + "value": [ + "bar", + "baz" + ] + }, + { + "op": "test", + "path": "/foo/0", + "value": "bar" + }, + { + "op": "test", + "path": "/", + "value": 0 + }, + { + "op": "test", + "path": "/a~1b", + "value": 1 + }, + { + "op": "test", + "path": "/c%d", + "value": 2 + }, + { + "op": "test", + "path": "/e^f", + "value": 3 + }, + { + "op": "test", + "path": "/g|h", + "value": 4 + }, + { + "op": "test", + "path": "/i\\j", + "value": 5 + }, + { + "op": "test", + "path": "/k\"l", + "value": 6 + }, + { + "op": "test", + "path": "/ ", + "value": 7 + }, + { + "op": "test", + "path": "/m~0n", + "value": 8 + } + ], + "expected": { + "": 0, + " ": 7, + "a/b": 1, + "c%d": 2, + "e^f": 3, + "foo": [ + "bar", + "baz" + ], + "g|h": 4, + "i\\j": 5, + "k\"l": 6, + "m~n": 8 + } + }, + { + "comment": "Move to same location has no effect", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "move", + "from": "/foo", + "path": "/foo" + } + ], + "expected": { + "foo": 1 + } + }, + { + "doc": { + "foo": 1, + "baz": [ + { + "qux": "hello" + } + ] + }, + "patch": [ + { + "op": "move", + "from": "/foo", + "path": "/bar" + } + ], + "expected": { + "baz": [ + { + "qux": "hello" + } + ], + "bar": 1 + } + }, + { + "doc": { + "baz": [ + { + "qux": "hello" + } + ], + "bar": 1 + }, + "patch": [ + { + "op": "move", + "from": "/baz/0/qux", + "path": "/baz/1" + } + ], + "expected": { + "baz": [ + {}, + "hello" + ], + "bar": 1 + } + }, + { + "doc": { + "baz": [ + { + "qux": "hello" + } + ], + "bar": 1 + }, + "patch": [ + { + "op": "copy", + "from": "/baz/0", + "path": "/boo" + } + ], + "expected": { + "baz": [ + { + "qux": "hello" + } + ], + "bar": 1, + "boo": { + "qux": "hello" + } + } + }, + { + "comment": "replacing the root of the document is possible with add", + "doc": { + "foo": "bar" + }, + "patch": [ + { + "op": "add", + "path": "", + "value": { + "baz": "qux" + } + } + ], + "expected": { + "baz": "qux" + } + }, + { + "comment": "Adding to \"/-\" adds to the end of the array", + "doc": [ + 1, + 2 + ], + "patch": [ + { + "op": "add", + "path": "/-", + "value": { + "foo": [ + "bar", + "baz" + ] + } + } + ], + "expected": [ + 1, + 2, + { + "foo": [ + "bar", + "baz" + ] + } + ] + }, + { + "comment": "Adding to \"/-\" adds to the end of the array, even n levels down", + "doc": [ + 1, + 2, + [ + 3, + [ + 4, + 5 + ] + ] + ], + "patch": [ + { + "op": "add", + "path": "/2/1/-", + "value": { + "foo": [ + "bar", + "baz" + ] + } + } + ], + "expected": [ + 1, + 2, + [ + 3, + [ + 4, + 5, + { + "foo": [ + "bar", + "baz" + ] + } + ] + ] + ] + }, + { + "comment": "test remove with bad number should fail", + "doc": { + "foo": 1, + "baz": [ + { + "qux": "hello" + } + ] + }, + "patch": [ + { + "op": "remove", + "path": "/baz/1e0/qux" + } + ], + "error": "remove op shouldn't remove from array with bad number" + }, + { + "comment": "test remove on array", + "doc": [ + 1, + 2, + 3, + 4 + ], + "patch": [ + { + "op": "remove", + "path": "/0" + } + ], + "expected": [ + 2, + 3, + 4 + ] + }, + { + "comment": "test repeated removes", + "doc": [ + 1, + 2, + 3, + 4 + ], + "patch": [ + { + "op": "remove", + "path": "/1" + }, + { + "op": "remove", + "path": "/2" + } + ], + "expected": [ + 1, + 3 + ] + }, + { + "comment": "test remove with bad index should fail", + "doc": [ + 1, + 2, + 3, + 4 + ], + "patch": [ + { + "op": "remove", + "path": "/1e0" + } + ], + "error": "remove op shouldn't remove from array with bad number" + }, + { + "comment": "test replace with bad number should fail", + "doc": [ + "" + ], + "patch": [ + { + "op": "replace", + "path": "/1e0", + "value": false + } + ], + "error": "replace op shouldn't replace in array with bad number" + }, + { + "comment": "test copy with bad number should fail", + "doc": { + "baz": [ + 1, + 2, + 3 + ], + "bar": 1 + }, + "patch": [ + { + "op": "copy", + "from": "/baz/1e0", + "path": "/boo" + } + ], + "error": "copy op shouldn't work with bad number" + }, + { + "comment": "test move with bad number should fail", + "doc": { + "foo": 1, + "baz": [ + 1, + 2, + 3, + 4 + ] + }, + "patch": [ + { + "op": "move", + "from": "/baz/1e0", + "path": "/foo" + } + ], + "error": "move op shouldn't work with bad number" + }, + { + "comment": "test add with bad number should fail", + "doc": [ + "foo", + "sil" + ], + "patch": [ + { + "op": "add", + "path": "/1e0", + "value": "bar" + } + ], + "error": "add op shouldn't add to array with bad number" + }, + { + "comment": "missing 'path' parameter", + "doc": {}, + "patch": [ + { + "op": "add", + "value": "bar" + } + ], + "error": "missing 'path' parameter" + }, + { + "comment": "'path' parameter with null value", + "doc": {}, + "patch": [ + { + "op": "add", + "path": null, + "value": "bar" + } + ], + "error": "null is not valid value for 'path'" + }, + { + "comment": "invalid JSON Pointer token", + "doc": {}, + "patch": [ + { + "op": "add", + "path": "foo", + "value": "bar" + } + ], + "error": "JSON Pointer should start with a slash" + }, + { + "comment": "missing 'value' parameter to add", + "doc": [ + 1 + ], + "patch": [ + { + "op": "add", + "path": "/-" + } + ], + "error": "missing 'value' parameter" + }, + { + "comment": "missing 'value' parameter to replace", + "doc": [ + 1 + ], + "patch": [ + { + "op": "replace", + "path": "/0" + } + ], + "error": "missing 'value' parameter" + }, + { + "comment": "missing 'value' parameter to test", + "doc": [ + null + ], + "patch": [ + { + "op": "test", + "path": "/0" + } + ], + "error": "missing 'value' parameter" + }, + { + "comment": "missing value parameter to test - where undef is falsy", + "doc": [ + false + ], + "patch": [ + { + "op": "test", + "path": "/0" + } + ], + "error": "missing 'value' parameter" + }, + { + "comment": "missing from parameter to copy", + "doc": [ + 1 + ], + "patch": [ + { + "op": "copy", + "path": "/-" + } + ], + "error": "missing 'from' parameter" + }, + { + "comment": "missing from location to copy", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "copy", + "from": "/bar", + "path": "/foo" + } + ], + "error": "missing 'from' location" + }, + { + "comment": "missing from parameter to move", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "move", + "path": "" + } + ], + "error": "missing 'from' parameter" + }, + { + "comment": "missing from location to move", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "move", + "from": "/bar", + "path": "/foo" + } + ], + "error": "missing 'from' location" + }, + { + "comment": "duplicate ops", + "doc": { + "foo": "bar" + }, + "patch": [ + { + "op": "move", + "path": "/baz", + "value": "qux", + "from": "/foo" + } + ], + "error": "patch has two 'op' members", + "disabled": true + }, + { + "comment": "unrecognized op should fail", + "doc": { + "foo": 1 + }, + "patch": [ + { + "op": "spam", + "path": "/foo", + "value": 1 + } + ], + "error": "Unrecognized op 'spam'" + }, + { + "comment": "test with bad array number that has leading zeros", + "doc": [ + "foo", + "bar" + ], + "patch": [ + { + "op": "test", + "path": "/00", + "value": "foo" + } + ], + "error": "test op should reject the array value, it has leading zeros" + }, + { + "comment": "test with bad array number that has leading zeros", + "doc": [ + "foo", + "bar" + ], + "patch": [ + { + "op": "test", + "path": "/01", + "value": "bar" + } + ], + "error": "test op should reject the array value, it has leading zeros" + }, + { + "comment": "Removing nonexistent field", + "doc": { + "foo": "bar" + }, + "patch": [ + { + "op": "remove", + "path": "/baz" + } + ], + "error": "removing a nonexistent field should fail" + }, + { + "comment": "Removing deep nonexistent path", + "doc": { + "foo": "bar" + }, + "patch": [ + { + "op": "remove", + "path": "/missing1/missing2" + } + ], + "error": "removing a nonexistent field should fail" + }, + { + "comment": "Removing nonexistent index", + "doc": [ + "foo", + "bar" + ], + "patch": [ + { + "op": "remove", + "path": "/2" + } + ], + "error": "removing a nonexistent index should fail" + }, + { + "comment": "Patch with different capitalisation than doc", + "doc": { + "foo": "bar" + }, + "patch": [ + { + "op": "add", + "path": "/FOO", + "value": "BAR" + } + ], + "expected": { + "foo": "bar", + "FOO": "BAR" + } + }, + { + "comment": "test copy object then change destination", + "doc": { + "foo": { + "bar": { + "baz": [ + { + "boo": "net" + } + ] + } + } + }, + "patch": [ + { + "op": "copy", + "from": "/foo", + "path": "/bak" + }, + { + "op": "replace", + "path": "/bak/bar/baz/0/boo", + "value": "qux" + } + ], + "expected": { + "foo": { + "bar": { + "baz": [ + { + "boo": "net" + } + ] + } + }, + "bak": { + "bar": { + "baz": [ + { + "boo": "qux" + } + ] + } + } + } + }, + { + "comment": "test copy object then change source", + "doc": { + "foo": { + "bar": { + "baz": [ + { + "boo": "net" + } + ] + } + } + }, + "patch": [ + { + "op": "copy", + "from": "/foo", + "path": "/bak" + }, + { + "op": "replace", + "path": "/foo/bar/baz/0/boo", + "value": "qux" + } + ], + "expected": { + "foo": { + "bar": { + "baz": [ + { + "boo": "qux" + } + ] + } + }, + "bak": { + "bar": { + "baz": [ + { + "boo": "net" + } + ] + } + } + } + } +]