chordsheetjs 7.8.0 → 7.9.0

package/README.md

@@ -387,10 +387,44 @@ PDF conversion.</p></dd>
 <dd><p>Formats a song into a plain text chord sheet</p></dd>
 <dt><a href="#ChordProParser">ChordProParser</a></dt>
 <dd><p>Parses a ChordPro chord sheet</p></dd>
-<dt><a href="#ChordSheetParser">ChordSheetParser</a></dt>
-<dd><p>Parses a normal chord sheet</p></dd>
+<dt><del><a href="#ChordSheetParser">ChordSheetParser</a></del></dt>
+<dd><p>Parses a normal chord sheet</p>
+<p>ChordSheetParser is deprecated, please use ChordsOverWordsParser.</p>
+<p>ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks
+support for many variations. Besides that, some chordpro feature have been ported back
+to ChordsOverWordsParser, which adds some interesting functionality.</p></dd>
 <dt><a href="#ChordsOverWordsParser">ChordsOverWordsParser</a></dt>
-<dd><p>Parses a chords over words sheet</p></dd>
+<dd><p>Parses a chords over words sheet into a song</p>
+<p>It support &quot;regular&quot; chord sheets:</p>
+<pre><code>       Am         C/G        F          C
+Let it be, let it be, let it be, let it be
+C                G              F  C/E Dm C
+Whisper words of wisdom, let it be
+</code></pre>
+<p>Additionally, some chordpro features have been &quot;ported back&quot;. For example, you can use chordpro directives:</p>
+<pre><code>{title: Let it be}
+{key: C}
+Chorus 1:
+       Am
+Let it be
+</code></pre>
+<p>For convenience, you can leave out the brackets:</p>
+<pre><code>title: Let it be
+Chorus 1:
+       Am
+Let it be
+</code></pre>
+<p>You can even use a markdown style frontmatter separator to separate the header from the song:</p>
+<pre><code>title: Let it be
+key: C
+---
+Chorus 1:
+       Am         C/G        F          C
+Let it be, let it be, let it be, let it be
+C                G              F  C/E Dm C
+Whisper words of wisdom, let it be
+</code></pre>
+<p><code>ChordsOverWordsParser</code> is the better version of <code>ChordSheetParser</code>, which is deprecated.</p></dd>
 <dt><a href="#ParserWarning">ParserWarning</a></dt>
 <dd><p>Represents a parser warning, currently only used by ChordProParser.</p></dd>
 <dt><a href="#PegBasedParser">PegBasedParser</a></dt>
@@ -1092,19 +1126,26 @@ PDF conversion.</p>
 
 <a name="ChordSheetParser"></a>
 
-## ChordSheetParser
+## ~~ChordSheetParser~~
+***Deprecated***
+
 <p>Parses a normal chord sheet</p>
+<p>ChordSheetParser is deprecated, please use ChordsOverWordsParser.</p>
+<p>ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks
+support for many variations. Besides that, some chordpro feature have been ported back
+to ChordsOverWordsParser, which adds some interesting functionality.</p>
 
 **Kind**: global class  
 
-* [ChordSheetParser](#ChordSheetParser)
+* ~~[ChordSheetParser](#ChordSheetParser)~~
     * [new ChordSheetParser([options])](#new_ChordSheetParser_new)
     * [.parse(chordSheet, [options])](#ChordSheetParser+parse) ⇒ [<code>Song</code>](#Song)
 
 <a name="new_ChordSheetParser_new"></a>
 
 ### new ChordSheetParser([options])
-<p>Instantiate a chord sheet parser</p>
+<p>Instantiate a chord sheet parser
+ChordSheetParser is deprecated, please use ChordsOverWordsParser.</p>
 
 
 | Param | Type | Default | Description |
@@ -1129,7 +1170,37 @@ PDF conversion.</p>
 <a name="ChordsOverWordsParser"></a>
 
 ## ChordsOverWordsParser
-<p>Parses a chords over words sheet</p>
+<p>Parses a chords over words sheet into a song</p>
+<p>It support &quot;regular&quot; chord sheets:</p>
+<pre><code>       Am         C/G        F          C
+Let it be, let it be, let it be, let it be
+C                G              F  C/E Dm C
+Whisper words of wisdom, let it be
+</code></pre>
+<p>Additionally, some chordpro features have been &quot;ported back&quot;. For example, you can use chordpro directives:</p>
+<pre><code>{title: Let it be}
+{key: C}
+Chorus 1:
+       Am
+Let it be
+</code></pre>
+<p>For convenience, you can leave out the brackets:</p>
+<pre><code>title: Let it be
+Chorus 1:
+       Am
+Let it be
+</code></pre>
+<p>You can even use a markdown style frontmatter separator to separate the header from the song:</p>
+<pre><code>title: Let it be
+key: C
+---
+Chorus 1:
+       Am         C/G        F          C
+Let it be, let it be, let it be, let it be
+C                G              F  C/E Dm C
+Whisper words of wisdom, let it be
+</code></pre>
+<p><code>ChordsOverWordsParser</code> is the better version of <code>ChordSheetParser</code>, which is deprecated.</p>
 
 **Kind**: global class  
 <a name="ChordsOverWordsParser+parse"></a>
@@ -1388,13 +1459,14 @@ of the root note. For example, <code>Em/A#</code> becomes <code>Em/Bb</code>.</p
 <a name="Chord.parse"></a>
 
 ### Chord.parse(chordString) ⇒ [<code>Chord</code>](#Chord) \| <code>null</code>
-<p>Tries to parse a chord string into a chord</p>
+<p>Tries to parse a chord string into a chord
+Any leading or trailing whitespace is removed first, so a chord like <code> \n  E/G# \r</code> is valid.</p>
 
 **Kind**: static method of [<code>Chord</code>](#Chord)  
 
 | Param | Description |
 | --- | --- |
-| chordString | <p>the chord string, eg <code>Esus4/G#</code> or <code>1sus4/#3</code></p> |
+| chordString | <p>the chord string, eg <code>Esus4/G#</code> or <code>1sus4/#3</code>.</p> |
 
 <a name="ChordSheetSerializer"></a>
 

package/lib/bundle.js

@@ -2395,7 +2395,8 @@ function $26f57998457eb2d4$var$normalizeChordSuffix(suffix) {
  */ class $26f57998457eb2d4$var$Chord {
     /**
    * Tries to parse a chord string into a chord
-   * @param chordString the chord string, eg `Esus4/G#` or `1sus4/#3`
+   * Any leading or trailing whitespace is removed first, so a chord like `  \n  E/G# \r ` is valid.
+   * @param chordString the chord string, eg `Esus4/G#` or `1sus4/#3`.
    * @returns {Chord|null}
    */ static parse(chordString) {
         try {
@@ -2405,7 +2406,7 @@ function $26f57998457eb2d4$var$normalizeChordSuffix(suffix) {
         }
     }
     static parseOrFail(chordString) {
-        const ast = (0, $ea7c5d4e4ce912f8$export$98e6a39c04603d36)(chordString);
+        const ast = (0, $ea7c5d4e4ce912f8$export$98e6a39c04603d36)(chordString.trim());
         return new $26f57998457eb2d4$var$Chord(ast);
     }
     /**
@@ -5597,6 +5598,12 @@ const $c049675f48c823b2$var$WHITE_SPACE = /\s/;
 const $c049675f48c823b2$var$CHORD_LINE_REGEX = /^\s*((([A-G])(#|b)?([^/\s]*)(\/([A-G])(#|b)?)?)(\s|$)+)+(\s|$)+/;
 /**
  * Parses a normal chord sheet
+ *
+ * ChordSheetParser is deprecated, please use ChordsOverWordsParser.
+ *
+ * ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks
+ * support for many variations. Besides that, some chordpro feature have been ported back
+ * to ChordsOverWordsParser, which adds some interesting functionality.
  */ class $c049675f48c823b2$var$ChordSheetParser {
     processingText = true;
     preserveWhitespace = true;
@@ -5608,9 +5615,16 @@ const $c049675f48c823b2$var$CHORD_LINE_REGEX = /^\s*((([A-G])(#|b)?([^/\s]*)(\/(
     lineCount = 0;
     /**
    * Instantiate a chord sheet parser
+   * ChordSheetParser is deprecated, please use ChordsOverWordsParser.
    * @param {Object} [options={}] options
    * @param {boolean} [options.preserveWhitespace=true] whether to preserve trailing whitespace for chords
+   * @deprecated
    */ constructor({ preserveWhitespace: preserveWhitespace = true  } = {}){
+        (0, $21a34a464e7bc609$export$b680e6b2c82f8c2f)(`ChordSheetParser is deprecated, please use ChordsOverWordsParser. 
+
+ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks 
+support for many variations. Besides that, some chordpro feature have been ported back 
+to ChordsOverWordsParser, which adds some interesting functionality.`);
         this.preserveWhitespace = preserveWhitespace;
     }
     /**
@@ -7469,7 +7483,42 @@ const $3df1df9cc0f1cab9$export$98e6a39c04603d36 = $3df1df9cc0f1cab9$var$peg$pars
 
 
 /**
- * Parses a chords over words sheet
+ * Parses a chords over words sheet into a song
+ *
+ * It support "regular" chord sheets:
+ *
+ *            Am         C/G        F          C
+ *     Let it be, let it be, let it be, let it be
+ *     C                G              F  C/E Dm C
+ *     Whisper words of wisdom, let it be
+ *
+ * Additionally, some chordpro features have been "ported back". For example, you can use chordpro directives:
+ *
+ *     {title: Let it be}
+ *     {key: C}
+ *     Chorus 1:
+ *            Am
+ *     Let it be
+ *
+ * For convenience, you can leave out the brackets:
+ *
+ *     title: Let it be
+ *     Chorus 1:
+ *            Am
+ *     Let it be
+ *
+ * You can even use a markdown style frontmatter separator to separate the header from the song:
+ *
+ *     title: Let it be
+ *     key: C
+ *     ---
+ *     Chorus 1:
+ *            Am         C/G        F          C
+ *     Let it be, let it be, let it be, let it be
+ *     C                G              F  C/E Dm C
+ *     Whisper words of wisdom, let it be
+ *
+ * `ChordsOverWordsParser` is the better version of `ChordSheetParser`, which is deprecated.
  */ class $c5e7c9181f4c1376$var$ChordsOverWordsParser extends (0, $6af2b7a7ad6b2cba$export$2e2bcd8739ae039) {
     /**
    * Parses a chords over words sheet into a song

package/lib/index.js

@@ -2394,7 +2394,8 @@ function $26f57998457eb2d4$var$normalizeChordSuffix(suffix) {
  */ class $26f57998457eb2d4$var$Chord {
     /**
    * Tries to parse a chord string into a chord
-   * @param chordString the chord string, eg `Esus4/G#` or `1sus4/#3`
+   * Any leading or trailing whitespace is removed first, so a chord like `  \n  E/G# \r ` is valid.
+   * @param chordString the chord string, eg `Esus4/G#` or `1sus4/#3`.
    * @returns {Chord|null}
    */ static parse(chordString) {
         try {
@@ -2404,7 +2405,7 @@ function $26f57998457eb2d4$var$normalizeChordSuffix(suffix) {
         }
     }
     static parseOrFail(chordString) {
-        const ast = (0, $ea7c5d4e4ce912f8$export$98e6a39c04603d36)(chordString);
+        const ast = (0, $ea7c5d4e4ce912f8$export$98e6a39c04603d36)(chordString.trim());
         return new $26f57998457eb2d4$var$Chord(ast);
     }
     /**
@@ -5596,6 +5597,12 @@ const $c049675f48c823b2$var$WHITE_SPACE = /\s/;
 const $c049675f48c823b2$var$CHORD_LINE_REGEX = /^\s*((([A-G])(#|b)?([^/\s]*)(\/([A-G])(#|b)?)?)(\s|$)+)+(\s|$)+/;
 /**
  * Parses a normal chord sheet
+ *
+ * ChordSheetParser is deprecated, please use ChordsOverWordsParser.
+ *
+ * ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks
+ * support for many variations. Besides that, some chordpro feature have been ported back
+ * to ChordsOverWordsParser, which adds some interesting functionality.
  */ class $c049675f48c823b2$var$ChordSheetParser {
     processingText = true;
     preserveWhitespace = true;
@@ -5607,9 +5614,16 @@ const $c049675f48c823b2$var$CHORD_LINE_REGEX = /^\s*((([A-G])(#|b)?([^/\s]*)(\/(
     lineCount = 0;
     /**
    * Instantiate a chord sheet parser
+   * ChordSheetParser is deprecated, please use ChordsOverWordsParser.
    * @param {Object} [options={}] options
    * @param {boolean} [options.preserveWhitespace=true] whether to preserve trailing whitespace for chords
+   * @deprecated
    */ constructor({ preserveWhitespace: preserveWhitespace = true  } = {}){
+        (0, $21a34a464e7bc609$export$b680e6b2c82f8c2f)(`ChordSheetParser is deprecated, please use ChordsOverWordsParser. 
+
+ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks 
+support for many variations. Besides that, some chordpro feature have been ported back 
+to ChordsOverWordsParser, which adds some interesting functionality.`);
         this.preserveWhitespace = preserveWhitespace;
     }
     /**
@@ -7468,7 +7482,42 @@ const $3df1df9cc0f1cab9$export$98e6a39c04603d36 = $3df1df9cc0f1cab9$var$peg$pars
 
 
 /**
- * Parses a chords over words sheet
+ * Parses a chords over words sheet into a song
+ *
+ * It support "regular" chord sheets:
+ *
+ *            Am         C/G        F          C
+ *     Let it be, let it be, let it be, let it be
+ *     C                G              F  C/E Dm C
+ *     Whisper words of wisdom, let it be
+ *
+ * Additionally, some chordpro features have been "ported back". For example, you can use chordpro directives:
+ *
+ *     {title: Let it be}
+ *     {key: C}
+ *     Chorus 1:
+ *            Am
+ *     Let it be
+ *
+ * For convenience, you can leave out the brackets:
+ *
+ *     title: Let it be
+ *     Chorus 1:
+ *            Am
+ *     Let it be
+ *
+ * You can even use a markdown style frontmatter separator to separate the header from the song:
+ *
+ *     title: Let it be
+ *     key: C
+ *     ---
+ *     Chorus 1:
+ *            Am         C/G        F          C
+ *     Let it be, let it be, let it be, let it be
+ *     C                G              F  C/E Dm C
+ *     Whisper words of wisdom, let it be
+ *
+ * `ChordsOverWordsParser` is the better version of `ChordSheetParser`, which is deprecated.
  */ class $c5e7c9181f4c1376$var$ChordsOverWordsParser extends (0, $6af2b7a7ad6b2cba$export$2e2bcd8739ae039) {
     /**
    * Parses a chords over words sheet into a song