<html><head><link rel="stylesheet" href="resource://content-accessible/plaintext.css"><style media="screen" id="__markdown-viewer__md_css">/*
* Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is furnished to do
* so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
@media (prefers-color-scheme: dark) {
:root {
--color-prettylights-syntax-comment: #8b949e;
--color-prettylights-syntax-constant: #79c0ff;
--color-prettylights-syntax-entity: #d2a8ff;
--color-prettylights-syntax-storage-modifier-import: #c9d1d9;
--color-prettylights-syntax-entity-tag: #7ee787;
--color-prettylights-syntax-keyword: #ff7b72;
--color-prettylights-syntax-string: #a5d6ff;
--color-prettylights-syntax-variable: #ffa657;
--color-prettylights-syntax-brackethighlighter-unmatched: #f85149;
--color-prettylights-syntax-invalid-illegal-text: #f0f6fc;
--color-prettylights-syntax-invalid-illegal-bg: #8e1519;
--color-prettylights-syntax-carriage-return-text: #f0f6fc;
--color-prettylights-syntax-carriage-return-bg: #b62324;
--color-prettylights-syntax-string-regexp: #7ee787;
--color-prettylights-syntax-markup-list: #f2cc60;
--color-prettylights-syntax-markup-heading: #1f6feb;
--color-prettylights-syntax-markup-italic: #c9d1d9;
--color-prettylights-syntax-markup-bold: #c9d1d9;
--color-prettylights-syntax-markup-deleted-text: #ffdcd7;
--color-prettylights-syntax-markup-deleted-bg: #67060c;
--color-prettylights-syntax-markup-inserted-text: #aff5b4;
--color-prettylights-syntax-markup-inserted-bg: #033a16;
--color-prettylights-syntax-markup-changed-text: #ffdfb6;
--color-prettylights-syntax-markup-changed-bg: #5a1e02;
--color-prettylights-syntax-markup-ignored-text: #c9d1d9;
--color-prettylights-syntax-markup-ignored-bg: #1158c7;
--color-prettylights-syntax-meta-diff-range: #d2a8ff;
--color-prettylights-syntax-brackethighlighter-angle: #8b949e;
--color-prettylights-syntax-sublimelinter-gutter-mark: #484f58;
--color-prettylights-syntax-constant-other-reference-link: #a5d6ff;
--color-fg-default: #c9d1d9;
--color-fg-muted: #8b949e;
--color-fg-subtle: #484f58;
--color-canvas-default: #0d1117;
--color-canvas-subtle: #161b22;
--color-border-default: #30363d;
--color-border-muted: #21262d;
--color-neutral-muted: rgba(110,118,129,0.4);
--color-accent-fg: #58a6ff;
--color-accent-emphasis: #1f6feb;
--color-danger-fg: #f85149;
}
}
@media (prefers-color-scheme: light) {
:root {
--color-prettylights-syntax-comment: #6e7781;
--color-prettylights-syntax-constant: #0550ae;
--color-prettylights-syntax-entity: #8250df;
--color-prettylights-syntax-storage-modifier-import: #24292f;
--color-prettylights-syntax-entity-tag: #116329;
--color-prettylights-syntax-keyword: #cf222e;
--color-prettylights-syntax-string: #0a3069;
--color-prettylights-syntax-variable: #953800;
--color-prettylights-syntax-brackethighlighter-unmatched: #82071e;
--color-prettylights-syntax-invalid-illegal-text: #f6f8fa;
--color-prettylights-syntax-invalid-illegal-bg: #82071e;
--color-prettylights-syntax-carriage-return-text: #f6f8fa;
--color-prettylights-syntax-carriage-return-bg: #cf222e;
--color-prettylights-syntax-string-regexp: #116329;
--color-prettylights-syntax-markup-list: #3b2300;
--color-prettylights-syntax-markup-heading: #0550ae;
--color-prettylights-syntax-markup-italic: #24292f;
--color-prettylights-syntax-markup-bold: #24292f;
--color-prettylights-syntax-markup-deleted-text: #82071e;
--color-prettylights-syntax-markup-deleted-bg: #FFEBE9;
--color-prettylights-syntax-markup-inserted-text: #116329;
--color-prettylights-syntax-markup-inserted-bg: #dafbe1;
--color-prettylights-syntax-markup-changed-text: #953800;
--color-prettylights-syntax-markup-changed-bg: #ffd8b5;
--color-prettylights-syntax-markup-ignored-text: #eaeef2;
--color-prettylights-syntax-markup-ignored-bg: #0550ae;
--color-prettylights-syntax-meta-diff-range: #8250df;
--color-prettylights-syntax-brackethighlighter-angle: #57606a;
--color-prettylights-syntax-sublimelinter-gutter-mark: #8c959f;
--color-prettylights-syntax-constant-other-reference-link: #0a3069;
--color-fg-default: #24292f;
--color-fg-muted: #57606a;
--color-fg-subtle: #6e7781;
--color-canvas-default: #ffffff;
--color-canvas-subtle: #f6f8fa;
--color-border-default: #d0d7de;
--color-border-muted: hsla(210,18%,87%,1);
--color-neutral-muted: rgba(175,184,193,0.2);
--color-accent-fg: #0969da;
--color-accent-emphasis: #0969da;
--color-danger-fg: #cf222e;
}
}
:root {
color: var(--color-fg-default);
background-color: var(--color-canvas-default);
}
.markdownroot {
-ms-text-size-adjust: 100%;
-webkit-text-size-adjust: 100%;
margin: 0;
font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";
font-size: 16px;
line-height: 1.5;
word-wrap: break-word;
}
.markdownroot .octicon {
display: inline-block;
fill: currentColor;
vertical-align: text-bottom;
}
.markdownroot h1:hover .anchor .octicon-link:before,
.markdownroot h2:hover .anchor .octicon-link:before,
.markdownroot h3:hover .anchor .octicon-link:before,
.markdownroot h4:hover .anchor .octicon-link:before,
.markdownroot h5:hover .anchor .octicon-link:before,
.markdownroot h6:hover .anchor .octicon-link:before {
width: 16px;
height: 16px;
content: ' ';
display: inline-block;
background-color: currentColor;
-webkit-mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' version='1.1' aria-hidden='true'><path fill-rule='evenodd' d='M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z'></path></svg>");
mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' version='1.1' aria-hidden='true'><path fill-rule='evenodd' d='M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z'></path></svg>");
}
.markdownroot details,
.markdownroot figcaption,
.markdownroot figure {
display: block;
}
.markdownroot summary {
display: list-item;
}
.markdownroot a {
background-color: transparent;
color: var(--color-accent-fg);
text-decoration: none;
}
.markdownroot a:active,
.markdownroot a:hover {
outline-width: 0;
}
.markdownroot abbr[title] {
border-bottom: none;
-webkit-text-decoration: underline dotted;
text-decoration: underline dotted;
}
.markdownroot b,
.markdownroot strong {
font-weight: 600;
}
.markdownroot dfn {
font-style: italic;
}
.markdownroot h1 {
margin: .67em 0;
font-weight: 600;
padding-bottom: .3em;
font-size: 2em;
border-bottom: 1px solid var(--color-border-muted);
}
.markdownroot mark {
background-color: #ff0;
color: var(--color-text-primary);
}
.markdownroot small {
font-size: 90%;
}
.markdownroot sub,
.markdownroot sup {
font-size: 75%;
line-height: 0;
position: relative;
vertical-align: baseline;
}
.markdownroot sub {
bottom: -0.25em;
}
.markdownroot sup {
top: -0.5em;
}
.markdownroot img {
border-style: none;
max-width: 100%;
box-sizing: content-box;
background-color: var(--color-canvas-default);
}
.markdownroot code,
.markdownroot kbd,
.markdownroot pre,
.markdownroot samp {
font-family: monospace,monospace;
font-size: 1em;
}
.markdownroot figure {
margin: 1em 40px;
}
.markdownroot hr {
box-sizing: content-box;
overflow: hidden;
background: transparent;
border-bottom: 1px solid var(--color-border-muted);
height: .25em;
padding: 0;
margin: 24px 0;
background-color: var(--color-border-default);
border: 0;
}
.markdownroot html [type=button],
.markdownroot [type=reset],
.markdownroot [type=submit] {
-webkit-appearance: button;
}
.markdownroot [type=button]::-moz-focus-inner,
.markdownroot [type=reset]::-moz-focus-inner,
.markdownroot [type=submit]::-moz-focus-inner {
border-style: none;
padding: 0;
}
.markdownroot [type=button]:-moz-focusring,
.markdownroot [type=reset]:-moz-focusring,
.markdownroot [type=submit]:-moz-focusring {
outline: 1px dotted ButtonText;
}
.markdownroot [type=checkbox],
.markdownroot [type=radio] {
box-sizing: border-box;
padding: 0;
}
.markdownroot [type=number]::-webkit-inner-spin-button,
.markdownroot [type=number]::-webkit-outer-spin-button {
height: auto;
}
.markdownroot [type=search] {
-webkit-appearance: textfield;
outline-offset: -2px;
}
.markdownroot [type=search]::-webkit-search-cancel-button,
.markdownroot [type=search]::-webkit-search-decoration {
-webkit-appearance: none;
}
.markdownroot ::-webkit-input-placeholder {
color: inherit;
opacity: .54;
}
.markdownroot ::-webkit-file-upload-button {
-webkit-appearance: button;
font: inherit;
}
.markdownroot a:hover {
text-decoration: underline;
}
.markdownroot hr::before {
display: table;
content: "";
}
.markdownroot hr::after {
display: table;
clear: both;
content: "";
}
.markdownroot table {
border-spacing: 0;
border-collapse: collapse;
display: block;
width: max-content;
max-width: 100%;
overflow: auto;
}
.markdownroot td,
.markdownroot th {
padding: 0;
}
.markdownroot details summary {
cursor: pointer;
}
.markdownroot details:not([open])>*:not(summary) {
display: none !important;
}
.markdownroot kbd {
display: inline-block;
padding: 3px 5px;
font: 11px ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace;
line-height: 10px;
color: var(--color-fg-default);
vertical-align: middle;
background-color: var(--color-canvas-subtle);
border: solid 1px var(--color-neutral-muted);
border-bottom-color: var(--color-neutral-muted);
border-radius: 6px;
box-shadow: inset 0 -1px 0 var(--color-neutral-muted);
}
.markdownroot h1,
.markdownroot h2,
.markdownroot h3,
.markdownroot h4,
.markdownroot h5,
.markdownroot h6 {
margin-top: 24px;
margin-bottom: 16px;
font-weight: 600;
line-height: 1.25;
}
.markdownroot h2 {
font-weight: 600;
padding-bottom: .3em;
font-size: 1.5em;
border-bottom: 1px solid var(--color-border-muted);
}
.markdownroot h3 {
font-weight: 600;
font-size: 1.25em;
}
.markdownroot h4 {
font-weight: 600;
font-size: 1em;
}
.markdownroot h5 {
font-weight: 600;
font-size: .875em;
}
.markdownroot h6 {
font-weight: 600;
font-size: .85em;
color: var(--color-fg-muted);
}
.markdownroot p {
margin-top: 0;
margin-bottom: 10px;
}
.markdownroot blockquote {
margin: 0;
padding: 0 1em;
color: var(--color-fg-muted);
border-left: .25em solid var(--color-border-default);
}
.markdownroot ul,
.markdownroot ol {
margin-top: 0;
margin-bottom: 0;
padding-left: 2em;
}
.markdownroot ol ol,
.markdownroot ul ol {
list-style-type: lower-roman;
}
.markdownroot ul ul ol,
.markdownroot ul ol ol,
.markdownroot ol ul ol,
.markdownroot ol ol ol {
list-style-type: lower-alpha;
}
.markdownroot dd {
margin-left: 0;
}
.markdownroot tt,
.markdownroot code {
font-family: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace;
font-size: 12px;
}
.markdownroot pre {
margin-top: 0;
margin-bottom: 0;
font-family: ui-monospace,SFMono-Regular,SF Mono,Menlo,Consolas,Liberation Mono,monospace;
font-size: 12px;
word-wrap: normal;
}
.markdownroot :-ms-input-placeholder {
color: var(--color-fg-subtle);
opacity: 1;
}
.markdownroot ::-ms-input-placeholder {
color: var(--color-fg-subtle);
opacity: 1;
}
.markdownroot ::placeholder {
color: var(--color-fg-subtle);
opacity: 1;
}
.markdownroot .pl-c {
color: var(--color-prettylights-syntax-comment);
}
.markdownroot .pl-c1,
.markdownroot .pl-s .pl-v {
color: var(--color-prettylights-syntax-constant);
}
.markdownroot .pl-e,
.markdownroot .pl-en {
color: var(--color-prettylights-syntax-entity);
}
.markdownroot .pl-smi,
.markdownroot .pl-s .pl-s1 {
color: var(--color-prettylights-syntax-storage-modifier-import);
}
.markdownroot .pl-ent {
color: var(--color-prettylights-syntax-entity-tag);
}
.markdownroot .pl-k {
color: var(--color-prettylights-syntax-keyword);
}
.markdownroot .pl-s,
.markdownroot .pl-pds,
.markdownroot .pl-s .pl-pse .pl-s1,
.markdownroot .pl-sr,
.markdownroot .pl-sr .pl-cce,
.markdownroot .pl-sr .pl-sre,
.markdownroot .pl-sr .pl-sra {
color: var(--color-prettylights-syntax-string);
}
.markdownroot .pl-v,
.markdownroot .pl-smw {
color: var(--color-prettylights-syntax-variable);
}
.markdownroot .pl-bu {
color: var(--color-prettylights-syntax-brackethighlighter-unmatched);
}
.markdownroot .pl-ii {
color: var(--color-prettylights-syntax-invalid-illegal-text);
background-color: var(--color-prettylights-syntax-invalid-illegal-bg);
}
.markdownroot .pl-c2 {
color: var(--color-prettylights-syntax-carriage-return-text);
background-color: var(--color-prettylights-syntax-carriage-return-bg);
}
.markdownroot .pl-sr .pl-cce {
font-weight: bold;
color: var(--color-prettylights-syntax-string-regexp);
}
.markdownroot .pl-ml {
color: var(--color-prettylights-syntax-markup-list);
}
.markdownroot .pl-mh,
.markdownroot .pl-mh .pl-en,
.markdownroot .pl-ms {
font-weight: bold;
color: var(--color-prettylights-syntax-markup-heading);
}
.markdownroot .pl-mi {
font-style: italic;
color: var(--color-prettylights-syntax-markup-italic);
}
.markdownroot .pl-mb {
font-weight: bold;
color: var(--color-prettylights-syntax-markup-bold);
}
.markdownroot .pl-md {
color: var(--color-prettylights-syntax-markup-deleted-text);
background-color: var(--color-prettylights-syntax-markup-deleted-bg);
}
.markdownroot .pl-mi1 {
color: var(--color-prettylights-syntax-markup-inserted-text);
background-color: var(--color-prettylights-syntax-markup-inserted-bg);
}
.markdownroot .pl-mc {
color: var(--color-prettylights-syntax-markup-changed-text);
background-color: var(--color-prettylights-syntax-markup-changed-bg);
}
.markdownroot .pl-mi2 {
color: var(--color-prettylights-syntax-markup-ignored-text);
background-color: var(--color-prettylights-syntax-markup-ignored-bg);
}
.markdownroot .pl-mdr {
font-weight: bold;
color: var(--color-prettylights-syntax-meta-diff-range);
}
.markdownroot .pl-ba {
color: var(--color-prettylights-syntax-brackethighlighter-angle);
}
.markdownroot .pl-sg {
color: var(--color-prettylights-syntax-sublimelinter-gutter-mark);
}
.markdownroot .pl-corl {
text-decoration: underline;
color: var(--color-prettylights-syntax-constant-other-reference-link);
}
.markdownroot [data-catalyst] {
display: block;
}
.markdownroot g-emoji {
font-family: "Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";
font-size: 1em;
font-style: normal !important;
font-weight: 400;
line-height: 1;
vertical-align: -0.075em;
}
.markdownroot g-emoji img {
width: 1em;
height: 1em;
}
.markdownroot::before {
display: table;
content: "";
}
.markdownroot::after {
display: table;
clear: both;
content: "";
}
.markdownroot>*:first-child {
margin-top: 0 !important;
}
.markdownroot>*:last-child {
margin-bottom: 0 !important;
}
.markdownroot a:not([href]) {
color: inherit;
text-decoration: none;
}
.markdownroot .absent {
color: var(--color-danger-fg);
}
.markdownroot .anchor {
float: left;
padding-right: 4px;
margin-left: -20px;
line-height: 1;
}
.markdownroot .anchor:focus {
outline: none;
}
.markdownroot p,
.markdownroot blockquote,
.markdownroot ul,
.markdownroot ol,
.markdownroot dl,
.markdownroot table,
.markdownroot pre,
.markdownroot details {
margin-top: 0;
margin-bottom: 16px;
}
.markdownroot blockquote>:first-child {
margin-top: 0;
}
.markdownroot blockquote>:last-child {
margin-bottom: 0;
}
.markdownroot sup>a::before {
content: "[";
}
.markdownroot sup>a::after {
content: "]";
}
.markdownroot h1 .octicon-link,
.markdownroot h2 .octicon-link,
.markdownroot h3 .octicon-link,
.markdownroot h4 .octicon-link,
.markdownroot h5 .octicon-link,
.markdownroot h6 .octicon-link {
color: var(--color-fg-default);
vertical-align: middle;
visibility: hidden;
}
.markdownroot h1:hover .anchor,
.markdownroot h2:hover .anchor,
.markdownroot h3:hover .anchor,
.markdownroot h4:hover .anchor,
.markdownroot h5:hover .anchor,
.markdownroot h6:hover .anchor {
text-decoration: none;
}
.markdownroot h1:hover .anchor .octicon-link,
.markdownroot h2:hover .anchor .octicon-link,
.markdownroot h3:hover .anchor .octicon-link,
.markdownroot h4:hover .anchor .octicon-link,
.markdownroot h5:hover .anchor .octicon-link,
.markdownroot h6:hover .anchor .octicon-link {
visibility: visible;
}
.markdownroot h1 tt,
.markdownroot h1 code,
.markdownroot h2 tt,
.markdownroot h2 code,
.markdownroot h3 tt,
.markdownroot h3 code,
.markdownroot h4 tt,
.markdownroot h4 code,
.markdownroot h5 tt,
.markdownroot h5 code,
.markdownroot h6 tt,
.markdownroot h6 code {
padding: 0 .2em;
font-size: inherit;
}
.markdownroot ul.no-list,
.markdownroot ol.no-list {
padding: 0;
list-style-type: none;
}
.markdownroot ol[type="1"] {
list-style-type: decimal;
}
.markdownroot ol[type=a] {
list-style-type: lower-alpha;
}
.markdownroot ol[type=i] {
list-style-type: lower-roman;
}
.markdownroot div>ol:not([type]) {
list-style-type: decimal;
}
.markdownroot ul ul,
.markdownroot ul ol,
.markdownroot ol ol,
.markdownroot ol ul {
margin-top: 0;
margin-bottom: 0;
}
.markdownroot li>p {
margin-top: 16px;
}
.markdownroot li+li {
margin-top: .25em;
}
.markdownroot dl {
padding: 0;
}
.markdownroot dl dt {
padding: 0;
margin-top: 16px;
font-size: 1em;
font-style: italic;
font-weight: 600;
}
.markdownroot dl dd {
padding: 0 16px;
margin-bottom: 16px;
}
.markdownroot table th {
font-weight: 600;
}
.markdownroot table th,
.markdownroot table td {
padding: 6px 13px;
border: 1px solid var(--color-border-default);
}
.markdownroot table tr {
background-color: var(--color-canvas-default);
border-top: 1px solid var(--color-border-muted);
}
.markdownroot table tr:nth-child(2n) {
background-color: var(--color-canvas-subtle);
}
.markdownroot table img {
background-color: transparent;
}
.markdownroot img[align=right] {
padding-left: 20px;
}
.markdownroot img[align=left] {
padding-right: 20px;
}
.markdownroot .emoji {
max-width: none;
vertical-align: text-top;
background-color: transparent;
}
.markdownroot span.frame {
display: block;
overflow: hidden;
}
.markdownroot span.frame>span {
display: block;
float: left;
width: auto;
padding: 7px;
margin: 13px 0 0;
overflow: hidden;
border: 1px solid var(--color-border-default);
}
.markdownroot span.frame span img {
display: block;
float: left;
}
.markdownroot span.frame span span {
display: block;
padding: 5px 0 0;
clear: both;
color: var(--color-fg-default);
}
.markdownroot span.align-center {
display: block;
overflow: hidden;
clear: both;
}
.markdownroot span.align-center>span {
display: block;
margin: 13px auto 0;
overflow: hidden;
text-align: center;
}
.markdownroot span.align-center span img {
margin: 0 auto;
text-align: center;
}
.markdownroot span.align-right {
display: block;
overflow: hidden;
clear: both;
}
.markdownroot span.align-right>span {
display: block;
margin: 13px 0 0;
overflow: hidden;
text-align: right;
}
.markdownroot span.align-right span img {
margin: 0;
text-align: right;
}
.markdownroot span.float-left {
display: block;
float: left;
margin-right: 13px;
overflow: hidden;
}
.markdownroot span.float-left span {
margin: 13px 0 0;
}
.markdownroot span.float-right {
display: block;
float: right;
margin-left: 13px;
overflow: hidden;
}
.markdownroot span.float-right>span {
display: block;
margin: 13px auto 0;
overflow: hidden;
text-align: right;
}
.markdownroot code,
.markdownroot tt {
padding: .2em .4em;
margin: 0;
font-size: 85%;
background-color: var(--color-neutral-muted);
border-radius: 6px;
}
.markdownroot code br,
.markdownroot tt br {
display: none;
}
.markdownroot del code {
text-decoration: inherit;
}
.markdownroot pre code {
font-size: 100%;
}
.markdownroot pre>code {
padding: 0;
margin: 0;
word-break: normal;
white-space: pre;
background: transparent;
border: 0;
}
.markdownroot .highlight {
margin-bottom: 16px;
}
.markdownroot .highlight pre {
margin-bottom: 0;
word-break: normal;
}
.markdownroot .highlight pre,
.markdownroot pre {
padding: 16px;
overflow: auto;
font-size: 85%;
line-height: 1.45;
background-color: var(--color-canvas-subtle);
border-radius: 6px;
}
.markdownroot pre code,
.markdownroot pre tt {
display: inline;
max-width: auto;
padding: 0;
margin: 0;
overflow: visible;
line-height: inherit;
word-wrap: normal;
background-color: transparent;
border: 0;
}
.markdownroot .csv-data td,
.markdownroot .csv-data th {
padding: 5px;
overflow: hidden;
font-size: 12px;
line-height: 1;
text-align: left;
white-space: nowrap;
}
.markdownroot .csv-data .blob-num {
padding: 10px 8px 9px;
text-align: right;
background: var(--color-canvas-default);
border: 0;
}
.markdownroot .csv-data tr {
border-top: 0;
}
.markdownroot .csv-data th {
font-weight: 600;
background: var(--color-canvas-subtle);
border-top: 0;
}
.markdownroot .footnotes {
font-size: 12px;
color: var(--color-fg-muted);
border-top: 1px solid var(--color-border-default);
}
.markdownroot .footnotes ol {
padding-left: 16px;
}
.markdownroot .footnotes li {
position: relative;
}
.markdownroot .footnotes li:target::before {
position: absolute;
top: -8px;
right: -8px;
bottom: -8px;
left: -24px;
pointer-events: none;
content: "";
border: 2px solid var(--color-accent-emphasis);
border-radius: 6px;
}
.markdownroot .footnotes li:target {
color: var(--color-fg-default);
}
.markdownroot .footnotes .data-footnote-backref g-emoji {
font-family: monospace;
}
.markdownroot [hidden] {
display: none !important;
}
.markdownroot ::-webkit-calendar-picker-indicator {
filter: invert(50%);
}
</style><style media="print" id="__markdown-viewer__md_print_css">:root {
background: white;
color: black;
font: 8pt serif;
line-height: 1.5;
vertical-align: baseline;
}
body, .markdownRoot {
max-width: 100%;
margin: 0;
padding: 0;
}
* {
margin: 0;
padding: 0;
}
p {
margin: 0 0 .3rem 0;
}
ul, ol {
padding-left: 2em
}
a {
color: #666;
text-decoration: underline;
}
a[href]:after {
content: ' (' attr(href) ')';
font-size: 1rem;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
padding: 0 0 .2em 0;
}
h1, h2, h3, h4, h5, h6, dt {
/* break-after: avoid; */
break-inside: avoid;
}
/* Hack to fix break-after: https://stackoverflow.com/a/53742871 */
h1:after, h2:after, h3:after, h4:after, h5:after, h6:after, dt:after {
content: "";
display: block;
/* .2em of padding + 3em for 2 full lines */
height: 3.2em;
margin-bottom: -3.2em;
}
blockquote, pre, li, dt, dd {
break-inside: avoid;
}
</style><style id="__markdown-viewer__hljs_css">.hljs-comment,.hljs-quote{color:#d4d0ab}.hljs-deletion,.hljs-name,.hljs-regexp,.hljs-selector-class,.hljs-selector-id,.hljs-tag,.hljs-template-variable,.hljs-variable{color:#ffa07a}.hljs-built_in,.hljs-builtin-name,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-type{color:#f5ab35}.hljs-attribute{color:gold}.hljs-addition,.hljs-bullet,.hljs-string,.hljs-symbol{color:#abe338}.hljs-section,.hljs-title{color:#00e0e0}.hljs-keyword,.hljs-selector-tag{color:#dcc6e0}.hljs{display:block;overflow-x:auto;background:#2b2b2b;color:#f8f8f2;padding:.5em}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}@media screen and (-ms-high-contrast:active){.hljs-addition,.hljs-attribute,.hljs-built_in,.hljs-builtin-name,.hljs-bullet,.hljs-comment,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-quote,.hljs-string,.hljs-symbol,.hljs-type{color:highlight}.hljs-keyword,.hljs-selector-tag{font-weight:700}}</style><style id="__markdown-viewer__katex_css">@font-face{font-family:KaTeX_AMS;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Caligraphic;font-style:normal;font-weight:700}@font-face{font-family:KaTeX_Caligraphic;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Fraktur;font-style:normal;font-weight:700}@font-face{font-family:KaTeX_Fraktur;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Main;font-style:normal;font-weight:700}@font-face{font-family:KaTeX_Main;font-style:italic;font-weight:700}@font-face{font-family:KaTeX_Main;font-style:italic;font-weight:400}@font-face{font-family:KaTeX_Main;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Math;font-style:italic;font-weight:700}@font-face{font-family:KaTeX_Math;font-style:italic;font-weight:400}@font-face{font-family:"KaTeX_SansSerif";font-style:normal;font-weight:700}@font-face{font-family:"KaTeX_SansSerif";font-style:italic;font-weight:400}@font-face{font-family:"KaTeX_SansSerif";font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Script;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Size1;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Size2;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Size3;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Size4;font-style:normal;font-weight:400}@font-face{font-family:KaTeX_Typewriter;font-style:normal;font-weight:400}.katex{text-rendering:auto;font:normal 1.21em KaTeX_Main,Times New Roman,serif;line-height:1.2;text-indent:0}.katex *{-ms-high-contrast-adjust:none!important;border-color:currentColor}.katex .katex-version:after{content:"0.13.13"}.katex .katex-mathml{clip:rect(1px,1px,1px,1px);border:0;height:1px;overflow:hidden;padding:0;position:absolute;width:1px}.katex .katex-html>.newline{display:block}.katex .base{position:relative;white-space:nowrap;width:-webkit-min-content;width:-moz-min-content;width:min-content}.katex .base,.katex .strut{display:inline-block}.katex .textbf{font-weight:700}.katex .textit{font-style:italic}.katex .textrm{font-family:KaTeX_Main}.katex .textsf{font-family:KaTeX_SansSerif}.katex .texttt{font-family:KaTeX_Typewriter}.katex .mathnormal{font-family:KaTeX_Math;font-style:italic}.katex .mathit{font-family:KaTeX_Main;font-style:italic}.katex .mathrm{font-style:normal}.katex .mathbf{font-family:KaTeX_Main;font-weight:700}.katex .boldsymbol{font-family:KaTeX_Math;font-style:italic;font-weight:700}.katex .amsrm,.katex .mathbb,.katex .textbb{font-family:KaTeX_AMS}.katex .mathcal{font-family:KaTeX_Caligraphic}.katex .mathfrak,.katex .textfrak{font-family:KaTeX_Fraktur}.katex .mathtt{font-family:KaTeX_Typewriter}.katex .mathscr,.katex .textscr{font-family:KaTeX_Script}.katex .mathsf,.katex .textsf{font-family:KaTeX_SansSerif}.katex .mathboldsf,.katex .textboldsf{font-family:KaTeX_SansSerif;font-weight:700}.katex .mathitsf,.katex .textitsf{font-family:KaTeX_SansSerif;font-style:italic}.katex .mainrm{font-family:KaTeX_Main;font-style:normal}.katex .vlist-t{border-collapse:collapse;display:inline-table;table-layout:fixed}.katex .vlist-r{display:table-row}.katex .vlist{display:table-cell;position:relative;vertical-align:bottom}.katex .vlist>span{display:block;height:0;position:relative}.katex .vlist>span>span{display:inline-block}.katex .vlist>span>.pstrut{overflow:hidden;width:0}.katex .vlist-t2{margin-right:-2px}.katex .vlist-s{display:table-cell;font-size:1px;min-width:2px;vertical-align:bottom;width:2px}.katex .vbox{align-items:baseline;display:inline-flex;flex-direction:column}.katex .hbox{width:100%}.katex .hbox,.katex .thinbox{display:inline-flex;flex-direction:row}.katex .thinbox{max-width:0;width:0}.katex .msupsub{text-align:left}.katex .mfrac>span>span{text-align:center}.katex .mfrac .frac-line{border-bottom-style:solid;display:inline-block;width:100%}.katex .hdashline,.katex .hline,.katex .mfrac .frac-line,.katex .overline .overline-line,.katex .rule,.katex .underline .underline-line{min-height:1px}.katex .mspace{display:inline-block}.katex .clap,.katex .llap,.katex .rlap{position:relative;width:0}.katex .clap>.inner,.katex .llap>.inner,.katex .rlap>.inner{position:absolute}.katex .clap>.fix,.katex .llap>.fix,.katex .rlap>.fix{display:inline-block}.katex .llap>.inner{right:0}.katex .clap>.inner,.katex .rlap>.inner{left:0}.katex .clap>.inner>span{margin-left:-50%;margin-right:50%}.katex .rule{border:0 solid;display:inline-block;position:relative}.katex .hline,.katex .overline .overline-line,.katex .underline .underline-line{border-bottom-style:solid;display:inline-block;width:100%}.katex .hdashline{border-bottom-style:dashed;display:inline-block;width:100%}.katex .sqrt>.root{margin-left:.27777778em;margin-right:-.55555556em}.katex .fontsize-ensurer.reset-size1.size1,.katex .sizing.reset-size1.size1{font-size:1em}.katex .fontsize-ensurer.reset-size1.size2,.katex .sizing.reset-size1.size2{font-size:1.2em}.katex .fontsize-ensurer.reset-size1.size3,.katex .sizing.reset-size1.size3{font-size:1.4em}.katex .fontsize-ensurer.reset-size1.size4,.katex .sizing.reset-size1.size4{font-size:1.6em}.katex .fontsize-ensurer.reset-size1.size5,.katex .sizing.reset-size1.size5{font-size:1.8em}.katex .fontsize-ensurer.reset-size1.size6,.katex .sizing.reset-size1.size6{font-size:2em}.katex .fontsize-ensurer.reset-size1.size7,.katex .sizing.reset-size1.size7{font-size:2.4em}.katex .fontsize-ensurer.reset-size1.size8,.katex .sizing.reset-size1.size8{font-size:2.88em}.katex .fontsize-ensurer.reset-size1.size9,.katex .sizing.reset-size1.size9{font-size:3.456em}.katex .fontsize-ensurer.reset-size1.size10,.katex .sizing.reset-size1.size10{font-size:4.148em}.katex .fontsize-ensurer.reset-size1.size11,.katex .sizing.reset-size1.size11{font-size:4.976em}.katex .fontsize-ensurer.reset-size2.size1,.katex .sizing.reset-size2.size1{font-size:.83333333em}.katex .fontsize-ensurer.reset-size2.size2,.katex .sizing.reset-size2.size2{font-size:1em}.katex .fontsize-ensurer.reset-size2.size3,.katex .sizing.reset-size2.size3{font-size:1.16666667em}.katex .fontsize-ensurer.reset-size2.size4,.katex .sizing.reset-size2.size4{font-size:1.33333333em}.katex .fontsize-ensurer.reset-size2.size5,.katex .sizing.reset-size2.size5{font-size:1.5em}.katex .fontsize-ensurer.reset-size2.size6,.katex .sizing.reset-size2.size6{font-size:1.66666667em}.katex .fontsize-ensurer.reset-size2.size7,.katex .sizing.reset-size2.size7{font-size:2em}.katex .fontsize-ensurer.reset-size2.size8,.katex .sizing.reset-size2.size8{font-size:2.4em}.katex .fontsize-ensurer.reset-size2.size9,.katex .sizing.reset-size2.size9{font-size:2.88em}.katex .fontsize-ensurer.reset-size2.size10,.katex .sizing.reset-size2.size10{font-size:3.45666667em}.katex .fontsize-ensurer.reset-size2.size11,.katex .sizing.reset-size2.size11{font-size:4.14666667em}.katex .fontsize-ensurer.reset-size3.size1,.katex .sizing.reset-size3.size1{font-size:.71428571em}.katex .fontsize-ensurer.reset-size3.size2,.katex .sizing.reset-size3.size2{font-size:.85714286em}.katex .fontsize-ensurer.reset-size3.size3,.katex .sizing.reset-size3.size3{font-size:1em}.katex .fontsize-ensurer.reset-size3.size4,.katex .sizing.reset-size3.size4{font-size:1.14285714em}.katex .fontsize-ensurer.reset-size3.size5,.katex .sizing.reset-size3.size5{font-size:1.28571429em}.katex .fontsize-ensurer.reset-size3.size6,.katex .sizing.reset-size3.size6{font-size:1.42857143em}.katex .fontsize-ensurer.reset-size3.size7,.katex .sizing.reset-size3.size7{font-size:1.71428571em}.katex .fontsize-ensurer.reset-size3.size8,.katex .sizing.reset-size3.size8{font-size:2.05714286em}.katex .fontsize-ensurer.reset-size3.size9,.katex .sizing.reset-size3.size9{font-size:2.46857143em}.katex .fontsize-ensurer.reset-size3.size10,.katex .sizing.reset-size3.size10{font-size:2.96285714em}.katex .fontsize-ensurer.reset-size3.size11,.katex .sizing.reset-size3.size11{font-size:3.55428571em}.katex .fontsize-ensurer.reset-size4.size1,.katex .sizing.reset-size4.size1{font-size:.625em}.katex .fontsize-ensurer.reset-size4.size2,.katex .sizing.reset-size4.size2{font-size:.75em}.katex .fontsize-ensurer.reset-size4.size3,.katex .sizing.reset-size4.size3{font-size:.875em}.katex .fontsize-ensurer.reset-size4.size4,.katex .sizing.reset-size4.size4{font-size:1em}.katex .fontsize-ensurer.reset-size4.size5,.katex .sizing.reset-size4.size5{font-size:1.125em}.katex .fontsize-ensurer.reset-size4.size6,.katex .sizing.reset-size4.size6{font-size:1.25em}.katex .fontsize-ensurer.reset-size4.size7,.katex .sizing.reset-size4.size7{font-size:1.5em}.katex .fontsize-ensurer.reset-size4.size8,.katex .sizing.reset-size4.size8{font-size:1.8em}.katex .fontsize-ensurer.reset-size4.size9,.katex .sizing.reset-size4.size9{font-size:2.16em}.katex .fontsize-ensurer.reset-size4.size10,.katex .sizing.reset-size4.size10{font-size:2.5925em}.katex .fontsize-ensurer.reset-size4.size11,.katex .sizing.reset-size4.size11{font-size:3.11em}.katex .fontsize-ensurer.reset-size5.size1,.katex .sizing.reset-size5.size1{font-size:.55555556em}.katex .fontsize-ensurer.reset-size5.size2,.katex .sizing.reset-size5.size2{font-size:.66666667em}.katex .fontsize-ensurer.reset-size5.size3,.katex .sizing.reset-size5.size3{font-size:.77777778em}.katex .fontsize-ensurer.reset-size5.size4,.katex .sizing.reset-size5.size4{font-size:.88888889em}.katex .fontsize-ensurer.reset-size5.size5,.katex .sizing.reset-size5.size5{font-size:1em}.katex .fontsize-ensurer.reset-size5.size6,.katex .sizing.reset-size5.size6{font-size:1.11111111em}.katex .fontsize-ensurer.reset-size5.size7,.katex .sizing.reset-size5.size7{font-size:1.33333333em}.katex .fontsize-ensurer.reset-size5.size8,.katex .sizing.reset-size5.size8{font-size:1.6em}.katex .fontsize-ensurer.reset-size5.size9,.katex .sizing.reset-size5.size9{font-size:1.92em}.katex .fontsize-ensurer.reset-size5.size10,.katex .sizing.reset-size5.size10{font-size:2.30444444em}.katex .fontsize-ensurer.reset-size5.size11,.katex .sizing.reset-size5.size11{font-size:2.76444444em}.katex .fontsize-ensurer.reset-size6.size1,.katex .sizing.reset-size6.size1{font-size:.5em}.katex .fontsize-ensurer.reset-size6.size2,.katex .sizing.reset-size6.size2{font-size:.6em}.katex .fontsize-ensurer.reset-size6.size3,.katex .sizing.reset-size6.size3{font-size:.7em}.katex .fontsize-ensurer.reset-size6.size4,.katex .sizing.reset-size6.size4{font-size:.8em}.katex .fontsize-ensurer.reset-size6.size5,.katex .sizing.reset-size6.size5{font-size:.9em}.katex .fontsize-ensurer.reset-size6.size6,.katex .sizing.reset-size6.size6{font-size:1em}.katex .fontsize-ensurer.reset-size6.size7,.katex .sizing.reset-size6.size7{font-size:1.2em}.katex .fontsize-ensurer.reset-size6.size8,.katex .sizing.reset-size6.size8{font-size:1.44em}.katex .fontsize-ensurer.reset-size6.size9,.katex .sizing.reset-size6.size9{font-size:1.728em}.katex .fontsize-ensurer.reset-size6.size10,.katex .sizing.reset-size6.size10{font-size:2.074em}.katex .fontsize-ensurer.reset-size6.size11,.katex .sizing.reset-size6.size11{font-size:2.488em}.katex .fontsize-ensurer.reset-size7.size1,.katex .sizing.reset-size7.size1{font-size:.41666667em}.katex .fontsize-ensurer.reset-size7.size2,.katex .sizing.reset-size7.size2{font-size:.5em}.katex .fontsize-ensurer.reset-size7.size3,.katex .sizing.reset-size7.size3{font-size:.58333333em}.katex .fontsize-ensurer.reset-size7.size4,.katex .sizing.reset-size7.size4{font-size:.66666667em}.katex .fontsize-ensurer.reset-size7.size5,.katex .sizing.reset-size7.size5{font-size:.75em}.katex .fontsize-ensurer.reset-size7.size6,.katex .sizing.reset-size7.size6{font-size:.83333333em}.katex .fontsize-ensurer.reset-size7.size7,.katex .sizing.reset-size7.size7{font-size:1em}.katex .fontsize-ensurer.reset-size7.size8,.katex .sizing.reset-size7.size8{font-size:1.2em}.katex .fontsize-ensurer.reset-size7.size9,.katex .sizing.reset-size7.size9{font-size:1.44em}.katex .fontsize-ensurer.reset-size7.size10,.katex .sizing.reset-size7.size10{font-size:1.72833333em}.katex .fontsize-ensurer.reset-size7.size11,.katex .sizing.reset-size7.size11{font-size:2.07333333em}.katex .fontsize-ensurer.reset-size8.size1,.katex .sizing.reset-size8.size1{font-size:.34722222em}.katex .fontsize-ensurer.reset-size8.size2,.katex .sizing.reset-size8.size2{font-size:.41666667em}.katex .fontsize-ensurer.reset-size8.size3,.katex .sizing.reset-size8.size3{font-size:.48611111em}.katex .fontsize-ensurer.reset-size8.size4,.katex .sizing.reset-size8.size4{font-size:.55555556em}.katex .fontsize-ensurer.reset-size8.size5,.katex .sizing.reset-size8.size5{font-size:.625em}.katex .fontsize-ensurer.reset-size8.size6,.katex .sizing.reset-size8.size6{font-size:.69444444em}.katex .fontsize-ensurer.reset-size8.size7,.katex .sizing.reset-size8.size7{font-size:.83333333em}.katex .fontsize-ensurer.reset-size8.size8,.katex .sizing.reset-size8.size8{font-size:1em}.katex .fontsize-ensurer.reset-size8.size9,.katex .sizing.reset-size8.size9{font-size:1.2em}.katex .fontsize-ensurer.reset-size8.size10,.katex .sizing.reset-size8.size10{font-size:1.44027778em}.katex .fontsize-ensurer.reset-size8.size11,.katex .sizing.reset-size8.size11{font-size:1.72777778em}.katex .fontsize-ensurer.reset-size9.size1,.katex .sizing.reset-size9.size1{font-size:.28935185em}.katex .fontsize-ensurer.reset-size9.size2,.katex .sizing.reset-size9.size2{font-size:.34722222em}.katex .fontsize-ensurer.reset-size9.size3,.katex .sizing.reset-size9.size3{font-size:.40509259em}.katex .fontsize-ensurer.reset-size9.size4,.katex .sizing.reset-size9.size4{font-size:.46296296em}.katex .fontsize-ensurer.reset-size9.size5,.katex .sizing.reset-size9.size5{font-size:.52083333em}.katex .fontsize-ensurer.reset-size9.size6,.katex .sizing.reset-size9.size6{font-size:.5787037em}.katex .fontsize-ensurer.reset-size9.size7,.katex .sizing.reset-size9.size7{font-size:.69444444em}.katex .fontsize-ensurer.reset-size9.size8,.katex .sizing.reset-size9.size8{font-size:.83333333em}.katex .fontsize-ensurer.reset-size9.size9,.katex .sizing.reset-size9.size9{font-size:1em}.katex .fontsize-ensurer.reset-size9.size10,.katex .sizing.reset-size9.size10{font-size:1.20023148em}.katex .fontsize-ensurer.reset-size9.size11,.katex .sizing.reset-size9.size11{font-size:1.43981481em}.katex .fontsize-ensurer.reset-size10.size1,.katex .sizing.reset-size10.size1{font-size:.24108004em}.katex .fontsize-ensurer.reset-size10.size2,.katex .sizing.reset-size10.size2{font-size:.28929605em}.katex .fontsize-ensurer.reset-size10.size3,.katex .sizing.reset-size10.size3{font-size:.33751205em}.katex .fontsize-ensurer.reset-size10.size4,.katex .sizing.reset-size10.size4{font-size:.38572806em}.katex .fontsize-ensurer.reset-size10.size5,.katex .sizing.reset-size10.size5{font-size:.43394407em}.katex .fontsize-ensurer.reset-size10.size6,.katex .sizing.reset-size10.size6{font-size:.48216008em}.katex .fontsize-ensurer.reset-size10.size7,.katex .sizing.reset-size10.size7{font-size:.57859209em}.katex .fontsize-ensurer.reset-size10.size8,.katex .sizing.reset-size10.size8{font-size:.69431051em}.katex .fontsize-ensurer.reset-size10.size9,.katex .sizing.reset-size10.size9{font-size:.83317261em}.katex .fontsize-ensurer.reset-size10.size10,.katex .sizing.reset-size10.size10{font-size:1em}.katex .fontsize-ensurer.reset-size10.size11,.katex .sizing.reset-size10.size11{font-size:1.19961427em}.katex .fontsize-ensurer.reset-size11.size1,.katex .sizing.reset-size11.size1{font-size:.20096463em}.katex .fontsize-ensurer.reset-size11.size2,.katex .sizing.reset-size11.size2{font-size:.24115756em}.katex .fontsize-ensurer.reset-size11.size3,.katex .sizing.reset-size11.size3{font-size:.28135048em}.katex .fontsize-ensurer.reset-size11.size4,.katex .sizing.reset-size11.size4{font-size:.32154341em}.katex .fontsize-ensurer.reset-size11.size5,.katex .sizing.reset-size11.size5{font-size:.36173633em}.katex .fontsize-ensurer.reset-size11.size6,.katex .sizing.reset-size11.size6{font-size:.40192926em}.katex .fontsize-ensurer.reset-size11.size7,.katex .sizing.reset-size11.size7{font-size:.48231511em}.katex .fontsize-ensurer.reset-size11.size8,.katex .sizing.reset-size11.size8{font-size:.57877814em}.katex .fontsize-ensurer.reset-size11.size9,.katex .sizing.reset-size11.size9{font-size:.69453376em}.katex .fontsize-ensurer.reset-size11.size10,.katex .sizing.reset-size11.size10{font-size:.83360129em}.katex .fontsize-ensurer.reset-size11.size11,.katex .sizing.reset-size11.size11{font-size:1em}.katex .delimsizing.size1{font-family:KaTeX_Size1}.katex .delimsizing.size2{font-family:KaTeX_Size2}.katex .delimsizing.size3{font-family:KaTeX_Size3}.katex .delimsizing.size4{font-family:KaTeX_Size4}.katex .delimsizing.mult .delim-size1>span{font-family:KaTeX_Size1}.katex .delimsizing.mult .delim-size4>span{font-family:KaTeX_Size4}.katex .nulldelimiter{display:inline-block;width:.12em}.katex .delimcenter,.katex .op-symbol{position:relative}.katex .op-symbol.small-op{font-family:KaTeX_Size1}.katex .op-symbol.large-op{font-family:KaTeX_Size2}.katex .accent>.vlist-t,.katex .op-limits>.vlist-t{text-align:center}.katex .accent .accent-body{position:relative}.katex .accent .accent-body:not(.accent-full){width:0}.katex .overlay{display:block}.katex .mtable .vertical-separator{display:inline-block;min-width:1px}.katex .mtable .arraycolsep{display:inline-block}.katex .mtable .col-align-c>.vlist-t{text-align:center}.katex .mtable .col-align-l>.vlist-t{text-align:left}.katex .mtable .col-align-r>.vlist-t{text-align:right}.katex .svg-align{text-align:left}.katex svg{fill:currentColor;stroke:currentColor;fill-rule:nonzero;fill-opacity:1;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;display:block;height:inherit;position:absolute;width:100%}.katex svg path{stroke:none}.katex img{border-style:none;max-height:none;max-width:none;min-height:0;min-width:0}.katex .stretchy{display:block;overflow:hidden;position:relative;width:100%}.katex .stretchy:after,.katex .stretchy:before{content:""}.katex .hide-tail{overflow:hidden;position:relative;width:100%}.katex .halfarrow-left{left:0;overflow:hidden;position:absolute;width:50.2%}.katex .halfarrow-right{overflow:hidden;position:absolute;right:0;width:50.2%}.katex .brace-left{left:0;overflow:hidden;position:absolute;width:25.1%}.katex .brace-center{left:25%;overflow:hidden;position:absolute;width:50%}.katex .brace-right{overflow:hidden;position:absolute;right:0;width:25.1%}.katex .x-arrow-pad{padding:0 .5em}.katex .cd-arrow-pad{padding:0 .55556em 0 .27778em}.katex .mover,.katex .munder,.katex .x-arrow{text-align:center}.katex .boxpad{padding:0 .3em}.katex .fbox,.katex .fcolorbox{border:.04em solid;box-sizing:border-box}.katex .cancel-pad{padding:0 .2em}.katex .cancel-lap{margin-left:-.2em;margin-right:-.2em}.katex .sout{border-bottom-style:solid;border-bottom-width:.08em}.katex .angl{border-right:.049em solid;border-top:.049em solid;box-sizing:border-box;margin-right:.03889em}.katex .anglpad{padding:0 .03889em}.katex .eqn-num:before{content:"(" counter(katexEqnNo) ")";counter-increment:katexEqnNo}.katex .mml-eqn-num:before{content:"(" counter(mmlEqnNo) ")";counter-increment:mmlEqnNo}.katex .mtr-glue{width:50%}.katex .cd-vert-arrow{display:inline-block;position:relative}.katex .cd-label-left{display:inline-block;position:absolute;right:calc(50% + .3em);text-align:left}.katex .cd-label-right{display:inline-block;left:calc(50% + .3em);position:absolute;text-align:right}.katex-display{display:block;margin:1em 0;text-align:center}.katex-display>.katex{display:block;text-align:center;white-space:nowrap}.katex-display>.katex>.katex-html{display:block;position:relative}.katex-display>.katex>.katex-html>.tag{position:absolute;right:0}.katex-display.leqno>.katex>.katex-html>.tag{left:0;right:auto}.katex-display.fleqn>.katex{padding-left:2em;text-align:left}body{counter-reset:katexEqnNo mmlEqnNo}
</style><style id="__markdown-viewer__texmath_css">/* style for html inside of browsers */
.katex { font-size: 1em !important; } /* align KaTeX font-size to surrounding text */
eq { display: inline-block; }
eqn { display: block}
section.eqno {
display: flex;
flex-direction: row;
align-content: space-between;
align-items: center;
}
section.eqno > eqn {
width: 100%;
margin-left: 3em;
}
section.eqno > span {
width:3em;
text-align:right;
}
</style><style id="__markdown-viewer__menu_css">/* Style for the menu, possible positions/visibility */
#__markdown-viewer__tools {
margin:0;
padding:0;
background:#555;
color:#eee;
box-shadow:0 -1px rgba(0,0,0,.5) inset;
border-radius: .5em;
max-width: 25%;
min-width: 2.8em;
min-height: 3em;
z-index: 2147483647;
position: relative;
}
#__markdown-viewer__tools.floating {
float:right;
margin: 0 0 .5em .5em;
}
#__markdown-viewer__tools.fixed {
max-height: calc(100vh - 1em);
overflow-y: auto;
position:fixed;
top:.5em;
right:1em;
}
#__markdown-viewer__tools.hidden {
display:none;
}
@media print {
#__markdown-viewer__tools {
display: none;
}
}
#__markdown-viewer__tools a[href]:after {
content: "";
}
/* Style for the menu top */
label[for=__markdown-viewer__show-tools] {
display:block;
padding:0 18px 0 12px;
line-height:3em;
background:#333;
cursor:pointer;
border-radius: .5em;
min-height: 3em;
width: .9em;
position: absolute;
right: 0;
}
input#__markdown-viewer__show-tools:not(:checked) ~ label {
margin-left: -.9em;
}
input#__markdown-viewer__show-tools:checked ~ label {
}
label[for=__markdown-viewer__show-tools]:before{
}
label[for=__markdown-viewer__show-tools]:after {
content:"";
display:inline-block;
float:right;
margin-top:1.5em;
right:5px;
width:0;
height:0;
border-style: solid;
border-color: rgba(255,255,255,.5) transparent;
border-width: 4px 4px 0 4px;
transition:border-bottom .1s, border-top .1s .1s;
}
input#__markdown-viewer__show-tools:checked ~ label:after {
border-top-width:0;
border-bottom-width:4px;
transition:border-top .1s, border-bottom .1s .1s;
}
/* hide the input that tracks the menu's visibility */
input#__markdown-viewer__show-tools {
display:none;
}
/* style, and hide/show menu items based on the input being checked */
#__markdown-viewer__tools > .toggleable {
overflow:hidden;
transition-property:max-height, max-width, padding-top, padding-bottom, margin-top, margin-bottom;
transition-duration:0.5s;
}
input#__markdown-viewer__show-tools:checked ~ .toggleable {
/* maxes should be 'none' or infinite values, however those are not aniimatable, so just put something big enough. */
max-width: 2000px;
max-height: 2000px;
overflow-y: auto;
transition-timing-function:ease-in;
}
input#__markdown-viewer__show-tools:not(:checked) ~ .toggleable {
max-height:0;
max-width:0;
transition-timing-function:ease-out;
padding-top:0;
padding-bottom:0;
margin-top:0;
margin-bottom:0;
}
/* style the table of contents and its items */
#__markdown-viewer__toc {
display:block;
padding: .5em;
border:0;
}
#__markdown-viewer__toc::before {
content: "Table of Contents";
text-align: center;
display: block;
font-weight: bold;
text-decoration: underline;
}
#__markdown-viewer__toc {
margin-top: 2em;
}
#__markdown-viewer__tools.fixed input#__markdown-viewer__show-tools:checked ~ #__markdown-viewer__toc {
max-height: calc(100vh - 16em);
}
input#__markdown-viewer__show-tools:checked ~ #__markdown-viewer__toc::before {
position: absolute;
top: .5em;
left: 0;
right: 3em;
}
#__markdown-viewer__tools select {
max-width: 40%;
margin: 0 .5em;
}
#__markdown-viewer__tools select,
#__markdown-viewer__toc * {
white-space: nowrap;
overflow-x: hidden;
text-overflow: ellipsis;
}
#__markdown-viewer__tools a {
color: white;
text-decoration: none;
}
#__markdown-viewer__toc ul {
list-style: inside "• ";
padding: 0;
margin: 0;
}
#__markdown-viewer__toc ul ul {
padding-left: 1.5em;
}
/* Style the "Download Source" button at the end of the menu */
#__markdown-viewer__tools > p {
text-align:center;
padding: 0 .5em;
}
#__markdown-viewer__download {
/* appearance: button; */
-moz-appearance: button !important;
display:inline-block;
text-align: center;
text-decoration:none;
margin: .5em auto;
}
</style><style id="__markdown-viewer__custom_css"></style><meta name="viewport" content="width=device-width, initial-scale=1"><title>Chapter 2: Advanced Calculator</title></head><body><div id="__markdown-viewer__tools" class="floating"><input type="checkbox" id="__markdown-viewer__show-tools"><label for="__markdown-viewer__show-tools"></label><div id="__markdown-viewer__toc" class="toggleable"><ul><li><a href="#chapter-2-advanced-calculator">Chapter 2: Advanced Calculator</a><ul><li><a href="#motivation">Motivation</a></li><li><a href="#principal-features">Principal Features</a><ul><li><a href="#the-abstract-syntax-type-expr">The Abstract Syntax Type Expr</a></li><li><a href="#lexical-scanner-and-main">Lexical scanner and main</a></li></ul></li><li><a href="#training-the-parser-for-better-error-reporting">Training The Parser For Better Error Reporting</a></li></ul></li></ul></div><p class="toggleable">Pick a markdown and code style:<br><select id="__markdown-viewer__mdselect"><option value="sss">default</option><option value="github">github</option></select><select id="__markdown-viewer__hlselect"><option value="a11y-dark">a11y-dark</option><option value="a11y-light">a11y-light</option><option value="a11y-auto">a11y-auto</option><option value="agate">agate</option><option value="androidstudio">androidstudio</option><option value="an-old-hope">an-old-hope</option><option value="arduino-light">arduino-light</option><option value="arta">arta</option><option value="ascetic">ascetic</option><option value="atelier-cave-dark">atelier-cave-dark</option><option value="atelier-cave-light">atelier-cave-light</option><option value="atelier-cave-auto">atelier-cave-auto</option><option value="atelier-dune-dark">atelier-dune-dark</option><option value="atelier-dune-light">atelier-dune-light</option><option value="atelier-dune-auto">atelier-dune-auto</option><option value="atelier-estuary-dark">atelier-estuary-dark</option><option value="atelier-estuary-light">atelier-estuary-light</option><option value="atelier-estuary-auto">atelier-estuary-auto</option><option value="atelier-forest-dark">atelier-forest-dark</option><option value="atelier-forest-light">atelier-forest-light</option><option value="atelier-forest-auto">atelier-forest-auto</option><option value="atelier-heath-dark">atelier-heath-dark</option><option value="atelier-heath-light">atelier-heath-light</option><option value="atelier-heath-auto">atelier-heath-auto</option><option value="atelier-lakeside-dark">atelier-lakeside-dark</option><option value="atelier-lakeside-light">atelier-lakeside-light</option><option value="atelier-lakeside-auto">atelier-lakeside-auto</option><option value="atelier-plateau-dark">atelier-plateau-dark</option><option value="atelier-plateau-light">atelier-plateau-light</option><option value="atelier-plateau-auto">atelier-plateau-auto</option><option value="atelier-savanna-dark">atelier-savanna-dark</option><option value="atelier-savanna-light">atelier-savanna-light</option><option value="atelier-savanna-auto">atelier-savanna-auto</option><option value="atelier-seaside-dark">atelier-seaside-dark</option><option value="atelier-seaside-light">atelier-seaside-light</option><option value="atelier-seaside-auto">atelier-seaside-auto</option><option value="atelier-sulphurpool-dark">atelier-sulphurpool-dark</option><option value="atelier-sulphurpool-light">atelier-sulphurpool-light</option><option value="atelier-sulphurpool-auto">atelier-sulphurpool-auto</option><option value="atom-one-dark">atom-one-dark</option><option value="atom-one-dark-reasonable">atom-one-dark-reasonable</option><option value="atom-one-light">atom-one-light</option><option value="brown-paper">brown-paper</option><option value="codepen-embed">codepen-embed</option><option value="color-brewer">color-brewer</option><option value="darcula">darcula</option><option value="dark">dark</option><option value="default">default</option><option value="docco">docco</option><option value="dracula">dracula</option><option value="far">far</option><option value="foundation">foundation</option><option value="github">github</option><option value="github-gist">github-gist</option><option value="gml">gml</option><option value="googlecode">googlecode</option><option value="gradient-dark">gradient-dark</option><option value="grayscale">grayscale</option><option value="gruvbox-dark">gruvbox-dark</option><option value="gruvbox-light">gruvbox-light</option><option value="gruvbox-auto">gruvbox-auto</option><option value="hopscotch">hopscotch</option><option value="hybrid">hybrid</option><option value="idea">idea</option><option value="ir-black">ir-black</option><option value="isbl-editor-dark">isbl-editor-dark</option><option value="isbl-editor-light">isbl-editor-light</option><option value="isbl-editor-auto">isbl-editor-auto</option><option value="kimbie">kimbie</option><option value="kimbie">kimbie</option><option value="lightfair">lightfair</option><option value="lioshi">lioshi</option><option value="magula">magula</option><option value="mono-blue">mono-blue</option><option value="monokai">monokai</option><option value="monokai-sublime">monokai-sublime</option><option value="night-owl">night-owl</option><option value="nnfx">nnfx</option><option value="nnfx-dark">nnfx-dark</option><option value="nord">nord</option><option value="obsidian">obsidian</option><option value="ocean">ocean</option><option value="paraiso-dark">paraiso-dark</option><option value="paraiso-light">paraiso-light</option><option value="paraiso-auto">paraiso-auto</option><option value="pojoaque">pojoaque</option><option value="purebasic">purebasic</option><option value="qtcreator_dark">qtcreator_dark</option><option value="qtcreator_light">qtcreator_light</option><option value="qtcreator_auto">qtcreator_auto</option><option value="railscasts">railscasts</option><option value="rainbow">rainbow</option><option value="routeros">routeros</option><option value="school-book">school-book</option><option value="shades-of-purple">shades-of-purple</option><option value="solarized-dark">solarized-dark</option><option value="solarized-light">solarized-light</option><option value="solarized-auto">solarized-auto</option><option value="srcery">srcery</option><option value="sunburst">sunburst</option><option value="tomorrow">tomorrow</option><option value="tomorrow-night">tomorrow-night</option><option value="tomorrow-night-blue">tomorrow-night-blue</option><option value="tomorrow-night-bright">tomorrow-night-bright</option><option value="tomorrow-night-eighties">tomorrow-night-eighties</option><option value="vs">vs</option><option value="vs2015">vs2015</option><option value="xcode">xcode</option><option value="xt256">xt256</option><option value="zenburn">zenburn</option></select></p><p class="toggleable"><a id="__markdown-viewer__download" download="markdown.html" style="display: none;" href="blob:null/409e5f2c-8751-4e0d-ad53-796ae579b7b8">Download as HTML</a></p></div><div class="markdownRoot"><h2 id="chapter-2-advanced-calculator">Chapter 2: Advanced Calculator</h2>
<p>In the second chapter of this tutorial, we write a more advanced
version of the calculator example and describe a more complete set of
features of RustLr including:</p>
<ul>
<li>How to write ambiguous grammars with operator precedence and associativity
declarations.</li>
<li>How to parse, create abstract syntax, and report syntactic and semantic errors for more sophisticated kinds of
expressions that include variables
and scoping rules, in particular expressions such as <code>let x=3 in x*x</code>.</li>
<li>How to use a simple error-recovery technique.</li>
<li>How to use patterns when defining grammar production rules.</li>
<li>How to train the parser interactively for better error reporting.</li>
</ul>
<p>The <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/calc4.grammar">grammar</a>
for the more advanced calculator is as follows:</p>
<pre><code class="language-ignore">!<span class="hljs-keyword">use</span> crate::exprtrees::*; <span class="hljs-comment">/* ! lines are injected verbatim into parser */</span>
!<span class="hljs-keyword">use</span> crate::exprtrees::Expr::*;
!<span class="hljs-keyword">use</span> rustlr::{LBox};
lifetime <span class="hljs-symbol">'src_lt</span>
absyntype Expr<<span class="hljs-symbol">'src_lt</span>>
externtype <span class="hljs-built_in">i64</span>
nonterminals E ES
terminals + - * / ( ) = ;
terminals <span class="hljs-keyword">let</span> <span class="hljs-keyword">in</span> int var
topsym ES
resync ;
left * <span class="hljs-number">500</span>
left / <span class="hljs-number">500</span>
left + <span class="hljs-number">400</span>
left - <span class="hljs-number">400</span>
left = <span class="hljs-number">200</span>
# <span class="hljs-keyword">for</span> lexical scanner generation:
lexvalue int Num(n) Val(n)
lexvalue var Alphanum(x) Var(x)
lexattribute set_line_comment(<span class="hljs-string">"#"</span>)
E --> int:m { m.value }
E --> var:s { s.value }
E --> E:e1 + E:e2 { Plus(e1.lbox(),parser.lbx(<span class="hljs-number">2</span>,e2.value)) }
E --> E:[e1] - E:[e2] { Minus(e1,e2)}
E --> E:[e1] / E:[e2] { Divide(e1,e2) }
E --> E:[e1] * E:[e2] { Times(e1,e2) }
E(<span class="hljs-number">600</span>) --> - E:[e] { Negative(e) }
E --> ( E:e ) { e.value }
E --> <span class="hljs-keyword">let</span> E:@Var(x)@ = E:[e] <span class="hljs-keyword">in</span> E:[b] {Letexp(x,e,b)}
ES --> E:[n] ; { Seq(<span class="hljs-built_in">vec!</span>[n]) }
ES ==> ES:@Seq(<span class="hljs-keyword">mut</span> v)@ E:[e] ; {
v.push(e);
Seq(v)
} <==
# ==> and <== are required <span class="hljs-keyword">for</span> rules spanning multiple lines
EOF
</code></pre>
<h3 id="motivation">Motivation</h3>
<p>Using an LR parser generator has a non-trivial learning curve.
Working with strictly unambiguous grammars can be non-intuitive.
Intuitively we'd like to see something close to the BNF definition of
syntax: <code>E --> E+E | E*E | E-E</code>, etc. Every expression <code>E</code> can
be a subexpression of a larger one. But such grammars are ambiguous
and thus not LR. The ambiguity comes from the unspecified precedence
of operators + and *, and the unspecified associativity of -. Another
ambiguity is illustrated by the infamous "dangling else" problem.
In a grammar with</p>
<pre><code> `E --> if (E) E | if (E) E else E`
</code></pre>
<p>how should we parse <em><code>if (a) if (b) c else d</code></em>? To associate the
<code>else</code> with the inner <code>if</code>, we must delay the reduction by the first
rule in favor of the second. Eliminating such ambiguities by
rewriting the grammar can be non-trivial. However, these kinds of
ambiguities can also be eliminated by augmenting the ambiguous grammar with
operator precedence and associativity declarations. These are
evident from declarations such as <strong><code>left * 500</code></strong>. In addition to
giving precedence to symbols, however, each production rule of the grammar
must also be assigned a precedence. This can usually be calculated
automatically by finding the symbol on the right-hand side with the highest
precedence. However, there are cases when we must assign the precedence
manually, as in the rule <code>E(600) --> - E</code>. The - symbol has higher precedence
when it appears as a unary operator compared to all binary operators.</p>
<p>One might argue that the theoretically correct approach is to write unambiguous
grammars. But that approach entails a steep learning curve and even
seasoned grammar hackers may find it difficult to always write conflict-free
grammars. As well shall see in Chapter 4, using simpler, ambiguous grammars
has another important advantage in that it allows us to generate reasonable
abstract syntax representations from the grammar automatically.</p>
<p>The main purpose of a parser is to transform <em>concrete syntax</em>, which
is usually a string, into <em>abstract syntax</em>, which is usually a tree.
Parsing is only one of the first stages in a modern interpreter or
compiler. Many important tasks such as type checking can be carried
out in other stages. Errors can be syntactic - meaning that the
syntax is not accepted by the grammar, or semantic, such as type
incompatibilities. Usually only syntactic errors are reported by the
parser. However, all error reports made by the interpreter/compiler
must indicate the location in the orignal text (line and column
numbers) where the error is traced to. This implies that the parser
must insert this location information into the abstract syntax tree.
All data structures designed for the abstract syntax must accommodate
this information. In an object oriented programming language, this
can be easily done by defining an abstract superclass for all such
structures. But Rust has only minimal support for OOP. It has no
direct support for inheritance. Instead, rustlr implements a mechanism
called <strong><a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a></strong>.</p>
<p>Trees are defined recursively - in Rust, this usually means using the
Box smart pointer.
An <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a> encapsulates a Box along with a pair of u32 values
indicating a line and a column number (thus taking up only 64 bits of
extra space). It implements Deref and DerefMut by redirecting the
dereferences to the encapsulated box. This means that an LBox can be
used like a Box - except when we need to access the location
information.</p>
<p>It is recommended (but not required) that the enums and
structs making up the abstract syntax use <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a>, e.g.</p>
<p><code>enum Expr { Plus(LBox<Expr>,LBox<Expr>), Times(LBox<Expr>,LBox<expr>), etc.. }</code></p>
<p>Rustlr has features that facilitate the use of LBox. For example, on the
right-hand side of a production rule a labeled symbol in form <code>E:[a]</code> means
that the semantic value associated with the symbol is automatically
placed in an LBox that also includes the lexical
location information, and this LBox is assigned to <code>a</code>.
A similar mechanism for Rc, <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LRc.html">LRc</a>, also exists, but without the same
level of support.</p>
<p>In the following we further detail the additional features of rustlr
demonstrated by this grammar and associated abstract syntax structures.</p>
<h3 id="principal-features">Principal Features</h3>
<p>The grammar shown above differs from the <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/chapter1.html">first</a> chapter in the following principal ways.</p>
<ol>
<li>
<p>The grammar is ambiguous. There are <em>shift-reduce</em> conflicts from
the pure grammar that are resolved using operator precedence and
associativity rules as declared by grammar directives such as <strong><code>left * 500</code></strong>.
A terminal symbol that's to be used as an operator can be
declared as left or right associative and a positive integer defines
the precedence level.<br>
If a production rule is not explicitly assigned a precedence,
it is assigned to be the same as that of the right-hand side
symbol with the highest precedence.
The default precedence of all grammar symbols is zero.
<em>(Internally, the precedence is represented by the absolute value of a signed integer: positive
for left-associative, negative for right-associative, and zero means
unassigned.)</em></p>
<p>Rustlr resolves <strong>shift-reduce</strong> conflicts as follows:</p>
<ul>
<li>A lookahead symbol with strictly higher precedence than the rule results
in <em>shift</em>. A warning is always given if the rule has precedence zero.</li>
<li>A lookahead symbol with strictly lower precedence than the rule results
in <em>reduce</em>. A warning is always given if the lookahead has precedence zero (undeclared precedence)</li>
<li>A lookahead symbol with the same precedence and associativity as the rule,
and which is declared right-associative, will result in <em>shift</em>.</li>
<li>A lookahead symbol with the same precedence and associativity as the rule,
and which is declared left-associative, will result in <em>reduce</em>.</li>
<li>In other situations the conflict is <em>resolved in favor of shift</em>, with a
warning sent to stdout regardless of trace level. All shift-reduce
conflicts are warned at trace level 2 or higher.</li>
</ul>
<p>Had we left out the last declaration <code>left = 200</code>, for example, rustlr
will give multiple shift-reduce warnings, although the generated parser
would be the same.</p>
<p>Using this scheme, the "dangling else" problem can be solved by giving
"else" a higher precedence than "if".</p>
<p>Rustlr also resolves <strong>reduce-reduce</strong>
conflicts by always favoring the rule that appears first in the
grammar, although a warning is always sent to stdout regardless of trace
level.</p>
</li>
<li>
<p>The language that the grammar defines includes expressions of the form
<strong><code>let x = 1 in (let x = 10 in x*x) + x</code></strong>, which should evaluate to 101.
The lexical analyzer and parser must recognize alphanumeric symbols
such as <code>x</code> as variables. Since version 0.2.0, rustlr no longer requires
owned strings to represent such constructs: the new <a href="https://docs.rs/rustlr/latest/rustlr/lexer_interface/trait.Tokenizer.html">Tokenizer</a> trait
and <a href="https://docs.rs/rustlr/latest/rustlr/lexer_interface/struct.TerminalToken.html">TerminalToken</a> type allow the construction of zero-copy lexers.
The <strong><code>lifetime</code></strong> declaration in the grammar allows the use of constructs
with non-static references (<code>'src_lt str</code>) in abstract syntax representations. Currently, only a single lifetime declaration is allowed: this is usually
referring to the lifetime of the input. If it becomes clear that more than
one lifetime might be needed, rustlr will be updated accordingly.
Evaluating let-expressions also illustrate the separation of syntactic from semantic
analysis: checking the scopes of variables introduced by <code>let</code> happens after the
parsing stage.</p>
</li>
<li>
<p>The grammar's abstract syntax is defined in a separate module,
<a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/src/exprtrees.rs">exprtrees.rs</a>. The abstract syntax tree type ('absyntype') 'Expr' of this module
uses <strong><a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a></strong>,
as explained above. LBox implements deref coercion on the boxed value, but also
carries the lexical position information when they're needed. The
<a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html#method.lbox">StackedItem::lbox</a>, <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.ZCParser.html#method.lb">ZCParser.lb</a> and the <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.ZCParser.html#method.lbx">ZCParser.lbx</a> functions can be
invoked from within the semantic actions to automatically transfer the
parser's lexical information while creating an LBox. However, the easiest way to use LBox, in most situation, is to label a grammar symbol as in <strong><code>E:[a]</code></strong>: this means that in the semantic action of the rule <strong><code>a</code></strong> will be bound to an LBox enclosing the semantic value associated with the grammar symbol. It is
recommended that <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a> (or <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LRc.html">LRc</a>) be used instead of Box (Rc) when
defining the recursive enums and structs that typically form the
abstract syntax representation. This allows accurate error reporting
after the parse tree is built, as in the division-by-zero example
shown below.</p>
</li>
<li>
<p>The language allows a sequence of arithmetic expressions to be evaluated
in turn by separating them with semicolons, such as in <code>2+3; 4-1;</code>.
The semicolon also allows us
to define a simple error-recovery point: <strong><code>resync ;</code></strong> indicates that when a
parser error is encountered, the parser will skip past the next semicolon,
then look down its parse stack for a state with which it can continue parsing.
In otherwords, failure to parse one expression does not mean it will not try to
parse the next ones. Rustlr does implement other error-recovery techniques, which are explored in a <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/cpmz.grammar">later chapter</a>.</p>
</li>
<li>
<p>The labels attached to grammar symbols on the right-hand side of
grammar productions can be more than a simple variable or irrefutable pattern
(as demonstrated in the first calculator). It can also be a pattern
enclosed in @...@. Rustlr generates an if-let expression that attempts to
bind the pattern to what's popped from the parse stack. The value is
moved to a mut variable before being deconstructed by the pattern.
In general, the label associated with a right-hand side grammar symbol can
be of the following forms (two were used in the first grammar):</p>
<ol>
<li>
<p><strong><code>E:a + E:b</code></strong>: this is found in the first grammar, each symbol 'a', 'b'
is a mutable Rust variable that's assigned to the <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html">StackedItem</a>
popped from the parse stack, which includes .value, .line and .column.</p>
</li>
<li>
<p><strong><code>E:(a,b)</code></strong>: The label can also be a simple, irrefutable pattern
enclosed in parentheses, which are required even if the pattern is a single
variable. Furthermore, (currently) no whitespaces are allowed in the pattern.
The pattern is bound directly to the .value of the StackedItem popped from
the stack. One can recover the line/column information in several
ways: it is recommended to use <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a> using
the <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.ZCParser.html#method.lbx">ZCParser::lbx</a> or the <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html#method.lbox">StackedItem::lbox</a> functions, or a
labeled pattern such as <code>E:[a]</code>.
The <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html#method.lbox">StackedItem::lbox</a> function transforms a <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html">StackedItem</a>
into an LBox.
The <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.ZCParser.html#method.lbx">ZCParser::lbx</a> function takes an index and an expression and produces an LBox. The index indicates the position, starting
from zero, of the grammar
symbol on the right-hand side of the production that the value is
associated with. For example, the rule for <code>E --> E + E</code> can also be
written as</p>
<p><code>E --> E:(a) + E:(b) { Plus(parser.lbx(0,a), parser.lbx(2,b)) }</code></p>
</li>
<li>
<p><strong><code>E:[a]</code></strong>: If an alphanumeric label is enclosed in square brackets,
then the <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html">StackedItem</a> is automatically converted into an <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a>
encapsulating the value and the lexical position. This form is most
convenient in the majority of cases if the abstract syntax uses LBox
in its recursive definitions. The labels are already LBoxes:</p>
<p><code>E --> E:[a] + E:[b] { Plus(a,b) }</code></p>
</li>
<li>
<p><strong><code>E:@Seq(mut v)@</code></strong>: as seen in this grammar. This pattern is if-let
bound to the <strong>.value</strong> popped from the stack as a mutable variable (the .value is moved to the pattern). The
specified semantic action is injected into the body of if-let. A parser
error report is generated if the pattern fails to match, in which
case the default value of the abstract syntax type is returned.
To be precise, the semantic action function generated for the last rule of the
grammar is</p>
<pre><code>|parser|{ let mut _item2<span class="hljs-number">_</span> = parser.popstack();
let mut e = parser.popstack(); let mut _item0<span class="hljs-number">_</span> = parser.popstack();
<span class="hljs-keyword">if</span> let (Se<span class="hljs-string">q(mut v)</span>,)=(_item0<span class="hljs-number">_</span>.value,) {
v.push(e.lbox());
Se<span class="hljs-string">q(v)</span>
} <span class="hljs-keyword">else</span> {parser.bad_pattern(<span class="hljs-string">"(Seq(mut v),)"</span>)} }
</code></pre>
<p>Rustlr generates a variable of the form <code>_item{n}_</code> to hold the
value of the <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html">StackedItem</a>, if no direct label is specified.
Notice that <code>_item0_.value</code> is <em>moved</em> into the pattern so generally
it cannot be referenced again.</p>
</li>
<li>
<p><strong><code>E:es@Seq(v)@</code></strong> The pattern can be named. 'es' will be a mut variable
assigned to the StackedItem popped from the stack and an if-let is
generated that attempts to match the pattern to <strong><code>&mut es</code></strong>.
The named label can also be in the form <strong><code>[es]</code></strong>, which will transform
the StakedItem into an LBox assigned to es: in this case, the pattern is bound to
<strong><code>&mut *es</code></strong>.</p>
</li>
</ol>
<p>For example, the last production rule of this grammar is equivalent to:</p>
<pre><code>ES --> ES:es@<span class="hljs-built_in">Seq</span>(v)@ E:e ; {
v<span class="hljs-selector-class">.push</span>(parser<span class="hljs-selector-class">.lbx</span>(<span class="hljs-number">1</span>,e<span class="hljs-selector-class">.value</span>));
es<span class="hljs-selector-class">.value</span>
}
</code></pre>
<p>In contrast to a non-named pattern, the value is <strong>not</strong> moved into the
pattern, which means we can still refer to it as <code>es.value</code>. The call
to <a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.ZCParser.html#method.lbx">parser.lbx</a> requires an index, starting from 0, of the grammar symbol
on the right-hand side of the production along with a value and forms
an LBox with starting line/column information. In this case, it is
equivalent to <code>v.push(e.lbox())</code>: the .lbox function converts the
<a href="https://docs.rs/rustlr/latest/rustlr/zc_parser/struct.StackedItem.html">StackedItem</a> to an <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a>. But calling .lbox is only possible because
this form of pattern does not move the .value out of the StackedItem.</p>
</li>
</ol>
<h4 id="the-abstract-syntax-type-expr">The Abstract Syntax Type <strong>Expr</strong></h4>
<p>To see how <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a> can be used after the parsing stage, let's take a close look at the definition of the abstract syntax type:</p>
<pre><code class="language-ignore">pub <span class="hljs-class"><span class="hljs-keyword">enum</span> <span class="hljs-title">Expr</span><'<span class="hljs-title">t</span>>
</span>{
<span class="hljs-type">Var</span>(<span class="hljs-operator">&</span>'t str),
<span class="hljs-type">Val</span>(i64),
<span class="hljs-type">Plus</span>(<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>,<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>), <span class="hljs-comment">// LBox replaces Box for recursive defs</span>
<span class="hljs-type">Times</span>(<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>,<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>),
<span class="hljs-type">Divide</span>(<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>,<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>),
<span class="hljs-type">Minus</span>(<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>,<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>),
<span class="hljs-type">Negative</span>(<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>),
<span class="hljs-type">Letexp</span>(<span class="hljs-operator">&</span>'t str,<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>,<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>), <span class="hljs-comment">// let x=Expr in Expr</span>
<span class="hljs-type">Seq</span>(<span class="hljs-type">Vec</span><<span class="hljs-type">LBox</span><<span class="hljs-type">Expr</span><'t>>>),
<span class="hljs-type">Nothing</span>,
}
</code></pre>
<p>The variant <code>Nothing</code> allows us to define a default, which is required for
any 'absyntype' of the grammar:</p>
<pre><code><span class="hljs-keyword">impl</span> <span class="hljs-built_in">Default</span> <span class="hljs-keyword">for</span> Expr<<span class="hljs-symbol">'_</span>> {
<span class="hljs-function"><span class="hljs-keyword">fn</span> <span class="hljs-title">default</span></span>() -> <span class="hljs-keyword">Self</span> { Nothing }
}<span class="hljs-comment">//impl Default</span>
</code></pre>
<p>Unlike in the first example, here evaluation is defined after the parsing stage,
when the abstract syntax tree is available as a complete structure. 'Let'-expressions, which introduce variables to the language, can only be
evaluated given a set of bindings for the variables. This "environment"
structure is defined below:</p>
<pre><code><span class="hljs-keyword">pub</span> <span class="hljs-class"><span class="hljs-keyword">enum</span> <span class="hljs-title">Env</span></span><<span class="hljs-symbol">'t</span>> {
Nil,
Cons(&<span class="hljs-symbol">'t</span> <span class="hljs-built_in">str</span>, <span class="hljs-built_in">i64</span>, Rc<Env<<span class="hljs-symbol">'t</span>>>)
}
<span class="hljs-function"><span class="hljs-keyword">fn</span> <span class="hljs-title">push</span></span><<span class="hljs-symbol">'t</span>>(var:&<span class="hljs-symbol">'t</span> <span class="hljs-built_in">str</span>, val:<span class="hljs-built_in">i64</span>, env:&Rc<Env<<span class="hljs-symbol">'t</span>>>) -> Rc<Env<<span class="hljs-symbol">'t</span>>>
{ Rc::new(Cons(var,val,Rc::clone(env))) }
<span class="hljs-function"><span class="hljs-keyword">fn</span> <span class="hljs-title">lookup</span></span><<span class="hljs-symbol">'t</span>>(x:&<span class="hljs-symbol">'t</span> <span class="hljs-built_in">str</span>, env:&Rc<Env<<span class="hljs-symbol">'t</span>>>) -> <span class="hljs-built_in">Option</span><<span class="hljs-built_in">i64</span>> {
<span class="hljs-keyword">let</span> <span class="hljs-keyword">mut</span> current = env;
<span class="hljs-keyword">while</span> <span class="hljs-keyword">let</span> Cons(y,v,e) = &**current {
<span class="hljs-keyword">if</span> &x==y {<span class="hljs-keyword">return</span> <span class="hljs-literal">Some</span>(*v);}
<span class="hljs-keyword">else</span> {current = e;}
}
<span class="hljs-keyword">return</span> <span class="hljs-literal">None</span>;
}<span class="hljs-comment">//lookup</span>
</code></pre>
<p>Since this tutorial is about the parser generation stage and not so much about
later stages of interpretation/compilation, I will not go into too
much detail as to how such a data structure is needed. It defines a non-mutable
linked list, with a constructive <code>cons</code>, that we use to emulate
lexical scoping. The Env enum also allows lists to share components
(different 'car', same 'cdr'). The <code>lookup</code> function looks up the value
bound to a variable in an enviornment.</p>
<p>The evaluation function is given below. Sequences of expressions
(under the <code>Seq</code> variant) are evaluated one after the other with their
results printed, and the value of the last expression of the sequence is
returned.
Note that <a href="https://docs.rs/rustlr/latest/rustlr/generic_absyn/struct.LBox.html">LBox</a> is used in the same way as a Box in most of the cases except for
Division. Here we access the line and column numbers enclosed inside the LBox to print
an error message when division-by-zero is detected.</p>
<pre><code><span class="hljs-keyword">pub</span> <span class="hljs-function"><span class="hljs-keyword">fn</span> <span class="hljs-title">eval</span></span><<span class="hljs-symbol">'t</span>>(env:&Rc<Env<<span class="hljs-symbol">'t</span>>>, exp:&Expr<<span class="hljs-symbol">'t</span>>) -> <span class="hljs-built_in">Option</span><<span class="hljs-built_in">i64</span>> {
<span class="hljs-keyword">match</span> exp {
Var(x) => {
<span class="hljs-keyword">if</span> <span class="hljs-keyword">let</span> <span class="hljs-literal">Some</span>(v) = lookup(x,env) {<span class="hljs-literal">Some</span>(v)}
<span class="hljs-keyword">else</span> { eprint!(<span class="hljs-string">"UNBOUND VARIABLE {} ... "</span>,x); <span class="hljs-literal">None</span>}
},
Val(x) => <span class="hljs-literal">Some</span>(*x),
Plus(x,y) => eval(env,x).map(|a|{eval(env,y).map(|b|{a+b})}).flatten(),
Times(x,y) => eval(env,x).map(|a|{eval(env,y).map(|b|{a*b})}).flatten(),
Minus(x,y) => eval(env,x).map(|a|{eval(env,y).map(|b|{a-b})}).flatten(),
Negative(x) => eval(env,x).map(|a|{-<span class="hljs-number">1</span>*a}), <span class="hljs-comment">//no need for bind here </span>
Divide(x,y) => {
eval(env,y)
.map(|yval|{<span class="hljs-keyword">if</span> yval==<span class="hljs-number">0</span> {
eprint!(<span class="hljs-string">"Division by zero (expression starting at column {}) on line {} of {:?} at column {} ... "</span>,y.column(),y.line(),x,x.column());
<span class="hljs-literal">None</span>
} <span class="hljs-keyword">else</span> {eval(env,x).map(|xval|{<span class="hljs-literal">Some</span>(xval/yval)})}
})
.flatten().flatten()
},
Letexp(x,e,b) => {
eval(env,e).map(|ve|{
<span class="hljs-keyword">let</span> newenv = push(x,ve,env);
eval(&newenv,b) }).flatten()
}
Seq(V) => {
<span class="hljs-keyword">let</span> <span class="hljs-keyword">mut</span> ev = <span class="hljs-literal">None</span>;
<span class="hljs-keyword">for</span> x <span class="hljs-keyword">in</span> V
{
ev = eval(env,x);
<span class="hljs-keyword">if</span> <span class="hljs-keyword">let</span> <span class="hljs-literal">Some</span>(val) = ev {
<span class="hljs-built_in">println!</span>(<span class="hljs-string">"result for line {}: {} ;"</span>,x.line(),&val);
} <span class="hljs-keyword">else</span> { eprintln!(<span class="hljs-string">"Error evaluating line {};"</span>,x.line()); }
}<span class="hljs-comment">//for</span>
ev
},
Nothing => <span class="hljs-literal">None</span>,
}<span class="hljs-comment">//match</span>
}<span class="hljs-comment">//eval</span>
</code></pre>
<p>For those not familiar with the monadic functors (map and flatten),
the clause for <code>Plus</code>, for example, is equivalent to</p>
<p><code>if let Some(a)=eval(env,x) { if let Some(b)= eval(env,y) {Some(a+b)} else {None} } else {None}</code>.</p>
<br>
<h4 id="lexical-scanner-and-main"><strong>Lexical scanner and main</strong></h4>
<p>The directives <strong>lexvalue</strong>, <strong>lexname</strong> and <strong>lexattribute</strong> are used to
configure an automatically generated lexical tokenizer.
'lexvalue' should be used
for all terminal symbols that carry (non-default) semantic values, such as
numerical constants and string literals. The two <strong>lexvalue</strong> directives
state that "int" terminal symbols (<a href="https://docs.rs/rustlr/latest/rustlr/lexer_interface/struct.TerminalToken.html">TerminalTokens</a>) are created
from RawToken::Num(n) and carray semantic values Val(n), while
"var" terminals carry values Var(x) and are formed from RawToken::Alphanum(x).
The generated lexer will distinguish alphanumeric tokens that correspond
to other declared terminal symbols of the grammar such as "let".
All other "Alphanums" will be parsed as "var".</p>
<p>The <a href="https://docs.rs/rustlr/latest/rustlr/lexer_interface/enum.RawToken.html">RawToken</a> enum defines n to be an i64 and x to be a &str.
Generally speaking, for each value-carrying terminal symbol of the grammar,
write a similar <em>lexvalue</em> declaration by identifying the type of RawToken
that it corresponds to and how to construct the semantic value from the token.</p>
<p>Please note that
whitespaces are only allowed in the specification of the semantic value (in the
future we may rewrite rustlr inside rustlr, but this is not a priority as the
hand-coded grammar parser suffices for most cases if used a little carefully).</p>
<p>Since no reserved symbols such as "|" or "{" are used in this language, the
<strong>lexname</strong> directive is not used. These reserved symbols cannot be used
as terminal symbols. One must choose names such as VBAR and write
<code>lexname VBAR |</code> to define the correspondence between the grammar symbol
and its textual form.</p>
<p>The <strong>lexattribute</strong> directive can be used to set any attribute on the
lexer to be generated. Consult the docs for <a href="https://docs.rs/rustlr/latest/rustlr/lexer_interface/struct.StrTokenizer.html">StrTokenizer</a>.
The following samples are valid lexattribute declarations</p>
<blockquote>
<pre><code> lexattribute keep_newline = true
lexattribute keep_comment = true
lexattribute keep_whitespace = true
lexattribute set_multiline_comments("/* */")
lexattribute set_line_comment("")
</code></pre>
</blockquote>
<p>Setting the line_comment or multiline_comments to the empty string will mean
that such comments are not recognized. The keep_flags are all false be
default. <a href="https://docs.rs/rustlr/latest/rustlr/lexer_interface/struct.StrTokenizer.html">StrTokenizer</a> recognizes C-style comments by default.</p>
<p>The presence of these directives automatically enables the -genlex option.
The lexer created is called calc4lexer and is found in with the generated
parser. Use the <strong>calc4lexer::from_str</strong> and <strong>calc4lexer::from_source</strong>
functions to create instances of this zero-copy lexical scanner (consult
<a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/src/main.rs">main.rs</a>
for example).</p>
<p>Generate the parser with</p>
<blockquote>
<p>rustlr calc4.grammar -trace 3 > calculator.states</p>
</blockquote>
<p>This creates a file <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/src/calc4parser.rs">calc4parser.rs</a>, although each time it's generated
the state numbers may be different: the -trace 3 option prints these states
to stdout.
Create a cargo crate with the following dependency in Cargo.toml:</p>
<pre><code><span class="hljs-attr">rustlr</span> = <span class="hljs-string">"0.3"</span>
</code></pre>
<p>copy the <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/src/main.rs">main.rs</a>, <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/src/exprtrees.rs">exprtrees.rs</a> and the generated <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/src/calc4parser.rs">calc4parser.rs</a> files into src/. The supplied main parses and evaluates the following input:</p>
<pre><code><span class="hljs-number">-5</span>-(<span class="hljs-number">4</span><span class="hljs-number">-2</span>)*<span class="hljs-number">5</span>;
<span class="hljs-meta">#3(1+2); # syntax (parsing) <span class="hljs-meta-keyword">error</span></span>
<span class="hljs-meta">#5%2; # syntax <span class="hljs-meta-keyword">error</span> (% is not defined by grammar)</span>
<span class="hljs-number">5</span><span class="hljs-number">-7</span>- <span class="hljs-number">-9</span> ;
<span class="hljs-number">4</span>*<span class="hljs-number">3</span><span class="hljs-number">-9</span>;
<span class="hljs-number">2</span>+<span class="hljs-number">1</span>/(<span class="hljs-number">2</span><span class="hljs-number">-1</span><span class="hljs-number">-1</span>); <span class="hljs-meta"># division by 0 (semantic) <span class="hljs-meta-keyword">error</span></span>
<span class="hljs-keyword">let</span> x = <span class="hljs-number">10</span> <span class="hljs-keyword">in</span> <span class="hljs-number">2</span>+x;
<span class="hljs-keyword">let</span> x = <span class="hljs-number">1</span> <span class="hljs-keyword">in</span> (x+ (<span class="hljs-keyword">let</span> x=<span class="hljs-number">10</span> <span class="hljs-keyword">in</span> x+x) + x);
(<span class="hljs-keyword">let</span> x = <span class="hljs-number">2</span> <span class="hljs-keyword">in</span> x+x) + x; <span class="hljs-meta"># unbound variable (semantic) <span class="hljs-meta-keyword">error</span></span>
(<span class="hljs-keyword">let</span> x = <span class="hljs-number">4</span> <span class="hljs-keyword">in</span> x/<span class="hljs-number">2</span>) + (<span class="hljs-keyword">let</span> x=<span class="hljs-number">10</span> <span class="hljs-keyword">in</span> x*(<span class="hljs-keyword">let</span> y=<span class="hljs-number">100</span> <span class="hljs-keyword">in</span> y/x));
</code></pre>
<p><strong>cargo run</strong> produces the following output:</p>
<pre><code>Expression tree <span class="hljs-selector-tag">from</span> parse: <span class="hljs-built_in">Seq</span>([<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Negative</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">5</span>)), <span class="hljs-built_in">Times</span>(<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">4</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>)), Val
(<span class="hljs-number">5</span>))), <span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">5</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">7</span>)), <span class="hljs-built_in">Negative</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">9</span>))), <span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Times</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">4</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">3</span>)), <span class="hljs-built_in">Val</span>(<span class="hljs-number">9</span>
)), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Divide</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>), <span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>)), <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>)))), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>
<span class="hljs-number">0</span>), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>))), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">10</span>),
<span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>)))), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>))), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>)
)), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>)), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">4</span>), <span class="hljs-built_in">Divide</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>))), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">10</span>), T
<span class="hljs-built_in">imes</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"y"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">100</span>), <span class="hljs-built_in">Divide</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"y"</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>))))))])
---------------------------------------
result for line <span class="hljs-number">1</span>: -<span class="hljs-number">15</span> ;
result for line <span class="hljs-number">4</span>: <span class="hljs-number">7</span> ;
result for line <span class="hljs-number">5</span>: <span class="hljs-number">3</span> ;
Division by zero (expression starting at column <span class="hljs-number">5</span>) on line <span class="hljs-number">6</span> of Val(<span class="hljs-number">1</span>) at column <span class="hljs-number">3</span> ... Error evaluating line <span class="hljs-number">6</span>;
result for line <span class="hljs-number">7</span>: <span class="hljs-number">12</span> ;
result for line <span class="hljs-number">8</span>: <span class="hljs-number">22</span> ;
UNBOUND VARIABLE x ... Error evaluating line <span class="hljs-number">9</span>;
result for line <span class="hljs-number">10</span>: <span class="hljs-number">102</span> ;
Final result after evaluation: <span class="hljs-built_in">Some</span>(<span class="hljs-number">102</span>)
</code></pre>
<p>This chapter is followed by an <strong><a href="https://cs.hofstra.edu/~cscccl/rustlr_project/minijava/mj.grammar">addendum</a></strong>, which contains a larger example with further
illustration of the techniques explained here.</p>
<hr>
<h3 id="training-the-parser-for-better-error-reporting">Training The Parser For Better Error Reporting</h3>
<p>It is recommended that, when a parser is generated, the -trace 3 option is
given, which will print all the LR states that are created. This may be helpful
when training the parser. Each time the parser is regenerated the states may
have different numbers identifying them, even if the grammar is unchanged.</p>
<p>With a newly generated parser, when a parser error is encountered, the
line and column numbers are printed and an "unexpected symbol" error
message is given. To print more helpful error messages, the parser can
be trained interactively. Interactive training also produces a script
for future, automatic retraining when a new parser is generated.</p>
<p>Modify <a href="https://cs.hofstra.edu/~cscccl/rustlr_project/calc4/src/main.rs">main.rs</a> by uncommenting lines 2 and 3 in the input:</p>
<pre><code><span class="hljs-number">3</span>(<span class="hljs-number">1</span>+<span class="hljs-number">2</span>) <span class="hljs-meta"># syntax (parsing) <span class="hljs-meta-keyword">error</span></span>
<span class="hljs-number">5</span>%<span class="hljs-number">2</span>; <span class="hljs-meta"># syntax <span class="hljs-meta-keyword">error</span></span>
</code></pre>
<p>Note that the supplied main already calls <code>parse_train(&mut scanner2,"calc4parser.rs");</code> For input with no errors, this call works the same way as <code>parse(&mut scanner2);</code> The <a href="https://docs.rs/rustlr/latest/rustlr/runtime_parser/struct.RuntimeParser.html#method.parse_stdio_train">parse_train</a> function takes a path to a copy of the parser being trained (it's not recommended to change the copy that
you're using this way).
Cargo run will lead to the following (possible) training session, depending on
user input:</p>
<pre><code>PARSER ERROR: unexpected symbol ( on line <span class="hljs-number">2</span>, column <span class="hljs-number">2</span> ..
>>>TRAINER: if this message is not adequate (for state <span class="hljs-number">1</span>), enter a replacement (default n
o change): missing an operator symbol such as *
>>>TRAINER: should this message be given for all unexpected symbols in the current state?
(default yes) no
PARSER ERROR: unexpected symbol % on line <span class="hljs-number">3</span>, column <span class="hljs-number">2</span> ..
>>>TRAINER: if this message is not adequate (for state <span class="hljs-number">1</span>), enter a replacement (default n
o change): this symbol is not recognized as a valid operator in this language
Expression tree from parse: <span class="hljs-built_in">Seq</span>([<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Negative</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">5</span>)), <span class="hljs-built_in">Times</span>(<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">4</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>)), Val
(<span class="hljs-number">5</span>))), <span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">5</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">7</span>)), <span class="hljs-built_in">Negative</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">9</span>))), <span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Times</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">4</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">3</span>)), <span class="hljs-built_in">Val</span>(<span class="hljs-number">9</span>
)), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Divide</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>), <span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Minus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>)), <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>)))), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>
<span class="hljs-number">0</span>), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>))), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">1</span>), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">10</span>),
<span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>)))), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>))), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>)
)), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>)), <span class="hljs-built_in">Plus</span>(<span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">4</span>), <span class="hljs-built_in">Divide</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Val</span>(<span class="hljs-number">2</span>))), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"x"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">10</span>), T
<span class="hljs-built_in">imes</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>), <span class="hljs-built_in">Letexp</span>(<span class="hljs-string">"y"</span>, <span class="hljs-built_in">Val</span>(<span class="hljs-number">100</span>), <span class="hljs-built_in">Divide</span>(<span class="hljs-built_in">Var</span>(<span class="hljs-string">"y"</span>), <span class="hljs-built_in">Var</span>(<span class="hljs-string">"x"</span>))))))])
---------------------------------------
result for line <span class="hljs-number">1</span>: -<span class="hljs-number">15</span> ;
result for line <span class="hljs-number">4</span>: <span class="hljs-number">7</span> ;
result for line <span class="hljs-number">5</span>: <span class="hljs-number">3</span> ;
Division by zero (expression starting at column <span class="hljs-number">5</span>) on line <span class="hljs-number">6</span> of Val(<span class="hljs-number">1</span>) at column <span class="hljs-number">3</span> ... Er
ror evaluating line <span class="hljs-number">6</span>;
result for line <span class="hljs-number">7</span>: <span class="hljs-number">12</span> ;
result for line <span class="hljs-number">8</span>: <span class="hljs-number">22</span> ;
UNBOUND VARIABLE x ... Error evaluating line <span class="hljs-number">9</span>;
result for line <span class="hljs-number">10</span>: <span class="hljs-number">102</span> ;
Parser error, best effort after recovery: <span class="hljs-built_in">Some</span>(<span class="hljs-number">102</span>)
</code></pre>
<p>Notice that error recovery was effective and the parser still produced a usable
parse tree: however, the parser's error_occurred flag will be set. It is
under consideration as to whether future editions of Rustlr will also allow the
error-recovery strategy to be trainable in the same way. For now, only a fixed
number of strategies are available. In the opinion of the author, the resync
technique is the simplest and most effective.</p>
<p>If the augmented parser is used on the same input, it will display the trained
message in addition to "unexpected symbol..."</p>
<p>You can see how training augments the LR state transition table by
examining the <code>load_extras</code> function at the end of the generated parser:</p>
<pre><code><span class="hljs-selector-tag">fn</span> <span class="hljs-selector-tag">load_extras</span>(<span class="hljs-attribute">parser</span>:&mut RuntimeParser<Expr,Expr>)
{
<span class="hljs-selector-tag">parser</span><span class="hljs-selector-class">.RSM</span><span class="hljs-selector-attr">[1]</span><span class="hljs-selector-class">.insert</span>(<span class="hljs-string">"("</span>,<span class="hljs-attribute">Stateaction</span>::Error(<span class="hljs-string">"missing an operator symbol such as *"</span>));
<span class="hljs-selector-tag">parser</span><span class="hljs-selector-class">.RSM</span><span class="hljs-selector-attr">[1]</span><span class="hljs-selector-class">.insert</span>(<span class="hljs-string">"ANY_ERROR"</span>,<span class="hljs-attribute">Stateaction</span>::Error("this symbol is <span class="hljs-keyword">not</span> recognized as a
valid operator in this language"));
}<span class="hljs-comment">//end of load_extras: don't change this line as it affects augmentation</span>
</code></pre>
<p>When the "unexpected symbol" is recognized as a declared symbol of the grammar, the trainer will be given the option of entering the error message for either
just that symbol, or all unexpected symbols in the same state. If the latter is
chosen then an entry is created for the reserved <code>ANY_ERROR</code> symbol. If the
unexpected symbol is not recognized as a terminal symbol of the grammar, an
<code>ANY_ERROR</code> entry is always created. You can see the contents of "state 1"
if you created it with the -trace 3 option. You will of course have to understand the LR parsing algorithm to make use of the information.</p>
<p>When the modified parser runs and encounters another unexpected symbol in the
same state, it will first see if there is an entry for that symbol; if none
exists, it will look for an <code>ANY_ERROR</code> entry for a message to display.
Thus the two entries do not conflict with eachother.</p>
<p>The interactive session also generated a script file, which would be called
<em>"calc4parser.rs_script.txt"</em>, with the following contents:</p>
<pre><code># Rustlr training script <span class="hljs-keyword">for</span> calc4parser.rs
<span class="hljs-number">2</span> <span class="hljs-number">2</span> ( ::: missing an <span class="hljs-keyword">operator</span> symbol such <span class="hljs-keyword">as</span> *
<span class="hljs-number">3</span> <span class="hljs-number">2</span> ANY_ERROR ::: <span class="hljs-keyword">this</span> symbol <span class="hljs-keyword">is</span> not recognized <span class="hljs-keyword">as</span> an <span class="hljs-keyword">operator</span> <span class="hljs-keyword">in</span> <span class="hljs-keyword">this</span> language
</code></pre>
<p>This script can be used to retrain a newly genenerated parser (with different state numbers) with the <a href="https://docs.rs/rustlr/latest/rustlr/runtime_parser/struct.RuntimeParser.html#method.train_from_script">train_from_script</a> function
provided the same input from the original training. The line and column numbers
of where the errors are expected are recorded in the script. Please note that
training from script has not yet been tested on a large scale.</p>
<hr>
</div></body></html>