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 , xo_open_marker_h , xo_close_marker , xo_close_marker_h
  15 .Nd prevent and allow closing of open constructs
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft xo_ssize_t
  21 .Fn xo_open_marker "const char *name"
  22 .Ft xo_ssize_t
  23 .Fn xo_open_marker_h "xo_handle_t *handle" "const char *name"
  24 .Ft xo_ssize_t
  25 .Fn xo_close_marker "const char *name"
  26 .Ft xo_ssize_t
  27 .Fn  xo_close_marker_h "xo_handle_t *handle" "const char *name"
  28 .Sh DESCRIPTION
  29 .Nm libxo
  30 represents hierarchy using two constructs:
  31 .Dq containers
  32 and
  33 .Dq lists .
  34 A marker can be used to affect how open constructs are closed, either
  35 by preventing their (implicit or explicit) closure or by forcing their
  36 closure.
  37 While a marker is open, no other open constructs can be closed.
  38 When a marker is closed, all constructs open since the marker was opened
  39 will be closed.
  40 A marker is used to "freeze" any open constructs.
  41 Calls to
  42 .Fn xo_close_*
  43 functions that would normally close them will be ignored, effectively
  44 blocking their closure.
  45 However when
  46 .Fn xo_close_marker
  47 is called, any containers, lists, or leaf-lists open since the
  48 matching
  49 .Fn xo_open_marker
  50 call will be close and the marker discarded.
  51 Markers use names which are not user-visible, allowing the caller to
  52 choose appropriate internal names.
  53 The marker has no value and is not emitted in any form.
  54 .Pp
  55 To open a marker, call
  56 .Fn xo_open_marker
  57 or
  58 .Fn xo_open_marker_h .
  59 The former uses the default handle and
  60 the latter accepts a specific handle.
  61 .Pp
  62 To close a marker, use the
  63 .Fn xo_close_marker
  64 or
  65 .Fn xo_close_marker_h
  66 functions.
  67 .Pp
  68 Each open call must have a matching close call.
  69 .Pp
  70 In this example, the
  71 .Fn xo_close_container
  72 call on line [1] will be ignored, since the open marker "outer"
  73 will prevent close of any open constructs that precede it.
  74 The
  75 .Fn xo_close_marker
  76 call on line [2] will close the "system" container, since it was
  77 opened after the "outer" marker.
  78 .Bd -literal -offset indent -compact
  79     Example:
  80
  81         xo_open_container("top");
  82         xo_open_marker("outer");
  83         xo_open_container("system");
  84         xo_emit("{:host-name/%s%s%s", hostname,
  85                 domainname ? "." : "", domainname ?: "");
  86         xo_close_container("top");   /* [1] */
  87         xo_close_marker("outer");    /* [2] */
  88         xo_close_container("top");
  89 .Ed
  90 .Pp
  91 In this example, the code whiffles through a list of fish, calling a
  92 function to emit details about each fish.  The marker "fish-guts" is
  93 used to ensure that any constructs opened by the function are closed
  94 properly.
  95 .Bd -literal -offset indent
  96     for (i = 0; fish[i]; i++) {
  97         xo_open_instance("fish");
  98         xo_open_marker("fish-guts");
  99         dump_fish_details(i);
 100         xo_close_marker("fish-guts");
 101     }
 102 .Ed
 103 .Sh SEE ALSO
 104 .Xr xo_emit 3 ,
 105 .Xr libxo 3
 106 .Sh HISTORY
 107 The
 108 .Nm libxo
 109 library first appeared in
 110 .Fx 11.0 .
 111 .Sh AUTHORS
 112 .Nm libxo
 113 was written by
 114 .An Phil Shafer Aq Mt phil@freebsd.org .
 115