{"id":16664235,"url":"https://github.com/glguy/toml-parser","last_synced_at":"2025-03-17T00:31:28.794Z","repository":{"id":20544223,"uuid":"90115655","full_name":"glguy/toml-parser","owner":"glguy","description":"Haskell parser and printer for the TOML 1.0.0 file format","archived":false,"fork":false,"pushed_at":"2024-07-10T03:58:46.000Z","size":409,"stargazers_count":25,"open_issues_count":0,"forks_count":7,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-10-13T10:44:32.215Z","etag":null,"topics":["haskell","toml"],"latest_commit_sha":null,"homepage":"https://hackage.haskell.org/package/toml-parser","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glguy.png","metadata":{"files":{"readme":"README.lhs","changelog":"ChangeLog.md","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-03T06:27:38.000Z","updated_at":"2024-08-09T20:31:59.000Z","dependencies_parsed_at":"2024-01-18T00:20:39.747Z","dependency_job_id":"d6b2b1fa-7319-424f-a766-b15fa994ba42","html_url":"https://github.com/glguy/toml-parser","commit_stats":{"total_commits":26,"total_committers":4,"mean_commits":6.5,"dds":0.6153846153846154,"last_synced_commit":"a338e635292fa96dbcf15313f0a27c3ae1110d1f"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glguy%2Ftoml-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glguy%2Ftoml-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glguy%2Ftoml-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glguy%2Ftoml-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glguy","download_url":"https://codeload.github.com/glguy/toml-parser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221669218,"owners_count":16860837,"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":["haskell","toml"],"created_at":"2024-10-12T10:44:19.398Z","updated_at":"2024-10-27T11:34:30.561Z","avatar_url":"https://github.com/glguy.png","language":"Haskell","readme":"# TOML Parser\n\nThis package implements a validating parser for [TOML 1.0.0](https://toml.io/en/v1.0.0).\n\nThis package uses an [alex](https://haskell-alex.readthedocs.io/en/latest/)-generated\nlexer and [happy](https://haskell-happy.readthedocs.io/en/latest/)-generated parser.\n\nIt also provides a pair of classes for serializing into and out of TOML.\n\n## Package Structure\n\n```mermaid\n---\ntitle: Package Structure\n---\nstateDiagram-v2\n    classDef important font-weight:bold;\n\n    TOML:::important --\u003e ApplicationTypes:::important : decode\n    ApplicationTypes --\u003e TOML : encode\n    TOML --\u003e [Token]: Lexer\n    [Token] --\u003e [Expr]: Parser\n    [Expr] --\u003e Table : Semantics\n    Table --\u003e ApplicationTypes : FromValue\n    ApplicationTypes --\u003e Table : ToValue\n    Table --\u003e TOML : Pretty\n```\n\nMost users will only need to import **Toml** or **Toml.Schema**. Other top-level\nmodules are for low-level hacking on the TOML format itself. All modules below\nthese top-level modules are exposed to provide direct access to library implementation\ndetails.\n\n- **Toml** - Basic encoding and decoding TOML\n- **Toml.Schema** - TOML schemas for application types\n- **Toml.Semantics** - Low-level semantic operations on TOML syntax\n- **Toml.Syntax** - Low-level parsing of text into TOML raw syntax\n\n## Examples\n\nThis file uses [markdown-unlit](https://hackage.haskell.org/package/markdown-unlit)\nto ensure that its code typechecks and stays in sync with the rest of the package.\n\n```haskell\n{-# Language OverloadedStrings #-}\nimport Data.Text (Text)\nimport GHC.Generics (Generic)\nimport QuoteStr (quoteStr)\nimport Test.Hspec (Spec, hspec, it, shouldBe)\nimport Toml\nimport Toml.Schema\n\nmain :: IO ()\nmain = hspec (parses \u003e\u003e decodes \u003e\u003e encodes \u003e\u003e warns \u003e\u003e errors)\n```\n\n### Using the raw parser\n\nConsider this sample TOML text from the TOML specification.\n\n```haskell\nfruitStr :: Text\nfruitStr = [quoteStr|\n```\n\n```toml\n[[fruits]]\nname = \"apple\"\n\n[fruits.physical]  # subtable\ncolor = \"red\"\nshape = \"round\"\n\n[[fruits.varieties]]  # nested array of tables\nname = \"red delicious\"\n\n[[fruits.varieties]]\nname = \"granny smith\"\n\n\n[[fruits]]\nname = \"banana\"\n\n[[fruits.varieties]]\nname = \"plantain\"\n```\n\n```haskell\n|]\n```\n\nParsing using this package generates the following unstructured value\n\n```haskell\nparses :: Spec\nparses = it \"parses\" $\n    forgetTableAnns \u003c$\u003e parse fruitStr\n    `shouldBe`\n    Right (table [\n        (\"fruits\", List [\n            Table (table [\n                (\"name\", Text \"apple\"),\n                (\"physical\", Table (table [\n                    (\"color\", Text \"red\"),\n                    (\"shape\", Text \"round\")])),\n                (\"varieties\", List [\n                    Table (table [(\"name\", Text \"red delicious\")]),\n                    Table (table [(\"name\", Text \"granny smith\")])])]),\n            Table (table [\n                (\"name\", Text \"banana\"),\n                (\"varieties\", List [\n                    Table (table [(\"name\", Text \"plantain\")])])])])])\n```\n\n### Defining a schema\n\nWe can define a schema for our TOML format in the form of instances of\n`FromValue`, `ToValue`, and `ToTable` in order to read TOML directly\ninto structured data form. This example manually derives some of the\ninstances as a demonstration.\n\n```haskell\nnewtype Fruits = Fruits { fruits :: [Fruit] }\n    deriving (Eq, Show, Generic)\n    deriving (ToTable, ToValue, FromValue) via GenericTomlTable Fruits\n\ndata Fruit = Fruit { name :: String, physical :: Maybe Physical, varieties :: [Variety] }\n    deriving (Eq, Show, Generic)\n    deriving (ToTable, ToValue, FromValue) via GenericTomlTable Fruit\n\ndata Physical = Physical { color :: String, shape :: String }\n    deriving (Eq, Show, Generic)\n    deriving (ToTable, ToValue, FromValue) via GenericTomlTable Physical\n\nnewtype Variety = Variety String\n    deriving (Eq, Show)\n\ninstance FromValue Variety where\n    fromValue = parseTableFromValue (Variety \u003c$\u003e reqKey \"name\")\ninstance ToValue Variety where\n    toValue = defaultTableToValue\ninstance ToTable Variety where\n    toTable (Variety x) = table [\"name\" .= x]\n\n```\n\nWe can run this example on the original value to deserialize it into domain-specific datatypes.\n\n```haskell\ndecodes :: Spec\ndecodes = it \"decodes\" $\n    decode fruitStr\n    `shouldBe`\n    Success [] (Fruits [\n        Fruit\n            \"apple\"\n            (Just (Physical \"red\" \"round\"))\n            [Variety \"red delicious\", Variety \"granny smith\"],\n        Fruit \"banana\" Nothing [Variety \"plantain\"]])\n\nencodes :: Spec\nencodes = it \"encodes\" $\n    show (encode (Fruits [Fruit\n            \"apple\"\n            (Just (Physical \"red\" \"round\"))\n            [Variety \"red delicious\", Variety \"granny smith\"]]))\n    `shouldBe` [quoteStr|\n        [[fruits]]\n        name = \"apple\"\n\n        [fruits.physical]\n        color = \"red\"\n        shape = \"round\"\n\n        [[fruits.varieties]]\n        name = \"red delicious\"\n\n        [[fruits.varieties]]\n        name = \"granny smith\"|]\n```\n\n### Useful errors and warnings\n\nThis package takes care to preserve source information as much as possible\nin order to provide useful feedback to users. These examples show a couple\nof the message that can be generated when things don't go perfectly.\n\n```haskell\nwarns :: Spec\nwarns = it \"warns\" $\n    decode [quoteStr|\n        name = \"simulated\"\n        typo = 10|]\n    `shouldBe`\n    Success\n        [\"2:1: unexpected key: typo in \u003ctop-level\u003e\"] -- warnings\n        (Variety \"simulated\")\n\nerrors :: Spec\nerrors = it \"errors\" $\n    decode [quoteStr|\n        # Physical characteristics table\n        color = \"blue\"\n        shape = []|]\n    `shouldBe`\n    (Failure\n        [\"3:9: expected string but got array in shape\"]\n        :: Result String Physical)\n```\n\n## More Examples\n\nA demonstration of using this package at a more realistic scale\ncan be found in [HieDemoSpec](test/HieDemoSpec.hs). The various unit\ntest files demonstrate what you can do with this library and what\noutputs you can expect.\n\nSee the low-level operations used to build a TOML syntax highlighter\nin [TomlHighlighter](test-drivers/highlighter/Main.hs).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglguy%2Ftoml-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglguy%2Ftoml-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglguy%2Ftoml-parser/lists"}