mirror of
https://github.com/c-cube/linol.git
synced 2025-12-10 05:04:00 -05:00
36 lines
23 KiB
HTML
36 lines
23 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Util (yojson.Yojson.Safe.Util)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.0.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../../../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../../../index.html">Index</a> » <a href="../../../index.html">yojson</a> » <a href="../../index.html">Yojson</a> » <a href="../index.html">Safe</a> » Util</nav><header class="odoc-preamble"><h1>Module <code><span>Safe.Util</span></code></h1><p>This module provides combinators for extracting fields from JSON values.</p><p>This module provides combinators for extracting fields from JSON values. This approach is recommended for reading a few fields from data returned by public APIs. However for more complex applications we recommend <a href="https://github.com/ahrefs/atd">Atdgen</a>.</p><p>Here is some sample JSON data:</p><pre>{
|
||
"id": "398eb027",
|
||
"name": "John Doe",
|
||
"pages": [
|
||
{
|
||
"id": 1,
|
||
"title": "The Art of Flipping Coins",
|
||
"url": "http://example.com/398eb027/1"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"deleted": true
|
||
},
|
||
{
|
||
"id": 3,
|
||
"title": "Artichoke Salad",
|
||
"url": "http://example.com/398eb027/3"
|
||
},
|
||
{
|
||
"id": 4,
|
||
"title": "Flying Bananas",
|
||
"url": "http://example.com/398eb027/4"
|
||
}
|
||
]
|
||
}</pre><p>In order to extract the "id" field, assuming it is mandatory, we would use the following OCaml code that operates on single JSON nodes:</p><pre>open Yojson.Basic.Util
|
||
...
|
||
let id = json |> member "id" |> to_string in
|
||
...</pre><p>In order to extract all the "title" fields, we would write the following OCaml code that operates on lists of JSON nodes, skipping undefined nodes and nodes of unexpected type:</p><pre>open Yojson.Basic.Util
|
||
|
||
let extract_titles (json : Yojson.Basic.t) : string list =
|
||
[json]
|
||
|> filter_member "pages"
|
||
|> flatten
|
||
|> filter_member "title"
|
||
|> filter_string</pre></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#exception-free-filters">Exception-free filters</a></li></ul></nav></div><div class="odoc-content"><div class="odoc-spec"><div class="spec exception anchored" id="exception-Type_error"><a href="#exception-Type_error" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Type_error</span> <span class="keyword">of</span> string * <a href="../index.html#type-t">t</a></span></code></div><div class="spec-doc"><p>Raised when the JSON value is not of the correct type to support an operation, e.g. <code>member</code> on an <code>`Int</code>. The string message explains the mismatch.</p></div></div><div class="odoc-spec"><div class="spec exception anchored" id="exception-Undefined"><a href="#exception-Undefined" class="anchor"></a><code><span><span class="keyword">exception</span> </span><span><span class="exception">Undefined</span> <span class="keyword">of</span> string * <a href="../index.html#type-t">t</a></span></code></div><div class="spec-doc"><p>Raised when the equivalent JavaScript operation on the JSON value would return undefined. Currently this only happens when an array index is out of bounds.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-keys"><a href="#val-keys" class="anchor"></a><code><span><span class="keyword">val</span> keys : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p>Returns all the key names in the given JSON object.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON object.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-values"><a href="#val-values" class="anchor"></a><code><span><span class="keyword">val</span> values : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p>Return all the value in the given JSON object.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON object.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-combine"><a href="#val-combine" class="anchor"></a><code><span><span class="keyword">val</span> combine : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <a href="../index.html#type-t">t</a></span></code></div><div class="spec-doc"><p>Combine two JSON objects together.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <code>Invalid_argument</code> <p>if either argument is not a JSON object.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-member"><a href="#val-member" class="anchor"></a><code><span><span class="keyword">val</span> member : <span>string <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <a href="../index.html#type-t">t</a></span></code></div><div class="spec-doc"><p><code>member k obj</code> returns the value associated with the key <code>k</code> in the JSON object <code>obj</code>, or <code>`Null</code> if <code>k</code> is not present in <code>obj</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if <code>obj</code> is not a JSON object.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-path"><a href="#val-path" class="anchor"></a><code><span><span class="keyword">val</span> path : <span><span>string list</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> option</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-index"><a href="#val-index" class="anchor"></a><code><span><span class="keyword">val</span> index : <span>int <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <a href="../index.html#type-t">t</a></span></code></div><div class="spec-doc"><p><code>index i arr</code> returns the value at index <code>i</code> in the JSON array <code>arr</code>. Negative indices count from the end of the list (so -1 is the last element).</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if <code>arr</code> is not a JSON array.</p></li></ul><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Undefined"><code>Undefined</code></a> <p>if index is out of bounds.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-map"><a href="#val-map" class="anchor"></a><code><span><span class="keyword">val</span> map : <span><span>(<span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <a href="../index.html#type-t">t</a>)</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <a href="../index.html#type-t">t</a></span></code></div><div class="spec-doc"><p><code>map f arr</code> calls the function <code>f</code> on each element of the JSON array <code>arr</code>, and returns a JSON array containing the results.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if <code>arr</code> is not an JSON array.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_assoc"><a href="#val-to_assoc" class="anchor"></a><code><span><span class="keyword">val</span> to_assoc : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span><span>(string * <a href="../index.html#type-t">t</a>)</span> list</span></span></code></div><div class="spec-doc"><p>Extract the items of a JSON object.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON object.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_option"><a href="#val-to_option" class="anchor"></a><code><span><span class="keyword">val</span> to_option : <span><span>(<span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> option</span></span></code></div><div class="spec-doc"><p>Return <code>None</code> if the JSON value is null or map the JSON value to <code>Some</code> value using the provided function.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_bool"><a href="#val-to_bool" class="anchor"></a><code><span><span class="keyword">val</span> to_bool : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> bool</span></code></div><div class="spec-doc"><p>Extract a boolean value.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON boolean.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_bool_option"><a href="#val-to_bool_option" class="anchor"></a><code><span><span class="keyword">val</span> to_bool_option : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span>bool option</span></span></code></div><div class="spec-doc"><p>Extract <code>Some</code> boolean value, return <code>None</code> if the value is null.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is neither.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_number"><a href="#val-to_number" class="anchor"></a><code><span><span class="keyword">val</span> to_number : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> float</span></code></div><div class="spec-doc"><p>Extract a number.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON number.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_number_option"><a href="#val-to_number_option" class="anchor"></a><code><span><span class="keyword">val</span> to_number_option : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span>float option</span></span></code></div><div class="spec-doc"><p>Extract <code>Some</code> number, return <code>None</code> if the value is null.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is neither.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_float"><a href="#val-to_float" class="anchor"></a><code><span><span class="keyword">val</span> to_float : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> float</span></code></div><div class="spec-doc"><p>Extract a float value. <code>to_number</code> is generally preferred as it also works with int literals.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON float.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_float_option"><a href="#val-to_float_option" class="anchor"></a><code><span><span class="keyword">val</span> to_float_option : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span>float option</span></span></code></div><div class="spec-doc"><p>Extract <code>Some</code> float value, return <code>None</code> if the value is null. <code>to_number_option</code> is generally preferred as it also works with int literals.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is neither.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_int"><a href="#val-to_int" class="anchor"></a><code><span><span class="keyword">val</span> to_int : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> int</span></code></div><div class="spec-doc"><p>Extract an int from a JSON int.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON int.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_int_option"><a href="#val-to_int_option" class="anchor"></a><code><span><span class="keyword">val</span> to_int_option : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span>int option</span></span></code></div><div class="spec-doc"><p>Extract <code>Some</code> int from a JSON int, return <code>None</code> if the value is null.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is neither.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_list"><a href="#val-to_list" class="anchor"></a><code><span><span class="keyword">val</span> to_list : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p>Extract a list from JSON array.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON array.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_string"><a href="#val-to_string" class="anchor"></a><code><span><span class="keyword">val</span> to_string : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> string</span></code></div><div class="spec-doc"><p>Extract a string from a JSON string.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is not a JSON string.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-to_string_option"><a href="#val-to_string_option" class="anchor"></a><code><span><span class="keyword">val</span> to_string_option : <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span>string option</span></span></code></div><div class="spec-doc"><p>Extract <code>Some</code> string from a JSON string, return <code>None</code> if the value is null.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if argument is neither.</p></li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-convert_each"><a href="#val-convert_each" class="anchor"></a><code><span><span class="keyword">val</span> convert_each : <span><span>(<span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span class="type-var">'a</span>)</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> <span class="arrow">-></span></span> <span><span class="type-var">'a</span> list</span></span></code></div><div class="spec-doc"><p>The conversion functions above cannot be used with <code>map</code>, because they do not return JSON values. This convenience function <code>convert_each to_f arr</code> is equivalent to <code>List.map to_f (to_list arr)</code>.</p><ul class="at-tags"><li class="raises"><span class="at-tag">raises</span> <a href="#exception-Type_error"><code>Type_error</code></a> <p>if <code>arr</code> is not a JSON array.</p></li></ul></div></div><h4 id="exception-free-filters"><a href="#exception-free-filters" class="anchor"></a>Exception-free filters</h4><p>The following functions operate on lists of JSON nodes. None of them raises an exception when a certain kind of node is expected but no node or the wrong kind of node is found. Instead of raising an exception, nodes that are not as expected are simply ignored.</p><div class="odoc-spec"><div class="spec value anchored" id="val-filter_map"><a href="#val-filter_map" class="anchor"></a><code><span><span class="keyword">val</span> filter_map : <span><span>(<span><span class="type-var">'a</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> option</span>)</span> <span class="arrow">-></span></span> <span><span><span class="type-var">'a</span> list</span> <span class="arrow">-></span></span> <span><span class="type-var">'b</span> list</span></span></code></div><div class="spec-doc"><p><code>filter_map f l</code> maps each element of the list <code>l</code> to an optional value using function <code>f</code> and unwraps the resulting values.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-flatten"><a href="#val-flatten" class="anchor"></a><code><span><span class="keyword">val</span> flatten : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p>Expects JSON arrays and returns all their elements as a single list. <code>flatten l</code> is equivalent to <code>List.flatten (filter_list l)</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_index"><a href="#val-filter_index" class="anchor"></a><code><span><span class="keyword">val</span> filter_index : <span>int <span class="arrow">-></span></span> <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p>Expects JSON arrays and returns all their elements existing at the given position.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_list"><a href="#val-filter_list" class="anchor"></a><code><span><span class="keyword">val</span> filter_list : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span><span><a href="../index.html#type-t">t</a> list</span> list</span></span></code></div><div class="spec-doc"><p>Expects JSON arrays and unwraps them.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_member"><a href="#val-filter_member" class="anchor"></a><code><span><span class="keyword">val</span> filter_member : <span>string <span class="arrow">-></span></span> <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span><a href="../index.html#type-t">t</a> list</span></span></code></div><div class="spec-doc"><p>Expects JSON objects and returns all the fields of the given name (at most one field per object).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_assoc"><a href="#val-filter_assoc" class="anchor"></a><code><span><span class="keyword">val</span> filter_assoc : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span><span><span>(string * <a href="../index.html#type-t">t</a>)</span> list</span> list</span></span></code></div><div class="spec-doc"><p>Expects JSON objects and unwraps them.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_bool"><a href="#val-filter_bool" class="anchor"></a><code><span><span class="keyword">val</span> filter_bool : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span>bool list</span></span></code></div><div class="spec-doc"><p>Expects JSON booleans and unwraps them.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_int"><a href="#val-filter_int" class="anchor"></a><code><span><span class="keyword">val</span> filter_int : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span>int list</span></span></code></div><div class="spec-doc"><p>Expects JSON integers (<code>`Int</code> nodes) and unwraps them.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_float"><a href="#val-filter_float" class="anchor"></a><code><span><span class="keyword">val</span> filter_float : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span>float list</span></span></code></div><div class="spec-doc"><p>Expects JSON floats (<code>`Float</code> nodes) and unwraps them.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_number"><a href="#val-filter_number" class="anchor"></a><code><span><span class="keyword">val</span> filter_number : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span>float list</span></span></code></div><div class="spec-doc"><p>Expects JSON numbers (<code>`Int</code> or <code>`Float</code>) and unwraps them. Ints are converted to floats.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-filter_string"><a href="#val-filter_string" class="anchor"></a><code><span><span class="keyword">val</span> filter_string : <span><span><a href="../index.html#type-t">t</a> list</span> <span class="arrow">-></span></span> <span>string list</span></span></code></div><div class="spec-doc"><p>Expects JSON strings and unwraps them.</p></div></div></div></body></html>
|