{"id":13509772,"url":"https://github.com/yakaz/yamerl","last_synced_at":"2025-05-14T16:01:41.307Z","repository":{"id":5824150,"uuid":"7039585","full_name":"yakaz/yamerl","owner":"yakaz","description":"YAML 1.2 and JSON parser in pure Erlang","archived":false,"fork":false,"pushed_at":"2025-01-29T10:24:19.000Z","size":847,"stargazers_count":208,"open_issues_count":3,"forks_count":53,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-05T19:06:11.500Z","etag":null,"topics":["elixir","erlang","erlang-libraries","parsing","yaml","yaml-parser"],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yakaz.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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-12-06T17:12:04.000Z","updated_at":"2025-03-04T21:45:53.000Z","dependencies_parsed_at":"2024-06-18T12:42:57.861Z","dependency_job_id":"70764230-76a3-4ab3-892d-3864c528e115","html_url":"https://github.com/yakaz/yamerl","commit_stats":{"total_commits":318,"total_committers":18,"mean_commits":"17.666666666666668","dds":0.3459119496855346,"last_synced_commit":"bf9d8b743bfc9775f2ddad9fb8d18ba5dc29d3e1"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakaz%2Fyamerl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakaz%2Fyamerl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakaz%2Fyamerl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yakaz%2Fyamerl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yakaz","download_url":"https://codeload.github.com/yakaz/yamerl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631606,"owners_count":21136553,"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":["elixir","erlang","erlang-libraries","parsing","yaml","yaml-parser"],"created_at":"2024-08-01T02:01:12.814Z","updated_at":"2025-04-12T20:37:51.344Z","avatar_url":"https://github.com/yakaz.png","language":"Erlang","funding_links":[],"categories":["YAML"],"sub_categories":[],"readme":"# yamerl: YAML 1.2 and JSON parser in Erlang\n\n[![Hex.pm](https://img.shields.io/hexpm/v/yamerl)](https://hex.pm/packages/yamerl/)\n[![Test](https://github.com/yakaz/yamerl/actions/workflows/test-and-release.yaml/badge.svg)](https://github.com/yakaz/yamerl/actions/workflows/test-and-release.yaml)\n[![Codecov](https://codecov.io/gh/yakaz/yamerl/branch/master/graph/badge.svg?token=R0OGKZ2RK2)](https://codecov.io/gh/yakaz/yamerl)\n\nYAML is a human-friendly data serialization format. The specification\nfor this language and many examples are available from the [Official\nYAML web site](http://www.yaml.org/). You may also want to check the\n[YAML Wikipedia article](http://en.wikipedia.org/wiki/YAML).\n\n**yamerl** is a pure [Erlang application](http://www.erlang.org/)\nwhich is able to parse [YAML 1.1](http://yaml.org/spec/1.1/) and\n[YAML 1.2](http://www.yaml.org/spec/1.2/spec.html) documents, as well\nas [JSON](http://json.org/) documents. It only depends on standard\nErlang/OTP applications; no external dependency is required. It doesn't\nuse native code either (neither port drivers nor NIFs).\n\nyamerl can be used inside Elixir projects, like any other Erlang\nlibrary. You can find an example later in this README.\n\nyamerl is distributed under the terms of the **2-clause BSD license**;\nsee `LICENSE`.\n\n## Integrate to your project\n\nyamerl uses [Rebar 3](http://www.rebar3.org/) as its build system so\nit can be integrated to many common build systems.\n\n### Rebar\n\nyamerl is available as a [Hex.pm package](https://hex.pm/packages/yamerl).\nThus you can simply list it as a package dependency in your `rebar.config`:\n\n```erlang\n{deps, [yamerl]}.\n```\n\n### Erlang.mk\n\nErlang.mk knows about yamerl. You just need to add `yamerl` as a\ndependency in your `Makefile`:\n\n```make\nDEPS = yamerl\n```\n\n### Mix\n\nYou can use yamerl in your Elixir project. yamerl is available as a\n[Hex.pm package](https://hex.pm/packages/yamerl). Thus you can simply\nlist its name in your `mix.exs`:\n\n```elixir\ndef project do\n  [\n    deps: [{:yamerl, \"~\u003e 0.8.0\"}]\n  ]\nend\n```\n\n## Getting started\n\nBefore using yamerl, the application must be started:\n```erlang\napplication:start(yamerl).\n```\n\nNow, one can use the `yamerl_constr` module to parse and construct a\nlist of documents from:\n* an in-memory document (string or binary);\n* a regular file;\n* a stream.\n\nBecause a YAML input stream may contain multiple documents,\n`yamerl_constr` always returns a list of documents, even if the input\nstream only contains one.\n\n### Parsing an in-memory document\n\n```erlang\nyamerl_constr:string(\"Hello World!\").\n```\n```erlang\n% List of documents; here, only one document.\n[\n % Document #1; contains a single scalar.\n \"Hello World!\"\n]\n```\n\nHere, the returned value is a list of documents containing one document.\nThis document has a scalar as its sole node.\n\n### Parsing a file\n\nConsidering the following YAML file:\n```yaml\n# applications.yaml\n- application: kernel\n  version:     2.15.3\n  path:        /usr/local/lib/erlang/lib/kernel-2.15.3\n- application: stdlib\n  version:     1.18.3\n  path:        /usr/local/lib/erlang/lib/stdlib-1.18.3\n- application: sasl\n  version:     2.2.1\n  path:        /usr/local/lib/erlang/lib/sasl-2.2.1\n```\n\n```erlang\nyamerl_constr:file(\"applications.yaml\").\n```\n```erlang\n% List of documents; again, only one document here.\n[\n % List of mappings.\n [\n  % Mapping, represented as a proplist: each entry has the form {Key, Value}.\n  [\n   {\"application\", \"kernel\"},\n   {\"version\", \"2.15.3\"},\n   {\"path\", \"/usr/local/lib/erlang/lib/kernel-2.15.3\"}\n  ], [\n   {\"application\", \"stdlib\"},\n   {\"version\", \"1.18.3\"},\n   {\"path\", \"/usr/local/lib/erlang/lib/stdlib-1.18.3\"}\n  ], [\n   {\"application\", \"sasl\"},\n   {\"version\", \"2.2.1\"},\n   {\"path\", \"/usr/local/lib/erlang/lib/sasl-2.2.1\"}\n  ]\n ]\n]\n```\n\n### Parsing a stream\n\nThe developer is responsible for reading the stream and provide the\nchunks to yamerl.\n\n```erlang\n% Initialize a new construction state. It takes a term describing the\n% source; it may be any Erlang term.\nParser0 = yamerl_constr:new({file, \"\u003cstdin\u003e\"}),\n\n% Read chunks and feed the parser. A new parser state is returned.\n{continue, Parser1} = yamerl_constr:next_chunk(Parser0, Chunk1),\n% ...\n{continue, Parser2} = yamerl_constr:next_chunk(Parser1, Chunk2),\n\n% When the stream ends, tell the parser it's the last chunk.\nDocuments = yamerl_constr:last_chunk(Parser2, Chunk3).\n```\n\n## Simple vs. full document structures\n\n`yamerl_constr` comes with two built-in modes:\n* It can output simple documents, eg. documents based on basic Erlang\n    structures (strings, numbers, lists, proplists). This is the default\n    mode.\n* It can output detailed documents using records. These records carry\n    more information such as line/column, tag URI, YAML node type, module\n    used to construct it, etc.\n\nIf we use the following YAML document:\n```yaml\n# system.yaml\n- os: FreeBSD\n  version: 9.0-RELEASE-p3\n```\n\n* Simple documents:\n\n ```erlang\nyamerl_constr:file(\"system.yaml\").\n```\n\n ```erlang\n% List of documents.\n[\n     % List of mappings.\n     [\n      % Mapping with two entries.\n      [\n       {\"os\", \"FreeBSD\"},\n       {\"version\",\"9.0-RELEASE-p3\"}\n      ]\n     ]\n]\n```\n\n* Full documents:\n\n ```erlang\nyamerl_constr:file(\"system.yaml\", [{detailed_constr, true}]).\n```\n\n ```erlang\n% List of documents.\n[\n     % Document with a list as its root node.\n     {yamerl_doc,\n      {yamerl_seq, yamerl_node_seq, \"tag:yaml.org,2002:seq\", [{line, 2}, {column, 1}], [\n       % Mapping #1.\n       {yamerl_map, yamerl_node_map, \"tag:yaml.org,2002:map\", [{line, 2}, {column, 3}], [\n        {\n         % Mapping entry #1.\n         {yamerl_str, yamerl_node_str, \"tag:yaml.org,2002:str\", [{line, 2}, {column, 3}], \"os\"},\n         {yamerl_str, yamerl_node_str, \"tag:yaml.org,2002:str\", [{line, 2}, {column, 7}], \"FreeBSD\"}\n        }, {\n         % Mapping entry #2.\n         {yamerl_str, yamerl_node_str, \"tag:yaml.org,2002:str\", [{line, 3}, {column, 3}], \"version\"},\n         {yamerl_str, yamerl_node_str, \"tag:yaml.org,2002:str\", [{line, 3}, {column, 12}], \"9.0-RELEASE-p3\"}\n        }\n       ]}\n      ],\n      1}\n     }\n]\n```\n\n## Use yamerl in an Elixir project\n\nHere is a complete example:\n\n1. You first need to add `yamerl` to the dependencies list in `mix.exs`:\n\n ```elixir\n# mix.exs, created with `mix new myapp` and updated to have `yamerl` as\n# a dependency.\ndefmodule Myapp.Mixfile do\n  use Mix.Project\n\n  def project do\n    [app: :myapp,\n     version: \"0.1.0\",\n     elixir: \"~\u003e 1.3\",\n     build_embedded: Mix.env == :prod,\n     start_permanent: Mix.env == :prod,\n     deps: deps()]\n  end\n\n  # Configuration for the OTP application\n  #\n  # Type \"mix help compile.app\" for more information\n  def application do\n    [applications: [:logger]]\n  end\n\n  # Dependencies can be Hex packages:\n  #\n  #   {:mydep, \"~\u003e 0.3.0\"}\n  #\n  # Or git/path repositories:\n  #\n  #   {:mydep, git: \"https://github.com/elixir-lang/mydep.git\", tag: \"0.1.0\"}\n  #\n  # Type \"mix help deps\" for more examples and options\n  defp deps do\n    [\n      {:yamerl, \"~\u003e 0.4.0\"}\n    ]\n  end\nend\n```\n\n2. Start the `yamerl` application and use the constructor, either in\n simple or detailed mode:\n\n ```elixir\n# lib/myapp.ex\ndefmodule Myapp do\n  def simple(filename) do\n    # The yamerl application must be started before any use of it.\n    Application.start(:yamerl)\n\n    :yamerl_constr.file(filename)\n  end\n\n  def detailed(filename) do\n    # The yamerl application must be started before any use of it.\n    Application.start(:yamerl)\n\n    :yamerl_constr.file(filename, [:detailed_constr])\n  end\nend\n```\n\nNow let's use the `Myapp` module to parse the same YAML example file as\nabove:\n\n```yaml\n# system.yaml\n- os: FreeBSD\n  version: 9.0-RELEASE-p3\n```\n\n* Parsing in simple mode:\n\n ```elixir\nMyapp.simple(\"system.yaml\")\n```\n\n ```elixir\n# List of documents.\n[\n     # List of mappings.\n     [\n      # Mapping with two entries.\n      [\n       {'os', 'FreeBSD'},\n       {'version', '9.0-RELEASE-p3'}\n      ]\n     ]\n]\n```\n\n* Parsing in detailed mode:\n\n ```elixir\nMyapp.detailed(\"system.yaml\")\n```\n\n ```elixir\n# List of documents.\n[\n     # Document with a list as its root node.\n     yamerl_doc:\n     {:yamerl_seq, :yamerl_node_seq, 'tag:yaml.org,2002:seq', [line: 2, column: 1],\n      [\n       # Mapping #1.\n       {:yamerl_map, :yamerl_node_map, 'tag:yaml.org,2002:map', [line: 2, column: 3],\n        [\n         # Mapping entry #1.\n         {\n          {:yamerl_str, :yamerl_node_str, 'tag:yaml.org,2002:str', [line: 2, column: 3], 'os'},\n          {:yamerl_str, :yamerl_node_str, 'tag:yaml.org,2002:str', [line: 2, column: 7], 'FreeBSD'}\n         },\n         # Mapping entry #2.\n         {\n          {:yamerl_str, :yamerl_node_str, 'tag:yaml.org,2002:str', [line: 3, column: 3], 'version'},\n          {:yamerl_str, :yamerl_node_str, 'tag:yaml.org,2002:str', [line: 3, column: 12], '9.0-RELEASE-p3'}\n         }\n        ]\n       }\n      ],\n      1\n     }\n]\n```\n\n## Complete documentation\n\nSee https://hexdocs.pm/yamerl/ for a complete user guide and reference\nmanual.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyakaz%2Fyamerl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyakaz%2Fyamerl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyakaz%2Fyamerl/lists"}