docs: updated

Author: cybercoder-naj

core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/LexerBuilder.kt

@@ -1,6 +1,7 @@
 package io.github.cybercodernaj.parkour.lexer
 
 import io.github.cybercodernaj.parkour.lexer.internal.Lexer
+import io.github.cybercodernaj.parkour.exceptions.LexicalException
 
 /**
  * A helper class to create the [Lexer].
@@ -68,7 +69,7 @@ class LexerBuilder internal constructor() {
   var multilineComments: Pair<Regex, Regex>? = Lexer.Defaults.multilineComments
 
   /**
-   * Supply the regex pattern that defines the rules for identifiers.
+   * The regex pattern that defines the rules for identifiers.
    * Identifiers are parts of the program that are named by the user;
    * for instance, the field name or class name.
    *
@@ -96,14 +97,59 @@ class LexerBuilder internal constructor() {
   private val _operators: MutableList<String> = mutableListOf()
   internal val operators: List<String> get() = _operators
 
-  internal var integerLiteral: Regex = Lexer.Defaults.integerLiteral
-    private set
+  /**
+   * The regex that detects and extracts integer literals from the string.
+   * This should usually only consider strict integers.
+   *
+   * ### Usage
+   *
+   * ```kt
+   * val myLexer = lexer {
+   *   integerLiteral = Regex("[+-]?[0-9_]+")
+   * }
+   * ```
+   *
+   * @see Lexer.Defaults.integerLiteral
+   * @author Nishant Aanjaney Jalan
+   * @since 0.2.0
+   */
+  var integerLiteral: Regex = Lexer.Defaults.integerLiteral
 
-  internal var floatingLiteral: Regex = Lexer.Defaults.floatingLiteral
-    private set
+  /**
+   * The regex that detects and extracts floating point literals from the string.
+   * This should usually only consider numbers that have a decimal point.
+   *
+   * ### Usage
+   *
+   * ```kt
+   * val myLexer = lexer {
+   *   floatingLiteral = Regex("[-+]?[0-9_]*\.[0-9_]+(?:[eE][-+]?[0-9_]+)?")
+   * }
+   * ```
+   *
+   * @see Lexer.Defaults.floatingLiteral
+   * @author Nishant Aanjaney Jalan
+   * @since 0.2.0
+   */
+  var floatingLiteral: Regex = Lexer.Defaults.floatingLiteral
 
-  internal var singleLineString: Set<String> = Lexer.Defaults.singleLineString
-    private set
+  /**
+   * The enclosing strings that should denote the start and end of single-line strings.
+   * The lexer will throw a [LexicalException] when a string literal is not terminated in the same line.
+   *
+   * ### Usage
+   *
+   * ```kt
+   * val myLexer = lexer {
+   *   floatingLiteral = Regex("[-+]?[0-9_]*\.[0-9_]+(?:[eE][-+]?[0-9_]+)?")
+   * }
+   * ```
+   *
+   * @see Lexer.Defaults.singleLineString
+   * @author Nishant Aanjaney Jalan
+   * @since 0.2.0
+   */
+  var singleLineString: Set<String> = Lexer.Defaults.singleLineString
 
   /**
    * Hard keywords are a characters and symbols that give a particular meaning to a program.

core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/docs.md

@@ -1,3 +1,23 @@
 # Package io.github.cybercodernaj.parkour.lexer
 
-Docs for the lexer
+The lexer is responsible to convert the given string into a stream of Tokens.
+
+The lexer takes in multiple settings via the `LexerBuilder` that configures how it behaves.
+It performs lexical analysis on a line-by-line basis and returns the next unconsumed token.
+A newline character **always** separates a token.
+
+## How to make a Lexer config
+
+You can build your customised Lexer with the `lexer` function.
+
+```kotlin
+fun main() {
+  val myLexer = lexer {
+     ignorePattern = Regex("""\s+""")
+     singleLineComments = Regex("//")
+     /* more configurations */
+  }
+}
+```
+
+Find all configuration options and in more detail in `LexerBuilder`. 

core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt

@@ -6,39 +6,7 @@ import io.github.cybercodernaj.parkour.lexer.LexerBuilder
 import io.github.cybercodernaj.parkour.utils.Position
 
 /**
- * The lexer is responsible to convert the given string into a stream of [Token]s.
- * The lexer take in multiple settings via the [LexerBuilder] that configures how it behaves.
- * It will perform lexical analysis on a line-by-line basis and return the next unconsumed token.
- * A newline character **always** separates a token unless it is a multiline comment.
- *
- * ### Literals
- *
- * There are only three types of literals the lexer manages.
- * 1. Integer literals are normally lexed with a pure stream of numbers with underscores.
- * 2. Floating literals are normally lexed with a forced decimal point with optional exponentiation.
- * 3. String literals are normally lexed exact strings till it finds the original match.
- *
- * Additionally, escape sequences are required to input special characters inside string literals.
- *
- * @constructor Creates a lexer with the provided properties.
- * @param ignorePattern characters that satisfy this regex would be skipped.
- * @param singleLineComments The regex that defines how a single-line comment starts.
- *    Once identified, the lexer will skip the remaining line. (Default: null)
- * @param multilineComments A pair of regexes, the starting pattern and the ending pattern for a
- *    multiline comment block. (Default: null)
- * @param identifiers A regex string that defines the rules for defining a name.
- * @param hardKeywords A set of strings that are considered hard keywords.
- *    Hard keywords are a characters and symbols that give a particular meaning to a program.
- *    They may not be used as identifiers. (Default: [])
- * @param operators A set of strings that are considered as operators.
- *    Operators are characters and symbols that may perform arithmetic or logical operations. (Default: [])
- * @param separators A set of strings that are considered as separators.
- *    Separators are characters and symbols that act like delimiters to separate other meaningful elements. (Default: [])
- * @param integerLiteral a regex that detects an integer literal.
- * @param floatingLiteral a regex that detects a floating point number literal.
- * @param singleLineString a set of strings that denote the start and end enclosing strings.
- * The lexer will throw a [LexicalException] when a string literal is not terminated in the same line.
- * @param escapeSequences a list of regex that matches an escape sequence. On match, it will return a Char based on the string matched.
+ * This class is internal. You can create an instance of this class by [LexerBuilder]
  *
  * @author Nishant Aanjaney Jalan
  * @since 0.1.0

docs/core/index.html

@@ -99,7 +99,7 @@ <h2 class="">Packages</h2>
           </div>
         </div>
         <div><span class="brief-comment"><a data-name="-545240740%2FPackages%2F537371977" anchor-label="io.github.cybercodernaj.parkour.lexer" id="-545240740%2FPackages%2F537371977" data-filterable-set=":core:dokkaHtmlPartial/main"></a>
-            <p class="paragraph">Docs for the lexer</p>
+            <p class="paragraph">The lexer is responsible to convert the given string into a stream of Tokens.</p>
           </span></div>
       </div>
     </div>

docs/core/io.github.cybercodernaj.parkour.lexer.internal/-lexer/-defaults/escape-sequences.html

@@ -63,7 +63,7 @@
   <div class="cover ">
     <h1 class="cover"><span>escape</span><wbr><span><span>Sequences</span></span></h1>
   </div>
-  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="escape-sequences.html">escapeSequences</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/index.html">List</a><span class="token operator">&lt;</span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-pair/index.html">Pair</a><span class="token operator">&lt;</span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="token punctuation">, </span><span class="token punctuation">(</span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html">String</a><span class="token punctuation">)</span><span class="token operator"> -&gt; </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-char/index.html">Char</a><span class="token operator">&gt;</span><span class="token operator">&gt;</span><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L81">source</a>)</span></span></div></div></div>
+  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="escape-sequences.html">escapeSequences</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/index.html">List</a><span class="token operator">&lt;</span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-pair/index.html">Pair</a><span class="token operator">&lt;</span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="token punctuation">, </span><span class="token punctuation">(</span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html">String</a><span class="token punctuation">)</span><span class="token operator"> -&gt; </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-char/index.html">Char</a><span class="token operator">&gt;</span><span class="token operator">&gt;</span><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L49">source</a>)</span></span></div></div></div>
 </div>
       <div class="footer">
         <span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2024 Nishant Aanjaney Jalan</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span>

docs/core/io.github.cybercodernaj.parkour.lexer.internal/-lexer/-defaults/floating-literal.html

@@ -63,7 +63,7 @@
   <div class="cover ">
     <h1 class="cover"><span>floating</span><wbr><span><span>Literal</span></span></h1>
   </div>
-  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="floating-literal.html">floatingLiteral</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L79">source</a>)</span></span></div></div></div>
+  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="floating-literal.html">floatingLiteral</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L47">source</a>)</span></span></div></div></div>
 </div>
       <div class="footer">
         <span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2024 Nishant Aanjaney Jalan</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span>

docs/core/io.github.cybercodernaj.parkour.lexer.internal/-lexer/-defaults/identifiers.html

@@ -63,7 +63,7 @@
   <div class="cover ">
     <h1 class="cover"><span><span>identifiers</span></span></h1>
   </div>
-  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="identifiers.html">identifiers</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L77">source</a>)</span></span></div></div></div>
+  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="identifiers.html">identifiers</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L45">source</a>)</span></span></div></div></div>
 </div>
       <div class="footer">
         <span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2024 Nishant Aanjaney Jalan</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span>

docs/core/io.github.cybercodernaj.parkour.lexer.internal/-lexer/-defaults/ignore-pattern.html

@@ -63,7 +63,7 @@
   <div class="cover ">
     <h1 class="cover"><span>ignore</span><wbr><span><span>Pattern</span></span></h1>
   </div>
-  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="ignore-pattern.html">ignorePattern</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L74">source</a>)</span></span></div><p class="paragraph">The lexer will skip over any strings that match this regex. This acts like a token separator.</p><span class="kdoc-tag"><h4 class="">Author</h4><p class="paragraph">Nishant Aanjaney Jalan</p></span><span class="kdoc-tag"><h4 class="">Since</h4><p class="paragraph">0.2.0</p></span></div></div>
+  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="ignore-pattern.html">ignorePattern</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L42">source</a>)</span></span></div><p class="paragraph">The lexer will skip over any strings that match this regex. This acts like a token separator.</p><span class="kdoc-tag"><h4 class="">Author</h4><p class="paragraph">Nishant Aanjaney Jalan</p></span><span class="kdoc-tag"><h4 class="">Since</h4><p class="paragraph">0.2.0</p></span></div></div>
 </div>
       <div class="footer">
         <span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2024 Nishant Aanjaney Jalan</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span>

docs/core/io.github.cybercodernaj.parkour.lexer.internal/-lexer/-defaults/index.html

@@ -62,7 +62,7 @@
   <div class="breadcrumbs"><a href="../../../index.html">parkour</a><span class="delimiter">/</span><a href="../../index.html">io.github.cybercodernaj.parkour.lexer.internal</a><span class="delimiter">/</span><a href="../index.html">Lexer</a><span class="delimiter">/</span><span class="current">Defaults</span></div>
   <div class="cover ">
     <h1 class="cover"><span><span>Defaults</span></span></h1>
-    <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">object </span><a href="index.html">Defaults</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L66">source</a>)</span></span></div><p class="paragraph">A list of common patterns and lists of items that most programming languages and data serialization formats.</p><span class="kdoc-tag"><h4 class="">Author</h4><p class="paragraph">Nishant Aanjaney Jalan</p></span><span class="kdoc-tag"><h4 class="">Since</h4><p class="paragraph">0.2.0</p></span></div></div>
+    <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">object </span><a href="index.html">Defaults</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L34">source</a>)</span></span></div><p class="paragraph">A list of common patterns and lists of items that most programming languages and data serialization formats.</p><span class="kdoc-tag"><h4 class="">Author</h4><p class="paragraph">Nishant Aanjaney Jalan</p></span><span class="kdoc-tag"><h4 class="">Since</h4><p class="paragraph">0.2.0</p></span></div></div>
   </div>
   <div class="tabbedcontent">
     <div class="tabs-section" tabs-section="tabs-section"><button class="section-tab" data-active="" data-togglable="CONSTRUCTOR,TYPE,PROPERTY,FUNCTION">Members</button></div>

docs/core/io.github.cybercodernaj.parkour.lexer.internal/-lexer/-defaults/integer-literal.html

@@ -63,7 +63,7 @@
   <div class="cover ">
     <h1 class="cover"><span>integer</span><wbr><span><span>Literal</span></span></h1>
   </div>
-  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="integer-literal.html">integerLiteral</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L78">source</a>)</span></span></div></div></div>
+  <div class="platform-hinted " data-platform-hinted="data-platform-hinted"><div class="content sourceset-dependent-content" data-active="" data-togglable=":core:dokkaHtmlPartial/main"><div class="symbol monospace"><span class="token keyword">val </span><a href="integer-literal.html">integerLiteral</a><span class="token operator">: </span><a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/index.html">Regex</a><span class="clearfix"><span class="floating-right">(<a href="https://github.com/cybercoder-naj/parkour/tree/main/core/src/main/kotlin/io/github/cybercodernaj/parkour/lexer/internal/Lexer.kt#L46">source</a>)</span></span></div></div></div>
 </div>
       <div class="footer">
         <span class="go-to-top-icon"><a href="#content" id="go-to-top-link"></a></span><span>© 2024 Nishant Aanjaney Jalan</span><span class="pull-right"><span>Generated by </span><a href="https://github.com/Kotlin/dokka"><span>dokka</span><span class="padded-icon"></span></a></span>