From 845bee8f334e0aa2925383bd0cc6a28646549e0c Mon Sep 17 00:00:00 2001
From: Erez Shinan <erezshin+git@gmail.com>
Date: Thu, 9 Mar 2023 15:11:13 +0100
Subject: [PATCH] Docs: Added section about strict-mode to how-to-use

---
 docs/how_to_use.md | 45 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/docs/how_to_use.md b/docs/how_to_use.md
index e10be30e..85558ac4 100644
--- a/docs/how_to_use.md
+++ b/docs/how_to_use.md
@@ -74,9 +74,13 @@ Note 1: Interegular currently only runs when the lexer is `basic` or `contextual
 
 Note 2: Some advanced regex features, such as lookahead and lookbehind, may prevent interegular from detecting existing collisions.
 
-### LALR
+### Shift/Reduce collisions
 
-By default Lark silently resolves Shift/Reduce conflicts as Shift. To enable warnings pass `debug=True`. To get the messages printed you have to configure the `logger` beforehand. For example:
+By default Lark automatically resolves Shift/Reduce conflicts as Shift. It produces notifications as debug messages.
+
+when users pass `debug=True`, those notifications are written as warnings.
+
+Either way, to get the messages printed you have to configure the `logger` beforehand. For example:
 
 ```python
 import logging
@@ -90,6 +94,43 @@ as: a*
 a: "a"
 '''
 p = Lark(collision_grammar, parser='lalr', debug=True)
+# Shift/Reduce conflict for terminal A: (resolving as shift)
+#  * <as : >
+# Shift/Reduce conflict for terminal A: (resolving as shift)
+#  * <as : __as_star_0>
+```
+
+### Strict-Mode
+
+Lark, by default, accepts grammars with unresolved Shift/Reduce collisions (which it always resolves to shift), and regex collisions.
+
+Strict-mode allows users to validate that their grammars don't contain these collisions.
+
+When Lark is initialized with `strict=True`, it raises an exception on any Shift/Reduce or regex collision.
+
+If `interegular` isn't installed, an exception is thrown.
+
+When using strict-mode, users will be expected to resolve their collisions manually:
+
+- To resolve Shift/Reduce collisions, adjust the priority weights of the rules involved, until there are no more collisions.
+
+- To resolve regex collisions, change the involved regexes so that they can no longer both match the same input (Lark provides an example).
+
+Strict-mode only applies to LALR for now.
+
+```python
+from lark import Lark
+
+collision_grammar = '''
+start: as as
+as: a*
+a: "a"
+'''
+p = Lark(collision_grammar, parser='lalr', strict=True)
+
+# Traceback (most recent call last):
+#   ...
+# lark.exceptions.GrammarError: Shift/Reduce conflict for terminal A. [strict-mode]
 ```
 
 ## Tools