Line data    Source code

       1             : #ifndef HEADER_fd_src_ballet_toml_fd_toml_h
       2             : #define HEADER_fd_src_ballet_toml_fd_toml_h
       3             : 
       4             : /* fd_toml.h provides APIs for parsing TOML config files.
       5             : 
       6             :    Grammar: https://github.com/toml-lang/toml/blob/1.0.0/toml.abnf */
       7             : 
       8             : #include "../../util/pod/fd_pod.h"
       9             : 
      10             : /* Error codes */
      11             : 
      12           3 : #define FD_TOML_SUCCESS     ( 0L)  /* ok */
      13           0 : #define FD_TOML_ERR_POD     (-1L)  /* ran out of output space */
      14           0 : #define FD_TOML_ERR_SCRATCH (-2L)  /* ran out of scratch space */
      15           0 : #define FD_TOML_ERR_KEY     (-3L)  /* oversz key */
      16           0 : #define FD_TOML_ERR_DUP     (-4L)  /* duplicate key */
      17           0 : #define FD_TOML_ERR_RANGE   (-5L)  /* overflow */
      18             : 
      19             : FD_PROTOTYPES_BEGIN
      20             : 
      21             : /* fd_toml_parse deserializes a TOML document and inserts the document's
      22             :    object tree into an fd_pod.  toml points to the first byte of the
      23             :    TOML.  toml_sz is the byte length of the TOML.  If toml_sz==0 then
      24             :    the toml pointer is ignored (may be invalid).  pod is a local join to
      25             :    an fd_pod_t.  [scratch,scratch+scratch_sz) is arbitrary unaligned
      26             :    scratch memory used during deserialization.  scratch_sz>=4kB
      27             :    recommended.  If scratch_sz is too small, may fail to deserialize
      28             :    long strings and sub tables.   On success, returns FD_POD_SUCCESS.
      29             :    On parse failure returns the line number at which the failure
      30             :    occurred (1-indexed). If the pod does not have enough space returns
      31             :    FD_TOML_ERR_OOM.  Note that toml is not interpreted as a cstr -- No
      32             :    terminating zero is fine and so are stray zeros in the middle of the
      33             :    file.
      34             : 
      35             :    fd_toml_parse is not hardened against untrusted input. fd_toml_parse
      36             :    is not optimized for performance.
      37             : 
      38             :    Mapping:
      39             : 
      40             :     TOML type      | Example     | fd_pod type
      41             :     ---------------|-------------|--------------------------------------
      42             :      table         | [key]       | subpod
      43             :      array table   | [[key]]     | subpod (keys %d formatted cstrs)
      44             :      inline table  | x={a=1,b=2} | subpod
      45             :      inline array  | x=[1,2]     | subpod (keys %d formatted cstrs)
      46             :      bool          | true        | int
      47             :      integer       | -3          | long
      48             :      float         | 3e-3        | float
      49             :      string        | 'hello'     | cstr
      50             :      datetime      | 2022-08-16  | ulong (ns since unix epoch)
      51             : 
      52             :    Despite the name, TOML is neither "obvious" nor "minimal".  fd_toml
      53             :    thus only supports a subset of the 'spec' and ignores some horrors.
      54             :    Known errata:
      55             : 
      56             :    - fd_toml allows duplicate tables and arrays whereas TOML has various
      57             :      complicated rules that forbid such.  For example, the following
      58             :      is not allowed in toml:
      59             : 
      60             :        fruit = []
      61             :        [[fruit]]  # inline arrays are immutable
      62             : 
      63             :    - fd_toml allows mixing tables and arrays which is forbidden in TOML
      64             : 
      65             :        a = [1]
      66             :        a.b = 1
      67             : 
      68             :    - Missing validation for out-of-bounds Unicode escapes
      69             : 
      70             :    - Missing support for CRLF
      71             : 
      72             :    - Missing support for subtables of array tables.
      73             :      The following gets deserialized as {a={b={c={d="val0"}}}} instead
      74             :      of {a=[{b=[{c={d="val0"}}]}]}
      75             : 
      76             :        [[a]]
      77             :          [[a.b]]
      78             :            [a.b.c]
      79             :              d = "val0"
      80             : 
      81             :    - Missing support for dot-escapes.
      82             :      The tables ["a.b"] and [a.b] are the same in fd_toml.
      83             : 
      84             :    - Keys with embedded NUL characters are truncated whereas they are
      85             :      legal in TOML.
      86             : 
      87             :    - Infinite and NaN floats are rejected. */
      88             : 
      89             : long
      90             : fd_toml_parse( void const * toml,
      91             :                ulong        toml_sz,
      92             :                uchar *      pod,
      93             :                uchar *      scratch,
      94             :                ulong        scratch_sz );
      95             : 
      96             : FD_PROTOTYPES_END
      97             : 
      98             : #endif /* HEADER_fd_src_ballet_toml_fd_toml_h */