From 754bbf7a25a8dda49b5d08ef0d0443bbf5af0e36 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 7 Apr 2024 13:41:34 -0500
Subject: new repository

---
 devdocs/elisp/smie-grammar.html | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 devdocs/elisp/smie-grammar.html

(limited to 'devdocs/elisp/smie-grammar.html')

diff --git a/devdocs/elisp/smie-grammar.html b/devdocs/elisp/smie-grammar.html
new file mode 100644
index 00000000..f09ae782
--- /dev/null
+++ b/devdocs/elisp/smie-grammar.html
@@ -0,0 +1,34 @@
+ <h4 class="subsubsection">Defining the Grammar of a Language</h4>   <p>The usual way to define the SMIE grammar of a language is by defining a new global variable that holds the precedence table by giving a set of BNF rules. For example, the grammar definition for a small Pascal-like language could look like: </p>
+<div class="example"> <pre class="example">(require 'smie)
+(defvar sample-smie-grammar
+  (smie-prec2-&gt;grammar
+   (smie-bnf-&gt;prec2
+</pre>
+<pre class="example">    '((id)
+      (inst ("begin" insts "end")
+            ("if" exp "then" inst "else" inst)
+            (id ":=" exp)
+            (exp))
+      (insts (insts ";" insts) (inst))
+      (exp (exp "+" exp)
+           (exp "*" exp)
+           ("(" exps ")"))
+      (exps (exps "," exps) (exp)))
+</pre>
+<pre class="example">    '((assoc ";"))
+    '((assoc ","))
+    '((assoc "+") (assoc "*")))))
+</pre>
+</div> <p>A few things to note: </p> <ul> <li> The above grammar does not explicitly mention the syntax of function calls: SMIE will automatically allow any sequence of sexps, such as identifiers, balanced parentheses, or <code>begin ... end</code> blocks to appear anywhere anyway. </li>
+<li> The grammar category <code>id</code> has no right hand side: this does not mean that it can match only the empty string, since as mentioned any sequence of sexps can appear anywhere anyway. </li>
+<li> Because non terminals cannot appear consecutively in the BNF grammar, it is difficult to correctly handle tokens that act as terminators, so the above grammar treats <code>";"</code> as a statement <em>separator</em> instead, which SMIE can handle very well. </li>
+<li> Separators used in sequences (such as <code>","</code> and <code>";"</code> above) are best defined with BNF rules such as <code>(foo (foo "separator" foo) ...)</code> which generate precedence conflicts which are then resolved by giving them an explicit <code>(assoc "separator")</code>. </li>
+<li> The <code>("(" exps ")")</code> rule was not needed to pair up parens, since SMIE will pair up any characters that are marked as having paren syntax in the syntax table. What this rule does instead (together with the definition of <code>exps</code>) is to make it clear that <code>","</code> should not appear outside of parentheses. </li>
+<li> Rather than have a single <em>precs</em> table to resolve conflicts, it is preferable to have several tables, so as to let the BNF part of the grammar specify relative precedences where possible. </li>
+<li> Unless there is a very good reason to prefer <code>left</code> or <code>right</code>, it is usually preferable to mark operators as associative, using <code>assoc</code>. For that reason <code>"+"</code> and <code>"*"</code> are defined above as <code>assoc</code>, although the language defines them formally as left associative. </li>
+</ul><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/SMIE-Grammar.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/SMIE-Grammar.html</a>
+  </p>
+</div>
-- 
cgit v1.2.3