ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-07-05 00:24:22 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/bytecode-module/3-mtd.html

224 lines
35 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Metadata</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
<meta name="viewport" content="width=device-width initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
var popup = document.getElementById(material_id);
popup.classList.toggle("show");
}
</script>
<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body class="commentary-font">
<nav role="navigation">
<h1><a href="../index.html">
<img src="../docs-assets/Inform.png" height=72">
</a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../indocn.html">indoc</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="../../../inweb/index.html">inweb</a></li>
<li><a href="../../../intest/index.html">intest</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'Metadata' generated by Inweb-->
<div class="breadcrumbs">
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../intern.html">Inter Modules</a></li><li><a href="index.html">bytecode</a></li><li><a href="index.html#3">Chapter 3: Their Instructions</a></li><li><b>Metadata</b></li></ul></div>
<p class="purpose">Looking up metadata in special constants.</p>
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. </b>This section is in some ways a postscript to <a href="4-tcc2.html" class="internal">The Constant Construct</a>. If
constants are created which have names matching...
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Metadata::valid_key</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">Metadata::valid_key</span></span>:<br/>Symbols - <a href="2-sym.html#SP2">&#167;2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">key</span><span class="plain-syntax">, </span><span class="constant-syntax">0</span><span class="plain-syntax">) == </span><span class="character-syntax">'^'</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>...then their symbols are given the <span class="extract"><span class="extract-syntax">METADATA_KEY_ISYMF</span></span> flag: see
<a href="2-sym.html#SP2" class="internal">InterSymbol::new_for_symbols_table</a>. These symbols never code-generate: see
<a href="../final-module/2-vc.html" class="internal">Vanilla Constants (in final)</a>. It follows that metadata cannot be part of the
program at runtime. Nor can metadata be wired to anything else, either way
round &mdash; see <a href="2-tw2.html#SP5" class="internal">Wiring::wire_to</a>.
</p>
<p class="commentary">So the only purpose metadata can serve is to annotate the program, to assist
tools such as the <a href="../pipeline-module/index.html" class="internal">pipeline</a> module. Metadata helps with linking, optimisation,
and similar tasks.
</p>
<p class="commentary">Since metadata exists solely so that other parts of the Inform tool chain can
read its values, we clearly need an API for doing that, and this is the point
of the present section.
</p>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>Some metadata keys are expected, and others are optional. The following
determines whether a given package <span class="extract"><span class="extract-syntax">pack</span></span> contains a value for metadata <span class="extract"><span class="extract-syntax">key</span></span>:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">Metadata::value_node</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">Metadata::value_node</span></span>:<br/><a href="3-mtd.html#SP4">&#167;4</a>, <a href="3-mtd.html#SP5">&#167;5</a>, <a href="3-mtd.html#SP6">&#167;6</a>, <a href="3-mtd.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_symbol</span><span class="plain-syntax"> *</span><span class="identifier-syntax">md</span><span class="plain-syntax"> = </span><a href="2-st.html#SP7" class="function-link"><span class="function-syntax">InterSymbolsTable::symbol_from_name</span></a><span class="plain-syntax">(</span><a href="2-pck.html#SP10" class="function-link"><span class="function-syntax">InterPackage::scope</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">), </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">md</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">md</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">definition</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Metadata::exists</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">)) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b>So for each kind of data we allow, we provide a required and an optional
version, which differ only in that the required version halts with an error
if the key is missing.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="constant-syntax">inter_ti</span><span class="plain-syntax"> </span><span class="function-syntax">Metadata::read_numeric</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">D</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-mtd.html#SP4_1" class="named-paragraph-link"><span class="named-paragraph">Extract the numeric value</span><span class="named-paragraph-number">4.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="3-mtd.html#SP8" class="function-link"><span class="function-syntax">Metadata::err</span></a><span class="plain-syntax">(</span><span class="string-syntax">"not defined"</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">); </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="constant-syntax">inter_ti</span><span class="plain-syntax"> </span><span class="function-syntax">Metadata::read_optional_numeric</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">D</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-mtd.html#SP4_1" class="named-paragraph-link"><span class="named-paragraph">Extract the numeric value</span><span class="named-paragraph-number">4.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4_1" class="paragraph-anchor"></a><b>&#167;4.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Extract the numeric value</span><span class="named-paragraph-number">4.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-tcc2.html#SP8" class="function-link"><span class="function-syntax">ConstantInstruction::list_format</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">) == </span><span class="constant-syntax">CONST_LIST_FORMAT_NONE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_pair</span><span class="plain-syntax"> </span><span class="identifier-syntax">val</span><span class="plain-syntax"> = </span><a href="4-tcc2.html#SP8" class="function-link"><span class="function-syntax">ConstantInstruction::constant</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-ivp.html#SP5" class="function-link"><span class="function-syntax">InterValuePairs::is_number</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">val</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="3-mtd.html#SP8" class="function-link"><span class="function-syntax">Metadata::err</span></a><span class="plain-syntax">(</span><span class="string-syntax">"not numeric"</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="3-ivp.html#SP4" class="function-link"><span class="function-syntax">InterValuePairs::to_number</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">val</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-mtd.html#SP4">&#167;4</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>A metadata key cannot be wired to a symbol; but it can have its value set
to a symbol, so:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_symbol</span><span class="plain-syntax"> *</span><span class="function-syntax">Metadata::required_symbol</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">D</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-mtd.html#SP5_1" class="named-paragraph-link"><span class="named-paragraph">Extract the symbolic value</span><span class="named-paragraph-number">5.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="3-mtd.html#SP8" class="function-link"><span class="function-syntax">Metadata::err</span></a><span class="plain-syntax">(</span><span class="string-syntax">"required symbolic metadata not supplied"</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">inter_symbol</span><span class="plain-syntax"> *</span><span class="function-syntax">Metadata::optional_symbol</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">D</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-mtd.html#SP5_1" class="named-paragraph-link"><span class="named-paragraph">Extract the symbolic value</span><span class="named-paragraph-number">5.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5_1" class="paragraph-anchor"></a><b>&#167;5.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Extract the symbolic value</span><span class="named-paragraph-number">5.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">D</span><span class="plain-syntax">) &amp;&amp; (</span><a href="4-tcc2.html#SP8" class="function-link"><span class="function-syntax">ConstantInstruction::list_format</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">) == </span><span class="constant-syntax">CONST_LIST_FORMAT_NONE</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_pair</span><span class="plain-syntax"> </span><span class="identifier-syntax">val</span><span class="plain-syntax"> = </span><a href="4-tcc2.html#SP8" class="function-link"><span class="function-syntax">ConstantInstruction::constant</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-ivp.html#SP14" class="function-link"><span class="function-syntax">InterValuePairs::is_symbolic</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">val</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="3-mtd.html#SP8" class="function-link"><span class="function-syntax">Metadata::err</span></a><span class="plain-syntax">(</span><span class="string-syntax">"not symbolic"</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="3-ivp.html#SP13" class="function-link"><span class="function-syntax">InterValuePairs::to_symbol_in</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">val</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-mtd.html#SP5">&#167;5</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>Text:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">Metadata::required_textual</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">D</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-mtd.html#SP6_1" class="named-paragraph-link"><span class="named-paragraph">Extract the textual value</span><span class="named-paragraph-number">6.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="3-mtd.html#SP8" class="function-link"><span class="function-syntax">Metadata::err</span></a><span class="plain-syntax">(</span><span class="string-syntax">"required textual metadata not supplied"</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="function-syntax">Metadata::optional_textual</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">D</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-mtd.html#SP6_1" class="named-paragraph-link"><span class="named-paragraph">Extract the textual value</span><span class="named-paragraph-number">6.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP6_1" class="paragraph-anchor"></a><b>&#167;6.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Extract the textual value</span><span class="named-paragraph-number">6.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="4-tcc2.html#SP8" class="function-link"><span class="function-syntax">ConstantInstruction::list_format</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">) == </span><span class="constant-syntax">CONST_LIST_FORMAT_NONE</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_pair</span><span class="plain-syntax"> </span><span class="identifier-syntax">val</span><span class="plain-syntax"> = </span><a href="4-tcc2.html#SP8" class="function-link"><span class="function-syntax">ConstantInstruction::constant</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-ivp.html#SP7" class="function-link"><span class="function-syntax">InterValuePairs::is_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">val</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="3-mtd.html#SP8" class="function-link"><span class="function-syntax">Metadata::err</span></a><span class="plain-syntax">(</span><span class="string-syntax">"not textual"</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="3-ivp.html#SP6" class="function-link"><span class="function-syntax">InterValuePairs::to_text</span></a><span class="plain-syntax">(</span><a href="2-pck.html#SP4" class="function-link"><span class="function-syntax">InterPackage::tree</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">), </span><span class="identifier-syntax">val</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-mtd.html#SP6">&#167;6</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>Lists (which are optional only, and return only as the node from which values
must then be extracted):
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="function-syntax">Metadata::optional_list</span><span class="plain-syntax">(</span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inter_tree_node</span><span class="plain-syntax"> *</span><span class="identifier-syntax">D</span><span class="plain-syntax"> = </span><a href="3-mtd.html#SP3" class="function-link"><span class="function-syntax">Metadata::value_node</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">D</span><span class="plain-syntax">) &amp;&amp; (</span><a href="4-tcc2.html#SP8" class="function-link"><span class="function-syntax">ConstantInstruction::list_format</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">D</span><span class="plain-syntax">) == </span><span class="constant-syntax">CONST_LIST_FORMAT_WORDS</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">D</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. </b>Metadata errors are fatal:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Metadata::err</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">Metadata::err</span></span>:<br/><a href="3-mtd.html#SP4">&#167;4</a>, <a href="3-mtd.html#SP4_1">&#167;4.1</a>, <a href="3-mtd.html#SP5">&#167;5</a>, <a href="3-mtd.html#SP5_1">&#167;5.1</a>, <a href="3-mtd.html#SP6">&#167;6</a>, <a href="3-mtd.html#SP6_1">&#167;6.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">err</span><span class="plain-syntax">, </span><span class="reserved-syntax">inter_package</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">key</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">, </span><span class="string-syntax">"Error on metadata '%S' in package '"</span><span class="plain-syntax">, </span><span class="identifier-syntax">key</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-pck.html#SP19" class="function-link"><span class="function-syntax">InterPackage::write_URL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">STDERR</span><span class="plain-syntax">, </span><span class="string-syntax">"': %s\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">err</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="identifier-syntax">err</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="3-idt.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresschapter"><a href="1-bm.html">1</a></li><li class="progresschapter"><a href="2-it.html">2</a></li><li class="progresscurrentchapter">3</li><li class="progresssection"><a href="3-ic.html">ic</a></li><li class="progresssection"><a href="3-iibf.html">iibf</a></li><li class="progresssection"><a href="3-iitf.html">iitf</a></li><li class="progresssection"><a href="3-vi.html">vi</a></li><li class="progresssection"><a href="3-ivp.html">ivp</a></li><li class="progresssection"><a href="3-idt.html">idt</a></li><li class="progresscurrent">mtd</li><li class="progresssection"><a href="3-ie.html">ie</a></li><li class="progresssection"><a href="3-tp.html">tp</a></li><li class="progresschapter"><a href="4-tcc.html">4</a></li><li class="progresschapter"><a href="5-tac.html">5</a></li><li class="progresschapter"><a href="6-tpc.html">6</a></li><li class="progressnext"><a href="3-ie.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink