{"id":13410539,"url":"https://github.com/Componolit/SXML","last_synced_at":"2025-03-14T16:32:41.923Z","repository":{"id":107366313,"uuid":"135038084","full_name":"Componolit/SXML","owner":"Componolit","description":"Formally verified, bounded-stack XML library","archived":false,"fork":false,"pushed_at":"2020-05-26T13:27:49.000Z","size":72653,"stargazers_count":21,"open_issues_count":6,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-07-31T20:43:07.044Z","etag":null,"topics":["ada","formal-methods","formal-verification","parser","spark","xml"],"latest_commit_sha":null,"homepage":"","language":"Ada","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Componolit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-05-27T10:55:08.000Z","updated_at":"2024-01-18T02:30:20.000Z","dependencies_parsed_at":"2023-05-17T06:30:59.647Z","dependency_job_id":null,"html_url":"https://github.com/Componolit/SXML","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Componolit%2FSXML","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Componolit%2FSXML/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Componolit%2FSXML/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Componolit%2FSXML/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Componolit","download_url":"https://codeload.github.com/Componolit/SXML/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243610314,"owners_count":20318940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ada","formal-methods","formal-verification","parser","spark","xml"],"created_at":"2024-07-30T20:01:07.557Z","updated_at":"2025-03-14T16:32:41.889Z","avatar_url":"https://github.com/Componolit.png","language":"Ada","funding_links":[],"categories":["Libraries"],"sub_categories":["Format Readers and Writers","Format Readers, Writers and Checkers"],"readme":"# SXML: A formally verified XML library in SPARK.\n\n[![Build Status](https://travis-ci.org/Componolit/SXML.svg?branch=master)](https://travis-ci.org/Componolit/SXML)\n\nSXML is an XML library implemented in pure\n[SPARK 2014](https://www.adacore.com/about-spark). Absence of runtime errors\nand bounded stack usage have been proven for the library. This makes it a ideal\nchoice for processing information of untrusted origin.\n\nThe full API documentation is available in [doc/api/index.html](doc/api/index.html).\n\n## Structure\n\nThe library consists of four parts: the generator, the parser, the serializer\nand the query interface.\n\n### SXML.Generator\n\nThe generator interface allows for declaring XML documents directly inside\nSPARK code. This is much more concise and safe than constructing an XML\ndocument by consecutive calls to API functions.\n\nConstructors for elements (`E`), for attributes (`A`) and for content (`C`) can\nbe combined using the combination operator (`+`). The following XML document is\nto be declared using the SXML generator:\n\n```XML\n\u003cconfig\u003e\n  \u003creport delay_ms=\"500\"/\u003e\n  \u003cparent-provides\u003e\n    \u003cservice name=\"CAP\"/\u003e\n    \u003cservice name=\"CPU\"\u003eSome content\u003c/service\u003e\n  \u003c/parent-provides\u003e\n\u003c/config\u003e\n```\n\nThe declaration is analogous to the XML document:\n\n```Ada\nwith SXML.Generator;\n\nprocedure Simple\nis\n   use SXML.Generator;\nbegin\n   Document : Document_Type :=\n   E (\"config\",\n     E (\"report\", A (\"delay_ms\", 500)) +\n     E (\"parent-provides\",\n       E (\"service\", A (\"name\", \"CAP\")) +\n       E (\"service\", A (\"name\", \"CPU\"), C (\"Some content\"))\n     )\n   );\n\nend Simple;\n```\n\nRefer to the sections on serialization and querying on how to use the resulting\ndocument.\n\n### SXML.Parser\n\nThis interface parses an XML document from its textual representations.\nParsing documents is very simple:\n\n```Ada\nwith SXML.Parser;\n\nprocedure Parse\nis\n   use SXML.Parser;\n   Input : String :=\n     \"\u003cconfig\u003e\"\n   \u0026 \"   \u003creport delay_ms=\"\"500\"\"/\u003e\"\n   \u0026 \"   \u003cparent-provides\u003e\"\n   \u0026 \"      \u003cservice name=\"\"CAP\"\"/\u003e\"\n   \u0026 \"      \u003cservice name=\"\"CPU\"\"\u003eSome content\u003c/service\u003e\"\n   \u0026 \"   \u003c/parent-provides\u003e\"\n   \u0026 \"\u003c/config\u003e\";\n   Document : SXML.Document_Type (1 .. 100) := (others =\u003e SXML.Null_Node);\n   Result   : Match_Type;\n   Position : Natural;\nbegin\n   Parse (Data         =\u003e Input,\n          Document     =\u003e Document,\n          Parse_Result =\u003e Result,\n          Position     =\u003e Position);\n   if Result /= Match_OK\n   then\n      null;\n   end if;\nend Parse;\n```\n\n### SXML.Query\n\nThe query interface operates on a document (`SXML.Document_Type`) that was\nparsed or constructed. There is a low level API that works on a state object of\ntype `SXML.Query.State_Type`. Before using the API, the state is initialized\nfor the document to be queried using the `Init` function. There are a number of\noperations to navigate through the document and return data:\n\n| **Operation**  | **Description**                         |\n|:---------------|:----------------------------------------|\n| Name           | Return name for current node            |\n| Child          | Get child node of current node          |\n| Sibling        | Get sibling node of current node        |\n| Find_Sibling   | Find sibling of current node by name    |\n| Attribute      | Get first attribute of an opening node  |\n| Value          | Return value of current attribute       |\n| Next_Attribute | Get next attribute of current attribute |\n| Find_Attribute | Find attribute of current node by name  |\n\nAll operations have a result output parameter of type `Result_Type` indicating\nwhether the operation was successful, the data was not found (e.g. signaling\nthe last attribute of an element) or that an error occurred.\n\nA more convenient way to obtain an element inside a document is the `Path`\noperation. It receives a simple path as a string argument pointing to an\nelement starting from the root of the document, e.g. `/root/child/grandchild`.\nAs of now, exactly one element can be referenced in a path query. Attributes\ncan subsequently be queried using the `Find_Attribute` operation.\n\n### SXML.Serialize\n\nThe serialization operation `To_String` converts a document into it's string\nrepresentation. The result is stored into a fixed buffer which must be large\nenough to hold the result.\n\n# Validation and Verification\n\nA number of measures have been adopted to ensure that SXML correctly handles\nXML files and that it does not crash when exposed to malicious data. We prove\nthe absence of runtime errors using `gnatprove` and bounded stack usage with\n`gnatstack` (except for SXML.Generator which is inherently unbounded). We\nfuzzed the parser and serializer using American Fuzzy Lop (AFL) for more than\n200 million executions without any crash or hang. A test suite with more than\n3000 tests is available to test conformance of the parser.\n\n## Absence of Runtime Errors\n\nTo prove and build the library just type `make` in the root of the source\ndirectory. The GNAT and SPARK toolset (Pro 20 or Community 2019) must be\ninstalled and in your path.\n\n## Bounded Stack Usage\n\nTo show stack usage run `make stack` in the root of the source directory. The\n`gnatstack` tool (part of GNAT Pro) must be installed.\n\n## Fuzzing\n\nTo fuzz the parser using AFL with the included `fuzzdriver` program, run `make\nfuzz` in the root of the source directory. AFL must be installed.\n\n## Tests\n\nTo run the unit tests only, type `make testonly` in the root of the source\ndirectory. For the slightly bigger test suite including parser tests, type\n`make testbulk` and for the full test suite run `make testinsane` (this will\ndownload many large files from the Internet).\n\n# Limitations\n\nThe largest name that can be found using `SXML.Query.Find_Attribute` and\n`SXML.Query.Find_Sibling` is currently limited to 1024 characters due to an\ninternal fixed-size buffer that is used.\n\nSpecial XML sections like CDATA, comments, DOCTYPE and procession information\nare accepted by the parser, but ignored by all other parts of SXML.\n\nAs the constructor and combinator functions in `SXML.Generator` return\nunbounded arrays of type `Document_Type` and `Attributes_Type`, those functions\nare not bounded in stack usage. When using the generator interface, make sure\nto use static inputs and manually review stack usage to prevent stack overflows.\n\n# Authors and License\n\nAdrian-Ken Rueegsegger (@Kensan), Alexander Senier (@senier)\n\nThis code is distributed under the terms of the GNU Affero General Public\nLicense version 3, see LICENSE for details. Send email to sxml@componolit.com\nfor commercial licensing and support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FComponolit%2FSXML","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FComponolit%2FSXML","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FComponolit%2FSXML/lists"}