contrib/libxo/libxo/xo_open_marker.3

   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
   6 .\" # using the SOFTWARE, you agree to be bound by the terms of that
   7 .\" # LICENSE.
   8 .\" # Phil Shafer, January 2015
   9 .\"
  10 .Dd January 22, 2015
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_open_marker
  15 .Nd prevent and allow closing of open constructs
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Sh NAME
  21 .Nm xo_open_marker
  22 .Nm xo_open_marker_h
  23 .Nm xo_close_marker
  24 .Nm xo_close_marker_h
  25 .Nd open and close markers
  26 .Sh LIBRARY
  27 .Lb libxo
  28 .Sh SYNOPSIS
  29 .Ft int
  30 .Fn xo_open_marker "const char *name"
  31 .Ft int
  32 .Fn xo_open_marker_h "xo_handle_t *handle" "const char *name"
  33 .Ft int
  34 .Fn xo_close_marker "const char *name"
  35 .Ft int
  36 .Fn  xo_close_marker_h "xo_handle_t *handle" "const char *name"
  37 .Sh DESCRIPTION
  38 .Nm libxo
  39 represents hierarchy using two constructs:
  40 .Dq containers
  41 and
  42 .Dq lists .
  43 A marker can be used to affect how open constructs are closed, either
  44 by preventing their (implicit or explicit) closure or by forcing their
  45 closure.
  46 While a marker is open, no other open constructs can be closed.
  47 When a marker is closed, all constructs open since the marker was opened
  48 will be closed.
  49 A marker is used to "freeze" any open constructs.
  50 Calls to
  51 .Fn xo_close_*
  52 functions that would normally close them will be ignored, effectively
  53 blocking their closure.
  54 However when
  55 .Fn xo_close_marker
  56 is called, any containers, lists, or leaf-lists open since the
  57 matching
  58 .Fn xo_open_marker
  59 call will be close and the marker discarded.
  60 Markers use names which are not user-visible, allowing the caller to
  61 choose appropriate internal names.
  62 The marker has no value and is not emitted in any form.
  63 .Pp
  64 To open a marker, call
  65 .Fn xo_open_marker
  66 or
  67 .Fn xo_open_marker_h .
  68 The former uses the default handle and
  69 the latter accepts a specific handle.
  70 .Pp
  71 To close a marker, use the
  72 .Fn xo_close_marker
  73 or
  74 .Fn xo_close_marker_h
  75 functions.
  76 .Pp
  77 Each open call must have a matching close call.
  78 .Pp
  79 In this example, the
  80 .Fn xo_close_container
  81 call on line [1] will be ignored, since the open marker "outer"
  82 will prevent close of any open constructs that precede it.
  83 The
  84 .Fn xo_close_marker
  85 call on line [2] will close the "system" container, since it was
  86 opened after the "outer" marker.
  87 .Bd -literal -offset indent -compact
  88     Example:
  89
  90         xo_open_container("top");
  91         xo_open_marker("outer");
  92         xo_open_container("system");
  93         xo_emit("{:host-name/%s%s%s", hostname,
  94                 domainname ? "." : "", domainname ?: "");
  95         xo_close_container("top");   /* [1] */
  96         xo_close_marker("outer");    /* [2] */
  97         xo_close_container("top");
  98 .Ed
  99 .Pp
 100 In this example, the code whiffles through a list of fish, calling a
 101 function to emit details about each fish.  The marker "fish-guts" is
 102 used to ensure that any constructs opened by the function are closed
 103 properly.
 104 .Bd -literal -offset indent
 105     for (i = 0; fish[i]; i++) {
 106         xo_open_instance("fish");
 107         xo_open_marker("fish-guts");
 108         dump_fish_details(i);
 109         xo_close_marker("fish-guts");
 110     }
 111 .Ed
 112 .Sh ADDITIONAL DOCUMENTATION
 113 Complete documentation can be found on github:
 114 .Bd -literal -offset indent
 115 http://juniper.github.io/libxo/libxo-manual.html
 116 .Ed
 117 .Pp
 118 .Nm libxo
 119 lives on github as:
 120 .Bd -literal -offset indent
 121 https://github.com/Juniper/libxo
 122 .Ed
 123 .Pp
 124 The latest release of
 125 .Nm libxo
 126 is available at:
 127 .Bd -literal -offset indent
 128 https://github.com/Juniper/libxo/releases
 129 .Ed
 130 .Sh SEE ALSO
 131 .Xr xo_emit 3
 132 .Sh HISTORY
 133 The
 134 .Nm libxo
 135 library was added in
 136 .Fx 11.0 .
 137 .Sh AUTHOR
 138 Phil Shafer