1406a584dSPhil Shafer /* 2*5e203a9dSPhil Shafer * Copyright (c) 2019, Juniper Networks, Inc. 3406a584dSPhil Shafer * All rights reserved. 4406a584dSPhil Shafer * This SOFTWARE is licensed under the LICENSE provided in the 5406a584dSPhil Shafer * ../Copyright file. By downloading, installing, copying, or otherwise 6406a584dSPhil Shafer * using the SOFTWARE, you agree to be bound by the terms of that 7406a584dSPhil Shafer * LICENSE. 8406a584dSPhil Shafer * 9406a584dSPhil Shafer * Phil Shafer, March 2019 10406a584dSPhil Shafer */ 11406a584dSPhil Shafer 12406a584dSPhil Shafer #ifndef XO_EXPLICIT_H 13406a584dSPhil Shafer #define XO_EXPLICIT_H 14406a584dSPhil Shafer 15406a584dSPhil Shafer /* 16406a584dSPhil Shafer * NOTE WELL: This file is needed to software that implements an 17406a584dSPhil Shafer * explicit transition between libxo states on its internal stack. 18406a584dSPhil Shafer * General libxo code should _never_ include this header file. 19406a584dSPhil Shafer */ 20406a584dSPhil Shafer 21406a584dSPhil Shafer 22406a584dSPhil Shafer /* 23406a584dSPhil Shafer * A word about states: We use a finite state machine (FMS) approach 24406a584dSPhil Shafer * to help remove fragility from the caller's code. Instead of 25406a584dSPhil Shafer * requiring a specific order of calls, we'll allow the caller more 26406a584dSPhil Shafer * flexibility and make the library responsible for recovering from 27406a584dSPhil Shafer * missed steps. The goal is that the library should not be capable 28406a584dSPhil Shafer * of emitting invalid xml or json, but the developer shouldn't need 29406a584dSPhil Shafer * to know or understand all the details about these encodings. 30406a584dSPhil Shafer * 31406a584dSPhil Shafer * You can think of states as either states or events, since they 32406a584dSPhil Shafer * function rather like both. None of the XO_CLOSE_* events will 33406a584dSPhil Shafer * persist as states, since the matching stack frame will be popped. 34406a584dSPhil Shafer * Same is true of XSS_EMIT, which is an event that asks us to 35406a584dSPhil Shafer * prep for emitting output fields. 36406a584dSPhil Shafer */ 37406a584dSPhil Shafer 38406a584dSPhil Shafer /* Stack frame states */ 39406a584dSPhil Shafer typedef unsigned xo_state_t; /* XSS_* values */ 40406a584dSPhil Shafer #define XSS_INIT 0 /* Initial stack state */ 41406a584dSPhil Shafer #define XSS_OPEN_CONTAINER 1 42406a584dSPhil Shafer #define XSS_CLOSE_CONTAINER 2 43406a584dSPhil Shafer #define XSS_OPEN_LIST 3 44406a584dSPhil Shafer #define XSS_CLOSE_LIST 4 45406a584dSPhil Shafer #define XSS_OPEN_INSTANCE 5 46406a584dSPhil Shafer #define XSS_CLOSE_INSTANCE 6 47406a584dSPhil Shafer #define XSS_OPEN_LEAF_LIST 7 48406a584dSPhil Shafer #define XSS_CLOSE_LEAF_LIST 8 49406a584dSPhil Shafer #define XSS_DISCARDING 9 /* Discarding data until recovered */ 50406a584dSPhil Shafer #define XSS_MARKER 10 /* xo_open_marker's marker */ 51406a584dSPhil Shafer #define XSS_EMIT 11 /* xo_emit has a leaf field */ 52406a584dSPhil Shafer #define XSS_EMIT_LEAF_LIST 12 /* xo_emit has a leaf-list ({l:}) */ 53406a584dSPhil Shafer #define XSS_FINISH 13 /* xo_finish was called */ 54406a584dSPhil Shafer 55406a584dSPhil Shafer #define XSS_MAX 13 56406a584dSPhil Shafer 57406a584dSPhil Shafer void 58406a584dSPhil Shafer xo_explicit_transition (xo_handle_t *xop, xo_state_t new_state, 59406a584dSPhil Shafer const char *tag, xo_xof_flags_t flags); 60406a584dSPhil Shafer 61406a584dSPhil Shafer #endif /* XO_EXPLICIT_H */ 62