<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.18">
<meta name="author" content="René Ferdinand Rivera Morell">
<meta name="copyright" content="Copyright 2022 René Ferdinand Rivera Morell">
<title>Tool Introspection</title>
<style>
@import url(https://fonts.googleapis.com/css?family=Varela+Round|Open+Sans:400italic,600italic,400,600|Ubuntu+Mono:400);
/*! normalize.css v2.1.2 | MIT License | git.io/normalize */
/* ========================================================================== HTML5 display definitions ========================================================================== */
/** Correct `block` display not defined in IE 8/9. */
article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }

/** Correct `inline-block` display not defined in IE 8/9. */
audio, canvas, video { display: inline-block; }

/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */
audio:not([controls]) { display: none; height: 0; }

/** Address `[hidden]` styling not present in IE 8/9. Hide the `template` element in IE, Safari, and Firefox < 22. */
[hidden], template { display: none; }

script { display: none !important; }

/* ========================================================================== Base ========================================================================== */
/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */
html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ }

/** Remove default margin. */
body { margin: 0; }

/* ========================================================================== Links ========================================================================== */
/** Remove the gray background color from active links in IE 10. */
a { background: transparent; }

/** Address `outline` inconsistency between Chrome and other browsers. */
a:focus { outline: thin dotted; }

/** Improve readability when focused and also mouse hovered in all browsers. */
a:active, a:hover { outline: 0; }

/* ========================================================================== Typography ========================================================================== */
/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari 5, and Chrome. */
h1 { font-size: 2em; margin: 0.67em 0; }

/** Address styling not present in IE 8/9, Safari 5, and Chrome. */
abbr[title] { border-bottom: 1px dotted; }

/** Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome. */
b, strong { font-weight: bold; }

/** Address styling not present in Safari 5 and Chrome. */
dfn { font-style: italic; }

/** Address differences between Firefox and other browsers. */
hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }

/** Address styling not present in IE 8/9. */
mark { background: #ff0; color: #000; }

/** Correct font family set oddly in Safari 5 and Chrome. */
code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }

/** Improve readability of pre-formatted text in all browsers. */
pre { white-space: pre-wrap; }

/** Set consistent quote types. */
q { quotes: "\201C" "\201D" "\2018" "\2019"; }

/** Address inconsistent and variable font size in all browsers. */
small { font-size: 80%; }

/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */
sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }

sup { top: -0.5em; }

sub { bottom: -0.25em; }

/* ========================================================================== Embedded content ========================================================================== */
/** Remove border when inside `a` element in IE 8/9. */
img { border: 0; }

/** Correct overflow displayed oddly in IE 9. */
svg:not(:root) { overflow: hidden; }

/* ========================================================================== Figures ========================================================================== */
/** Address margin not present in IE 8/9 and Safari 5. */
figure { margin: 0; }

/* ========================================================================== Forms ========================================================================== */
/** Define consistent border, margin, and padding. */
fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }

/** 1. Correct `color` not being inherited in IE 8/9. 2. Remove padding so people aren't caught out if they zero out fieldsets. */
legend { border: 0; /* 1 */ padding: 0; /* 2 */ }

/** 1. Correct font family not being inherited in all browsers. 2. Correct font size not being inherited in all browsers. 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome. */
button, input, select, textarea { font-family: inherit; /* 1 */ font-size: 100%; /* 2 */ margin: 0; /* 3 */ }

/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */
button, input { line-height: normal; }

/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+. Correct `select` style inheritance in Firefox 4+ and Opera. */
button, select { text-transform: none; }

/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */
button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ }

/** Re-set default cursor for disabled elements. */
button[disabled], html input[disabled] { cursor: default; }

/** 1. Address box sizing set to `content-box` in IE 8/9. 2. Remove excess padding in IE 8/9. */
input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ }

/** 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome. 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome (include `-moz` to future-proof). */
input[type="search"] { -webkit-appearance: textfield; /* 1 */ -moz-box-sizing: content-box; -webkit-box-sizing: content-box; /* 2 */ box-sizing: content-box; }

/** Remove inner padding and search cancel button in Safari 5 and Chrome on OS X. */
input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; }

/** Remove inner padding and border in Firefox 4+. */
button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }

/** 1. Remove default vertical scrollbar in IE 8/9. 2. Improve readability and alignment in all browsers. */
textarea { overflow: auto; /* 1 */ vertical-align: top; /* 2 */ }

/* ========================================================================== Tables ========================================================================== */
/** Remove most spacing between table cells. */
table { border-collapse: collapse; border-spacing: 0; }

meta.foundation-mq-small { font-family: "only screen and (min-width: 768px)"; width: 768px; }

meta.foundation-mq-medium { font-family: "only screen and (min-width:1280px)"; width: 1280px; }

meta.foundation-mq-large { font-family: "only screen and (min-width:1440px)"; width: 1440px; }

*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }

html, body { font-size: 100%; }

body { background: #fefdfd; color: rgba(0, 0, 0, 0.8); padding: 0; margin: 0; font-family: "Open Sans", sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }

a:hover { cursor: pointer; }

img, object, embed { max-width: 100%; height: auto; }

object, embed { height: 100%; }

img { -ms-interpolation-mode: bicubic; }

#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }

.left { float: left !important; }

.right { float: right !important; }

.text-left { text-align: left !important; }

.text-right { text-align: right !important; }

.text-center { text-align: center !important; }

.text-justify { text-align: justify !important; }

.hide { display: none; }

.antialiased { -webkit-font-smoothing: antialiased; }

img { display: inline-block; vertical-align: middle; }

textarea { height: auto; min-height: 50px; }

select { width: 100%; }

p.lead { font-size: 1.21875em; line-height: 1.6; }

.subheader, .admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { line-height: 1.25; color: #002c5e; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }

/* Typography resets */
div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }

/* Default Link Styles */
a { color: #005580; text-decoration: underline; line-height: inherit; }
a:hover, a:focus { color: #078d71; }
a img { border: none; }

/* Default paragraph styles */
p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; text-rendering: optimizeLegibility; }
p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }

/* Default header styles */
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: "Varela Round", sans-serif; font-weight: 400; font-style: normal; color: #00326b; text-rendering: optimizeLegibility; margin-top: 0.8em; margin-bottom: 0.5em; line-height: 1.0625em; }
h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #057aff; line-height: 0; }

h1 { font-size: 2.125em; }

h2 { font-size: 1.6875em; }

h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }

h4 { font-size: 1.125em; }

h5 { font-size: 1.125em; }

h6 { font-size: 1em; }

hr { border: solid rgba(145, 135, 84, 0.15); border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }

/* Helpful Typography Defaults */
em, i { font-style: italic; line-height: inherit; }

strong, b { font-weight: bold; line-height: inherit; }

small { font-size: 60%; line-height: inherit; }

code { font-family: "Ubuntu Mono", "Inconsolata", monospace; font-weight: 400; color: #331d00; }

/* Lists */
ul, ol, dl { font-size: 1em; line-height: 1.5; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }

ul, ol { margin-left: 1.5em; }
ul.no-bullet, ol.no-bullet { margin-left: 1.5em; }

/* Unordered Lists */
ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; /* Override nested font-size change */ }
ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }
ul.square { list-style-type: square; }
ul.circle { list-style-type: circle; }
ul.disc { list-style-type: disc; }
ul.no-bullet { list-style: none; }

/* Ordered Lists */
ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }

/* Definition Lists */
dl dt { margin-bottom: 0.3125em; font-weight: bold; }
dl dd { margin-bottom: 1.25em; }

/* Abbreviations */
abbr, acronym { text-transform: uppercase; font-size: 90%; color: rgba(0, 0, 0, 0.8); border-bottom: 1px dotted #ddd; cursor: help; }

abbr { text-transform: none; }

/* Blockquotes */
blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #ddd; }
blockquote cite { display: block; font-size: 0.8125em; color: #666; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #666; }

blockquote, blockquote p { line-height: 1.5; color: #999; }

/* Microformats */
.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #ddd; padding: 0.625em 0.75em; }
.vcard li { margin: 0; display: block; }
.vcard .fn { font-weight: bold; font-size: 0.9375em; }

.vevent .summary { font-weight: bold; }
.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }

@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.25; }
  h1 { font-size: 2.75em; }
  h2 { font-size: 2.3125em; }
  h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
  h4 { font-size: 1.4375em; } }
/* Tables */
table { background: #fff; margin-bottom: 1.25em; border: solid 1px rgba(145, 135, 84, 0.15); }
table thead, table tfoot { background: rgba(119, 84, 22, 0.1); font-weight: bold; }
table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: rgba(0, 0, 0, 0.8); text-align: left; }
table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: rgba(0, 0, 0, 0.8); }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: rgba(119, 84, 22, 0.025); }
table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.5; }

body { tab-size: 4; word-wrap: anywhere; -moz-osx-font-smoothing: grayscale; -webkit-font-smoothing: antialiased; }

table { word-wrap: normal; }

h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.25; }

object, svg { display: inline-block; vertical-align: middle; }

.center { margin-left: auto; margin-right: auto; }

.stretch { width: 100%; }

.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
.clearfix:after, .float-group:after { clear: both; }

:not(pre).nobreak { word-wrap: normal; }
:not(pre).nowrap { white-space: nowrap; }
:not(pre).pre-wrap { white-space: pre-wrap; }

:not(pre):not([class^=L]) > code { font-size: 1.0625em; font-style: normal !important; letter-spacing: 0; padding: 0; line-height: 1.25; }

pre { color: inherit; font-family: "Liberation Mono", "Consolas", monospace; line-height: 1.4; }
pre code, pre pre { color: inherit; font-size: inherit; line-height: inherit; }
pre > code { display: block; }

pre.nowrap, pre.nowrap pre { white-space: pre; word-wrap: normal; }

em em { font-style: normal; }

strong strong { font-weight: normal; }

.keyseq { color: rgba(51, 51, 51, 0.8); }

kbd { font-family: "Ubuntu Mono", "Inconsolata", monospace; display: inline-block; color: rgba(0, 0, 0, 0.8); font-size: 0.65em; line-height: 1.45; background-color: #f7f7f7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -moz-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 0.1em white inset; margin: 0 0.15em; padding: 0.2em 0.5em; vertical-align: middle; position: relative; top: -0.1em; white-space: nowrap; }

.keyseq kbd:first-child { margin-left: 0; }

.keyseq kbd:last-child { margin-right: 0; }

.menuseq, .menuref { color: #000; }

.menuseq b:not(.caret), .menuref { font-weight: inherit; }

.menuseq { word-spacing: -0.02em; }
.menuseq b.caret { font-size: 1.25em; line-height: 0.8; }
.menuseq i.caret { font-weight: bold; text-align: center; width: 0.45em; }

b.button:before, b.button:after { position: relative; top: -1px; font-weight: normal; }

b.button:before { content: "["; padding: 0 3px 0 2px; }

b.button:after { content: "]"; padding: 0 2px 0 3px; }

p a > code:hover { color: #1a0f00; }

#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }
#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }

#content { margin-top: 1.25em; }

#content:before { content: none; }

#header > h1:first-child { color: #703f1c; margin-top: 2.25rem; margin-bottom: 0; }
#header > h1:first-child + #toc { margin-top: 8px; border-top: 1px solid rgba(145, 135, 84, 0.15); }
#header > h1:only-child, body.toc2 #header > h1:nth-last-child(2) { border-bottom: 1px solid rgba(145, 135, 84, 0.15); padding-bottom: 8px; }
#header .details { border-bottom: 1px solid rgba(145, 135, 84, 0.15); line-height: 1.45; padding-top: 0.25em; padding-bottom: 0.25em; padding-left: 0.25em; color: #666; display: -ms-flexbox; display: -webkit-flex; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; }
#header .details span:first-child { margin-left: -0.125em; }
#header .details span.email a { color: #999; }
#header .details br { display: none; }
#header .details br + span:before { content: "\00a0\2013\00a0"; }
#header .details br + span.author:before { content: "\00a0\22c5\00a0"; color: #999; }
#header .details br + span#revremark:before { content: "\00a0|\00a0"; }
#header #revnumber { text-transform: capitalize; }
#header #revnumber:after { content: "\00a0"; }

#content > h1:first-child:not([class]) { color: #703f1c; border-bottom: 1px solid rgba(145, 135, 84, 0.15); padding-bottom: 8px; margin-top: 0; padding-top: 1rem; margin-bottom: 1.25rem; }

#toc { border-bottom: 0px solid #ddd; padding-bottom: 0.5em; }
#toc > ul { margin-left: 0.125em; }
#toc ul.sectlevel0 > li > a { font-style: italic; }
#toc ul.sectlevel0 ul.sectlevel1 { margin: 0.5em 0; }
#toc ul { font-family: "Varela Round", sans-serif; list-style-type: none; }
#toc li { line-height: 1.3334; margin-top: 0.3334em; }
#toc a { text-decoration: none; }
#toc a:active { text-decoration: underline; }

#toctitle { color: #002c5e; font-size: 1.2em; }

@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; }
  body.toc2 { padding-left: 15em; padding-right: 0; }
  #toc.toc2 { margin-top: 0 !important; background: #f2f2f4; position: fixed; width: 15em; left: 0; top: 0; border-right: 1px solid #ddd; border-top-width: 0 !important; border-bottom-width: 0 !important; z-index: 1000; padding: 1.25em 1em; height: 100%; overflow: auto; }
  #toc.toc2 #toctitle { margin-top: 0; margin-bottom: 0.8rem; font-size: 1.2em; }
  #toc.toc2 > ul { font-size: 0.9em; margin-bottom: 0; }
  #toc.toc2 ul ul { margin-left: 0; padding-left: 1em; }
  #toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
  body.toc2.toc-right { padding-left: 0; padding-right: 15em; }
  body.toc2.toc-right #toc.toc2 { border-right-width: 0; border-left: 1px solid #ddd; left: auto; right: 0; } }
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
  #toc.toc2 { width: 20em; }
  #toc.toc2 #toctitle { font-size: 1.375em; }
  #toc.toc2 > ul { font-size: 0.95em; }
  #toc.toc2 ul ul { padding-left: 1.25em; }
  body.toc2.toc-right { padding-left: 0; padding-right: 20em; } }
#content #toc { border-style: solid; border-width: 1px; border-color: #d6d6dd; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f4; -webkit-border-radius: 6px; border-radius: 6px; }
#content #toc > :first-child { margin-top: 0; }
#content #toc > :last-child { margin-bottom: 0; }

#footer { max-width: none; background: #0b445a; padding: 1.25em; }

#footer-text { color: #fefdfd; line-height: 1.35; }

#content { margin-bottom: 0.625em; }

.sect1 { padding-bottom: 0.625em; }

@media only screen and (min-width: 768px) { #content { margin-bottom: 1.25em; }
  .sect1 { padding-bottom: 1.25em; } }
.sect1:last-child { padding-bottom: 0; }

.sect1 + .sect1 { border-top: 0px solid #ddd; }

#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; z-index: 1001; width: 1.5ex; margin-left: -1.5ex; display: block; text-decoration: none !important; visibility: hidden; text-align: center; font-weight: normal; }
#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: "\00A7"; font-size: 0.85em; display: block; padding-top: 0.1em; }
#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }
#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #00326b; text-decoration: none; }
#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #002652; }

details, .audioblock, .imageblock, .literalblock, .listingblock, .stemblock, .videoblock { margin-bottom: 1.25em; }

details > summary:first-of-type { cursor: pointer; display: list-item; outline: none; margin-bottom: 0.75em; }

.admonitionblock td.content > .title, .audioblock > .title, .exampleblock > .title, .imageblock > .title, .listingblock > .title, .literalblock > .title, .stemblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, table.tableblock > .title, .verseblock > .title, .videoblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-rendering: optimizeLegibility; text-align: left; }

table.tableblock.fit-content > caption.title { white-space: nowrap; width: 0; }

.paragraph.lead > p, #preamble > .sectionbody > [class="paragraph"]:first-of-type p { font-size: 1.21875em; line-height: 1.6; color: #703f1c; }

table.tableblock #preamble > .sectionbody > [class="paragraph"]:first-of-type p { font-size: inherit; }

.admonitionblock > table { border-collapse: separate; border: 0; background: none; width: 100%; }
.admonitionblock > table td.icon { text-align: center; width: 80px; }
.admonitionblock > table td.icon img { max-width: none; }
.admonitionblock > table td.icon .title { font-weight: bold; font-family: "Varela Round", sans-serif; text-transform: uppercase; }
.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid rgba(145, 135, 84, 0.15); color: #666; word-wrap: anywhere; }
.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }

.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #eddbdb; margin-bottom: 1.25em; padding: 1.25em; background: #fefdfd; -webkit-border-radius: 6px; border-radius: 6px; }
.exampleblock > .content > :first-child { margin-top: 0; }
.exampleblock > .content > :last-child { margin-bottom: 0; }

.sidebarblock { border-style: solid; border-width: 1px; border-color: #d1d1d8; margin-bottom: 1.25em; padding: 1.25em; background: #ececef; -webkit-border-radius: 6px; border-radius: 6px; }
.sidebarblock > :first-child { margin-top: 0; }
.sidebarblock > :last-child { margin-bottom: 0; }
.sidebarblock > .content > .title { color: #002c5e; margin-top: 0; }

.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }

.literalblock pre, .listingblock > .content > pre { border: 1px solid rgba(16, 195, 196, 0.125); -webkit-border-radius: 6px; border-radius: 6px; overflow-x: auto; padding: 1em; font-size: 0.8125em; }
@media only screen and (min-width: 768px) { .literalblock pre, .listingblock > .content > pre { font-size: 0.90625em; } }
@media only screen and (min-width: 1280px) { .literalblock pre, .listingblock > .content > pre { font-size: 1em; } }

.literalblock pre, .listingblock > .content > pre:not(.highlight), .listingblock > .content > pre[class="highlight"], .listingblock > .content > pre[class^="highlight "] { background: rgba(16, 195, 196, 0.05); }

.literalblock.output pre { color: rgba(16, 195, 196, 0.05); background-color: inherit; }

.listingblock > .content { position: relative; }

.listingblock code[data-lang]:before { display: none; content: attr(data-lang); position: absolute; font-size: 0.75em; top: 0.425rem; right: 0.5rem; line-height: 1; text-transform: uppercase; color: inherit; opacity: 0.5; }

.listingblock:hover code[data-lang]:before { display: block; }

.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: inherit; opacity: 0.5; }

.listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; }

.listingblock pre.highlightjs { padding: 0; }
.listingblock pre.highlightjs > code { padding: 1em; -webkit-border-radius: 6px; border-radius: 6px; }

.prettyprint { background: rgba(16, 195, 196, 0.05); }

pre.prettyprint .linenums { line-height: 1.4; margin-left: 2em; }

pre.prettyprint li { background: none; list-style-type: inherit; padding-left: 0; }

pre.prettyprint li code[data-lang]:before { opacity: 1; }

pre.prettyprint li:not(:first-child) code[data-lang]:before { display: none; }

table.linenotable { border-collapse: separate; border: 0; margin-bottom: 0; background: none; }
table.linenotable td[class] { color: inherit; vertical-align: top; padding: 0; line-height: inherit; white-space: normal; }
table.linenotable td.code { padding-left: 0.75em; }
table.linenotable td.linenos { border-right: 1px solid currentColor; opacity: 0.35; padding-right: 0.5em; }

pre.pygments .lineno { border-right: 1px solid currentColor; opacity: 0.35; display: inline-block; margin-right: 0.75em; }
pre.pygments .lineno:before { content: ""; margin-right: -0.125em; }

.quoteblock { margin: 0 1em 1.25em 1.5em; display: table; }
.quoteblock:not(.excerpt) > .title { margin-left: -1.5em; margin-bottom: 0.75em; }
.quoteblock blockquote, .quoteblock p { color: #999; font-size: 1.15rem; line-height: 1.75; word-spacing: 0.1em; letter-spacing: 0; font-style: italic; text-align: justify; }
.quoteblock blockquote { margin: 0; padding: 0; border: 0; }
.quoteblock blockquote:before { content: "\201c"; float: left; font-size: 2.75em; font-weight: bold; line-height: 0.6em; margin-left: -0.6em; color: #002c5e; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }
.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
.quoteblock .attribution { margin-top: 0.75em; margin-right: 0.5ex; text-align: right; }

.verseblock { margin: 0 1em 1.25em 1em; }
.verseblock pre { font-family: "Open Sans", "DejaVu Sans", sans; font-size: 1.15rem; color: #999; font-weight: 300; text-rendering: optimizeLegibility; }
.verseblock pre strong { font-weight: 400; }
.verseblock .attribution { margin-top: 1.25rem; margin-left: 0.5ex; }

.quoteblock .attribution, .verseblock .attribution { font-size: 0.8125em; line-height: 1.45; font-style: italic; }
.quoteblock .attribution br, .verseblock .attribution br { display: none; }
.quoteblock .attribution cite, .verseblock .attribution cite { display: block; letter-spacing: -0.025em; color: #666; }

.quoteblock.abstract blockquote:before, .quoteblock.excerpt blockquote:before, .quoteblock .quoteblock blockquote:before { display: none; }
.quoteblock.abstract blockquote, .quoteblock.abstract p, .quoteblock.excerpt blockquote, .quoteblock.excerpt p, .quoteblock .quoteblock blockquote, .quoteblock .quoteblock p { line-height: 1.6; word-spacing: 0; }
.quoteblock.abstract { margin: 0 1em 1.25em 1em; display: block; }
.quoteblock.abstract > .title { margin: 0 0 0.375em 0; font-size: 1.15em; text-align: center; }
.quoteblock.excerpt > blockquote, .quoteblock .quoteblock { padding: 0 0 0.25em 1em; border-left: 0.25em solid rgba(145, 135, 84, 0.15); }
.quoteblock.excerpt, .quoteblock .quoteblock { margin-left: 0; }
.quoteblock.excerpt blockquote, .quoteblock.excerpt p, .quoteblock .quoteblock blockquote, .quoteblock .quoteblock p { color: inherit; font-size: 1.0625rem; }
.quoteblock.excerpt .attribution, .quoteblock .quoteblock .attribution { color: inherit; text-align: left; margin-right: 0; }

p.tableblock:last-child { margin-bottom: 0; }

td.tableblock > .content { margin-bottom: 1.25em; word-wrap: anywhere; }
td.tableblock > .content > :last-child { margin-bottom: -1.25em; }

table.tableblock, th.tableblock, td.tableblock { border: 0 solid rgba(145, 135, 84, 0.15); }

table.grid-all > * > tr > * { border-width: 1px; }

table.grid-cols > * > tr > * { border-width: 0 1px; }

table.grid-rows > * > tr > * { border-width: 1px 0; }

table.frame-all { border-width: 1px; }

table.frame-ends { border-width: 1px 0; }

table.frame-sides { border-width: 0 1px; }

table.frame-none > colgroup + * > :first-child > *, table.frame-sides > colgroup + * > :first-child > * { border-top-width: 0; }

table.frame-none > :last-child > :last-child > *, table.frame-sides > :last-child > :last-child > * { border-bottom-width: 0; }

table.frame-none > * > tr > :first-child, table.frame-ends > * > tr > :first-child { border-left-width: 0; }

table.frame-none > * > tr > :last-child, table.frame-ends > * > tr > :last-child { border-right-width: 0; }

table.stripes-all tr, table.stripes-odd tr:nth-of-type(odd), table.stripes-even tr:nth-of-type(even), table.stripes-hover tr:hover { background: rgba(119, 84, 22, 0.025); }

th.halign-left, td.halign-left { text-align: left; }

th.halign-right, td.halign-right { text-align: right; }

th.halign-center, td.halign-center { text-align: center; }

th.valign-top, td.valign-top { vertical-align: top; }

th.valign-bottom, td.valign-bottom { vertical-align: bottom; }

th.valign-middle, td.valign-middle { vertical-align: middle; }

table thead th, table tfoot th { font-weight: bold; }

tbody tr th { display: table-cell; line-height: 1.5; background: rgba(119, 84, 22, 0.1); }

tbody tr th, tbody tr th p, tfoot tr th, tfoot tr th p { color: rgba(0, 0, 0, 0.8); font-weight: bold; }

p.tableblock > code:only-child { background: none; padding: 0; }

p.tableblock { font-size: 1em; }

ol { margin-left: 1.75em; }

ul li ol { margin-left: 1.5em; }

dl dd { margin-left: 1.125em; }

dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }

ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; }

ul.checklist, ul.none, ol.none, ul.no-bullet, ol.no-bullet, ol.unnumbered, ul.unstyled, ol.unstyled { list-style-type: none; }

ul.no-bullet, ol.no-bullet, ol.unnumbered { margin-left: 0.625em; }

ul.unstyled, ol.unstyled { margin-left: 0; }

ul.checklist { margin-left: 0.625em; }

ul.checklist li > p:first-child > .fa-square-o:first-child, ul.checklist li > p:first-child > .fa-check-square-o:first-child { width: 1.25em; font-size: 0.8em; position: relative; bottom: 0.125em; }

ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }

ul.inline { display: -ms-flexbox; display: -webkit-box; display: flex; -ms-flex-flow: row wrap; -webkit-flex-flow: row wrap; flex-flow: row wrap; list-style: none; margin: 0 0 0.625em -1.25em; }

ul.inline > li { margin-left: 1.25em; }

.unstyled dl dt { font-weight: normal; font-style: normal; }

ol.arabic { list-style-type: decimal; }

ol.decimal { list-style-type: decimal-leading-zero; }

ol.loweralpha { list-style-type: lower-alpha; }

ol.upperalpha { list-style-type: upper-alpha; }

ol.lowerroman { list-style-type: lower-roman; }

ol.upperroman { list-style-type: upper-roman; }

ol.lowergreek { list-style-type: lower-greek; }

.hdlist > table, .colist > table { border: 0; background: none; }
.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }

td.hdlist1, td.hdlist2 { vertical-align: top; padding: 0 0.625em; }

td.hdlist1 { font-weight: bold; padding-bottom: 1.25em; }

td.hdlist2 { word-wrap: anywhere; }

.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }

.colist td:not([class]):first-child { padding: 0.4em 0.75em 0 0.75em; line-height: 1; vertical-align: top; }
.colist td:not([class]):first-child img { max-width: none; }
.colist td:not([class]):last-child { padding: 0.25em 0; }

.thumb, .th { line-height: 0; display: inline-block; border: solid 4px #fff; -webkit-box-shadow: 0 0 0 1px #ddd; box-shadow: 0 0 0 1px #ddd; }

.imageblock.left { margin: 0.25em 0.625em 1.25em 0; }
.imageblock.right { margin: 0.25em 0 1.25em 0.625em; }
.imageblock > .title { margin-bottom: 0; }
.imageblock.thumb, .imageblock.th { border-width: 6px; }
.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }

.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
.image.left { margin-right: 0.625em; }
.image.right { margin-left: 0.625em; }

a.image { text-decoration: none; display: inline-block; }
a.image object { pointer-events: none; }

sup.footnote, sup.footnoteref { font-size: 0.875em; position: static; vertical-align: super; }
sup.footnote a, sup.footnoteref a { text-decoration: none; }
sup.footnote a:active, sup.footnoteref a:active { text-decoration: underline; }

#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
#footnotes hr { width: 20%; min-width: 6.25em; margin: -0.25em 0 0.75em 0; border-width: 1px 0 0 0; }
#footnotes .footnote { padding: 0 0.375em 0 0.225em; line-height: 1.3334; font-size: 0.875em; margin-left: 1.2em; margin-bottom: 0.2em; }
#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; margin-left: -1.05em; }
#footnotes .footnote:last-of-type { margin-bottom: 0; }
#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }

.gist .file-data > table { border: 0; background: #fff; width: 100%; margin-bottom: 0; }
.gist .file-data > table td.line-data { width: 99%; }

div.unbreakable { page-break-inside: avoid; }

.big { font-size: larger; }

.small { font-size: smaller; }

.underline { text-decoration: underline; }

.overline { text-decoration: overline; }

.line-through { text-decoration: line-through; }

.aqua { color: #00bfbf; }

.aqua-background { background-color: #00fafa; }

.black { color: black; }

.black-background { background-color: black; }

.blue { color: #0000bf; }

.blue-background { background-color: #0000fa; }

.fuchsia { color: #bf00bf; }

.fuchsia-background { background-color: #fa00fa; }

.gray { color: #606060; }

.gray-background { background-color: #7d7d7d; }

.green { color: #006000; }

.green-background { background-color: #007d00; }

.lime { color: #00bf00; }

.lime-background { background-color: #00fa00; }

.maroon { color: #600000; }

.maroon-background { background-color: #7d0000; }

.navy { color: #000060; }

.navy-background { background-color: #00007d; }

.olive { color: #606000; }

.olive-background { background-color: #7d7d00; }

.purple { color: #600060; }

.purple-background { background-color: #7d007d; }

.red { color: #bf0000; }

.red-background { background-color: #fa0000; }

.silver { color: #909090; }

.silver-background { background-color: #bcbcbc; }

.teal { color: #006060; }

.teal-background { background-color: #007d7d; }

.white { color: #bfbfbf; }

.white-background { background-color: #fafafa; }

.yellow { color: #bfbf00; }

.yellow-background { background-color: #fafa00; }

span.icon > .fa { cursor: default; }
a span.icon > .fa { cursor: inherit; }

.admonitionblock td.icon [class^="fa icon-"] { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }
.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #004060; }
.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }
.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; }
.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; }
.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; }

.conum[data-value] { display: inline-block; color: #fff !important; background-color: rgba(0, 0, 0, 0.8); -webkit-border-radius: 50%; border-radius: 50%; text-align: center; font-size: 0.75em; width: 1.67em; height: 1.67em; line-height: 1.67em; font-family: "Open Sans", "DejaVu Sans", sans-serif; font-style: normal; font-weight: bold; }
.conum[data-value] * { color: #fff !important; }
.conum[data-value] + b { display: none; }
.conum[data-value]:after { content: attr(data-value); }
pre .conum[data-value] { position: relative; top: -0.125em; }

b.conum * { color: inherit !important; }

.conum:not([data-value]):empty { display: none; }

#toc.toc2 ul ul { list-style-type: circle; padding-left: 2em; }

.sect1 { padding-bottom: 0 !important; margin-bottom: 2.5em; }

#header h1 { font-weight: bold; position: relative; left: -0.0625em; }

#content h2, #content h3, #content #toctitle, #content .sidebarblock > .content > .title, #content h4, #content h5, #content #toctitle { position: relative; left: -0.0625em; }
#content h2 { font-weight: bold; }

.paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { color: black; }

pre.pygments.highlight { background-color: rgba(16, 195, 196, 0.05); }

.pygments .tok-err { border: none !important; color: #800000 !important; }

.pygments .tok-c { color: #999 !important; }

</style>
<style>
pre.rouge table td { padding: 5px; }
pre.rouge table pre { margin: 0; }
pre.rouge, pre.rouge .w {
  color: #586e75;
}
pre.rouge .err {
  color: #002b36;
  background-color: #dc322f;
}
pre.rouge .c, pre.rouge .ch, pre.rouge .cd, pre.rouge .cm, pre.rouge .cpf, pre.rouge .c1, pre.rouge .cs {
  color: #657b83;
}
pre.rouge .cp {
  color: #b58900;
}
pre.rouge .nt {
  color: #b58900;
}
pre.rouge .o, pre.rouge .ow {
  color: #93a1a1;
}
pre.rouge .p, pre.rouge .pi {
  color: #93a1a1;
}
pre.rouge .gi {
  color: #859900;
}
pre.rouge .gd {
  color: #dc322f;
}
pre.rouge .gh {
  color: #268bd2;
  background-color: #002b36;
  font-weight: bold;
}
pre.rouge .k, pre.rouge .kn, pre.rouge .kp, pre.rouge .kr, pre.rouge .kv {
  color: #6c71c4;
}
pre.rouge .kc {
  color: #cb4b16;
}
pre.rouge .kt {
  color: #cb4b16;
}
pre.rouge .kd {
  color: #cb4b16;
}
pre.rouge .s, pre.rouge .sb, pre.rouge .sc, pre.rouge .dl, pre.rouge .sd, pre.rouge .s2, pre.rouge .sh, pre.rouge .sx, pre.rouge .s1 {
  color: #859900;
}
pre.rouge .sa {
  color: #6c71c4;
}
pre.rouge .sr {
  color: #2aa198;
}
pre.rouge .si {
  color: #d33682;
}
pre.rouge .se {
  color: #d33682;
}
pre.rouge .nn {
  color: #b58900;
}
pre.rouge .nc {
  color: #b58900;
}
pre.rouge .no {
  color: #b58900;
}
pre.rouge .na {
  color: #268bd2;
}
pre.rouge .m, pre.rouge .mb, pre.rouge .mf, pre.rouge .mh, pre.rouge .mi, pre.rouge .il, pre.rouge .mo, pre.rouge .mx {
  color: #859900;
}
pre.rouge .ss {
  color: #859900;
}
</style>
</head>
<body class="article toc2 toc-left">
<div id="header">
<h1>Tool Introspection</h1>
<div class="details">
<span id="author" class="author">René Ferdinand Rivera Morell</span><br>
<span id="email" class="email"><a href="mailto:grafikrobot@gmail.com">grafikrobot@gmail.com</a></span><br>
<span id="revnumber"> P2717R1,</span>
<span id="revdate">2023-05-17</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_abstract">1. Abstract</a></li>
<li><a href="#_revision_history">2. Revision History</a>
<ul class="sectlevel2">
<li><a href="#_revision_1_may_2023">2.1. Revision 1 (May 2023)</a></li>
<li><a href="#_revision_0_december_2022">2.2. Revision 0 (December 2022)</a></li>
</ul>
</li>
<li><a href="#_motivation">3. Motivation</a></li>
<li><a href="#_scope">4. Scope</a></li>
<li><a href="#_design">5. Design</a>
<ul class="sectlevel2">
<li><a href="#_introspection">5.1. Introspection</a></li>
<li><a href="#_declaration">5.2. Declaration</a></li>
<li><a href="#_levels">5.3. Levels</a></li>
<li><a href="#_capabilities">5.4. Capabilities</a></li>
<li><a href="#_version_specification">5.5. Version Specification</a></li>
<li><a href="#_version_matching">5.6. Version Matching</a></li>
<li><a href="#_format">5.7. Format</a></li>
<li><a href="#_capability_versions">5.8. Capability Versions</a></li>
<li><a href="#_impact_on_the_standard">5.9. Impact On The Standard</a></li>
</ul>
</li>
<li><a href="#_implementation_experience">6. Implementation Experience</a></li>
<li><a href="#_polls">7. Polls</a>
<ul class="sectlevel2">
<li><a href="#_sg15_p2717r0_2023_01_27">7.1. SG15: P2717R0 (2023-01-27)</a></li>
</ul>
</li>
<li><a href="#_wording">8. Wording</a>
<ul class="sectlevel2">
<li><a href="#_normative_references">8.1. Normative references</a></li>
<li><a href="#_specification_conformance">8.2. Specification: Conformance</a></li>
<li><a href="#_definitions">8.3. Definitions</a></li>
<li><a href="#_specification_introspection">8.4. Specification: Introspection</a></li>
<li><a href="#_json_schema">8.5. JSON Schema</a></li>
</ul>
</li>
<li><a href="#_examples">9. Examples</a>
<ul class="sectlevel2">
<li><a href="#_portable_command_lines">9.1. Portable Command Lines</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<style>
.sectionbody > div > .ins {
  border-left: solid 0.4em green;
  padding-left: 1em;
  text-decoration: underline solid green;
  text-underline-offset: 0.3em;
}
.def > .content :first-child {
  margin-left: 0;
}
.def > .content > * {
  margin-left: 3em;
}
.icon .title {
  font-size: 250%;
}
</style>
<div class="dlist">
<dl>
<dt class="hdlist1">Document number: </dt>
<dd>
<p>ISO/IEC/JTC1/SC22/WG21/P2717R1</p>
</dd>
<dt class="hdlist1">Date: </dt>
<dd>
<p>2023-05-17</p>
</dd>
<dt class="hdlist1">Audience: </dt>
<dd>
<p>SG15</p>
</dd>
<dt class="hdlist1">Reply-to: </dt>
<dd>
<p>René Ferdinand Rivera Morell - <em>grafikrobot at gmail dot com</em></p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_abstract"><a class="anchor" href="#_abstract"></a>1. Abstract</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We propose to add a mechanism for C&#43;&#43; tools to communicate what capabilities
a tool implements from the Ecosystem IS.
<sup class="footnote" id="_footnote_EcoIS">[<a id="_footnoteref_1" class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_revision_history"><a class="anchor" href="#_revision_history"></a>2. Revision History</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_revision_1_may_2023"><a class="anchor" href="#_revision_1_may_2023"></a>2.1. Revision 1 (May 2023)</h3>
<div class="paragraph">
<p>Addition of scope, functionality levels, use cases, and wording.
Simplified introspection and declaration interfaces to make implementing
introspection trivial and declaration straightforward. The simplification
removes the <em>bounded</em> introspection interface as superfluous.</p>
</div>
</div>
<div class="sect2">
<h3 id="_revision_0_december_2022"><a class="anchor" href="#_revision_0_december_2022"></a>2.2. Revision 0 (December 2022)</h3>
<div class="paragraph">
<p>Initial text.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_motivation"><a class="anchor" href="#_motivation"></a>3. Motivation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>C&#43;&#43; tools will implement the aspects of the Ecosystem IS <sup class="footnoteref">[<a class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup> that
are relevant to the particular tool. And when they implement those aspects they
may implement a particular edition of them. In order to allow other tools to
adjust their behavior to accommodate such differences we need a mechanism of
introspection for all tools. Additionally when one tool requests to use another
tool&#8217;s Ecosystem IS aspect it&#8217;s desirable to consistently communicate which
edition(s) of that aspect it can use.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_scope"><a class="anchor" href="#_scope"></a>4. Scope</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This proposal aims to specify a method for tools to communicate which specific
aspects of the Ecosystem IS they support and adhere to consumers (either other
tools or users). It does not prescribe which aspects of the Ecosystem IS the
tools must support or adhere to except to prescribe that supporting any
capability of the Ecosystem IS must also support this aspect. Ultimately it
wants to make it possible to address two cases:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>What does the tool support and adhere to?</p>
</li>
<li>
<p>The tool should adhere to what the consumer asks if possible.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_design"><a class="anchor" href="#_design"></a>5. Design</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There are two aspects that this proposal covers:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Introspection</dt>
<dd>
<p>A tool reporting its capabilities to a consumer.</p>
</dd>
<dt class="hdlist1">Declaration</dt>
<dd>
<p>A consumer specifying the capability edition and version.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p><em>Introspection</em> would allow a consumer to ask the target tool what versions of
of capabilities it supports. The target tool would respond with the range of
capabilities, or nothing, that it supports. With that information the consumer
can go ahead and follow the defined standard, in the Ecosystem IS
<sup class="footnoteref">[<a class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup>, to further interact with the target tool.</p>
</div>
<div class="paragraph">
<p>For <em>declaration</em> a consumer can specify a particular capability and a version
to interact with. And if the target tool recognizes the specification it can
continue to process the consumer&#8217;s use of that capability.</p>
</div>
<div class="paragraph">
<p>Even though these are two separate functions they are by necessity tied to each
other. In order for this pairing to work, and generally for tool
interoperability to work, the tool consumers and target tools must operate on
this minimal pair of functions to bootstrap their interactions. To make that
possible, this design follows some basic tenets:</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
Minimal
</td>
<td class="hdlist2">
<p>The interface of the target tool is a single universal command line
argument for each of the two operations.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Concise
</td>
<td class="hdlist2">
<p>The information communicated to and from the target tool and consumer
is as brief as needed to convey the required information.</p>
</td>
</tr>
<tr>
<td class="hdlist1">
Robust
</td>
<td class="hdlist2">
<p>The interface and information should not result in failure conditions
for either the consumer or target tool. Both ends of the interactions need to
rely on the stability of the interface to then be able to interoperate.</p>
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_introspection"><a class="anchor" href="#_introspection"></a>5.1. Introspection</h3>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">ℹ</div>
</td>
<td class="content">
We used to include a <em>bounded</em> introspection option. But turned out to be
not worth the added complexity in the consumer and tool.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The consumer can use a single method to query the target tool and obtain all the
capabilities that are available or specifically requested. The use case
supported is for unbounded <em>introspection</em> of the available capabilities with a
single valueless <code>--std-info</code> option.</p>
</div>
<div class="paragraph">
<p>And unbounded introspection simply returns everything the tool is capable
of doing. The tool has the option to respond with either all minimal single
(aka bare) versions or full version ranges. Either can be trivially implemented
by tools as most time it can be a hard-wired response text.</p>
</div>
<div class="paragraph">
<p>Running a tool with the option would look like the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell"><span class="nv">$ </span>tool <span class="nt">--std-info</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>And could produce this as a minimal JSON output to indicate the single version
of the capabilities it supports:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
  </span><span class="nl">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"std:info"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Or could produce this as a JSON output in the case of full version ranges:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
  </span><span class="nl">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"std:info"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[1,2.5]"</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Which would minimally indicate that the tool only supports the introspection
capability at versions "1.0.0" through "2.5.0".</p>
</div>
</div>
<div class="sect2">
<h3 id="_declaration"><a class="anchor" href="#_declaration"></a>5.2. Declaration</h3>
<div class="paragraph">
<p>The consumer can inform, i.e. declare, to the target tool that specific
capabilities should use particular versions when responding with information
using one or more <code>--std-info=&lt;VersionSpec&gt;</code> options. The declarations can only
exist in tandem with options for the mentioned capabilities. It&#8217;s expected that
a consumer will first <em>introspect</em> a target tool to discover what it supports.
Followed by the consumer <em>declaring</em> to the target tool what version(s) of the
capabilities it is willing to consume. The target tool can then either accept
the declared capability versions or indicate an error.</p>
</div>
<div class="paragraph">
<p>An exchange between a consumer and target tool would begin with the
<em>introspection</em>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">tool <span class="s2">"--std-info"</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>With a target tool response:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
  </span><span class="nl">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"std:info"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[1,2)"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"gcc:extra"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[2.1]"</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Which the consumer can use to <em>declare</em> the specific capability versions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell">tool <span class="s2">"--std-decl=std:info=2.0.0"</span> <span class="s2">"--std-decl=gcc:extra=2.1.0"</span> ...</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_levels"><a class="anchor" href="#_levels"></a>5.3. Levels</h3>
<div class="paragraph">
<p>For some use cases it helps to simplify the extent of information the
introspection understands. While it would be reasonable to expect a tool written
in a modern general purpose programming language to fully implement all aspects
of the introspection. It would not be practical to have a shell script parse
and recognize the more challenging aspect of parsing version number ranges and
matching them together. To support such use cases the introspection has to
support levels "min" and "full".</p>
</div>
<div class="paragraph">
<p>Obviously the "full" level equates to the tool understanding all the arguments
and values. The "min" level only understands these:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Only introspection <code>--std-info</code> option.</p>
</li>
<li>
<p>Single version number in the responses for <code>--std-info</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This has the effect that a tool which only support the "min" level can only
support specific versions of the capabilities it implements. But it also means
that consumers will need to adjust their behavior to the tool instead of being
able to ask the tool to adjust to the consumer. Consequently the consumer will
likely have the more complex logic to do that adjustment.</p>
</div>
</div>
<div class="sect2">
<h3 id="_capabilities"><a class="anchor" href="#_capabilities"></a>5.4. Capabilities</h3>
<div class="paragraph">
<p>For this proposal capabilities refers to any published coherent target tool
interface. This can include any single interface, like a single target tool
option. Or it can include a collective interface of the target tool that covers
many options. A capability is specified as a series of "scoped" identifiers
separated by colons (":"). The capability must match this regular expression:
<sup class="footnote" id="_footnote_Regex">[<a id="_footnoteref_2" class="footnote" href="#_footnotedef_2" title="View footnote.">2</a>]</sup></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="plan_text">^[a-z_]+(:[a-z_]+)+$</code></pre>
</div>
</div>
<div class="paragraph">
<p>At minimum a capability has two components. The first component is a general
scope that identifies if the capability is one in the IS, or if it&#8217;s a tool
vendor capability.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Standard</dt>
<dd>
<p>A capability with a scope of <code>std</code> indicates that it&#8217;s defined in the
IS. <sup class="footnoteref">[<a class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup></p>
</dd>
<dt class="hdlist1">Vendor</dt>
<dd>
<p>Any other capability, i.e. other than <code>std</code>, is available for vendors
to use as extensions outside the IS. <sup class="footnoteref">[<a class="footnote" href="#_footnotedef_1" title="View footnote.">1</a>]</sup></p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="_version_specification"><a class="anchor" href="#_version_specification"></a>5.5. Version Specification</h3>
<div class="paragraph">
<p>When indicating the version, or versions, to the target tool or the consumer the
version information is specified in two possible forms: a single version, or a
single version range.</p>
</div>
<div class="sect3">
<h4 id="_single_version"><a class="anchor" href="#_single_version"></a>5.5.1. Single Version</h4>
<div class="paragraph">
<p>A single version in this proposal is composed of a one to three dotted whole
numbers. The numbers are expected to be strictly increasing. But otherwise do
not impart any meaning to the components. Specifically this does not impart any
form of semantic meaning between versions. Although the specification of the
capabilities themselves may define such a semantic meaning. The format for the
version must match the regular expression:
<sup class="footnoteref">[<a class="footnote" href="#_footnotedef_2" title="View footnote.">2</a>]</sup></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="plain_text">^[0-9]+([.][0-9]+){0,2}$</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_version_range"><a class="anchor" href="#_version_range"></a>5.5.2. Version Range</h4>
<div class="paragraph">
<p>A version range in this proposal indicates a lower and upper bound of versions.
It is composed of a pair of versions, separated by a comma, and bracketed by
either an inclusive or exclusive symbol. This matches the intuition of a
mathematic interval, but with the use of the version triplet number line.
<sup class="footnote">[<a id="_footnoteref_3" class="footnote" href="#_footnotedef_3" title="View footnote.">3</a>]</sup>
Like the interval notation the <code>()</code> brackets indicate an exclusive point. And
the <code>[]</code> brackets indicate an inclusive point. As versions are decidedly not
single integers we use a <code>,</code> (comma) to separate the start and end of the range
instead of using <code>..</code>. Hence the format for the version range must match the
regular expression:
<sup class="footnoteref">[<a class="footnote" href="#_footnotedef_2" title="View footnote.">2</a>]</sup></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="plain_text">^[[(][0-9]+([.][0-9]+){0,2},[0-9]+([.][0-9]+){0,2}[)\\]]$</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_version_matching"><a class="anchor" href="#_version_matching"></a>5.6. Version Matching</h3>
<div class="paragraph">
<p>When given two version specifications tools will need to match the two to
determine the sub-range that are compatible with both. There are two aspects to
doing that matching: comparing the two single versions, and evaluating the
sub-range interval.</p>
</div>
<div class="sect3">
<h4 id="_single_version_comparison"><a class="anchor" href="#_single_version_comparison"></a>5.6.1. Single Version Comparison</h4>
<div class="paragraph">
<p>Comparing two single versions equates to three-way comparing each of the
components of both, <code>a</code> and <code>b</code>, as:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If the whole numbers of the first components, <code>i</code> and <code>j</code>, are not equal the
comparison is either <code>a &lt; b</code> or <code>a &gt; b</code> if <code>i &lt; j</code> or <code>i &gt; j</code> respectively.
Otherwise,</p>
</li>
<li>
<p>If the whole numbers of the second components, <code>k</code> and <code>l</code>, are not equal the
comparison is either <code>a &lt; b</code> or <code>a &gt; b</code> if <code>k &lt; l</code> or <code>k &gt; l</code> respectively.
Otherwise,</p>
</li>
<li>
<p>If the whole numbers of the third components, <code>m</code> and <code>n</code>, are not equal the
comparison is either <code>a &lt; b</code> or <code>a &gt; b</code> if <code>m &lt; n</code> or <code>m &gt; n</code> respectively.
Otherwise,</p>
</li>
<li>
<p>The versions are equal, i.e. <code>a == b</code>.</p>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4 id="_range_comparison"><a class="anchor" href="#_range_comparison"></a>5.6.2. Range Comparison</h4>
<div class="paragraph">
<p>Tools will need to compare either a single version to a version range, or a
version range to another range to determine the overlapping version sub-range.
The single version to a version range comparison can be reformulated to a
range-to-range comparison. I.e. a comparison of a single range <code>a</code> to a range
<code>b</code> is equivalent to a comparison of range <code>[a,a]</code> to range <code>b</code>. Hence we only
need to consider the range-to-range comparison. Although implementations may
use special case for comparing single-to-range and range-to-single.
Range-to-range should follow something like the following to compare a range
<code>a,b</code> to <code>m,n</code>, with some varied inclusive or exclusive ends:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If <code>b &lt; m</code> or <code>n &lt; a</code> the range is <em>empty</em>.</p>
</li>
<li>
<p>Otherwise, assign a <em>partial</em> range <code>x,y = max(a,m), min(b,n)</code>.</p>
</li>
<li>
<p>If <code>a</code> or <code>m</code> are inclusive, then:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>If <code>b</code> or <code>n</code> are inclusive, then the range is <code>[x,y]</code>.</p>
</li>
<li>
<p>Otherwise, the range is <code>[x,y)</code>.</p>
</li>
</ol>
</div>
</li>
<li>
<p>Otherwise, if <code>b</code> or <code>n</code> are inclusive, then the range is <code>(x,y]</code>.</p>
</li>
<li>
<p>Otherwise, the range is <code>(x,y)</code>.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_format"><a class="anchor" href="#_format"></a>5.7. Format</h3>
<div class="paragraph">
<p>The information reported by <em>introspection</em> is a JSON
<sup class="footnote" id="_footnote_json">[<a id="_footnoteref_4" class="footnote" href="#_footnotedef_4" title="View footnote.">4</a>]</sup>
format document. Some advantages to using JSON:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It is widely used and available either natively or through libraries in many
programming languages. Which is particularly important as C&#43;&#43; tools are
written in an array of differing programming languages.</p>
</li>
<li>
<p>It is a simple format to understand by both programs and humans.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In maintaining our goals of the interface being minimal, concise, and robust,
the format for communicating the capabilities is a single key/value collection,
i.e. a JSON object.
<sup class="footnoteref">[<a class="footnote" href="#_footnotedef_4" title="View footnote.">4</a>]</sup></p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Capability Identifier</dt>
<dd>
<p>The <em>key</em> is a string with the capability identifier. The
format of the is as described in the <a href="#_capabilities">Capabilities</a> section.</p>
</dd>
<dt class="hdlist1">Version Specification</dt>
<dd>
<p>The <em>value</em> indicates the versions supported by the tool
for the capability. The versions follows the format described in the
<a href="#_version_specification">Version Specification</a> section.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>In addition to the <em>capability identifier</em> / <em>version specification</em> members,
there are additional special members:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Schema</dt>
<dd>
<p>The document can also specify a reference to a JSON Schema.
<sup class="footnote" id="_footnote_jschema">[<a id="_footnoteref_5" class="footnote" href="#_footnotedef_5" title="View footnote.">5</a>]</sup>
For this the <em>key</em> would be <code>$schema</code>, and the <em>value</em> would a URI to a
published stable schema
(<code><a href="https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json" class="bare">https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json</a></code>).</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>There is one designated capability that is required to appear in the document:
The <code>std:info</code> capability with a corresponding <em>version specification</em>. This
requirement allows a consumer to identify the format of the rest of the document
at all times.</p>
</div>
<div class="paragraph">
<p>This is a minimal conforming document:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
  </span><span class="nl">"std:info"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.0.0"</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This is also a minimal conforming document. But specifies a range of versions
supported for the <code>std:info</code> capability:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
  </span><span class="nl">"std:info"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[1.0.0,2.0.0)"</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>This example adds a custom vendor capability and the schema reference:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
  </span><span class="nl">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"std:info"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[1.0.0,2.0.0)"</span><span class="p">,</span><span class="w">
  </span><span class="nl">"gcc:extra"</span><span class="p">:</span><span class="w"> </span><span class="s2">"1.5.0"</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>See the <a href="#_wording">Wording</a> for a <a href="#_json_schema">JSON Schema</a> for this format.</p>
</div>
</div>
<div class="sect2">
<h3 id="_capability_versions"><a class="anchor" href="#_capability_versions"></a>5.8. Capability Versions</h3>
<div class="paragraph">
<p>The capabilities and their version is expected to work similar to how C&#43;&#43;
feature macro version ([version.syn]) in that it specifies if a feature of a
standard is implemented and at what version. Although the meaning of the
capability version is not defined, it&#8217;s recommended that it follow some simple
rules:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The <em>major-number</em> should only change for large changes.</p>
</li>
<li>
<p>The <em>minor-number</em> should only change for fixes that are significant, but not
large.</p>
</li>
<li>
<p>The <em>patch-number</em> should only change for fixes that are simple and small.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>That is, it should roughly follow the industry understanding of sematic
versioning.
<sup class="footnote" id="_footnote_Semver">[<a id="_footnoteref_6" class="footnote" href="#_footnotedef_6" title="View footnote.">6</a>]</sup></p>
</div>
<div class="ulist">
<ul>
<li>
<p>Each part of the version number should always increment, but;</p>
</li>
<li>
<p>The <em>minor-number</em> should reset to zero when the <em>major-number</em> increases,
equivalently for the <em>patch-number</em> and <em>minor-number</em>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>These rules set it apart from the C&#43;&#43; feature macros that they impart some
meaning to a version relative to other versions.</p>
</div>
</div>
<div class="sect2">
<h3 id="_impact_on_the_standard"><a class="anchor" href="#_impact_on_the_standard"></a>5.9. Impact On The Standard</h3>
<div class="paragraph">
<p>This specification adds new functionality that is partly required for programs.
Other specifications that define program behavior will need to follow this
specification for conformance to the Ecosystem IS.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_implementation_experience"><a class="anchor" href="#_implementation_experience"></a>6. Implementation Experience</h2>
<div class="sectionbody">
<div class="paragraph">
<p>None yet.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_polls"><a class="anchor" href="#_polls"></a>7. Polls</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_sg15_p2717r0_2023_01_27"><a class="anchor" href="#_sg15_p2717r0_2023_01_27"></a>7.1. SG15: P2717R0 (2023-01-27)</h3>
<div class="paragraph">
<p>SG15 wants to pursue defining in the Tooling IS a way for tools to provide
portable information about which parts of the Tooling IS and vendor extensions
they support.</p>
</div>
<table class="tableblock frame-all grid-all fit-content">
<colgroup>
<col>
<col>
<col>
<col>
<col>
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">SF</th>
<th class="tableblock halign-center valign-top">F</th>
<th class="tableblock halign-center valign-top">N</th>
<th class="tableblock halign-center valign-top">A</th>
<th class="tableblock halign-center valign-top">SA</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-center valign-top"><p class="tableblock">5</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">3</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">0</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">0</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">0</p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_wording"><a class="anchor" href="#_wording"></a>8. Wording</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Wording is relative to
<a href="https://github.com/cplusplus/ecosystem-is/tree/86cfbd72b9fae73554935d5f7039a798b5583628">ecosystem-is/86cfbd7</a>.
<sup class="footnote">[<a id="_footnoteref_7" class="footnote" href="#_footnotedef_7" title="View footnote.">7</a>]</sup></p>
</div>
<div class="sect2">
<h3 id="_normative_references"><a class="anchor" href="#_normative_references"></a>8.1. Normative references</h3>
<div class="paragraph">
<p>In [intro.refs] add:</p>
</div>
<div class="dlist ins text-justify">
<dl>
<dt class="hdlist1">JSON</dt>
<dd>
<p>ISO/IEC 21778:2017, <em>Information technology — The JSON data interchange syntax</em></p>
</dd>
<dt class="hdlist1">POSIX</dt>
<dd>
<p>ISO/IEC 9945:2009, <em>Information technology — Portable Operating System Interface (POSIX®) Base Specifications, Issue 7</em></p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="_specification_conformance"><a class="anchor" href="#_specification_conformance"></a>8.2. Specification: Conformance</h3>
<div class="paragraph">
<p>Insert clause before <em>Terms and definitions</em> [intro.defs].</p>
</div>
<div class="sect3 ins text-justify">
<h4 id="cnf"><a class="anchor" href="#cnf"></a>8.2.1. Conformance <span class="right">[<a href="#cnf">cnf</a>]</span></h4>
<div class="paragraph">
<p>A conforming implementation shall meet the following criteria for conformance to
this standard:</p>
</div>
<div class="paragraph">
<p>— An application shall support the <em>minimum level</em> functionality of
introspection (<a href="#intspct-min">intspct.min</a>).</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_definitions"><a class="anchor" href="#_definitions"></a>8.3. Definitions</h3>
<div class="paragraph">
<p>Add the following to <em>Terms and definitions</em> [intro.defs].</p>
</div>
<div class="sect3 ins text-justify">
<h4 id="defns-application"><a class="anchor" href="#defns-application"></a>8.3.1. application <span class="right">[<a href="#defns-application">defns.application</a>]</span></h4>
<div class="paragraph">
<p>a computer program that performs some desired function.</p>
</div>
<div class="paragraph">
<p>[ <em>Note 1</em>: From POSIX.&#8201;&#8212;&#8201;<em>end note</em> ]</p>
</div>
</div>
<div class="sect3 ins text-justify">
<h4 id="defns-capability"><a class="anchor" href="#defns-capability"></a>8.3.2. capability <span class="right">[<a href="#defns-capability">defns.capability</a>]</span></h4>
<div class="paragraph">
<p>an aspect of an overall specification that defines a subset of the entire
specification.</p>
</div>
</div>
<div class="sect3 ins text-justify">
<h4 id="defns-file"><a class="anchor" href="#defns-file"></a>8.3.3. file <span class="right">[<a href="#defns-file">defns.file</a>]</span></h4>
<div class="paragraph">
<p>an object that can be written to, or read from, or both.</p>
</div>
<div class="paragraph">
<p>[ <em>Note 1</em>: From POSIX.&#8201;&#8212;&#8201;<em>end note</em> ]</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_specification_introspection"><a class="anchor" href="#_specification_introspection"></a>8.4. Specification: Introspection</h3>
<div class="paragraph">
<p>Insert clause after <em>Terms and definitions</em> [intro.defs].</p>
</div>
<div class="sect3 ins text-justify">
<h4 id="intspct"><a class="anchor" href="#intspct"></a>8.4.1. Introspection <span class="right">[<a href="#intspct">intspct</a>]</span></h4>
<div class="sect4">
<h5 id="intspct-pre"><a class="anchor" href="#intspct-pre"></a>8.4.1.1. Preamble <span class="right">[<a href="#intspct-pre">intspct.pre</a>]</span></h5>
<div class="paragraph">
<p>This clause describes options, output, and formats that describe what
capabilities of this standard an application supports. An application shall
support the <em>minimum level</em> functionality (<a href="#intspct-min">intspct.min</a>). An application can
support the <em>full level</em> functionality (<a href="#intspct-full">intspct.full</a>).</p>
</div>
<div class="paragraph">
<p>This clause specifies the <code>std:info</code> capability (<a href="#intspct-cap">intspct.cap</a>).</p>
</div>
</div>
<div class="sect4">
<h5 id="intspct-overview"><a class="anchor" href="#intspct-overview"></a>8.4.1.2. Overview <span class="right">[<a href="#intspct-overview">intspct.overview</a>]</span></h5>
<div class="openblock">
<div class="content">
<div class="paragraph">
<p><code><em>application</em> [--std-info[=<em>declaration</em>]] [--std-info-out=<em>file</em>]</code></p>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="intspct-options"><a class="anchor" href="#intspct-options"></a>8.4.1.3. Options <span class="right">[<a href="#intspct-options">intspct.options</a>]</span></h5>
<div class="paragraph">
<p>The following options shall be supported:</p>
</div>
<div id="intspct-opt-info" class="dlist">
<dl>
<dt class="hdlist1"><code>--std-info</code> <span class="right">[<a href="#intspct-opt-info">intspct.opt.info</a>]</span></dt>
<dd>
<p>Outputs the version information of the capabilities supported by the
application.
The option can be specified zero or one time.
The application shall support the option for <em>minimum level</em> (<a href="#intspct-min">intspct.min</a>)
functionality.</p>
</dd>
</dl>
</div>
<div id="intspct-opt-out" class="dlist">
<dl>
<dt class="hdlist1"><code>--std-info-out=<em>file</em></code> <span class="right">[<a href="#intspct-opt-out">intspct.opt.out</a>]</span></dt>
<dd>
<p>The pathname of a file to output the information to. If <em>file</em> is &#8216;-&#8217;, the
standard output shall be used.
The application shall support the option for <em>minimum level</em> (<a href="#intspct-min">intspct.min</a>)
functionality.
Not specifying this option while specifying the <code>--std-info</code> option
(<a href="#intspct-opt-info">intspct.opt.info</a>) shall be equivalent to also specifying a
<code>--std-info-out=-</code> option.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The following options should be supported:</p>
</div>
<div id="intspct-opt-decl" class="dlist">
<dl>
<dt class="hdlist1"><code>--std-info=<em>declaration</em></code> <span class="right">[<a href="#intspct-opt-decl">intspct.opt.decl</a>]</span></dt>
<dd>
<p>Declares the required capability version of the application.
The option can be specified any number of times.
The application shall support the option for <em>full level</em> (<a href="#intspct-full">intspct.full</a>)
functionality.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="intspct-output"><a class="anchor" href="#intspct-output"></a>8.4.1.4. Output <span class="right">[<a href="#intspct-output">intspct.output</a>]</span></h5>
<div class="paragraph">
<p>An application shall output a valid JSON text file that conforms to the
introspection schema (<a href="#intspct-schema">intspct.schema</a>) to the file specified in the options
(<a href="#intspct-opt-out">intspct.opt.out</a>).</p>
</div>
</div>
<div class="sect4">
<h5 id="intspct-schema"><a class="anchor" href="#intspct-schema"></a>8.4.1.5. Schema <span class="right">[<a href="#intspct-schema">intspct.schema</a>]</span></h5>
<div class="paragraph">
<p>An introspection JSON text file shall contain one introspection JSON object
(<a href="#intspct-schema-obj">intspct.schema.obj</a>).</p>
</div>
<div class="sect5">
<h6 id="intspct-schema-obj"><a class="anchor" href="#intspct-schema-obj"></a>8.4.1.5.1. Introspection Object <span class="right">[<a href="#intspct-schema-obj">intspct.schema.obj</a>]</span></h6>
<div class="paragraph">
<p>The <em>introspection object</em> is the root JSON object of the introspection JSON
text.</p>
</div>
<div class="paragraph">
<p>An <em>introspection object</em> can have the following fields.</p>
</div>
<div id="intspct-fld-schema" class="dlist">
<dl>
<dt class="hdlist1">JSON Schema Field <span class="right">[<a href="#intspct-fld-schema">intspct.schema.schema</a>]</span> </dt>
<dd>
<p><em>Name</em>: <code>$schema</code><br>
<em>Type</em>: <code>string</code><br>
<em>Value</em>:
  The value shall be a reference to a JSON Schema specification.<br>
<em>Description</em>:
  An <em>introspection object</em> can contain this field.
  If an <em>introspection object</em> does not contain this field the value shall be a
  reference to the JSON Schema corresponding to the current edition of this
  standard.</p>
</dd>
</dl>
</div>
<div id="intspct-fld-cap" class="dlist">
<dl>
<dt class="hdlist1">capability <span class="right">[<a href="#intspct-fld-cap">intspct.schema.cap</a>]</span> </dt>
<dd>
<p><em>Name</em>: <em>capability-identifier</em> (<a href="#intspct-cap">intspct.cap</a>)<br>
<em>Type</em>: <code>string</code><br>
<em>Value</em>:
  The value shall be a <em>version-number</em> for <em>minimum level</em> functionality.
  Or the value shall be a <em>version-range</em> for <em>full level</em> functionality.<br>
<em>Description</em>:
  An <em>introspection object</em> can contain this field one or more times.
  When the field appears more than one time the name of the fields shall be
  unique within the <em>introspection object</em>.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect4">
<h5 id="intspct-cap"><a class="anchor" href="#intspct-cap"></a>8.4.1.6. Capabilities <span class="right">[<a href="#intspct-cap">intspct.cap</a>]</span></h5>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<em>capability-identifier</em>: 
</td>
<td class="hdlist2">
<p><em>name</em> <em>scope-designator</em> <em>name</em> <em>sub-capability-identifier</em></p>
</td>
</tr>
<tr>
<td class="hdlist1">
<em>sub-capability-identifier</em>: 
</td>
<td class="hdlist2">
<p><em>scope-designator</em> <em>name</em> <em>sub-capability-identifier</em></p>
</td>
</tr>
<tr>
<td class="hdlist1">
<em>name</em>: one or more of 
</td>
<td class="hdlist2">
<p><code>a b c d e f g h i j k l m</code><br>
<code>n o p q r s t u v w x y z</code><br>
<code>_</code></p>
</td>
</tr>
<tr>
<td class="hdlist1">
<em>scope-designator</em>: 
</td>
<td class="hdlist2">
<p><code>:</code></p>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>A <em>capability-identifier</em> is composed of two or more <em>scope-designator</em>
delimited <em>name</em> parts.</p>
</div>
<div class="paragraph">
<p>The <em>name</em> <code>std</code> in a <em>capability-identifier</em> is reserved for capabilities
defined in this standard.</p>
</div>
<div class="paragraph">
<p>Applications can specify vendor designated <em>name</em> parts defined outside of this
standard.</p>
</div>
</div>
<div class="sect4">
<h5 id="intspct-vers"><a class="anchor" href="#intspct-vers"></a>8.4.1.7. Versions <span class="right">[<a href="#intspct-vers">intspct.vers</a>]</span></h5>
<div class="paragraph">
<p>A version shall be either a single version number (<a href="#intspct-vers-num">intspct.vers.num</a>) or a
version range (<a href="#intspct-vers-range">intspct.vers.range</a>).</p>
</div>
<div class="paragraph">
<p>A single version number shall be equivalent to the inclusive version range
spanning solely that single version number.</p>
</div>
<div class="paragraph">
<p>[ <em>Note 1</em>:
That is the version number <code>i.j.k</code> is equivalent to version range
<code>[i.j.k,i.j.k]</code>.
— <em>end note</em> ]</p>
</div>
<div class="sect5">
<h6 id="intspct-vers-num"><a class="anchor" href="#intspct-vers-num"></a>8.4.1.7.1. Version Number <span class="right">[<a href="#intspct-vers-num">intspct.vers.num</a>]</span></h6>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<em>version-number</em>: 
</td>
<td class="hdlist2">
<p><em>major-number</em> <code>.</code> <em>minor-number</em> <code>.</code> <em>patch-number</em></p>
</td>
</tr>
<tr>
<td class="hdlist1">
<em>major-number</em>: 
</td>
<td class="hdlist2">
<p><em>digits</em></p>
</td>
</tr>
<tr>
<td class="hdlist1">
<em>minor-number</em>: 
</td>
<td class="hdlist2">
<p><em>digits</em></p>
</td>
</tr>
<tr>
<td class="hdlist1">
<em>patch-number</em>: 
</td>
<td class="hdlist2">
<p><em>digits</em></p>
</td>
</tr>
<tr>
<td class="hdlist1">
<em>digits</em>: one or more of 
</td>
<td class="hdlist2">
<p><code>0 1 2 3 4 5 6 7 8 9</code></p>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>A version number is composed of 1, 2, or 3 decimal numbers (<em>digits</em>)
separated by a period (<code>.</code>).</p>
</div>
<div class="paragraph">
<p>A version number composed of 1 decimal number is equivalent to that decimal
number followed by <code>.0.0</code>.</p>
</div>
<div class="paragraph">
<p>[ <em>Note 1</em>:
That is the version number <code>N</code> is equivalent to <code>N.0.0</code>.
— <em>end note</em> ]</p>
</div>
<div class="paragraph">
<p>A version number composed of 2 decimal number parts is equivalent to those
decimal number parts followed by <code>.0</code>.</p>
</div>
<div class="paragraph">
<p>[ <em>Note 2</em>:
That is the version number <code>N.M</code> is equivalent to <code>N.M.0</code>.
— <em>end note</em> ]</p>
</div>
<div class="paragraph">
<p>Version numbers define a total ordering where version number <em>a</em> with parts
<em>i</em>, <em>j</em>, <em>k</em> is ordered before version number <em>b</em> with parts <em>p</em>, <em>q</em>, <em>r</em>
when: <em>i</em> &lt; <em>p</em>, or <em>i</em> == <em>p</em> and <em>j</em> &lt; <em>q</em>, or <em>i</em> == <em>p</em> and <em>j</em> == <em>q</em>
and <em>k</em> &lt; <em>r</em>.</p>
</div>
<div class="paragraph">
<p>Otherwise version number <em>a</em> is ordered before version number <em>b</em> when:
<em>i</em> &gt; <em>p</em>, or <em>i</em> == <em>p</em> and <em>j</em> &gt; <em>q</em>, or <em>i</em> == <em>p</em> and <em>j</em> == <em>q</em>
and <em>k</em> &gt; <em>r</em>.</p>
</div>
<div class="paragraph">
<p>Otherwise version number <em>a</em> is the same as version number <em>b</em>.</p>
</div>
</div>
<div class="sect5">
<h6 id="intspct-vers-range"><a class="anchor" href="#intspct-vers-range"></a>8.4.1.7.2. Version Range <span class="right">[<a href="#intspct-vers-range">intspct.vers.range</a>]</span></h6>
<div class="dlist">
<dl>
<dt class="hdlist1"><em>version-range</em>: </dt>
<dd>
<p><em>version-range-min-bracket</em>
<em>version-min-number</em> <code>,</code> <em>version-max-number</em>
<em>version-range-max-bracket</em></p>
</dd>
<dt class="hdlist1"><em>version-min-number</em>: </dt>
<dd>
<p><em>version-number</em></p>
</dd>
<dt class="hdlist1"><em>version-max-number</em>: </dt>
<dd>
<p><em>version-number</em></p>
</dd>
<dt class="hdlist1"><em>version-range-min-bracket</em>: one of </dt>
<dd>
<p><code>[ (</code></p>
</dd>
<dt class="hdlist1"><em>version-range-max-bracket</em>: one of </dt>
<dd>
<p><code>) ]</code></p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>A version range is composed of either one version number bracketed,
or two version numbers separated by a comma (<code>,</code>) and bracketed.</p>
</div>
<div class="paragraph">
<p>[ <em>Example 1</em>:<br>
<code>[1.0.0]</code><br>
A version range with a single version number.
— <em>end example</em> ]</p>
</div>
<div class="paragraph">
<p>[ <em>Example 2</em>:<br>
<code>[1.0.0,2.0.0]</code><br>
A version range with a two version numbers.
— <em>end example</em> ]</p>
</div>
<div class="paragraph">
<p>A version range <em>a</em> that is <code>[<em>i</em>,<em>j</em>]</code> makes <em>i</em> and <em>j</em> inclusive version
range numbers.</p>
</div>
<div class="paragraph">
<p>A version range <em>a</em> that is <code>(<em>i</em>,<em>j</em>)</code> makes <em>i</em> and <em>j</em> exclusive version
range numbers.</p>
</div>
<div class="paragraph">
<p>A version range <em>a</em> that is <code>(<em>i</em>,<em>j</em>]</code> makes <em>i</em> an exclusive version number.</p>
</div>
<div class="paragraph">
<p>A version range <em>a</em> that is <code>[<em>i</em>,<em>j</em>)</code> makes <em>j</em> an exclusive version number.</p>
</div>
<div class="paragraph">
<p>A version range with a single inclusive version number <em>x</em> is equivalent to the
version range <code>[<em>x</em>,<em>x</em>]</code>.</p>
</div>
<div class="paragraph">
<p>A version range with a single exclusive version number <em>x</em> is invalid.</p>
</div>
<div class="paragraph">
<p>An exclusive version number <em>x</em> does not include the version number <em>x</em> when
compared to another version number <em>y</em>.</p>
</div>
<div class="paragraph">
<p>A version range <em>a</em> with version numbers <em>i</em> and <em>j</em> when compared to a version
range <em>b</em> with version number <em>m</em> and <em>n</em> will result in an empty version range
when: <em>j</em> &lt; <em>m</em> or <em>n</em> &lt; <em>i</em>.f</p>
</div>
<div class="paragraph">
<p>Otherwise if <em>i</em> or <em>m</em> are inclusive version numbers and if <em>j</em> or <em>n</em> are
inclusive version numbers the resulting range when <em>a</em> is compare to <em>b</em> is
the inclusive version numbers "lesser of <em>i</em> and <em>m</em>" and
"lesser of <em>j</em> and <em>n</em>".</p>
</div>
<div class="paragraph">
<p>Otherwise if <em>i</em> or <em>m</em> are inclusive version numbers and if <em>j</em> or <em>n</em> are
inclusive version numbers the resulting range when <em>a</em> is compare to <em>b</em> is
the inclusive version number "lesser of <em>i</em> and <em>m</em>" and the exclusive version
number "lesser of <em>j</em> and <em>n</em>".</p>
</div>
<div class="paragraph">
<p>Otherwise if <em>j</em> or <em>n</em> are inclusive version numbers the resulting range when
<em>a</em> is compared to <em>b</em> is the exclusive version number "lesser of <em>i</em> and <em>m</em>"
and the inclusive version number "lesser of <em>j</em> and <em>n</em>".</p>
</div>
<div class="paragraph">
<p>Otherwise the resulting range when <em>a</em> is compared to <em>b</em> is the exclusive
version numbers "lesser of <em>i</em> and <em>m</em>" and "lesser of <em>j</em> and <em>n</em>".</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="intspct-min"><a class="anchor" href="#intspct-min"></a>8.4.1.8. Minimum Level <span class="right">[<a href="#intspct-min">intspct.min</a>]</span></h5>
<div class="paragraph">
<p>An application that supports the <em>minimum level</em> functionality indicates it by
specifying a single version (<a href="#intspct-vers-single">[intspct-vers-single]</a>) as the value of the
<code>std:info</code> capability (<a href="#intspct-cap">intspct.cap</a>).</p>
</div>
<div class="paragraph">
<p>[ <em>Example 1</em>:<br>
<code>{ "std:info": "1.0.0" }</code><br>
— <em>end example</em> ]</p>
</div>
</div>
<div class="sect4">
<h5 id="intspct-full"><a class="anchor" href="#intspct-full"></a>8.4.1.9. Full Level <span class="right">[<a href="#intspct-full">intspct.full</a>]</span></h5>
<div class="paragraph">
<p>An application can support the <em>full level</em> functionality as defined in this
section. An application that reports supporting the <em>full level</em> functionality
shall support all of the functionality in this section.</p>
</div>
<div class="paragraph">
<p>An application that supports the <em>full level</em> functionality indicates it by
specifying a version range (<a href="#intspct-vers-single">[intspct-vers-single]</a>) as the value of the
<code>std:info</code> capability (<a href="#intspct-cap">intspct.cap</a>).</p>
</div>
<div class="paragraph">
<p>[ <em>Example 1</em>:<br>
<code>{ "std:info": "[1.0.0]" }</code><br>
— <em>end example</em> ]</p>
</div>
</div>
<div class="sect4">
<h5 id="intspct-info"><a class="anchor" href="#intspct-info"></a>8.4.1.10. Introspection Information <span class="right">[<a href="#intspct-info">intspct.info</a>]</span></h5>
<div class="paragraph">
<p>An application shall output an introspection schema (<a href="#intspct-schema">intspct.schema</a>) that
contains one capability field for each capability that the application supports
when given the <code>--std-info</code> option (<a href="#intspct-opt-info">intspct.opt.info</a>).</p>
</div>
<div class="paragraph">
<p>An application shall indicate the single version (<a href="#intspct-vers-num">intspct.vers.num</a>) or
version range (<a href="#intspct-vers-range">intspct.vers.range</a>) of each capability it supports as the
value of the capability field.</p>
</div>
</div>
<div class="sect4">
<h5 id="intspct-dcl"><a class="anchor" href="#intspct-dcl"></a>8.4.1.11. Introspection Declaration <span class="right">[<a href="#intspct-dcl">intspct.dcl</a>]</span></h5>
<div class="paragraph">
<p>An application that supports the <em>full level</em> functionality when given one or
more <code>--std-info=<em>declaration</em></code> options shall conform its functionality to the
indicated edition of this standard in the given <em>declaration</em> <em>version-number</em>
for the given capability.</p>
</div>
<div class="hdlist">
<table>
<tr>
<td class="hdlist1">
<em>declaration</em> 
</td>
<td class="hdlist2">
<p><em>capability-identifier</em> <code>=</code> <em>version-number</em></p>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>An application, when not given a <code>--std-info=<em>declaration</em></code> option for a
capability it supports, should conform its functionality to the most recent
version of the standard it supports for that capability.</p>
</div>
<div class="paragraph">
<p>An application, when given a capability declaration option and the given
version is outside of the version range that the application supports, should
indicate an error.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_json_schema"><a class="anchor" href="#_json_schema"></a>8.5. JSON Schema</h3>
<div class="paragraph">
<p>Insert clause before <em>Bibliography</em>.</p>
</div>
<div class="sect3 ins text-justify">
<h4 id="intspct-json-schema"><a class="anchor" href="#intspct-json-schema"></a>8.5.1. Annex A (informative) Tool Introspection <em>JSON Schema</em> <span class="right">[<a href="#intspct-json-schema">intsjschm</a>]</span></h4>
<div class="sect4">
<h5 id="intspct-json-schema-general"><a class="anchor" href="#intspct-json-schema-general"></a>8.5.1.1. General <span class="right">[<a href="#intspct-json-schema-general">intsjschm.general</a>]</span></h5>
<div class="paragraph">
<p>This Annex describe defines the introspection capability schema
(<a href="#intspct-schema">intspct.schema</a>) in terms of a <em>JSON Schema</em>. A <em>JSON Schema</em> refers to the
IETF RFC draft "JSON Schema: A Media Type for Describing JSON Documents" as
specified in <a href="https://json-schema.org/draft/2020-12/json-schema-core.html" class="bare">https://json-schema.org/draft/2020-12/json-schema-core.html</a>.</p>
</div>
<div class="paragraph">
<p>This JSON Schema can be referenced as the <code>$schema</code> field with URI value of
<code>"https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json"</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="intspct-json-schema-spec"><a class="anchor" href="#intspct-json-schema-spec"></a>8.5.1.2. JSON Schema Specification <span class="right">[<a href="#intspct-json-schema-spec">intsjschm.spec</a>]</span></h5>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="json"><span class="p">{</span><span class="w">
	</span><span class="nl">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://json-schema.org/draft/2020-12/schema"</span><span class="p">,</span><span class="w">
	</span><span class="nl">"$id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"https://raw.githubusercontent.com/cplusplus/ecosystem-is/release/schema/std_info-1.0.0.json"</span><span class="p">,</span><span class="w">
	</span><span class="nl">"title"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Tool Introspection Version 1.0.0 JSON Schema"</span><span class="p">,</span><span class="w">
	</span><span class="nl">"required"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
		</span><span class="s2">"$schema"</span><span class="p">,</span><span class="w">
		</span><span class="s2">"std:info"</span><span class="w">
	</span><span class="p">],</span><span class="w">
	</span><span class="nl">"$defs"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
		</span><span class="nl">"VersionSpec"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
			</span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w">
			</span><span class="nl">"pattern"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^([0-9]+([.][0-9]+){0,2})|([[(][0-9]+([.][0-9]+){0,2},[0-9]+([.][0-9]+){0,2}[)</span><span class="se">\\</span><span class="s2">]])$"</span><span class="w">
		</span><span class="p">}</span><span class="w">
	</span><span class="p">},</span><span class="w">
	</span><span class="nl">"anyOf"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
		</span><span class="p">{</span><span class="w">
			</span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span><span class="w">
			</span><span class="nl">"properties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
				</span><span class="nl">"$schema"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
					</span><span class="nl">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"The URI of the JSON schema corresponding to the version of the tool introspection format."</span><span class="p">,</span><span class="w">
					</span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w">
					</span><span class="nl">"format"</span><span class="p">:</span><span class="w"> </span><span class="s2">"uri"</span><span class="w">
				</span><span class="p">},</span><span class="w">
				</span><span class="nl">"std:info"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
					</span><span class="nl">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"The Tool Introspection format version."</span><span class="p">,</span><span class="w">
					</span><span class="nl">"$ref"</span><span class="p">:</span><span class="w"> </span><span class="s2">"#/$defs/VersionSpec"</span><span class="w">
				</span><span class="p">}</span><span class="w">
			</span><span class="p">}</span><span class="w">
		</span><span class="p">},</span><span class="w">
		</span><span class="p">{</span><span class="w">
			</span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"object"</span><span class="p">,</span><span class="w">
			</span><span class="nl">"propertyNames"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
				</span><span class="nl">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="p">,</span><span class="w">
				</span><span class="nl">"pattern"</span><span class="p">:</span><span class="w"> </span><span class="s2">"^[a-z_]+(:[a-z_]+)+$"</span><span class="w">
			</span><span class="p">},</span><span class="w">
			</span><span class="nl">"patternProperties"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
				</span><span class="nl">""</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
					</span><span class="nl">"$ref"</span><span class="p">:</span><span class="w"> </span><span class="s2">"#/$defs/VersionSpec"</span><span class="w">
				</span><span class="p">}</span><span class="w">
			</span><span class="p">}</span><span class="w">
		</span><span class="p">}</span><span class="w">
	</span><span class="p">]</span><span class="w">
</span><span class="p">}</span></code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_examples"><a class="anchor" href="#_examples"></a>9. Examples</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_portable_command_lines"><a class="anchor" href="#_portable_command_lines"></a>9.1. Portable Command Lines</h3>
<div class="paragraph">
<p>Assuming that the Ecosystem IS specifies a common set of portable command line
compiler options an interaction between a build system (or user at a command
prompt) and a compiler could look like:</p>
</div>
<div class="paragraph">
<p>Build systems asks the compiler for supported capabilities:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell"><span class="nv">$ </span>c++ <span class="nt">--std-info</span>
<span class="o">{</span> <span class="s2">"std:info"</span>: <span class="s2">"[1]"</span>, <span class="s2">"std:cli:c++"</span>, <span class="s2">"[1]"</span> <span class="o">}</span></code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">ℹ</div>
</td>
<td class="content">
The build system would likely want to cache that information as it&#8217;s
likely to be static for the release of the compiler.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The build system could then declare and use any such portable compiler options:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell"><span class="nv">$ </span>c++ <span class="nt">--std-info</span><span class="o">=</span>std:cli:c++<span class="o">=</span>1 <span class="nt">-std</span><span class="o">=</span>c++26 <span class="nt">-I</span> /home/user/boost <span class="nt">-o</span> myapp main.cpp</code></pre>
</div>
</div>
<div class="paragraph">
<p>The interaction when the compiler tool only supports the minimum level would be:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell"><span class="nv">$ </span>c++ <span class="nt">--std-info</span>
<span class="o">{</span> <span class="s2">"std:info"</span>: <span class="s2">"1"</span>, <span class="s2">"std:cli:c++"</span>, <span class="s2">"1"</span> <span class="o">}</span>
<span class="nv">$ </span>c++ <span class="nt">-std</span><span class="o">=</span>c++26 <span class="nt">-I</span> /home/user/boost <span class="nt">-o</span> myapp main.cpp</code></pre>
</div>
</div>
<div class="paragraph">
<p>This example predicts that it might be useful outside of the C&#43;&#43; ecosystem by
using <code>std:cli:c++</code> to indicate a C&#43;&#43; specific command line. It could be
that Fortran uses a different, but possibly overlapping CLI:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="rouge highlight"><code data-lang="shell"><span class="nv">$ </span>gcc <span class="nt">--std-info</span>
<span class="o">{</span> <span class="s2">"std:info"</span>: <span class="s2">"1"</span>, <span class="s2">"std:cli:c++"</span>, <span class="s2">"1"</span>, <span class="s2">"gcc:cli:fortran"</span>, <span class="s2">"1"</span> <span class="o">}</span>
<span class="nv">$ </span>gcc <span class="nt">-std</span><span class="o">=</span>f2018 <span class="nt">-o</span> myapp main.fpp</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footnotes">
<hr>
<div class="footnote" id="_footnotedef_1">
<a href="#_footnoteref_1">1</a>. <a href="https://wg21.link/P2656" class="bare">https://wg21.link/P2656</a> C&#43;&#43; Ecosystem International Standard
</div>
<div class="footnote" id="_footnotedef_2">
<a href="#_footnoteref_2">2</a>. ECMAScript® 2022 language specification, 13th edition, June 2022 (<a href="https://www.ecma-international.org/publications-and-standards/standards/ecma-262/" class="bare">https://www.ecma-international.org/publications-and-standards/standards/ecma-262/</a>)
</div>
<div class="footnote" id="_footnotedef_3">
<a href="#_footnoteref_3">3</a>. Wikipedia: Interval (mathematics) (<a href="https://en.wikipedia.org/wiki/Interval_(mathematics)" class="bare">https://en.wikipedia.org/wiki/Interval_(mathematics)</a>)
</div>
<div class="footnote" id="_footnotedef_4">
<a href="#_footnoteref_4">4</a>. ISO/IEC 21778:2017 Information technology — The JSON data interchange syntax, (<a href="https://www.iso.org/standard/71616.html" class="bare">https://www.iso.org/standard/71616.html</a>)
</div>
<div class="footnote" id="_footnotedef_5">
<a href="#_footnoteref_5">5</a>. JSON Schema: A Media Type for Describing JSON Documents (<a href="http://json-schema.org/latest/json-schema-core.html" class="bare">http://json-schema.org/latest/json-schema-core.html</a>)
</div>
<div class="footnote" id="_footnotedef_6">
<a href="#_footnoteref_6">6</a>. Semantic Versioning (<a href="https://semver.org/" class="bare">https://semver.org/</a>)
</div>
<div class="footnote" id="_footnotedef_7">
<a href="#_footnoteref_7">7</a>. Working Draft, C&#43;&#43; Ecosystem International Standard 2023-04-01 (<a href="https://github.com/cplusplus/ecosystem-is/tree/86cfbd72b9fae73554935d5f7039a798b5583628" class="bare">https://github.com/cplusplus/ecosystem-is/tree/86cfbd72b9fae73554935d5f7039a798b5583628</a>)
</div>
</div>
</body>
</html>