chordsheetjs 10.2.0 → 10.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +479 -466
  2. package/lib/bundle.js +35 -10
  3. package/lib/bundle.min.js +17 -17
  4. package/lib/index.js +35 -11
  5. package/lib/index.js.map +1 -1
  6. package/lib/main.d.ts +35 -35
  7. package/lib/main.d.ts.map +1 -1
  8. package/lib/module.js +35 -11
  9. package/lib/module.js.map +1 -1
  10. package/package.json +8 -11
package/README.md CHANGED
@@ -364,6 +364,8 @@ subject to breaking changes between major versions.
364
364
  ## Classes
365
365
 
366
366
  <dl>
367
+ <dt><a href="#ChordSheetSerializer">ChordSheetSerializer</a></dt>
368
+ <dd><p>Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)</p></dd>
367
369
  <dt><a href="#ChordLyricsPair">ChordLyricsPair</a></dt>
368
370
  <dd><p>Represents a chord with the corresponding (partial) lyrics</p></dd>
369
371
  <dt><a href="#Comment">Comment</a></dt>
@@ -381,6 +383,8 @@ metadata.get('author') // =&gt; 'John'</p>
381
383
  <dd><p>Represents a song in a chord sheet. Currently a chord sheet can only have one song.</p></dd>
382
384
  <dt><a href="#Tag">Tag</a></dt>
383
385
  <dd><p>Represents a tag/directive. See https://www.chordpro.org/chordpro/chordpro-directives/</p></dd>
386
+ <dt><a href="#Chord">Chord</a></dt>
387
+ <dd><p>Represents a Chord, consisting of a root, suffix (quality) and bass</p></dd>
384
388
  <dt><a href="#ChordProFormatter">ChordProFormatter</a></dt>
385
389
  <dd><p>Formats a song into a ChordPro chord sheet</p></dd>
386
390
  <dt><a href="#ChordsOverWordsFormatter">ChordsOverWordsFormatter</a></dt>
@@ -396,6 +400,9 @@ metadata.get('author') // =&gt; 'John'</p>
396
400
  PDF conversion.</p></dd>
397
401
  <dt><a href="#TextFormatter">TextFormatter</a></dt>
398
402
  <dd><p>Formats a song into a plain text chord sheet</p></dd>
403
+ <dt><a href="#Key">Key</a></dt>
404
+ <dd><p>Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).</p>
405
+ <p>The only function considered public API is <code>Key.distance</code></p></dd>
399
406
  <dt><a href="#ChordProParser">ChordProParser</a></dt>
400
407
  <dd><p>Parses a ChordPro chord sheet</p></dd>
401
408
  <dt><del><a href="#ChordSheetParser">ChordSheetParser</a></del></dt>
@@ -441,13 +448,6 @@ Whisper words of wisdom, let it be
441
448
  <dt><a href="#UltimateGuitarParser">UltimateGuitarParser</a></dt>
442
449
  <dd><p>Parses an Ultimate Guitar chord sheet with metadata
443
450
  Inherits from [ChordSheetParser](#ChordSheetParser)</p></dd>
444
- <dt><a href="#Chord">Chord</a></dt>
445
- <dd><p>Represents a Chord, consisting of a root, suffix (quality) and bass</p></dd>
446
- <dt><a href="#ChordSheetSerializer">ChordSheetSerializer</a></dt>
447
- <dd><p>Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)</p></dd>
448
- <dt><a href="#Key">Key</a></dt>
449
- <dd><p>Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).</p>
450
- <p>The only function considered public API is <code>Key.distance</code></p></dd>
451
451
  </dl>
452
452
 
453
453
  ## Constants
@@ -577,6 +577,37 @@ Possible values are 'solfege', 'symbol', 'numeral' and 'number'</p></dd>
577
577
  <dd><p>Returns applicable keys to transpose to from the provided key</p></dd>
578
578
  </dl>
579
579
 
580
+ <a name="ChordSheetSerializer"></a>
581
+
582
+ ## ChordSheetSerializer
583
+ <p>Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)</p>
584
+
585
+ **Kind**: global class
586
+
587
+ * [ChordSheetSerializer](#ChordSheetSerializer)
588
+ * [.serialize()](#ChordSheetSerializer+serialize) ⇒
589
+ * [.deserialize(serializedSong)](#ChordSheetSerializer+deserialize) ⇒ [<code>Song</code>](#Song)
590
+
591
+ <a name="ChordSheetSerializer+serialize"></a>
592
+
593
+ ### chordSheetSerializer.serialize() ⇒
594
+ <p>Serializes the chord sheet to a plain object, which can be converted to any format like JSON, XML etc
595
+ Can be deserialized using [deserialize](deserialize)</p>
596
+
597
+ **Kind**: instance method of [<code>ChordSheetSerializer</code>](#ChordSheetSerializer)
598
+ **Returns**: <p>object A plain JS object containing all chord sheet data</p>
599
+ <a name="ChordSheetSerializer+deserialize"></a>
600
+
601
+ ### chordSheetSerializer.deserialize(serializedSong) ⇒ [<code>Song</code>](#Song)
602
+ <p>Deserializes a song that has been serialized using [serialize](serialize)</p>
603
+
604
+ **Kind**: instance method of [<code>ChordSheetSerializer</code>](#ChordSheetSerializer)
605
+ **Returns**: [<code>Song</code>](#Song) - <p>The deserialized song</p>
606
+
607
+ | Param | Type | Description |
608
+ | --- | --- | --- |
609
+ | serializedSong | <code>object</code> | <p>The serialized song</p> |
610
+
580
611
  <a name="ChordLyricsPair"></a>
581
612
 
582
613
  ## ChordLyricsPair
@@ -857,6 +888,7 @@ the paragraph contents as one string where lines are separated by newlines.</p>
857
888
  * [.transposeUp([options])](#Song+transposeUp) ⇒ [<code>Song</code>](#Song)
858
889
  * [.transposeDown([options])](#Song+transposeDown) ⇒ [<code>Song</code>](#Song)
859
890
  * [.changeKey(newKey)](#Song+changeKey) ⇒ [<code>Song</code>](#Song)
891
+ * [.useModifier(modifier)](#Song+useModifier) ⇒ [<code>Song</code>](#Song)
860
892
  * [.changeMetadata(name, value)](#Song+changeMetadata)
861
893
  * [.mapItems(func)](#Song+mapItems) ⇒ [<code>Song</code>](#Song)
862
894
  * [.mapLines(func)](#Song+mapLines) ⇒ [<code>Song</code>](#Song)
@@ -1010,6 +1042,18 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
1010
1042
  | --- | --- | --- |
1011
1043
  | newKey | <code>string</code> | <p>The new key.</p> |
1012
1044
 
1045
+ <a name="Song+useModifier"></a>
1046
+
1047
+ ### song.useModifier(modifier) ⇒ [<code>Song</code>](#Song)
1048
+ <p>Returns a copy of the song with all chords changed to the specified modifier.</p>
1049
+
1050
+ **Kind**: instance method of [<code>Song</code>](#Song)
1051
+ **Returns**: [<code>Song</code>](#Song) - <p>the changed song</p>
1052
+
1053
+ | Param | Type | Description |
1054
+ | --- | --- | --- |
1055
+ | modifier | <code>Modifier</code> | <p>the new modifier</p> |
1056
+
1013
1057
  <a name="Song+changeMetadata"></a>
1014
1058
 
1015
1059
  ### song.changeMetadata(name, value)
@@ -1142,637 +1186,606 @@ https://chordpro.org/chordpro/directives-env_bridge/, https://chordpro.org/chord
1142
1186
 
1143
1187
  **Kind**: instance method of [<code>Tag</code>](#Tag)
1144
1188
  **Returns**: [<code>Tag</code>](#Tag) - <p>The cloned tag</p>
1145
- <a name="ChordProFormatter"></a>
1189
+ <a name="Chord"></a>
1146
1190
 
1147
- ## ChordProFormatter
1148
- <p>Formats a song into a ChordPro chord sheet</p>
1191
+ ## Chord
1192
+ <p>Represents a Chord, consisting of a root, suffix (quality) and bass</p>
1149
1193
 
1150
1194
  **Kind**: global class
1151
- <a name="ChordProFormatter+format"></a>
1152
1195
 
1153
- ### chordProFormatter.format(song) ⇒ <code>string</code>
1154
- <p>Formats a song into a ChordPro chord sheet.</p>
1196
+ * [Chord](#Chord)
1197
+ * _instance_
1198
+ * [.clone()](#Chord+clone) ⇒ [<code>Chord</code>](#Chord)
1199
+ * [.toChordSymbol([referenceKey])](#Chord+toChordSymbol) ⇒ [<code>Chord</code>](#Chord)
1200
+ * [.toChordSymbolString([referenceKey])](#Chord+toChordSymbolString) ⇒ <code>string</code>
1201
+ * [.isChordSymbol()](#Chord+isChordSymbol) ⇒ <code>boolean</code>
1202
+ * [.toChordSolfege([referenceKey])](#Chord+toChordSolfege) ⇒ [<code>Chord</code>](#Chord)
1203
+ * [.toChordSolfegeString([referenceKey])](#Chord+toChordSolfegeString) ⇒ <code>string</code>
1204
+ * [.isChordSolfege()](#Chord+isChordSolfege) ⇒ <code>boolean</code>
1205
+ * [.toNumeric([referenceKey])](#Chord+toNumeric) ⇒ [<code>Chord</code>](#Chord)
1206
+ * [.toNumeral([referenceKey])](#Chord+toNumeral) ⇒ [<code>Chord</code>](#Chord)
1207
+ * [.toNumeralString([referenceKey])](#Chord+toNumeralString) ⇒ <code>string</code>
1208
+ * [.isNumeric()](#Chord+isNumeric) ⇒ <code>boolean</code>
1209
+ * [.toNumericString([referenceKey])](#Chord+toNumericString) ⇒ <code>string</code>
1210
+ * [.isNumeral()](#Chord+isNumeral) ⇒ <code>boolean</code>
1211
+ * [.toString([configuration])](#Chord+toString) ⇒ <code>string</code>
1212
+ * [.normalize([key], [options])](#Chord+normalize) ⇒ [<code>Chord</code>](#Chord)
1213
+ * [.useModifier(newModifier)](#Chord+useModifier) ⇒ [<code>Chord</code>](#Chord)
1214
+ * [.transposeUp()](#Chord+transposeUp) ⇒ [<code>Chord</code>](#Chord)
1215
+ * [.transposeDown()](#Chord+transposeDown) ⇒ [<code>Chord</code>](#Chord)
1216
+ * [.transpose(delta)](#Chord+transpose) ⇒ [<code>Chord</code>](#Chord)
1217
+ * _static_
1218
+ * [.parse(chordString)](#Chord.parse) ⇒ [<code>Chord</code>](#Chord) \| <code>null</code>
1155
1219
 
1156
- **Kind**: instance method of [<code>ChordProFormatter</code>](#ChordProFormatter)
1157
- **Returns**: <code>string</code> - <p>The ChordPro string</p>
1220
+ <a name="Chord+clone"></a>
1158
1221
 
1159
- | Param | Type | Description |
1160
- | --- | --- | --- |
1161
- | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1222
+ ### chord.clone() ⇒ [<code>Chord</code>](#Chord)
1223
+ <p>Returns a deep copy of the chord</p>
1162
1224
 
1163
- <a name="ChordsOverWordsFormatter"></a>
1225
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1226
+ <a name="Chord+toChordSymbol"></a>
1164
1227
 
1165
- ## ChordsOverWordsFormatter
1166
- <p>Formats a song into a plain text chord sheet</p>
1228
+ ### chord.toChordSymbol([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1229
+ <p>Converts the chord to a chord symbol, using the supplied key as a reference.
1230
+ For example, a numeric chord <code>#4</code> with reference key <code>E</code> will return the chord symbol <code>A#</code>.
1231
+ When the chord is already a chord symbol, it will return a clone of the object.</p>
1167
1232
 
1168
- **Kind**: global class
1169
- <a name="ChordsOverWordsFormatter+format"></a>
1233
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1234
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the chord symbol</p>
1170
1235
 
1171
- ### chordsOverWordsFormatter.format(song) ⇒ <code>string</code>
1172
- <p>Formats a song into a plain text chord sheet</p>
1236
+ | Param | Type | Default | Description |
1237
+ | --- | --- | --- | --- |
1238
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1173
1239
 
1174
- **Kind**: instance method of [<code>ChordsOverWordsFormatter</code>](#ChordsOverWordsFormatter)
1175
- **Returns**: <code>string</code> - <p>the chord sheet</p>
1240
+ <a name="Chord+toChordSymbolString"></a>
1176
1241
 
1177
- | Param | Type | Description |
1178
- | --- | --- | --- |
1179
- | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1242
+ ### chord.toChordSymbolString([referenceKey]) ⇒ <code>string</code>
1243
+ <p>Converts the chord to a chord symbol string, using the supplied key as a reference.
1244
+ For example, a numeric chord <code>#4</code> with reference key <code>E</code> will return the chord symbol <code>A#</code>.
1245
+ When the chord is already a chord symbol, it will return a string version of the chord.</p>
1180
1246
 
1181
- <a name="Formatter"></a>
1247
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1248
+ **Returns**: <code>string</code> - <p>the chord symbol string</p>
1249
+ **See**: {toChordSymbol}
1182
1250
 
1183
- ## Formatter
1184
- <p>Base class for all formatters, taking care of receiving a configuration wrapping that inside a Configuration object</p>
1251
+ | Param | Type | Default | Description |
1252
+ | --- | --- | --- | --- |
1253
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1185
1254
 
1186
- **Kind**: global class
1187
- <a name="new_Formatter_new"></a>
1255
+ <a name="Chord+isChordSymbol"></a>
1188
1256
 
1189
- ### new Formatter([configuration])
1190
- <p>Instantiate</p>
1257
+ ### chord.isChordSymbol() ⇒ <code>boolean</code>
1258
+ <p>Determines whether the chord is a chord symbol</p>
1259
+
1260
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1261
+ <a name="Chord+toChordSolfege"></a>
1262
+
1263
+ ### chord.toChordSolfege([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1264
+ <p>Converts the chord to a chord solfege, using the supplied key as a reference.
1265
+ For example, a numeric chord <code>#4</code> with reference key <code>Mi</code> will return the chord symbol <code>La#</code>.
1266
+ When the chord is already a chord solfege, it will return a clone of the object.</p>
1191
1267
 
1268
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1269
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the chord solfege</p>
1192
1270
 
1193
1271
  | Param | Type | Default | Description |
1194
1272
  | --- | --- | --- | --- |
1195
- | [configuration] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1196
- | [configuration.evaluate] | <code>boolean</code> | <code>false</code> | <p>Whether or not to evaluate meta expressions. For more info about meta expressions, see: https://bit.ly/2SC9c2u</p> |
1197
- | [configuration.metadata] | <code>object</code> | <code>{}</code> | |
1198
- | [configuration.metadata.separator] | <code>string</code> | <code>&quot;\&quot;, \&quot;&quot;</code> | <p>The separator to be used when rendering a metadata value that has multiple values. See: https://bit.ly/2SC9c2u</p> |
1199
- | [configuration.key] | [<code>Key</code>](#Key) \| <code>string</code> | <code></code> | <p>The key to use for rendering. The chord sheet will be transposed from the song's original key (as indicated by the <code>{key}</code> directive) to the specified key. Note that transposing will only work if the original song key is set.</p> |
1200
- | [configuration.expandChorusDirective] | <code>boolean</code> | <code>false</code> | <p>Whether or not to expand <code>{chorus}</code> directives by rendering the last defined chorus inline after the directive.</p> |
1201
- | [configuration.useUnicodeModifiers] | <code>boolean</code> | <code>false</code> | <p>Whether or not to use unicode flat and sharp symbols.</p> |
1202
- | [configuration.normalizeChords] | <code>boolean</code> | <code>true</code> | <p>Whether or not to automatically normalize chords</p> |
1273
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1203
1274
 
1204
- <a name="HtmlDivFormatter"></a>
1275
+ <a name="Chord+toChordSolfegeString"></a>
1205
1276
 
1206
- ## HtmlDivFormatter
1207
- <p>Formats a song into HTML. It uses DIVs to align lyrics with chords, which makes it useful for responsive web pages.</p>
1277
+ ### chord.toChordSolfegeString([referenceKey]) ⇒ <code>string</code>
1278
+ <p>Converts the chord to a chord solfege string, using the supplied key as a reference.
1279
+ For example, a numeric chord <code>#4</code> with reference key <code>E</code> will return the chord solfege <code>A#</code>.
1280
+ When the chord is already a chord solfege, it will return a string version of the chord.</p>
1208
1281
 
1209
- **Kind**: global class
1210
- <a name="HtmlFormatter"></a>
1282
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1283
+ **Returns**: <code>string</code> - <p>the chord solfege string</p>
1284
+ **See**: {toChordSolfege}
1211
1285
 
1212
- ## HtmlFormatter
1213
- <p>Acts as a base class for HTML formatters</p>
1286
+ | Param | Type | Default | Description |
1287
+ | --- | --- | --- | --- |
1288
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1214
1289
 
1215
- **Kind**: global class
1290
+ <a name="Chord+isChordSolfege"></a>
1216
1291
 
1217
- * [HtmlFormatter](#HtmlFormatter)
1218
- * [.cssObject](#HtmlFormatter+cssObject) ⇒ <code>Object.&lt;string, Object.&lt;string, string&gt;&gt;</code>
1219
- * [.format(song)](#HtmlFormatter+format) ⇒ <code>string</code>
1220
- * [.cssString(scope)](#HtmlFormatter+cssString) ⇒ <code>string</code>
1292
+ ### chord.isChordSolfege() ⇒ <code>boolean</code>
1293
+ <p>Determines whether the chord is a chord solfege</p>
1221
1294
 
1222
- <a name="HtmlFormatter+cssObject"></a>
1295
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1296
+ <a name="Chord+toNumeric"></a>
1223
1297
 
1224
- ### htmlFormatter.cssObject ⇒ <code>Object.&lt;string, Object.&lt;string, string&gt;&gt;</code>
1225
- <p>Basic CSS, in object style à la useStyles, to use with the HTML output
1226
- For a CSS string see [cssString](cssString)</p>
1227
- <p>Example:</p>
1228
- <pre><code>'.paragraph': {
1229
- marginBottom: '1em'
1230
- }
1231
- </code></pre>
1298
+ ### chord.toNumeric([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1299
+ <p>Converts the chord to a numeric chord, using the supplied key as a reference.
1300
+ For example, a chord symbol A# with reference key E will return the numeric chord #4.</p>
1232
1301
 
1233
- **Kind**: instance property of [<code>HtmlFormatter</code>](#HtmlFormatter)
1234
- **Returns**: <code>Object.&lt;string, Object.&lt;string, string&gt;&gt;</code> - <p>the CSS object</p>
1235
- <a name="HtmlFormatter+format"></a>
1302
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1303
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the numeric chord</p>
1236
1304
 
1237
- ### htmlFormatter.format(song) ⇒ <code>string</code>
1238
- <p>Formats a song into HTML.</p>
1305
+ | Param | Type | Default | Description |
1306
+ | --- | --- | --- | --- |
1307
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1239
1308
 
1240
- **Kind**: instance method of [<code>HtmlFormatter</code>](#HtmlFormatter)
1241
- **Returns**: <code>string</code> - <p>The HTML string</p>
1309
+ <a name="Chord+toNumeral"></a>
1242
1310
 
1243
- | Param | Type | Description |
1244
- | --- | --- | --- |
1245
- | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1311
+ ### chord.toNumeral([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1312
+ <p>Converts the chord to a numeral chord, using the supplied key as a reference.
1313
+ For example, a chord symbol A# with reference key E will return the numeral chord #IV.</p>
1246
1314
 
1247
- <a name="HtmlFormatter+cssString"></a>
1315
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1316
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the numeral chord</p>
1248
1317
 
1249
- ### htmlFormatter.cssString(scope) ⇒ <code>string</code>
1250
- <p>Generates basic CSS, optionally scoped within the provided selector, to use with the HTML output</p>
1251
- <p>For example, execute cssString('.chordSheetViewer') will result in CSS like:</p>
1252
- <pre><code>.chordSheetViewer .paragraph {
1253
- margin-bottom: 1em;
1254
- }
1255
- </code></pre>
1318
+ | Param | Type | Default | Description |
1319
+ | --- | --- | --- | --- |
1320
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1256
1321
 
1257
- **Kind**: instance method of [<code>HtmlFormatter</code>](#HtmlFormatter)
1258
- **Returns**: <code>string</code> - <p>the CSS string</p>
1322
+ <a name="Chord+toNumeralString"></a>
1259
1323
 
1260
- | Param | Description |
1261
- | --- | --- |
1262
- | scope | <p>the CSS scope to use, for example <code>.chordSheetViewer</code></p> |
1324
+ ### chord.toNumeralString([referenceKey]) ⇒ <code>string</code>
1325
+ <p>Converts the chord to a numeral chord string, using the supplied kye as a reference.
1326
+ For example, a chord symbol A# with reference key E will return the numeral chord #4.</p>
1263
1327
 
1264
- <a name="HtmlTableFormatter"></a>
1328
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1329
+ **Returns**: <code>string</code> - <p>the numeral chord string</p>
1330
+ **See**: {toNumeral}
1265
1331
 
1266
- ## HtmlTableFormatter
1267
- <p>Formats a song into HTML. It uses TABLEs to align lyrics with chords, which makes the HTML for things like
1268
- PDF conversion.</p>
1332
+ | Param | Type | Default | Description |
1333
+ | --- | --- | --- | --- |
1334
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1269
1335
 
1270
- **Kind**: global class
1271
- <a name="TextFormatter"></a>
1336
+ <a name="Chord+isNumeric"></a>
1272
1337
 
1273
- ## TextFormatter
1274
- <p>Formats a song into a plain text chord sheet</p>
1338
+ ### chord.isNumeric() ⇒ <code>boolean</code>
1339
+ <p>Determines whether the chord is numeric</p>
1275
1340
 
1276
- **Kind**: global class
1277
- <a name="TextFormatter+format"></a>
1341
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1342
+ <a name="Chord+toNumericString"></a>
1278
1343
 
1279
- ### textFormatter.format(song) ⇒ <code>string</code>
1280
- <p>Formats a song into a plain text chord sheet</p>
1344
+ ### chord.toNumericString([referenceKey]) ⇒ <code>string</code>
1345
+ <p>Converts the chord to a numeric chord string, using the supplied kye as a reference.
1346
+ For example, a chord symbol A# with reference key E will return the numeric chord #4.</p>
1281
1347
 
1282
- **Kind**: instance method of [<code>TextFormatter</code>](#TextFormatter)
1283
- **Returns**: <code>string</code> - <p>the chord sheet</p>
1348
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1349
+ **Returns**: <code>string</code> - <p>the numeric chord string</p>
1350
+ **See**: {toNumeric}
1284
1351
 
1285
- | Param | Type | Description |
1286
- | --- | --- | --- |
1287
- | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1352
+ | Param | Type | Default | Description |
1353
+ | --- | --- | --- | --- |
1354
+ | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1288
1355
 
1289
- <a name="ChordProParser"></a>
1356
+ <a name="Chord+isNumeral"></a>
1290
1357
 
1291
- ## ChordProParser
1292
- <p>Parses a ChordPro chord sheet</p>
1358
+ ### chord.isNumeral() ⇒ <code>boolean</code>
1359
+ <p>Determines whether the chord is a numeral</p>
1293
1360
 
1294
- **Kind**: global class
1361
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1362
+ <a name="Chord+toString"></a>
1295
1363
 
1296
- * [ChordProParser](#ChordProParser)
1297
- * [.warnings](#ChordProParser+warnings) : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1298
- * [.parse(chordSheet, options)](#ChordProParser+parse) ⇒ [<code>Song</code>](#Song)
1364
+ ### chord.toString([configuration]) ⇒ <code>string</code>
1365
+ <p>Converts the chord to a string, eg <code>Esus4/G#</code> or <code>1sus4/#3</code></p>
1299
1366
 
1300
- <a name="ChordProParser+warnings"></a>
1367
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1368
+ **Returns**: <code>string</code> - <p>the chord string</p>
1301
1369
 
1302
- ### chordProParser.warnings : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1303
- <p>All warnings raised during parsing the chord sheet</p>
1370
+ | Param | Type | Default | Description |
1371
+ | --- | --- | --- | --- |
1372
+ | [configuration] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1373
+ | [configuration.useUnicodeModifier] | <code>boolean</code> | <code>false</code> | <p>Whether or not to use unicode modifiers. This will make <code>#</code> (sharp) look like <code>♯</code> and <code>b</code> (flat) look like <code>♭</code></p> |
1304
1374
 
1305
- **Kind**: instance property of [<code>ChordProParser</code>](#ChordProParser)
1306
- <a name="ChordProParser+parse"></a>
1375
+ <a name="Chord+normalize"></a>
1307
1376
 
1308
- ### chordProParser.parse(chordSheet, options) ⇒ [<code>Song</code>](#Song)
1309
- <p>Parses a ChordPro chord sheet into a song</p>
1377
+ ### chord.normalize([key], [options]) ⇒ [<code>Chord</code>](#Chord)
1378
+ <p>Normalizes the chord root and bass notes:</p>
1379
+ <ul>
1380
+ <li>Fab becomes Mi</li>
1381
+ <li>Dob becomes Si</li>
1382
+ <li>Si# becomes Do</li>
1383
+ <li>Mi# becomes Fa</li>
1384
+ <li>Fb becomes E</li>
1385
+ <li>Cb becomes B</li>
1386
+ <li>B# becomes C</li>
1387
+ <li>E# becomes F</li>
1388
+ <li>4b becomes 3</li>
1389
+ <li>1b becomes 7</li>
1390
+ <li>7# becomes 1</li>
1391
+ <li>3# becomes 4</li>
1392
+ </ul>
1393
+ <p>Besides that it normalizes the suffix if <code>normalizeSuffix</code> is <code>true</code>.
1394
+ For example, <code>sus2</code> becomes <code>2</code>, <code>sus4</code> becomes <code>sus</code>.
1395
+ All suffix normalizations can be found in <code>src/normalize_mappings/suffix-mapping.txt</code>.</p>
1396
+ <p>When the chord is minor, bass notes are normalized off of the relative major
1397
+ of the root note. For example, <code>Em/A#</code> becomes <code>Em/Bb</code>.</p>
1310
1398
 
1311
- **Kind**: instance method of [<code>ChordProParser</code>](#ChordProParser)
1312
- **Returns**: [<code>Song</code>](#Song) - <p>The parsed song</p>
1313
- **See**: https://peggyjs.org/documentation.html#using-the-parser
1399
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1400
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the normalized chord</p>
1314
1401
 
1315
1402
  | Param | Type | Default | Description |
1316
1403
  | --- | --- | --- | --- |
1317
- | chordSheet | <code>string</code> | | <p>the ChordPro chord sheet</p> |
1318
- | options | <code>ChordProParserOptions</code> | | <p>Parser options.</p> |
1319
- | options.softLineBreaks | <code>ChordProParserOptions.softLineBreaks</code> | <code>false</code> | <p>If true, a backslash followed by * a space is treated as a soft line break</p> |
1320
-
1321
- <a name="ChordSheetParser"></a>
1404
+ | [key] | [<code>Key</code>](#Key) \| <code>string</code> | <code></code> | <p>the key to normalize to</p> |
1405
+ | [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1406
+ | [options.normalizeSuffix] | <code>boolean</code> | <code>true</code> | <p>whether to normalize the chord suffix after transposing</p> |
1322
1407
 
1323
- ## ~~ChordSheetParser~~
1324
- ***Deprecated***
1408
+ <a name="Chord+useModifier"></a>
1325
1409
 
1326
- <p>Parses a normal chord sheet</p>
1327
- <p>ChordSheetParser is deprecated, please use ChordsOverWordsParser.</p>
1328
- <p>ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks
1329
- support for many variations. Besides that, some chordpro feature have been ported back
1330
- to ChordsOverWordsParser, which adds some interesting functionality.</p>
1410
+ ### chord.useModifier(newModifier) ⇒ [<code>Chord</code>](#Chord)
1411
+ <p>Switches to the specified modifier</p>
1331
1412
 
1332
- **Kind**: global class
1413
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1414
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the new, changed chord</p>
1333
1415
 
1334
- * ~~[ChordSheetParser](#ChordSheetParser)~~
1335
- * [new ChordSheetParser([options])](#new_ChordSheetParser_new)
1336
- * [.parse(chordSheet, [options])](#ChordSheetParser+parse) ⇒ [<code>Song</code>](#Song)
1416
+ | Param | Description |
1417
+ | --- | --- |
1418
+ | newModifier | <p>the modifier to use: <code>'#'</code> or <code>'b'</code></p> |
1337
1419
 
1338
- <a name="new_ChordSheetParser_new"></a>
1420
+ <a name="Chord+transposeUp"></a>
1339
1421
 
1340
- ### new ChordSheetParser([options])
1341
- <p>Instantiate a chord sheet parser
1342
- ChordSheetParser is deprecated, please use ChordsOverWordsParser.</p>
1422
+ ### chord.transposeUp() ⇒ [<code>Chord</code>](#Chord)
1423
+ <p>Transposes the chord up by 1 semitone. Eg. A becomes A#, Eb becomes E</p>
1343
1424
 
1425
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1426
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the new, transposed chord</p>
1427
+ <a name="Chord+transposeDown"></a>
1344
1428
 
1345
- | Param | Type | Default | Description |
1346
- | --- | --- | --- | --- |
1347
- | [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1348
- | [options.preserveWhitespace] | <code>boolean</code> | <code>true</code> | <p>whether to preserve trailing whitespace for chords</p> |
1429
+ ### chord.transposeDown() ⇒ [<code>Chord</code>](#Chord)
1430
+ <p>Transposes the chord down by 1 semitone. Eg. A# becomes A, E becomes Eb</p>
1349
1431
 
1350
- <a name="ChordSheetParser+parse"></a>
1432
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1433
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the new, transposed chord</p>
1434
+ <a name="Chord+transpose"></a>
1351
1435
 
1352
- ### chordSheetParser.parse(chordSheet, [options]) ⇒ [<code>Song</code>](#Song)
1353
- <p>Parses a chord sheet into a song</p>
1436
+ ### chord.transpose(delta) ⇒ [<code>Chord</code>](#Chord)
1437
+ <p>Transposes the chord by the specified number of semitones</p>
1354
1438
 
1355
- **Kind**: instance method of [<code>ChordSheetParser</code>](#ChordSheetParser)
1356
- **Returns**: [<code>Song</code>](#Song) - <p>The parsed song</p>
1439
+ **Kind**: instance method of [<code>Chord</code>](#Chord)
1440
+ **Returns**: [<code>Chord</code>](#Chord) - <p>the new, transposed chord</p>
1357
1441
 
1358
- | Param | Type | Default | Description |
1359
- | --- | --- | --- | --- |
1360
- | chordSheet | <code>string</code> | | <p>The ChordPro chord sheet</p> |
1361
- | [options] | <code>Object</code> | <code>{}</code> | <p>Optional parser options</p> |
1362
- | [options.song] | [<code>Song</code>](#Song) | <code></code> | <p>The [Song](#Song) to store the song data in</p> |
1442
+ | Param | Description |
1443
+ | --- | --- |
1444
+ | delta | <p>de number of semitones</p> |
1363
1445
 
1364
- <a name="ChordsOverWordsParser"></a>
1446
+ <a name="Chord.parse"></a>
1365
1447
 
1366
- ## ChordsOverWordsParser
1367
- <p>Parses a chords over words sheet into a song</p>
1368
- <p>It support &quot;regular&quot; chord sheets:</p>
1369
- <pre><code> Am C/G F C
1370
- Let it be, let it be, let it be, let it be
1371
- C G F C/E Dm C
1372
- Whisper words of wisdom, let it be
1373
- </code></pre>
1374
- <p>Additionally, some chordpro features have been &quot;ported back&quot;. For example, you can use chordpro directives:</p>
1375
- <pre><code>{title: Let it be}
1376
- {key: C}
1377
- Chorus 1:
1378
- Am
1379
- Let it be
1380
- </code></pre>
1381
- <p>For convenience, you can leave out the brackets:</p>
1382
- <pre><code>title: Let it be
1383
- Chorus 1:
1384
- Am
1385
- Let it be
1386
- </code></pre>
1387
- <p>You can even use a markdown style frontmatter separator to separate the header from the song:</p>
1388
- <pre><code>title: Let it be
1389
- key: C
1390
- ---
1391
- Chorus 1:
1392
- Am C/G F C
1393
- Let it be, let it be, let it be, let it be
1394
- C G F C/E Dm C
1395
- Whisper words of wisdom, let it be
1396
- </code></pre>
1397
- <p><code>ChordsOverWordsParser</code> is the better version of <code>ChordSheetParser</code>, which is deprecated.</p>
1448
+ ### Chord.parse(chordString) ⇒ [<code>Chord</code>](#Chord) \| <code>null</code>
1449
+ <p>Tries to parse a chord string into a chord
1450
+ Any leading or trailing whitespace is removed first, so a chord like <code> \n E/G# \r</code> is valid.</p>
1398
1451
 
1399
- **Kind**: global class
1452
+ **Kind**: static method of [<code>Chord</code>](#Chord)
1400
1453
 
1401
- * [ChordsOverWordsParser](#ChordsOverWordsParser)
1402
- * [.warnings](#ChordsOverWordsParser+warnings) : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1403
- * [.parse(chordSheet, options)](#ChordsOverWordsParser+parse) ⇒ [<code>Song</code>](#Song)
1454
+ | Param | Description |
1455
+ | --- | --- |
1456
+ | chordString | <p>the chord string, eg <code>Esus4/G#</code> or <code>1sus4/#3</code>.</p> |
1404
1457
 
1405
- <a name="ChordsOverWordsParser+warnings"></a>
1458
+ <a name="ChordProFormatter"></a>
1406
1459
 
1407
- ### chordsOverWordsParser.warnings : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1408
- <p>All warnings raised during parsing the chord sheet</p>
1460
+ ## ChordProFormatter
1461
+ <p>Formats a song into a ChordPro chord sheet</p>
1409
1462
 
1410
- **Kind**: instance property of [<code>ChordsOverWordsParser</code>](#ChordsOverWordsParser)
1411
- <a name="ChordsOverWordsParser+parse"></a>
1463
+ **Kind**: global class
1464
+ <a name="ChordProFormatter+format"></a>
1412
1465
 
1413
- ### chordsOverWordsParser.parse(chordSheet, options) ⇒ [<code>Song</code>](#Song)
1414
- <p>Parses a chords over words sheet into a song</p>
1466
+ ### chordProFormatter.format(song) ⇒ <code>string</code>
1467
+ <p>Formats a song into a ChordPro chord sheet.</p>
1415
1468
 
1416
- **Kind**: instance method of [<code>ChordsOverWordsParser</code>](#ChordsOverWordsParser)
1417
- **Returns**: [<code>Song</code>](#Song) - <p>The parsed song</p>
1418
- **See**: https://peggyjs.org/documentation.html#using-the-parser
1469
+ **Kind**: instance method of [<code>ChordProFormatter</code>](#ChordProFormatter)
1470
+ **Returns**: <code>string</code> - <p>The ChordPro string</p>
1419
1471
 
1420
- | Param | Type | Default | Description |
1421
- | --- | --- | --- | --- |
1422
- | chordSheet | <code>string</code> | | <p>the chords over words sheet</p> |
1423
- | options | <code>ChordsOverWordsParserOptions</code> | | <p>Parser options.</p> |
1424
- | options.softLineBreaks | <code>ChordsOverWordsParserOptions.softLineBreaks</code> | <code>false</code> | <p>If true, a backslash followed by a space is treated as a soft line break</p> |
1472
+ | Param | Type | Description |
1473
+ | --- | --- | --- |
1474
+ | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1425
1475
 
1426
- <a name="ParserWarning"></a>
1476
+ <a name="ChordsOverWordsFormatter"></a>
1427
1477
 
1428
- ## ParserWarning
1429
- <p>Represents a parser warning, currently only used by ChordProParser.</p>
1478
+ ## ChordsOverWordsFormatter
1479
+ <p>Formats a song into a plain text chord sheet</p>
1430
1480
 
1431
1481
  **Kind**: global class
1432
- <a name="ParserWarning+toString"></a>
1482
+ <a name="ChordsOverWordsFormatter+format"></a>
1433
1483
 
1434
- ### parserWarning.toString() ⇒ <code>string</code>
1435
- <p>Returns a stringified version of the warning</p>
1484
+ ### chordsOverWordsFormatter.format(song) ⇒ <code>string</code>
1485
+ <p>Formats a song into a plain text chord sheet</p>
1436
1486
 
1437
- **Kind**: instance method of [<code>ParserWarning</code>](#ParserWarning)
1438
- **Returns**: <code>string</code> - <p>The string warning</p>
1439
- <a name="UltimateGuitarParser"></a>
1487
+ **Kind**: instance method of [<code>ChordsOverWordsFormatter</code>](#ChordsOverWordsFormatter)
1488
+ **Returns**: <code>string</code> - <p>the chord sheet</p>
1440
1489
 
1441
- ## UltimateGuitarParser
1442
- <p>Parses an Ultimate Guitar chord sheet with metadata
1443
- Inherits from [ChordSheetParser](#ChordSheetParser)</p>
1490
+ | Param | Type | Description |
1491
+ | --- | --- | --- |
1492
+ | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1493
+
1494
+ <a name="Formatter"></a>
1495
+
1496
+ ## Formatter
1497
+ <p>Base class for all formatters, taking care of receiving a configuration wrapping that inside a Configuration object</p>
1444
1498
 
1445
1499
  **Kind**: global class
1446
- <a name="new_UltimateGuitarParser_new"></a>
1500
+ <a name="new_Formatter_new"></a>
1447
1501
 
1448
- ### new UltimateGuitarParser([options])
1449
- <p>Instantiate a chord sheet parser</p>
1502
+ ### new Formatter([configuration])
1503
+ <p>Instantiate</p>
1450
1504
 
1451
1505
 
1452
1506
  | Param | Type | Default | Description |
1453
1507
  | --- | --- | --- | --- |
1454
- | [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1455
- | [options.preserveWhitespace] | <code>boolean</code> | <code>true</code> | <p>whether to preserve trailing whitespace for chords</p> |
1456
-
1457
- <a name="Chord"></a>
1508
+ | [configuration] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1509
+ | [configuration.evaluate] | <code>boolean</code> | <code>false</code> | <p>Whether or not to evaluate meta expressions. For more info about meta expressions, see: https://bit.ly/2SC9c2u</p> |
1510
+ | [configuration.metadata] | <code>object</code> | <code>{}</code> | |
1511
+ | [configuration.metadata.separator] | <code>string</code> | <code>&quot;\&quot;, \&quot;&quot;</code> | <p>The separator to be used when rendering a metadata value that has multiple values. See: https://bit.ly/2SC9c2u</p> |
1512
+ | [configuration.key] | [<code>Key</code>](#Key) \| <code>string</code> | <code></code> | <p>The key to use for rendering. The chord sheet will be transposed from the song's original key (as indicated by the <code>{key}</code> directive) to the specified key. Note that transposing will only work if the original song key is set.</p> |
1513
+ | [configuration.expandChorusDirective] | <code>boolean</code> | <code>false</code> | <p>Whether or not to expand <code>{chorus}</code> directives by rendering the last defined chorus inline after the directive.</p> |
1514
+ | [configuration.useUnicodeModifiers] | <code>boolean</code> | <code>false</code> | <p>Whether or not to use unicode flat and sharp symbols.</p> |
1515
+ | [configuration.normalizeChords] | <code>boolean</code> | <code>true</code> | <p>Whether or not to automatically normalize chords</p> |
1458
1516
 
1459
- ## Chord
1460
- <p>Represents a Chord, consisting of a root, suffix (quality) and bass</p>
1517
+ <a name="HtmlDivFormatter"></a>
1461
1518
 
1462
- **Kind**: global class
1463
-
1464
- * [Chord](#Chord)
1465
- * _instance_
1466
- * [.clone()](#Chord+clone) ⇒ [<code>Chord</code>](#Chord)
1467
- * [.toChordSymbol([referenceKey])](#Chord+toChordSymbol) ⇒ [<code>Chord</code>](#Chord)
1468
- * [.toChordSymbolString([referenceKey])](#Chord+toChordSymbolString) ⇒ <code>string</code>
1469
- * [.isChordSymbol()](#Chord+isChordSymbol) ⇒ <code>boolean</code>
1470
- * [.toChordSolfege([referenceKey])](#Chord+toChordSolfege) ⇒ [<code>Chord</code>](#Chord)
1471
- * [.toChordSolfegeString([referenceKey])](#Chord+toChordSolfegeString) ⇒ <code>string</code>
1472
- * [.isChordSolfege()](#Chord+isChordSolfege) ⇒ <code>boolean</code>
1473
- * [.toNumeric([referenceKey])](#Chord+toNumeric) ⇒ [<code>Chord</code>](#Chord)
1474
- * [.toNumeral([referenceKey])](#Chord+toNumeral) ⇒ [<code>Chord</code>](#Chord)
1475
- * [.toNumeralString([referenceKey])](#Chord+toNumeralString) ⇒ <code>string</code>
1476
- * [.isNumeric()](#Chord+isNumeric) ⇒ <code>boolean</code>
1477
- * [.toNumericString([referenceKey])](#Chord+toNumericString) ⇒ <code>string</code>
1478
- * [.isNumeral()](#Chord+isNumeral) ⇒ <code>boolean</code>
1479
- * [.toString([configuration])](#Chord+toString) ⇒ <code>string</code>
1480
- * [.normalize([key], [options])](#Chord+normalize) ⇒ [<code>Chord</code>](#Chord)
1481
- * [.useModifier(newModifier)](#Chord+useModifier) ⇒ [<code>Chord</code>](#Chord)
1482
- * [.transposeUp()](#Chord+transposeUp) ⇒ [<code>Chord</code>](#Chord)
1483
- * [.transposeDown()](#Chord+transposeDown) ⇒ [<code>Chord</code>](#Chord)
1484
- * [.transpose(delta)](#Chord+transpose) ⇒ [<code>Chord</code>](#Chord)
1485
- * _static_
1486
- * [.parse(chordString)](#Chord.parse) ⇒ [<code>Chord</code>](#Chord) \| <code>null</code>
1487
-
1488
- <a name="Chord+clone"></a>
1489
-
1490
- ### chord.clone() ⇒ [<code>Chord</code>](#Chord)
1491
- <p>Returns a deep copy of the chord</p>
1519
+ ## HtmlDivFormatter
1520
+ <p>Formats a song into HTML. It uses DIVs to align lyrics with chords, which makes it useful for responsive web pages.</p>
1492
1521
 
1493
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1494
- <a name="Chord+toChordSymbol"></a>
1522
+ **Kind**: global class
1523
+ <a name="HtmlFormatter"></a>
1495
1524
 
1496
- ### chord.toChordSymbol([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1497
- <p>Converts the chord to a chord symbol, using the supplied key as a reference.
1498
- For example, a numeric chord <code>#4</code> with reference key <code>E</code> will return the chord symbol <code>A#</code>.
1499
- When the chord is already a chord symbol, it will return a clone of the object.</p>
1525
+ ## HtmlFormatter
1526
+ <p>Acts as a base class for HTML formatters</p>
1500
1527
 
1501
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1502
- **Returns**: [<code>Chord</code>](#Chord) - <p>the chord symbol</p>
1528
+ **Kind**: global class
1503
1529
 
1504
- | Param | Type | Default | Description |
1505
- | --- | --- | --- | --- |
1506
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1530
+ * [HtmlFormatter](#HtmlFormatter)
1531
+ * [.cssObject](#HtmlFormatter+cssObject) ⇒ <code>Object.&lt;string, Object.&lt;string, string&gt;&gt;</code>
1532
+ * [.format(song)](#HtmlFormatter+format) ⇒ <code>string</code>
1533
+ * [.cssString(scope)](#HtmlFormatter+cssString) ⇒ <code>string</code>
1507
1534
 
1508
- <a name="Chord+toChordSymbolString"></a>
1535
+ <a name="HtmlFormatter+cssObject"></a>
1509
1536
 
1510
- ### chord.toChordSymbolString([referenceKey]) ⇒ <code>string</code>
1511
- <p>Converts the chord to a chord symbol string, using the supplied key as a reference.
1512
- For example, a numeric chord <code>#4</code> with reference key <code>E</code> will return the chord symbol <code>A#</code>.
1513
- When the chord is already a chord symbol, it will return a string version of the chord.</p>
1537
+ ### htmlFormatter.cssObject ⇒ <code>Object.&lt;string, Object.&lt;string, string&gt;&gt;</code>
1538
+ <p>Basic CSS, in object style à la useStyles, to use with the HTML output
1539
+ For a CSS string see [cssString](cssString)</p>
1540
+ <p>Example:</p>
1541
+ <pre><code>'.paragraph': {
1542
+ marginBottom: '1em'
1543
+ }
1544
+ </code></pre>
1514
1545
 
1515
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1516
- **Returns**: <code>string</code> - <p>the chord symbol string</p>
1517
- **See**: {toChordSymbol}
1546
+ **Kind**: instance property of [<code>HtmlFormatter</code>](#HtmlFormatter)
1547
+ **Returns**: <code>Object.&lt;string, Object.&lt;string, string&gt;&gt;</code> - <p>the CSS object</p>
1548
+ <a name="HtmlFormatter+format"></a>
1518
1549
 
1519
- | Param | Type | Default | Description |
1520
- | --- | --- | --- | --- |
1521
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1550
+ ### htmlFormatter.format(song) ⇒ <code>string</code>
1551
+ <p>Formats a song into HTML.</p>
1522
1552
 
1523
- <a name="Chord+isChordSymbol"></a>
1553
+ **Kind**: instance method of [<code>HtmlFormatter</code>](#HtmlFormatter)
1554
+ **Returns**: <code>string</code> - <p>The HTML string</p>
1524
1555
 
1525
- ### chord.isChordSymbol() ⇒ <code>boolean</code>
1526
- <p>Determines whether the chord is a chord symbol</p>
1556
+ | Param | Type | Description |
1557
+ | --- | --- | --- |
1558
+ | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1527
1559
 
1528
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1529
- <a name="Chord+toChordSolfege"></a>
1560
+ <a name="HtmlFormatter+cssString"></a>
1530
1561
 
1531
- ### chord.toChordSolfege([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1532
- <p>Converts the chord to a chord solfege, using the supplied key as a reference.
1533
- For example, a numeric chord <code>#4</code> with reference key <code>Mi</code> will return the chord symbol <code>La#</code>.
1534
- When the chord is already a chord solfege, it will return a clone of the object.</p>
1562
+ ### htmlFormatter.cssString(scope) ⇒ <code>string</code>
1563
+ <p>Generates basic CSS, optionally scoped within the provided selector, to use with the HTML output</p>
1564
+ <p>For example, execute cssString('.chordSheetViewer') will result in CSS like:</p>
1565
+ <pre><code>.chordSheetViewer .paragraph {
1566
+ margin-bottom: 1em;
1567
+ }
1568
+ </code></pre>
1535
1569
 
1536
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1537
- **Returns**: [<code>Chord</code>](#Chord) - <p>the chord solfege</p>
1570
+ **Kind**: instance method of [<code>HtmlFormatter</code>](#HtmlFormatter)
1571
+ **Returns**: <code>string</code> - <p>the CSS string</p>
1538
1572
 
1539
- | Param | Type | Default | Description |
1540
- | --- | --- | --- | --- |
1541
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1573
+ | Param | Description |
1574
+ | --- | --- |
1575
+ | scope | <p>the CSS scope to use, for example <code>.chordSheetViewer</code></p> |
1542
1576
 
1543
- <a name="Chord+toChordSolfegeString"></a>
1577
+ <a name="HtmlTableFormatter"></a>
1544
1578
 
1545
- ### chord.toChordSolfegeString([referenceKey]) ⇒ <code>string</code>
1546
- <p>Converts the chord to a chord solfege string, using the supplied key as a reference.
1547
- For example, a numeric chord <code>#4</code> with reference key <code>E</code> will return the chord solfege <code>A#</code>.
1548
- When the chord is already a chord solfege, it will return a string version of the chord.</p>
1579
+ ## HtmlTableFormatter
1580
+ <p>Formats a song into HTML. It uses TABLEs to align lyrics with chords, which makes the HTML for things like
1581
+ PDF conversion.</p>
1549
1582
 
1550
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1551
- **Returns**: <code>string</code> - <p>the chord solfege string</p>
1552
- **See**: {toChordSolfege}
1583
+ **Kind**: global class
1584
+ <a name="TextFormatter"></a>
1553
1585
 
1554
- | Param | Type | Default | Description |
1555
- | --- | --- | --- | --- |
1556
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a numeric or numeral.</p> |
1586
+ ## TextFormatter
1587
+ <p>Formats a song into a plain text chord sheet</p>
1557
1588
 
1558
- <a name="Chord+isChordSolfege"></a>
1589
+ **Kind**: global class
1590
+ <a name="TextFormatter+format"></a>
1559
1591
 
1560
- ### chord.isChordSolfege() ⇒ <code>boolean</code>
1561
- <p>Determines whether the chord is a chord solfege</p>
1592
+ ### textFormatter.format(song) ⇒ <code>string</code>
1593
+ <p>Formats a song into a plain text chord sheet</p>
1562
1594
 
1563
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1564
- <a name="Chord+toNumeric"></a>
1595
+ **Kind**: instance method of [<code>TextFormatter</code>](#TextFormatter)
1596
+ **Returns**: <code>string</code> - <p>the chord sheet</p>
1565
1597
 
1566
- ### chord.toNumeric([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1567
- <p>Converts the chord to a numeric chord, using the supplied key as a reference.
1568
- For example, a chord symbol A# with reference key E will return the numeric chord #4.</p>
1598
+ | Param | Type | Description |
1599
+ | --- | --- | --- |
1600
+ | song | [<code>Song</code>](#Song) | <p>The song to be formatted</p> |
1569
1601
 
1570
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1571
- **Returns**: [<code>Chord</code>](#Chord) - <p>the numeric chord</p>
1602
+ <a name="Key"></a>
1572
1603
 
1573
- | Param | Type | Default | Description |
1574
- | --- | --- | --- | --- |
1575
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1604
+ ## Key
1605
+ <p>Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).</p>
1606
+ <p>The only function considered public API is <code>Key.distance</code></p>
1576
1607
 
1577
- <a name="Chord+toNumeral"></a>
1608
+ **Kind**: global class
1609
+ <a name="Key.distance"></a>
1578
1610
 
1579
- ### chord.toNumeral([referenceKey]) ⇒ [<code>Chord</code>](#Chord)
1580
- <p>Converts the chord to a numeral chord, using the supplied key as a reference.
1581
- For example, a chord symbol A# with reference key E will return the numeral chord #IV.</p>
1611
+ ### Key.distance(oneKey, otherKey) ⇒ <code>number</code>
1612
+ <p>Calculates the distance in semitones between one key and another.</p>
1582
1613
 
1583
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1584
- **Returns**: [<code>Chord</code>](#Chord) - <p>the numeral chord</p>
1614
+ **Kind**: static method of [<code>Key</code>](#Key)
1615
+ **Returns**: <code>number</code> - <p>the distance in semitones</p>
1585
1616
 
1586
- | Param | Type | Default | Description |
1587
- | --- | --- | --- | --- |
1588
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1617
+ | Param | Type | Description |
1618
+ | --- | --- | --- |
1619
+ | oneKey | [<code>Key</code>](#Key) \| <code>string</code> | <p>the key</p> |
1620
+ | otherKey | [<code>Key</code>](#Key) \| <code>string</code> | <p>the other key</p> |
1589
1621
 
1590
- <a name="Chord+toNumeralString"></a>
1622
+ <a name="ChordProParser"></a>
1591
1623
 
1592
- ### chord.toNumeralString([referenceKey]) ⇒ <code>string</code>
1593
- <p>Converts the chord to a numeral chord string, using the supplied kye as a reference.
1594
- For example, a chord symbol A# with reference key E will return the numeral chord #4.</p>
1624
+ ## ChordProParser
1625
+ <p>Parses a ChordPro chord sheet</p>
1595
1626
 
1596
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1597
- **Returns**: <code>string</code> - <p>the numeral chord string</p>
1598
- **See**: {toNumeral}
1627
+ **Kind**: global class
1599
1628
 
1600
- | Param | Type | Default | Description |
1601
- | --- | --- | --- | --- |
1602
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1629
+ * [ChordProParser](#ChordProParser)
1630
+ * [.warnings](#ChordProParser+warnings) : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1631
+ * [.parse(chordSheet, options)](#ChordProParser+parse) ⇒ [<code>Song</code>](#Song)
1603
1632
 
1604
- <a name="Chord+isNumeric"></a>
1633
+ <a name="ChordProParser+warnings"></a>
1605
1634
 
1606
- ### chord.isNumeric() ⇒ <code>boolean</code>
1607
- <p>Determines whether the chord is numeric</p>
1635
+ ### chordProParser.warnings : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1636
+ <p>All warnings raised during parsing the chord sheet</p>
1608
1637
 
1609
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1610
- <a name="Chord+toNumericString"></a>
1638
+ **Kind**: instance property of [<code>ChordProParser</code>](#ChordProParser)
1639
+ <a name="ChordProParser+parse"></a>
1611
1640
 
1612
- ### chord.toNumericString([referenceKey]) ⇒ <code>string</code>
1613
- <p>Converts the chord to a numeric chord string, using the supplied kye as a reference.
1614
- For example, a chord symbol A# with reference key E will return the numeric chord #4.</p>
1641
+ ### chordProParser.parse(chordSheet, options) ⇒ [<code>Song</code>](#Song)
1642
+ <p>Parses a ChordPro chord sheet into a song</p>
1615
1643
 
1616
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1617
- **Returns**: <code>string</code> - <p>the numeric chord string</p>
1618
- **See**: {toNumeric}
1644
+ **Kind**: instance method of [<code>ChordProParser</code>](#ChordProParser)
1645
+ **Returns**: [<code>Song</code>](#Song) - <p>The parsed song</p>
1646
+ **See**: https://peggyjs.org/documentation.html#using-the-parser
1619
1647
 
1620
1648
  | Param | Type | Default | Description |
1621
1649
  | --- | --- | --- | --- |
1622
- | [referenceKey] | [<code>Key</code>](#Key) \| <code>string</code> \| <code>null</code> | <code></code> | <p>the reference key. The key is required when converting a chord symbol</p> |
1623
-
1624
- <a name="Chord+isNumeral"></a>
1650
+ | chordSheet | <code>string</code> | | <p>the ChordPro chord sheet</p> |
1651
+ | options | <code>ChordProParserOptions</code> | | <p>Parser options.</p> |
1652
+ | options.softLineBreaks | <code>ChordProParserOptions.softLineBreaks</code> | <code>false</code> | <p>If true, a backslash followed by * a space is treated as a soft line break</p> |
1625
1653
 
1626
- ### chord.isNumeral() ⇒ <code>boolean</code>
1627
- <p>Determines whether the chord is a numeral</p>
1654
+ <a name="ChordSheetParser"></a>
1628
1655
 
1629
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1630
- <a name="Chord+toString"></a>
1656
+ ## ~~ChordSheetParser~~
1657
+ ***Deprecated***
1631
1658
 
1632
- ### chord.toString([configuration]) ⇒ <code>string</code>
1633
- <p>Converts the chord to a string, eg <code>Esus4/G#</code> or <code>1sus4/#3</code></p>
1659
+ <p>Parses a normal chord sheet</p>
1660
+ <p>ChordSheetParser is deprecated, please use ChordsOverWordsParser.</p>
1661
+ <p>ChordsOverWordsParser aims to support any kind of chord, whereas ChordSheetParser lacks
1662
+ support for many variations. Besides that, some chordpro feature have been ported back
1663
+ to ChordsOverWordsParser, which adds some interesting functionality.</p>
1634
1664
 
1635
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1636
- **Returns**: <code>string</code> - <p>the chord string</p>
1665
+ **Kind**: global class
1637
1666
 
1638
- | Param | Type | Default | Description |
1639
- | --- | --- | --- | --- |
1640
- | [configuration] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1641
- | [configuration.useUnicodeModifier] | <code>boolean</code> | <code>false</code> | <p>Whether or not to use unicode modifiers. This will make <code>#</code> (sharp) look like <code>♯</code> and <code>b</code> (flat) look like <code>♭</code></p> |
1667
+ * ~~[ChordSheetParser](#ChordSheetParser)~~
1668
+ * [new ChordSheetParser([options])](#new_ChordSheetParser_new)
1669
+ * [.parse(chordSheet, [options])](#ChordSheetParser+parse) ⇒ [<code>Song</code>](#Song)
1642
1670
 
1643
- <a name="Chord+normalize"></a>
1671
+ <a name="new_ChordSheetParser_new"></a>
1644
1672
 
1645
- ### chord.normalize([key], [options]) ⇒ [<code>Chord</code>](#Chord)
1646
- <p>Normalizes the chord root and bass notes:</p>
1647
- <ul>
1648
- <li>Fab becomes Mi</li>
1649
- <li>Dob becomes Si</li>
1650
- <li>Si# becomes Do</li>
1651
- <li>Mi# becomes Fa</li>
1652
- <li>Fb becomes E</li>
1653
- <li>Cb becomes B</li>
1654
- <li>B# becomes C</li>
1655
- <li>E# becomes F</li>
1656
- <li>4b becomes 3</li>
1657
- <li>1b becomes 7</li>
1658
- <li>7# becomes 1</li>
1659
- <li>3# becomes 4</li>
1660
- </ul>
1661
- <p>Besides that it normalizes the suffix if <code>normalizeSuffix</code> is <code>true</code>.
1662
- For example, <code>sus2</code> becomes <code>2</code>, <code>sus4</code> becomes <code>sus</code>.
1663
- All suffix normalizations can be found in <code>src/normalize_mappings/suffix-mapping.txt</code>.</p>
1664
- <p>When the chord is minor, bass notes are normalized off of the relative major
1665
- of the root note. For example, <code>Em/A#</code> becomes <code>Em/Bb</code>.</p>
1673
+ ### new ChordSheetParser([options])
1674
+ <p>Instantiate a chord sheet parser
1675
+ ChordSheetParser is deprecated, please use ChordsOverWordsParser.</p>
1666
1676
 
1667
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1668
- **Returns**: [<code>Chord</code>](#Chord) - <p>the normalized chord</p>
1669
1677
 
1670
1678
  | Param | Type | Default | Description |
1671
1679
  | --- | --- | --- | --- |
1672
- | [key] | [<code>Key</code>](#Key) \| <code>string</code> | <code></code> | <p>the key to normalize to</p> |
1673
1680
  | [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1674
- | [options.normalizeSuffix] | <code>boolean</code> | <code>true</code> | <p>whether to normalize the chord suffix after transposing</p> |
1675
-
1676
- <a name="Chord+useModifier"></a>
1677
-
1678
- ### chord.useModifier(newModifier) ⇒ [<code>Chord</code>](#Chord)
1679
- <p>Switches to the specified modifier</p>
1681
+ | [options.preserveWhitespace] | <code>boolean</code> | <code>true</code> | <p>whether to preserve trailing whitespace for chords</p> |
1680
1682
 
1681
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1682
- **Returns**: [<code>Chord</code>](#Chord) - <p>the new, changed chord</p>
1683
+ <a name="ChordSheetParser+parse"></a>
1683
1684
 
1684
- | Param | Description |
1685
- | --- | --- |
1686
- | newModifier | <p>the modifier to use: <code>'#'</code> or <code>'b'</code></p> |
1685
+ ### chordSheetParser.parse(chordSheet, [options]) ⇒ [<code>Song</code>](#Song)
1686
+ <p>Parses a chord sheet into a song</p>
1687
1687
 
1688
- <a name="Chord+transposeUp"></a>
1688
+ **Kind**: instance method of [<code>ChordSheetParser</code>](#ChordSheetParser)
1689
+ **Returns**: [<code>Song</code>](#Song) - <p>The parsed song</p>
1689
1690
 
1690
- ### chord.transposeUp() ⇒ [<code>Chord</code>](#Chord)
1691
- <p>Transposes the chord up by 1 semitone. Eg. A becomes A#, Eb becomes E</p>
1691
+ | Param | Type | Default | Description |
1692
+ | --- | --- | --- | --- |
1693
+ | chordSheet | <code>string</code> | | <p>The ChordPro chord sheet</p> |
1694
+ | [options] | <code>Object</code> | <code>{}</code> | <p>Optional parser options</p> |
1695
+ | [options.song] | [<code>Song</code>](#Song) | <code></code> | <p>The [Song](#Song) to store the song data in</p> |
1692
1696
 
1693
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1694
- **Returns**: [<code>Chord</code>](#Chord) - <p>the new, transposed chord</p>
1695
- <a name="Chord+transposeDown"></a>
1697
+ <a name="ChordsOverWordsParser"></a>
1696
1698
 
1697
- ### chord.transposeDown() ⇒ [<code>Chord</code>](#Chord)
1698
- <p>Transposes the chord down by 1 semitone. Eg. A# becomes A, E becomes Eb</p>
1699
+ ## ChordsOverWordsParser
1700
+ <p>Parses a chords over words sheet into a song</p>
1701
+ <p>It support &quot;regular&quot; chord sheets:</p>
1702
+ <pre><code> Am C/G F C
1703
+ Let it be, let it be, let it be, let it be
1704
+ C G F C/E Dm C
1705
+ Whisper words of wisdom, let it be
1706
+ </code></pre>
1707
+ <p>Additionally, some chordpro features have been &quot;ported back&quot;. For example, you can use chordpro directives:</p>
1708
+ <pre><code>{title: Let it be}
1709
+ {key: C}
1710
+ Chorus 1:
1711
+ Am
1712
+ Let it be
1713
+ </code></pre>
1714
+ <p>For convenience, you can leave out the brackets:</p>
1715
+ <pre><code>title: Let it be
1716
+ Chorus 1:
1717
+ Am
1718
+ Let it be
1719
+ </code></pre>
1720
+ <p>You can even use a markdown style frontmatter separator to separate the header from the song:</p>
1721
+ <pre><code>title: Let it be
1722
+ key: C
1723
+ ---
1724
+ Chorus 1:
1725
+ Am C/G F C
1726
+ Let it be, let it be, let it be, let it be
1727
+ C G F C/E Dm C
1728
+ Whisper words of wisdom, let it be
1729
+ </code></pre>
1730
+ <p><code>ChordsOverWordsParser</code> is the better version of <code>ChordSheetParser</code>, which is deprecated.</p>
1699
1731
 
1700
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1701
- **Returns**: [<code>Chord</code>](#Chord) - <p>the new, transposed chord</p>
1702
- <a name="Chord+transpose"></a>
1732
+ **Kind**: global class
1703
1733
 
1704
- ### chord.transpose(delta) ⇒ [<code>Chord</code>](#Chord)
1705
- <p>Transposes the chord by the specified number of semitones</p>
1734
+ * [ChordsOverWordsParser](#ChordsOverWordsParser)
1735
+ * [.warnings](#ChordsOverWordsParser+warnings) : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1736
+ * [.parse(chordSheet, options)](#ChordsOverWordsParser+parse) ⇒ [<code>Song</code>](#Song)
1706
1737
 
1707
- **Kind**: instance method of [<code>Chord</code>](#Chord)
1708
- **Returns**: [<code>Chord</code>](#Chord) - <p>the new, transposed chord</p>
1738
+ <a name="ChordsOverWordsParser+warnings"></a>
1709
1739
 
1710
- | Param | Description |
1711
- | --- | --- |
1712
- | delta | <p>de number of semitones</p> |
1740
+ ### chordsOverWordsParser.warnings : [<code>Array.&lt;ParserWarning&gt;</code>](#ParserWarning)
1741
+ <p>All warnings raised during parsing the chord sheet</p>
1713
1742
 
1714
- <a name="Chord.parse"></a>
1743
+ **Kind**: instance property of [<code>ChordsOverWordsParser</code>](#ChordsOverWordsParser)
1744
+ <a name="ChordsOverWordsParser+parse"></a>
1715
1745
 
1716
- ### Chord.parse(chordString) ⇒ [<code>Chord</code>](#Chord) \| <code>null</code>
1717
- <p>Tries to parse a chord string into a chord
1718
- Any leading or trailing whitespace is removed first, so a chord like <code> \n E/G# \r</code> is valid.</p>
1746
+ ### chordsOverWordsParser.parse(chordSheet, options) ⇒ [<code>Song</code>](#Song)
1747
+ <p>Parses a chords over words sheet into a song</p>
1719
1748
 
1720
- **Kind**: static method of [<code>Chord</code>](#Chord)
1749
+ **Kind**: instance method of [<code>ChordsOverWordsParser</code>](#ChordsOverWordsParser)
1750
+ **Returns**: [<code>Song</code>](#Song) - <p>The parsed song</p>
1751
+ **See**: https://peggyjs.org/documentation.html#using-the-parser
1721
1752
 
1722
- | Param | Description |
1723
- | --- | --- |
1724
- | chordString | <p>the chord string, eg <code>Esus4/G#</code> or <code>1sus4/#3</code>.</p> |
1753
+ | Param | Type | Default | Description |
1754
+ | --- | --- | --- | --- |
1755
+ | chordSheet | <code>string</code> | | <p>the chords over words sheet</p> |
1756
+ | options | <code>ChordsOverWordsParserOptions</code> | | <p>Parser options.</p> |
1757
+ | options.softLineBreaks | <code>ChordsOverWordsParserOptions.softLineBreaks</code> | <code>false</code> | <p>If true, a backslash followed by a space is treated as a soft line break</p> |
1725
1758
 
1726
- <a name="ChordSheetSerializer"></a>
1759
+ <a name="ParserWarning"></a>
1727
1760
 
1728
- ## ChordSheetSerializer
1729
- <p>Serializes a song into een plain object, and deserializes the serialized object back into a [Song](#Song)</p>
1761
+ ## ParserWarning
1762
+ <p>Represents a parser warning, currently only used by ChordProParser.</p>
1730
1763
 
1731
1764
  **Kind**: global class
1765
+ <a name="ParserWarning+toString"></a>
1732
1766
 
1733
- * [ChordSheetSerializer](#ChordSheetSerializer)
1734
- * [.serialize()](#ChordSheetSerializer+serialize) ⇒
1735
- * [.deserialize(serializedSong)](#ChordSheetSerializer+deserialize) ⇒ [<code>Song</code>](#Song)
1736
-
1737
- <a name="ChordSheetSerializer+serialize"></a>
1738
-
1739
- ### chordSheetSerializer.serialize() ⇒
1740
- <p>Serializes the chord sheet to a plain object, which can be converted to any format like JSON, XML etc
1741
- Can be deserialized using [deserialize](deserialize)</p>
1742
-
1743
- **Kind**: instance method of [<code>ChordSheetSerializer</code>](#ChordSheetSerializer)
1744
- **Returns**: <p>object A plain JS object containing all chord sheet data</p>
1745
- <a name="ChordSheetSerializer+deserialize"></a>
1746
-
1747
- ### chordSheetSerializer.deserialize(serializedSong) ⇒ [<code>Song</code>](#Song)
1748
- <p>Deserializes a song that has been serialized using [serialize](serialize)</p>
1749
-
1750
- **Kind**: instance method of [<code>ChordSheetSerializer</code>](#ChordSheetSerializer)
1751
- **Returns**: [<code>Song</code>](#Song) - <p>The deserialized song</p>
1752
-
1753
- | Param | Type | Description |
1754
- | --- | --- | --- |
1755
- | serializedSong | <code>object</code> | <p>The serialized song</p> |
1767
+ ### parserWarning.toString() ⇒ <code>string</code>
1768
+ <p>Returns a stringified version of the warning</p>
1756
1769
 
1757
- <a name="Key"></a>
1770
+ **Kind**: instance method of [<code>ParserWarning</code>](#ParserWarning)
1771
+ **Returns**: <code>string</code> - <p>The string warning</p>
1772
+ <a name="UltimateGuitarParser"></a>
1758
1773
 
1759
- ## Key
1760
- <p>Represents a key, such as Eb (symbol), #3 (numeric) or VII (numeral).</p>
1761
- <p>The only function considered public API is <code>Key.distance</code></p>
1774
+ ## UltimateGuitarParser
1775
+ <p>Parses an Ultimate Guitar chord sheet with metadata
1776
+ Inherits from [ChordSheetParser](#ChordSheetParser)</p>
1762
1777
 
1763
1778
  **Kind**: global class
1764
- <a name="Key.distance"></a>
1779
+ <a name="new_UltimateGuitarParser_new"></a>
1765
1780
 
1766
- ### Key.distance(oneKey, otherKey) ⇒ <code>number</code>
1767
- <p>Calculates the distance in semitones between one key and another.</p>
1781
+ ### new UltimateGuitarParser([options])
1782
+ <p>Instantiate a chord sheet parser</p>
1768
1783
 
1769
- **Kind**: static method of [<code>Key</code>](#Key)
1770
- **Returns**: <code>number</code> - <p>the distance in semitones</p>
1771
1784
 
1772
- | Param | Type | Description |
1773
- | --- | --- | --- |
1774
- | oneKey | [<code>Key</code>](#Key) \| <code>string</code> | <p>the key</p> |
1775
- | otherKey | [<code>Key</code>](#Key) \| <code>string</code> | <p>the other key</p> |
1785
+ | Param | Type | Default | Description |
1786
+ | --- | --- | --- | --- |
1787
+ | [options] | <code>Object</code> | <code>{}</code> | <p>options</p> |
1788
+ | [options.preserveWhitespace] | <code>boolean</code> | <code>true</code> | <p>whether to preserve trailing whitespace for chords</p> |
1776
1789
 
1777
1790
  <a name="ALBUM"></a>
1778
1791