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          15 : #define FD_TOML_SUCCESS     ( 0)  /* ok */
      13           0 : #define FD_TOML_ERR_POD     (-1)  /* ran out of output space */
      14           0 : #define FD_TOML_ERR_SCRATCH (-2)  /* ran out of scratch space */
      15           0 : #define FD_TOML_ERR_KEY     (-3)  /* oversz key */
      16           0 : #define FD_TOML_ERR_DUP     (-4)  /* duplicate key */
      17           0 : #define FD_TOML_ERR_RANGE   (-5)  /* overflow */
      18           0 : #define FD_TOML_ERR_PARSE   (-6)  /* parse fail */
      19             : 
      20             : /* FD_TOML_PATH_MAX is the max supported pod path length. */
      21             : 
      22             : #define FD_TOML_PATH_MAX (512UL)
      23             : 
      24             : /* fd_toml_err_info_t contains information about a TOML parse failure.  */
      25             : 
      26             : struct fd_toml_err_info {
      27             :   ulong line; /* 1-indexed line number */
      28             :   /* ... add more info here ... */
      29             : };
      30             : 
      31             : typedef struct fd_toml_err_info fd_toml_err_info_t;
      32             : 
      33             : FD_PROTOTYPES_BEGIN
      34             : 
      35             : /* fd_toml_parse deserializes a TOML document and inserts the document's
      36             :    object tree into an fd_pod.  toml points to the first byte of the
      37             :    TOML.  toml_sz is the byte length of the TOML.  If toml_sz==0 then
      38             :    the toml pointer is ignored (may be invalid).  pod is a local join to
      39             :    an fd_pod_t.  [scratch,scratch+scratch_sz) is arbitrary unaligned
      40             :    scratch memory used during deserialization.  scratch_sz>=4kB
      41             :    recommended.  If scratch_sz is too small, may fail to deserialize
      42             :    long strings and sub tables.  On success, returns FD_TOML_SUCCESS.
      43             :    On parse failure returns FD_TOML_ERR_*.  If opt_err!=NULL,
      44             :    initializes *opt_err with error information (even if the return code
      45             :    was success).
      46             : 
      47             :    Note that toml is not interpreted as a cstr -- No terminating zero is
      48             :    fine and so are stray zeros in the middle of the file.
      49             : 
      50             :    fd_toml_parse is not hardened against untrusted input. fd_toml_parse
      51             :    is not optimized for performance.
      52             : 
      53             :    Mapping:
      54             : 
      55             :     TOML type      | Example     | fd_pod type
      56             :     ---------------|-------------|--------------------------------------
      57             :      table         | [key]       | subpod
      58             :      array table   | [[key]]     | subpod (keys %d formatted cstrs)
      59             :      inline table  | x={a=1,b=2} | subpod
      60             :      inline array  | x=[1,2]     | subpod (keys %d formatted cstrs)
      61             :      bool          | true        | int
      62             :      integer       | -3          | long
      63             :      float         | 3e-3        | float
      64             :      string        | 'hello'     | cstr
      65             :      datetime      | 2022-08-16  | ulong (ns since unix epoch)
      66             : 
      67             :    Despite the name, TOML is neither "obvious" nor "minimal".  fd_toml
      68             :    thus only supports a subset of the 'spec' and ignores some horrors.
      69             :    Known errata:
      70             : 
      71             :    - fd_toml allows duplicate tables and arrays whereas TOML has various
      72             :      complicated rules that forbid such.  For example, the following
      73             :      is not allowed in toml:
      74             : 
      75             :        fruit = []
      76             :        [[fruit]]  # inline arrays are immutable
      77             : 
      78             :    - fd_toml allows mixing tables and arrays which is forbidden in TOML
      79             : 
      80             :        a = [1]
      81             :        a.b = 1
      82             : 
      83             :    - Missing validation for out-of-bounds Unicode escapes
      84             : 
      85             :    - Missing support for CRLF
      86             : 
      87             :    - Missing support for subtables of array tables.
      88             :      The following gets deserialized as {a={b={c={d="val0"}}}} instead
      89             :      of {a=[{b=[{c={d="val0"}}]}]}
      90             : 
      91             :        [[a]]
      92             :          [[a.b]]
      93             :            [a.b.c]
      94             :              d = "val0"
      95             : 
      96             :    - Missing support for dot-escapes.
      97             :      The tables ["a.b"] and [a.b] are the same in fd_toml.
      98             : 
      99             :    - Keys with embedded NUL characters are truncated whereas they are
     100             :      legal in TOML.
     101             : 
     102             :    - Infinite and NaN floats are rejected. */
     103             : 
     104             : int
     105             : fd_toml_parse( void const *         toml,
     106             :                ulong                toml_sz,
     107             :                uchar *              pod,
     108             :                uchar *              scratch,
     109             :                ulong                scratch_sz,
     110             :                fd_toml_err_info_t * opt_err );
     111             : 
     112             : /* fd_toml_strerror returns a human-readable error string with static
     113             :    storage describing the given FD_TOML_ERR_* code.  Works for negative
     114             :    return values in fd_toml_parse. */
     115             : 
     116             : FD_FN_CONST char const *
     117             : fd_toml_strerror( int err );
     118             : 
     119             : FD_PROTOTYPES_END
     120             : 
     121             : #endif /* HEADER_fd_src_ballet_toml_fd_toml_h */