HiNC-2025-win-desktop-Deploy/App/wwwroot/HiAPI-docsite/api/Hi.NcParsers.EvaluationSyntaxs.Evaluation.html

369 lines
21 KiB
HTML

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Namespace Hi.NcParsers.EvaluationSyntaxs.Evaluation | HiAPI-C# 2025 </title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="title" content="Namespace Hi.NcParsers.EvaluationSyntaxs.Evaluation | HiAPI-C# 2025 ">
<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.EvaluationSyntaxs.Evaluation">
<h1 id="Hi_NcParsers_EvaluationSyntaxs_Evaluation" data-uid="Hi.NcParsers.EvaluationSyntaxs.Evaluation" class="text-break">Namespace Hi.NcParsers.EvaluationSyntaxs.Evaluation</h1>
<div class="markdown level0 summary"></div>
<div class="markdown level0 conceptual"></div>
<div class="markdown level0 remarks"></div>
<h3 id="classes">
Classes
</h3>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.LocalVariableLookup.html">LocalVariableLookup</a></dt>
<dd><p>Reads Fanuc-style local macro variables (<code>#1-#33</code>) from
<code>Vars.Local</code> on the current <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html">SyntaxPiece</a> JSON,
falling back to the immediately previous block when they share the
same <a class="xref" href="Hi.NcParsers.Keywords.MacroFrame.html">MacroFrame</a> id. Self-gates the id range
so the evaluator's
<a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.VariableEvaluatorSyntax.html#Hi_NcParsers_EvaluationSyntaxs_VariableEvaluatorSyntax_RuntimeVariableLookups">RuntimeVariableLookups</a> chain can
fall through to the next lookup for out-of-range keys.</p>
<p>
Two-step lookup (mirrors <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.VolatileVariableLookup.html">VolatileVariableLookup</a>): the
current block sees writes that <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Fanuc.FanucMacroCallSyntax.html">FanucMacroCallSyntax</a>
stamped at inline time (the call-line argument bindings) and writes
that <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Fanuc.FanucLocalVariableReadingSyntax.html">FanucLocalVariableReadingSyntax</a>
applied on this block before the lookup runs; the previous block
(frame-checked) supplies body-internal writes from the prior block in
the same macro frame. Looking past the previous block is unnecessary
because the reader carries forward block-by-block within a frame.
</p>
<p>
Frame isolation via <a class="xref" href="Hi.NcParsers.Keywords.MacroFrame.html">MacroFrame</a>: a previous
block whose frame id differs from the current block's is skipped —
a macro body's body-internal locals are invisible to the caller after
return, and the caller's main-frame locals are invisible inside the
macro. M98/M198 subprogram inlining
(<a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.SubProgramCallSyntax.html">SubProgramCallSyntax</a>) deliberately
does <i>not</i> stamp <a class="xref" href="Hi.NcParsers.Keywords.MacroFrame.html">MacroFrame</a> on its
inlined blocks, so the callee inherits the caller's frame and sees
the caller's locals — matching real Fanuc M98 semantics.
</p>
<p>
Stateless and dependency-free — instances are interchangeable.
</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcBinaryExpr.html">NcBinaryExpr</a></dt>
<dd><p>Binary operation on two operands. Covers arithmetic
(<code>+ - * /</code> / <code>MOD</code>), comparison
(<code>EQ NE GT GE LT LE</code>, yielding <code>1.0</code> / <code>0.0</code>), and
logical bitwise (<code>AND OR XOR</code>, operands truncated to
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.int64">long</a>).</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpr.html">NcExpr</a></dt>
<dd><p>AST root for a Fanuc Custom Macro B value expression. Concrete leaves
and combinators sit alongside <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionParser.html">NcExpressionParser</a>; walking
is the job of <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html">NcExpressionEvaluator</a>.</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html">NcExpressionEvaluator</a></dt>
<dd><p>Walks an <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpr.html">NcExpr</a> AST and produces an <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.EvalResult.html">EvalResult</a>.
Resolves <code>#nnn</code> via an <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.IVariableLookup.html">IVariableLookup</a>; built-in function
names are matched case-insensitively against a fixed table.</p>
<p>
Phase-1 supports: <code>SIN COS TAN ASIN ACOS ATAN SQRT ABS ROUND FIX FUP LN
EXP POW</code>. Trigonometric arguments and results are in degrees, matching
Fanuc Custom Macro B convention. Unknown function names surface as
<a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_NcExpressionEvaluator_UnsupportedFunctionCode">UnsupportedFunctionCode</a>; arity mismatches as
<a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_NcExpressionEvaluator_ArgumentMismatchCode">ArgumentMismatchCode</a>; division / MOD by zero and domain
errors (e.g. <code>SQRT[-1]</code>) as <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_NcExpressionEvaluator_MathErrorCode">MathErrorCode</a>; vacant
operands as <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_NcExpressionEvaluator_VacantErrorCode">VacantErrorCode</a>.
</p>
<p>
<b>Numeric domain &amp; type conventions.</b> All values are IEEE 754
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.double">double</a> — there is no separate bool / int type at runtime.
Comparison ops (<code>EQ NE GT GE LT LE</code>) yield <code>1.0</code> (true) or
<code>0.0</code> (false), using strict double equality / ordering (NaN
compares as IEEE specifies — <code>NaN EQ NaN</code> is <code>0.0</code>). Logical
ops (<code>AND OR XOR</code>) truncate each operand to a 64-bit signed
integer (<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.math.truncate#system-math-truncate(system-double)">Truncate(double)</a> then cast to
<a class="xref" href="https://learn.microsoft.com/dotnet/api/system.int64">long</a>) before applying the bitwise operation; non-finite
or out-of-range operands surface <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_NcExpressionEvaluator_MathErrorCode">MathErrorCode</a> rather
than silently wrapping. Truthiness at caller-side <code>IF / WHILE</code>
gates is <code>value != 0</code> — any non-zero value (bit, float, comparator
result) is true.
</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionParser.html">NcExpressionParser</a></dt>
<dd><p>Recursive-descent parser for Fanuc Custom Macro B value expressions.
Pure: takes a string, produces an <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpr.html">NcExpr</a> AST. Performs no
variable lookup and no evaluation.</p>
<p>Grammar (lowest precedence at top):</p>
<pre><code class="lang-csharp">expr := or-expr
or-expr := and-expr (('OR' | 'XOR') and-expr)*
and-expr := cmp-expr ('AND' cmp-expr)*
cmp-expr := add-expr (('EQ' | 'NE' | 'GT' | 'GE' | 'LT' | 'LE') add-expr)*
add-expr := term (('+' | '-') term)*
term := factor (('*' | '/' | 'MOD') factor)*
factor := ('+' | '-')? primary
primary := number
| '#' integer
| '#' '[' expr ']'
| '[' expr ']'
| ident '[' arglist ']' ('/' '[' expr ']')?
arglist := expr (',' expr)*</code></pre>
<p>
Function names and keyword operators (<code>MOD</code>, <code>EQ NE GT GE LT LE</code>,
<code>AND OR XOR</code>) are case-insensitive (<code>SIN</code> = <code>sin</code>,
<code>EQ</code> = <code>eq</code>); each keyword requires a non-identifier character
on its right boundary so <code>EQ1</code> is not the <code>EQ</code> operator
followed by <code>1</code>. Whitespace is skipped between tokens. The
<code>'/' '[' expr ']'</code> tail captures the dual-bracket form Fanuc uses
for <code>ATAN[a]/[b]</code>; non-ATAN callers that happen to use it produce a
function with an extra arg, which the evaluator rejects with an arity
error.
</p>
<p>
Operator precedence intentionally puts boolean / logical layers below
arithmetic so <code>#1 + 1 GT 0</code> parses as <code>(#1 + 1) GT 0</code> and
<code>#1 GT 0 AND #2 LT 10</code> parses as <code>(#1 GT 0) AND (#2 LT 10)</code>,
matching the Fanuc Custom Macro B spec for <code>IF [..] GOTO</code> /
<code>IF [..] THEN</code> / <code>WHILE [..] DO</code> conditions.
</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcFunctionExpr.html">NcFunctionExpr</a></dt>
<dd><p>Built-in function call like <code>SIN[x]</code>, <code>SQRT[x]</code>, <code>ATAN[a]/[b]</code>.</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcIndirectVariableExpr.html">NcIndirectVariableExpr</a></dt>
<dd><p>Indirect variable reference <code>#[expr]</code>. The inner expression is
evaluated and truncated toward zero to obtain an integer; the lookup key
is then <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcIndirectVariableExpr.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_NcIndirectVariableExpr_Prefix">Prefix</a> concatenated with that integer
(e.g. <code>Prefix=&quot;#&quot;</code>, computed <code>124</code><code>&quot;#124&quot;</code>).</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcLiteralExpr.html">NcLiteralExpr</a></dt>
<dd><p>Numeric literal (e.g. <code>1.5</code>, <code>15.</code>, <code>.5</code>, <code>1e-3</code>).</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcUnaryExpr.html">NcUnaryExpr</a></dt>
<dd><p>Unary <code>+</code> or <code>-</code> applied to an operand.</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcVariableExpr.html">NcVariableExpr</a></dt>
<dd><p>Direct variable reference; <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcVariableExpr.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_NcVariableExpr_Key">Key</a> is the raw source token
(e.g. <code>&quot;#124&quot;</code>) passed verbatim to <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.IVariableLookup.html#Hi_NcParsers_EvaluationSyntaxs_Evaluation_IVariableLookup_Get_System_String_">Get(string)</a>.</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.VolatileVariableLookup.html">VolatileVariableLookup</a></dt>
<dd><p>Reads Fanuc-style non-retained common variables (<code>#100-#499</code>)
from <code>Vars.Volatile</code>. Self-gates the id range so the evaluator's
<a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.VariableEvaluatorSyntax.html#Hi_NcParsers_EvaluationSyntaxs_VariableEvaluatorSyntax_RuntimeVariableLookups">RuntimeVariableLookups</a> chain can
fall through to the next lookup for out-of-range keys.</p>
<p>
Single-step lookup: <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.VolatileVariableReadingSyntax.html">VolatileVariableReadingSyntax</a> already
dict-merges every block's <code>Vars.Volatile</code> into the next block, so
the entry — if it exists — must be on the current block (when this
lookup runs after the reader) or on the immediately previous block
(when this lookup runs before the reader on the same block, which is
the Fanuc preset's order — evaluator first, reader second). No
arbitrary walk-back: such a walk would be defensive overkill given
the reader's carry guarantee.
</p>
<p>
Stateless and dependency-free — instances are interchangeable. Reads
stay decoupled from the reader (read side here; write side in the
reader).
</p>
</dd>
</dl>
<h3 id="structs">
Structs
</h3>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.EvalResult.html">EvalResult</a></dt>
<dd><p>Outcome of evaluating an <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpr.html">NcExpr</a>. Either a successful
numeric value, or a failure with an error code matching the diagnostic
catalogue used by reading / evaluator syntaxes.</p>
</dd>
</dl>
<h3 id="interfaces">
Interfaces
</h3>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.IRuntimeVariableLookup.html">IRuntimeVariableLookup</a></dt>
<dd><p>Stateless variable lookup that needs per-block runtime context — the
current <a class="xref" href="Hi.NcParsers.Syntaxs.SyntaxPiece.html">SyntaxPiece</a> node (for <a class="xref" href="Hi.Common.Collections.LazyLinkedListNode-1.html#Hi_Common_Collections_LazyLinkedListNode_1_Previous">Previous</a>
traceback into runtime-state sections like <code>MachineCoordinateState</code>
/ <code>ProgramXyz</code>) and the dependency list (so the lookup can read
from sibling dependencies without holding a static reference).</p>
<p>
Distinguished from <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.IVariableLookup.html">IVariableLookup</a>: that one is for
long-lived dependencies that already hold their own data (parameter
tables, tool-offset wrappers, retained-variable tables) and need no
block context. <code>IRuntimeVariableLookup</code> is for context-sensitive
resolutions configured declaratively on
<a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.VariableEvaluatorSyntax.html#Hi_NcParsers_EvaluationSyntaxs_VariableEvaluatorSyntax_RuntimeVariableLookups">RuntimeVariableLookups</a>.
</p>
<p>
Implementations should be brand-specific (e.g. Fanuc <code>#5001-#5043</code>
position reads) and return <code>null</code> for keys outside their range so
the evaluator's chain can fall through to the next lookup.
</p>
<p>
Implementations are XML-serialised as part of
<a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.VariableEvaluatorSyntax.html">VariableEvaluatorSyntax</a>'s round-trip: each impl exposes a
static <code>XName</code>, registers itself with <a class="xref" href="Hi.Common.XmlUtils.XFactory.html#Hi_Common_XmlUtils_XFactory_Generators">Generators</a>,
and implements <a class="xref" href="Hi.Common.XmlUtils.IMakeXmlSource.html#Hi_Common_XmlUtils_IMakeXmlSource_MakeXmlSource_System_String_System_String_System_Boolean_">MakeXmlSource(string, string, bool)</a>. Since impls
are stateless, the typical body is just an empty element carrying the
type name; brand identity is restored by XFactory dispatch.
</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.IVariableLookup.html">IVariableLookup</a></dt>
<dd><p>Resolves a Custom Macro B variable reference to its current numeric value,
or <code>null</code> for vacant (Fanuc <code>&lt;vacant&gt;</code>) and out-of-scope alike.</p>
<p>
The key is the raw source token — Fanuc <code>"#124"</code>, Heidenhain
<code>"Q1"</code>, Siemens <code>"R1"</code> — so the interface itself is brand-agnostic.
Implementations are typically narrow (one per id range / per brand prefix)
and parse the prefix locally; chain them at the call site by trying each
in priority order until one returns a non-<code>null</code> value.
</p>
<p>
A returned <code>null</code> is treated by <a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcExpressionEvaluator.html">NcExpressionEvaluator</a>
as vacant and surfaces as a <code>Variable--Vacant</code> failure when the
value is consumed in arithmetic context.
</p>
</dd>
</dl>
<h3 id="enums">
Enums
</h3>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcBinaryOp.html">NcBinaryOp</a></dt>
<dd><p>Binary operators allowed in Fanuc Custom Macro B value expressions.</p>
</dd>
</dl>
<dl class="jumplist">
<dt><a class="xref" href="Hi.NcParsers.EvaluationSyntaxs.Evaluation.NcUnaryOp.html">NcUnaryOp</a></dt>
<dd><p>Unary operators allowed in Fanuc Custom Macro B value expressions.</p>
</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>