This repository has been archived on 2026-10-11. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/api/Hi.NcParsers.Syntaxs.SyntaxPiece.html
T

545 lines
20 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Class SyntaxPiece | HiAPI-C# 2025 </title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="title" content="Class SyntaxPiece | HiAPI-C# 2025 ">
<meta name="description" content="One NC block&#39;s source line paired with its parsed JSON payload during soft-NC processing.">
<link rel="icon" href="../img/HiAPI.favicon.ico">
<link rel="stylesheet" href="../public/docfx.min.css">
<link rel="stylesheet" href="../public/main.css">
<meta name="docfx:navrel" content="../toc.html">
<meta name="docfx:tocrel" content="toc.html">
<meta name="docfx:rel" content="../">
<meta name="loc:inThisArticle" content="In this article">
<meta name="loc:searchResultsCount" content="{count} results for &quot;{query}&quot;">
<meta name="loc:searchNoResults" content="No results for &quot;{query}&quot;">
<meta name="loc:tocFilter" content="Filter by title">
<meta name="loc:nextArticle" content="Next">
<meta name="loc:prevArticle" content="Previous">
<meta name="loc:themeLight" content="Light">
<meta name="loc:themeDark" content="Dark">
<meta name="loc:themeAuto" content="Auto">
<meta name="loc:changeTheme" content="Change theme">
<meta name="loc:copy" content="Copy">
<meta name="loc:downloadPdf" content="Download PDF">
<script type="module" src="./../public/docfx.min.js"></script>
<script>
const theme = localStorage.getItem('theme') || 'auto'
document.documentElement.setAttribute('data-bs-theme', theme === 'auto' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : theme)
</script>
</head>
<body class="tex2jax_ignore" data-layout="" data-yaml-mime="ManagedReference">
<header class="bg-body border-bottom">
<nav id="autocollapse" class="navbar navbar-expand-md" role="navigation">
<div class="container-xxl flex-nowrap">
<a class="navbar-brand" href="../index.html">
<img id="logo" class="svg" src="../img/HiAPI.logo.png" alt="">
</a>
<button class="btn btn-lg d-md-none border-0" type="button" data-bs-toggle="collapse" data-bs-target="#navpanel" aria-controls="navpanel" aria-expanded="false" aria-label="Toggle navigation">
<i class="bi bi-three-dots"></i>
</button>
<div class="collapse navbar-collapse" id="navpanel">
<div id="navbar">
<form class="search" role="search" id="search">
<i class="bi bi-search"></i>
<input class="form-control" id="search-query" type="search" disabled placeholder="Search" autocomplete="off" aria-label="Search">
</form>
</div>
</div>
</div>
</nav>
</header>
<main class="container-xxl">
<div class="toc-offcanvas">
<div class="offcanvas-md offcanvas-start" tabindex="-1" id="tocOffcanvas" aria-labelledby="tocOffcanvasLabel">
<div class="offcanvas-header">
<h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>
<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#tocOffcanvas" aria-label="Close"></button>
</div>
<div class="offcanvas-body">
<nav class="toc" id="toc"></nav>
</div>
</div>
</div>
<div class="content">
<div class="actionbar">
<button class="btn btn-lg border-0 d-md-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocOffcanvas" aria-controls="tocOffcanvas" aria-expanded="false" aria-label="Show table of contents">
<i class="bi bi-list"></i>
</button>
<nav id="breadcrumb"></nav>
</div>
<article data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece">
<h1 id="Hi_NcParsers_Syntaxs_SyntaxPiece" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece" class="text-break">
Class SyntaxPiece
</h1>
<div class="facts text-secondary">
<dl><dt>Namespace</dt><dd><a class="xref" href="Hi.html">Hi</a>.<a class="xref" href="Hi.NcParsers.html">NcParsers</a>.<a class="xref" href="Hi.NcParsers.Syntaxs.html">Syntaxs</a></dd></dl>
<dl><dt>Assembly</dt><dd>HiMech.dll</dd></dl>
</div>
<div class="markdown summary"><p>One NC block's source line paired with its parsed JSON payload during soft-NC processing.</p>
</div>
<div class="markdown conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public class SyntaxPiece : ISentenceCarrier, IGetSentence, ISentenceIndexed</code></pre>
</div>
<dl class="typelist inheritance">
<dt>Inheritance</dt>
<dd>
<div><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object">object</a></div>
<div><span class="xref">SyntaxPiece</span></div>
</dd>
</dl>
<dl class="typelist implements">
<dt>Implements</dt>
<dd>
<div><a class="xref" href="Hi.NcParsers.ISentenceCarrier.html">ISentenceCarrier</a></div>
<div><a class="xref" href="Hi.NcParsers.IGetSentence.html">IGetSentence</a></div>
<div><a class="xref" href="Hi.NcParsers.ISentenceIndexed.html">ISentenceIndexed</a></div>
</dd>
</dl>
<dl class="typelist inheritedMembers">
<dt>Inherited Members</dt>
<dd>
<div>
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object)</a>
</div>
<div>
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object, object)</a>
</div>
<div>
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a>
</div>
<div>
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>
</div>
<div>
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object.memberwiseclone">object.MemberwiseClone()</a>
</div>
<div>
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object, object)</a>
</div>
</dd></dl>
<dl class="typelist extensionMethods">
<dt>Extension Methods</dt>
<dd>
<div>
<a class="xref" href="Hi.Common.DuplicateUtil.html#Hi_Common_DuplicateUtil_TryDuplicate__1___0_System_Object___">DuplicateUtil.TryDuplicate&lt;TSelf&gt;(TSelf, params object[])</a>
</div>
<div>
<a class="xref" href="Hi.Common.InvokeUtil.html#Hi_Common_InvokeUtil_SelfInvoke__1___0_System_Action___0__">InvokeUtil.SelfInvoke&lt;TSrc&gt;(TSrc, Action&lt;TSrc&gt;)</a>
</div>
<div>
<a class="xref" href="Hi.Common.InvokeUtil.html#Hi_Common_InvokeUtil_SelfInvoke__2___0_System_Func___0___1__">InvokeUtil.SelfInvoke&lt;TSrc, TDst&gt;(TSrc, Func&lt;TSrc, TDst&gt;)</a>
</div>
<div>
<a class="xref" href="Hi.Coloring.ColorUtil.html#Hi_Coloring_ColorUtil_GetGloomyColor_System_Object_System_Double_System_Double_">ColorUtil.GetGloomyColor(object, double, double)</a>
</div>
<div>
<a class="xref" href="Hi.Common.NameUtil.html#Hi_Common_NameUtil_GetSelectionName_System_Object_">NameUtil.GetSelectionName(object)</a>
</div>
<div>
<a class="xref" href="Hi.Common.StringUtil.html#Hi_Common_StringUtil_GetPropertyStringIfToStringNotOverloaded_System_Object_System_Boolean_System_Boolean_">StringUtil.GetPropertyStringIfToStringNotOverloaded(object, bool, bool)</a>
</div>
<div>
<a class="xref" href="Hi.Parallels.LockUtil.html#Hi_Parallels_LockUtil_Lock_System_Object_">LockUtil.Lock(object)</a>
</div>
</dd></dl>
<h2 id="Hi_NcParsers_Syntaxs_SyntaxPiece_remarks">Remarks</h2>
<div class="markdown level0 remarks"><p>The design pattern of <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_Sentence">Sentence</a> and <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_JsonObject">JsonObject</a> are one-one mapping.</p>
<p><b>JSON value type convention:</b>
Prefer base types (double, int) over string for numeric values in <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_JsonObject">JsonObject</a>.
This applies to both parsing syntaxes and logic syntaxes.
Strings should only be used when the value is genuinely textual
(e.g., macro variable references like "#1", "Q2", coordinate IDs like "G54")
or when the value cannot be parsed to a number.
Use <a class="xref" href="Hi.NcParsers.ParsingSyntaxs.FloatTagValueSyntax.html">FloatTagValueSyntax</a>,
<a class="xref" href="Hi.NcParsers.ParsingSyntaxs.IntegerTagValueSyntax.html">IntegerTagValueSyntax</a>,
or <a class="xref" href="Hi.NcParsers.ParsingSyntaxs.ParameterizedFlagSyntax.html#Hi_NcParsers_ParsingSyntaxs_ParameterizedFlagSyntax_FloatParamPrefixes">FloatParamPrefixes</a>
/ <a class="xref" href="Hi.NcParsers.ParsingSyntaxs.ParameterizedFlagSyntax.html#Hi_NcParsers_ParsingSyntaxs_ParameterizedFlagSyntax_IntParamPrefixes">IntParamPrefixes</a>
to store typed values at parse time.
</p>
</div>
<h2 class="section" id="constructors">Constructors
</h2>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece__ctor_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.#ctor*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece__ctor_Hi_NcParsers_Sentence_System_Text_Json_Nodes_JsonObject_System_Int32_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.#ctor(Hi.NcParsers.Sentence,System.Text.Json.Nodes.JsonObject,System.Int32)">
SyntaxPiece(Sentence, JsonObject, int)
</h3>
<div class="markdown level1 summary"><p>Creates a piece binding <code class="paramref">sentence</code> to <code class="paramref">jsonObject</code> with its execution-order <code class="paramref">sentenceIndex</code>.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public SyntaxPiece(Sentence sentence, JsonObject jsonObject, int sentenceIndex)</code></pre>
</div>
<h4 class="section">Parameters</h4>
<dl class="parameters">
<dt><code>sentence</code> <a class="xref" href="Hi.NcParsers.Sentence.html">Sentence</a></dt>
<dd></dd>
<dt><code>jsonObject</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.text.json.nodes.jsonobject">JsonObject</a></dt>
<dd></dd>
<dt><code>sentenceIndex</code> <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.int32">int</a></dt>
<dd></dd>
</dl>
<h2 class="section" id="properties">Properties
</h2>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece_IsFrozen_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.IsFrozen*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece_IsFrozen" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.IsFrozen">
IsFrozen
</h3>
<div class="markdown level1 summary"><p>True when the parse result is held as a frozen UTF-8 snapshot instead
of a live <a class="xref" href="https://learn.microsoft.com/dotnet/api/system.text.json.nodes.jsonobject">JsonObject</a> graph — see
<a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_Freeze">Freeze()</a>.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public bool IsFrozen { get; }</code></pre>
</div>
<h4 class="section">Property Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.boolean">bool</a></dt>
<dd></dd>
</dl>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece_JsonObject_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.JsonObject*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece_JsonObject" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.JsonObject">
JsonObject
</h3>
<div class="markdown level1 summary"><p>Structured parse result built by syntax passes.</p>
<p>
While the piece is live (the default), this is the one mutable
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.text.json.nodes.jsonobject">JsonObject</a> every pipeline stage
reads and writes. After <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_Freeze">Freeze()</a>, the getter re-parses the
frozen UTF-8 snapshot and returns a FRESH object on every call — treat
it as a read-only snapshot: mutations land on the transient copy and
are lost, and two calls return different object references. All
mutating consumers run before the freeze boundary (see
<a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_Freeze">Freeze()</a>), so downstream readers (NC optimization,
writeback composition, GUI JSON panels) see identical content either
way. Setting this property replaces the live object and discards any
frozen snapshot.
</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public JsonObject JsonObject { get; set; }</code></pre>
</div>
<h4 class="section">Property Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.text.json.nodes.jsonobject">JsonObject</a></dt>
<dd></dd>
</dl>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece_Sentence_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.Sentence*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece_Sentence" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.Sentence">
Sentence
</h3>
<div class="markdown level1 summary"><p>Indexed source line and block text for this piece.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public Sentence Sentence { get; set; }</code></pre>
</div>
<h4 class="section">Property Value</h4>
<dl class="parameters">
<dt><a class="xref" href="Hi.NcParsers.Sentence.html">Sentence</a></dt>
<dd></dd>
</dl>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece_SentenceIndex_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.SentenceIndex*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece_SentenceIndex" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.SentenceIndex">
SentenceIndex
</h3>
<div class="markdown level1 summary"><p>0-based, session-globally unique ordinal in NC execution order.
Stamped at piece construction time by
<a class="xref" href="Hi.NcParsers.Segmenters.ISegmenter.html">GetSyntaxPieces(ISegmenter, List&lt;INcDependency&gt;, IEnumerable&lt;IndexedFileLine&gt;, int, NcDiagnosticProgress, CancellationToken)</a> from the session's
<a class="xref" href="Hi.NcParsers.Dependencys.SystemWired.SentenceIndexCounterDependency.html">SentenceIndexCounterDependency</a>:
each piece allocates the next counter value as the lazy pipeline
materializes it, so values are strictly increasing along the executed
stream — subprogram / macro bodies inlined by
<code>SubProgramCallSyntax</code> and friends interleave correctly between
host blocks, including nested calls. Useful as a cross-process
alignment key (messages, ClStripPos, MachiningStep) — unlike the
<code>(FileIndex, LineIndex)</code> source order, it reflects execution order.</p>
<p>
Values are NOT contiguous per file: eager label scans
(<code>LabelScanUtil</code> / <code>RewindToLine</code>) number the whole
re-segmented file and discard the pre-label prefix, leaving gaps.
Never negative — <code>-1</code> stays reserved as the "not in pipeline"
sentinel on downstream carriers. When the counter dependency is
absent (legacy XML preset), numbering falls back to the caller's
contiguous begin-index sequence, which can double-book across
inline boundaries.
</p>
<p>
Required at construction: the index is identity, not optional metadata.
Read-only after construction; the pipeline guarantees one stamping per
piece at the wrapping chokepoint.
</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public int SentenceIndex { get; }</code></pre>
</div>
<h4 class="section">Property Value</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.int32">int</a></dt>
<dd></dd>
</dl>
<h2 class="section" id="methods">Methods
</h2>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece_Freeze_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.Freeze*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece_Freeze" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.Freeze">
Freeze()
</h3>
<div class="markdown level1 summary"><p>Replaces the live <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_JsonObject">JsonObject</a> graph with its compact
UTF-8 serialization (~13× smaller live-memory footprint per retained
piece), keeping the piece readable through the <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_JsonObject">JsonObject</a>
getter via on-demand re-parse. Uses
<a class="xref" href="Hi.Common.JsonUtil.html#Hi_Common_JsonUtil_CompactNanOptions">CompactNanOptions</a> — the exact leaf encoding of
<a class="xref" href="Hi.Common.JsonUtil.html#Hi_Common_JsonUtil_ToLeafCompactJsonString_System_Text_Json_Nodes_JsonNode_System_Text_Json_JsonSerializerOptions_">ToLeafCompactJsonString(JsonNode, JsonSerializerOptions)</a> — so the JSON projection
of a frozen piece is byte-identical to the live one (NaN / Infinity
serialize as quoted literal strings; explicit nulls survive).</p>
<p>
Call only after every mutating consumer of this piece has run — the
session pipeline freezes a piece once it left the executing window
(its semantics completed plus a lag margin; see
<code>MachiningProcs.NcRunnerSessionState</code>). Idempotent; a piece with a
null <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html#Hi_NcParsers_Syntaxs_SyntaxPiece_JsonObject">JsonObject</a> stays null. Thread-safe against
concurrent readers: they observe either the live graph or the frozen
snapshot, never a torn state.
</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public void Freeze()</code></pre>
</div>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece_GetSentence_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.GetSentence*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece_GetSentence" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.GetSentence">
GetSentence()
</h3>
<div class="markdown level1 summary"><p>Returns the source <a class="xref" href="Hi.NcParsers.Sentence.html">Sentence</a> carried by this object.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public Sentence GetSentence()</code></pre>
</div>
<h4 class="section">Returns</h4>
<dl class="parameters">
<dt><a class="xref" href="Hi.NcParsers.Sentence.html">Sentence</a></dt>
<dd></dd>
</dl>
<a id="Hi_NcParsers_Syntaxs_SyntaxPiece_ToString_" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.ToString*"></a>
<h3 id="Hi_NcParsers_Syntaxs_SyntaxPiece_ToString" data-uid="Hi.NcParsers.Syntaxs.SyntaxPiece.ToString">
ToString()
</h3>
<div class="markdown level1 summary"><p>Serialize with <span class="xref">Hi.NcParsers.Syntaxs.NcSyntaxUtil.Options</span> to support NaN/Infinity.</p>
</div>
<div class="markdown level1 conceptual"></div>
<div class="codewrapper">
<pre><code class="lang-csharp hljs">public override string ToString()</code></pre>
</div>
<h4 class="section">Returns</h4>
<dl class="parameters">
<dt><a class="xref" href="https://learn.microsoft.com/dotnet/api/system.string">string</a></dt>
<dd></dd>
</dl>
</article>
<div class="contribution d-print-none">
</div>
</div>
<div class="affix">
<nav id="affix"></nav>
</div>
</main>
<div class="container-xxl search-results" id="search-results"></div>
<footer class="border-top text-secondary">
<div class="container-xxl">
<div class="flex-fill">
<span> Copyright © 2025 <a href='https://superhightech.com.tw'>Tech Coordinate</a>. All rights reserved. <a href='https://superhightech.com.tw'>超級高科技股份有限公司</a> © 2025 版權所有 </span>
</div>
</div>
</footer>
</body>
</html>