{"id":19434491,"url":"https://github.com/mlin/yajl-ocaml","last_synced_at":"2025-07-13T01:10:28.214Z","repository":{"id":4528619,"uuid":"5668736","full_name":"mlin/yajl-ocaml","owner":"mlin","description":"OCaml bindings for the YAJL streaming JSON parser","archived":false,"fork":false,"pushed_at":"2013-04-28T04:34:28.000Z","size":1648,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-25T06:29:05.583Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-09-04T07:07:49.000Z","updated_at":"2014-10-07T20:52:05.000Z","dependencies_parsed_at":"2022-09-12T06:30:15.710Z","dependency_job_id":null,"html_url":"https://github.com/mlin/yajl-ocaml","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mlin/yajl-ocaml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fyajl-ocaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fyajl-ocaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fyajl-ocaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fyajl-ocaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlin","download_url":"https://codeload.github.com/mlin/yajl-ocaml/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlin%2Fyajl-ocaml/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261205690,"owners_count":23124813,"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":[],"created_at":"2024-11-10T14:46:36.662Z","updated_at":"2025-06-21T22:41:40.036Z","avatar_url":"https://github.com/mlin.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [yajl-ocaml](https://github.com/mlin/yajl-ocaml)\n\nOCaml bindings for the [YAJL](http://lloyd.github.com/yajl/) streaming JSON\nparser. Also includes a convenient, high-level JSON representation.\n\n## Installation\n\nyajl-ocaml works on Linux and Mac OS X with OCaml 3.12 and above. The easiest\nway to install it is using [OPAM](http://opam.ocamlpro.com):\n`opam install yajl`.\n\nIf you don't use OPAM, set up [findlib](http://projects.camlcity.org/projects/findlib.html),\ndefine the `OCAMLFIND_DESTDIR` environment variable if necessary and\n\n```git clone https://github.com/mlin/yajl-ocaml.git \u0026\u0026 cd yajl-ocaml \u0026\u0026 make install```\n\n[![Build Status](https://travis-ci.org/mlin/yajl-ocaml.png)](https://travis-ci.org/mlin/yajl-ocaml)\n\nThe Makefile will automatically pull in a few dependencies, including YAJL\nitself and [ocaml+twt](http://people.csail.mit.edu/mikelin/ocaml+twt/).\n\nYou can then use `ocamlfind` as usual to include the `yajl` package when\ncompiling your program (making sure `OCAMLPATH` includes `OCAMLFIND_DESTDIR` if\nyou changed it).\n\n## API documentation\n\nSee [ocamldoc:YAJL](http://mlin.github.com/yajl-ocaml/YAJL.html)\n\n## Example usage\n\n### JSON parsing\n\nyajl-ocaml provides fairly direct bindings to the [YAJL callback\nAPI](https://github.com/lloyd/yajl/blob/master/src/api/yajl_parse.h), in which\nthe parser invokes your callback functions for each JSON \"event\" and it's\nmainly up to you to build a data structure based on the sequence of events.\nThe bindings help with threading a polymorphic \"context value\" through your\ncallbacks.\n\nHere's a program that demonstrates use of the callback API to build up a list\nof the events observed during parsing. It then post-processes the list to\nprint the number of string values in the input. In this example, `event list`\nis the type of the context value passed through the callbacks.\n\n```ocaml\ntype event = Null | Bool of bool | Int of int | Float of float | String of string\n  | Start_map | Map_key of string | End_map | Start_array | End_array\n\nlet on_null lst = Null :: lst\nlet on_bool lst b = (Bool b) :: lst\nlet on_int lst i = (Int i) :: lst\nlet on_float lst x = (Float x) :: lst\nlet on_string lst buf ofs len = (String (String.sub buf ofs len)) :: lst\nlet on_start_map lst = Start_map :: lst\nlet on_map_key lst buf ofs len = (Map_key (String.sub buf ofs len)) :: lst\nlet on_end_map lst = End_map :: lst\nlet on_start_array lst = Start_array :: lst\nlet on_end_array lst = End_array :: lst \n\nlet my_callbacks = {\n  YAJL.on_null = on_null;\n  on_bool = on_bool;\n  on_number =  `Parse_numbers ((`Int on_int), on_float);\n  on_string = on_string;\n  on_start_map = on_start_map;\n  on_map_key = on_map_key;\n  on_end_map = on_end_map;\n  on_start_array = on_start_array;\n  on_end_array = on_end_array\n}\n\nlet parser = YAJL.make_parser my_callbacks [] ;;\nYAJL.parse parser \"{\\\"foo\\\": [null,false,true,0,12345\" ;;\nYAJL.parse parser \",3.14159,6e23,\\\"bar\\\",\\\"\\\"]}\" ;;\nlet events = List.rev (YAJL.complete_parse parser) ;;\n\nPrintf.printf \"%d strings\\n\"\n  (List.length (List.filter (function String _ -\u003e true | _ -\u003e false) events))\n```\n\nNote that we provided the JSON data to YAJL in multiple parts. Large JSON data\ncan be streamed from a file or socket in arbitrary chunks, without buffering it\nall in memory, and the callbacks are invoked as early as possible.\n\n### JSON generation\n\nyajl-ocaml also provides bindings to YAJL's JSON generator functions.\n\n```ocaml\nlet json =\n  let gen = YAJL.make_gen () in\n  begin\n    YAJL.gen_start_map gen;\n    YAJL.gen_string gen \"key\";\n    YAJL.gen_start_array gen;\n    YAJL.gen_bool gen true;\n    List.iter (YAJL.gen_int gen) [1; 2; 3];\n    YAJL.gen_string gen \"骆驼\\\"\\000\";\n    YAJL.gen_end_array gen;\n    YAJL.gen_end_map gen;\n    let buf, ofs, len = YAJL.gen_get_buf gen in\n    String.sub buf ofs len\n  end ;;\n\nPrintf.printf \"%s\\n\" json\n```\n\nThis produces: `{\"key\":[true,1,2,3,\"骆驼\\\"\\u0000\"]}`. Note that YAJL handled\nescaping the string.\n\n## High-level JSON representation\n\nThis repo also contains an \"extra\" OCaml library with a convenient, high-level\nJSON representation based on data structures in\n[batteries](https://github.com/ocaml-batteries-team/batteries-included). Among\nother conveniences, it defines operators to make it especially easy to\nmanipulate JSON objects (look up keys, set values, etc.).\n\nTo use it `opam install yajl-extra`, or `make install-extra` in the repo\ndirectory, and then use package `yajl-extra`. This package provides a module\n`JSON`: [ocamldoc:JSON](http://mlin.github.com/yajl-ocaml/extra/JSON.html)\n\nAs an example, suppose we want to parse this configuration JSON.\n\n```\n{\"servers\": [\n  {\"host\": \"10.0.1.17\", \"port\": 9119},\n  {\"host\": \"10.0.1.18\", \"port\": 9120}\n]}\n```\n\nWe could do something like this:\n\n```ocaml\nopen Batteries_uni\nopen JSON.Operators\nlet config () =\n  let json = JSON.from_file \"config.json\" in\n  let servers = json$\"servers\" in\n  servers |\u003e JSON.array |\u003e Vect.to_array |\u003e Array.map\n    (fun entry -\u003e JSON.string (entry$\"host\"), JSON.int (entry$\"port\")) ;;\n\nconfig() |\u003e Array.iter (fun (host,port) -\u003e Printf.printf \"%s:%d\\n\" host port)\n```\n[batteries](https://github.com/ocaml-batteries-team/batteries-included) is\nrequired for this \"extra\" library, but not the callback-based yajl-ocaml.\n\n## Performance notes\n\nGiven a set of callbacks that don't do anything, yajl-ocaml will go through a\nlarge JSON much faster than other OCaml JSON libraries. Of course, that's not\na fair comparison, because that way of using yajl-ocaml would not produce any\nuseful results.\n\nGiven callbacks that produce a comparable general-purpose data structure, such\nas the \"extra\" JSON library, yajl-ocaml will not be much faster or slower than\nother good OCaml JSON libraries like [Yojson](http://mjambon.com/yojson.html),\nbecause that task is mainly bound to memory allocation, string copying, and\nnumber parsing.\n\nyajl-ocaml could be used to its greatest advantage somewhere in between: for\nexample, suppose you had to process a large numeric matrix represented as JSON\narrays. yajl-ocaml would give you the flexibility to do that much more\nefficiently than a general-purpose JSON parser (e.g., streaming the rows one-\nby-one while reusing the same `float array` to avoid memory allocation).\n\n## Running tests\n\nEnsure you have [oUnit](http://ounit.forge.ocamlcore.org/) and\n[batteries](https://github.com/ocaml-batteries-team/batteries-included)\ninstalled via findlib. Then, just `make test` in the repo directory. This will\nautomatically wget a certain large, pathological JSON before running the tests\n(which use it).\n\nThe tests also run on Travis CI: [![Build Status](https://travis-ci.org/mlin/yajl-ocaml.png)](https://travis-ci.org/mlin/yajl-ocaml)\n\n## Version history\n\n#### v0.7.3 (11 Jan 2013)\n\n- \"Extra\" JSON library now compiles against batteries 2.x; previous versions\n  used batteries 1.x.\n\n#### v0.7.2 (9 Dec 2012)\n\n- Fix JSON generation of large integers\n\n#### v0.7.1 (29 Oct 2012)\n\n- First released on OPAM\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlin%2Fyajl-ocaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlin%2Fyajl-ocaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlin%2Fyajl-ocaml/lists"}