contrib/libxo/libxo/xo_explicit.h

   1 /*
   2  * Copyright (c) 2015, Juniper Networks, Inc.
   3  * All rights reserved.
   4  * This SOFTWARE is licensed under the LICENSE provided in the
   5  * ../Copyright file. By downloading, installing, copying, or otherwise
   6  * using the SOFTWARE, you agree to be bound by the terms of that
   7  * LICENSE.
   8  *
   9  * Phil Shafer, March 2019
  10  */
  11
  12 #ifndef XO_EXPLICIT_H
  13 #define XO_EXPLICIT_H
  14
  15 /*
  16  * NOTE WELL: This file is needed to software that implements an
  17  * explicit transition between libxo states on its internal stack.
  18  * General libxo code should _never_ include this header file.
  19  */
  20
  21
  22 /*
  23  * A word about states: We use a finite state machine (FMS) approach
  24  * to help remove fragility from the caller's code.  Instead of
  25  * requiring a specific order of calls, we'll allow the caller more
  26  * flexibility and make the library responsible for recovering from
  27  * missed steps.  The goal is that the library should not be capable
  28  * of emitting invalid xml or json, but the developer shouldn't need
  29  * to know or understand all the details about these encodings.
  30  *
  31  * You can think of states as either states or events, since they
  32  * function rather like both.  None of the XO_CLOSE_* events will
  33  * persist as states, since the matching stack frame will be popped.
  34  * Same is true of XSS_EMIT, which is an event that asks us to
  35  * prep for emitting output fields.
  36  */
  37
  38 /* Stack frame states */
  39 typedef unsigned xo_state_t;    /* XSS_* values */
  40 #define XSS_INIT                0       /* Initial stack state */
  41 #define XSS_OPEN_CONTAINER      1
  42 #define XSS_CLOSE_CONTAINER     2
  43 #define XSS_OPEN_LIST           3
  44 #define XSS_CLOSE_LIST          4
  45 #define XSS_OPEN_INSTANCE       5
  46 #define XSS_CLOSE_INSTANCE      6
  47 #define XSS_OPEN_LEAF_LIST      7
  48 #define XSS_CLOSE_LEAF_LIST     8
  49 #define XSS_DISCARDING          9       /* Discarding data until recovered */
  50 #define XSS_MARKER              10      /* xo_open_marker's marker */
  51 #define XSS_EMIT                11      /* xo_emit has a leaf field */
  52 #define XSS_EMIT_LEAF_LIST      12      /* xo_emit has a leaf-list ({l:}) */
  53 #define XSS_FINISH              13      /* xo_finish was called */
  54
  55 #define XSS_MAX                 13
  56
  57 void
  58 xo_explicit_transition (xo_handle_t *xop, xo_state_t new_state,
  59                         const char *tag, xo_xof_flags_t flags);
  60
  61 #endif /* XO_EXPLICIT_H */