chordsheetjs 6.2.2 → 7.1.0

package/README.md

@@ -1,4 +1,4 @@
-# ChordChartJS [![Code Climate](https://codeclimate.com/github/PraiseCharts/ChordChartJS/badges/gpa.svg)](https://codeclimate.com/github/PraiseCharts/ChordChartJS)
+# ChordSheetJS [![Code Climate](https://codeclimate.com/github/martijnversluis/ChordSheetJS/badges/gpa.svg)](https://codeclimate.com/github/martijnversluis/ChordSheetJS)
 
 A JavaScript library for parsing and formatting chord sheets
 
@@ -11,6 +11,8 @@ A JavaScript library for parsing and formatting chord sheets
 
 ## Installation
 
+### Package managers
+
 `ChordSheetJS` is on npm, to install run:
 
 ```bash
@@ -422,7 +424,8 @@ Inherits from [ChordSheetParser](#ChordSheetParser)</p></dd>
 <dt><a href="#END_OF_VERSE">END_OF_VERSE</a> : <code>string</code></dt>
 <dd><p>Key meta directive. See https://www.chordpro.org/chordpro/directives-key/</p></dd>
 <dt><a href="#KEY">KEY</a> : <code>string</code></dt>
-<dd><p>Key meta directive. See https://www.chordpro.org/chordpro/directives-key/</p></dd>
+<dd><p>_Key meta directive. Reflects the key as transposed by the capo value
+See https://www.chordpro.org/chordpro/directives-key/</p></dd>
 <dt><a href="#_KEY">_KEY</a> : <code>string</code></dt>
 <dd><p>Lyricist meta directive. See https://www.chordpro.org/chordpro/directives-lyricist/</p></dd>
 <dt><a href="#LYRICIST">LYRICIST</a> : <code>string</code></dt>
@@ -631,10 +634,15 @@ If not, it returns [INDETERMINATE](#INDETERMINATE)</p>
     * [new Song(metadata)](#new_Song_new)
     * [.bodyLines](#Song+bodyLines) ⇒ <code>Array.&lt;Line&gt;</code>
     * [.bodyParagraphs](#Song+bodyParagraphs) ⇒ [<code>Array.&lt;Paragraph&gt;</code>](#Paragraph)
+    * [.paragraphs](#Song+paragraphs) : [<code>Array.&lt;Paragraph&gt;</code>](#Paragraph)
     * ~~[.metaData](#Song+metaData) ⇒~~
     * [.clone()](#Song+clone) ⇒ [<code>Song</code>](#Song)
-    * [.setCapo(capo)](#Song+setCapo) ⇒ [<code>Song</code>](#Song)
     * [.setKey(key)](#Song+setKey) ⇒ [<code>Song</code>](#Song)
+    * [.setCapo(capo)](#Song+setCapo) ⇒ [<code>Song</code>](#Song)
+    * [.changeKey(newKey)](#Song+changeKey) ⇒ [<code>Song</code>](#Song)
+    * [.changeMetadata(name, value)](#Song+changeMetadata)
+    * [.mapItems(func)](#Song+mapItems) ⇒ [<code>Song</code>](#Song)
+    * [.mapLines(func)](#Song+mapLines) ⇒ [<code>Song</code>](#Song)
 
 <a name="new_Song_new"></a>
 
@@ -662,6 +670,12 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 **Kind**: instance property of [<code>Song</code>](#Song)  
 **See**: [bodyLines](bodyLines)  
+<a name="Song+paragraphs"></a>
+
+### song.paragraphs : [<code>Array.&lt;Paragraph&gt;</code>](#Paragraph)
+<p>The [Paragraph](#Paragraph) items of which the song consists</p>
+
+**Kind**: instance property of [<code>Song</code>](#Song)  
 <a name="Song+metaData"></a>
 
 ### ~~song.metaData ⇒~~
@@ -678,13 +692,29 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 **Kind**: instance method of [<code>Song</code>](#Song)  
 **Returns**: [<code>Song</code>](#Song) - <p>The cloned song</p>  
+<a name="Song+setKey"></a>
+
+### song.setKey(key) ⇒ [<code>Song</code>](#Song)
+<p>Returns a copy of the song with the key value set to the specified key. It changes:</p>
+<ul>
+<li>the value for <code>key</code> in the <code>metadata</code> set</li>
+<li>any existing <code>key</code> directive</li>
+</ul>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>The changed song</p>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| key | <code>number</code> \| <code>null</code> | <p>the key. Passing <code>null</code> will:</p> <ul> <li>remove the current key from <code>metadata</code></li> <li>remove any <code>key</code> directive</li> </ul> |
+
 <a name="Song+setCapo"></a>
 
 ### song.setCapo(capo) ⇒ [<code>Song</code>](#Song)
-<p>Returns a copy of the song with the capo value set to the specified capo. It changes:</p>
+<p>Returns a copy of the song with the key value set to the specified capo. It changes:</p>
 <ul>
 <li>the value for <code>capo</code> in the <code>metadata</code> set</li>
-<li>any existing <code>capo</code> directive)</li>
+<li>any existing <code>capo</code> directive</li>
 </ul>
 
 **Kind**: instance method of [<code>Song</code>](#Song)  
@@ -694,9 +724,9 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 | --- | --- | --- |
 | capo | <code>number</code> \| <code>null</code> | <p>the capo. Passing <code>null</code> will:</p> <ul> <li>remove the current key from <code>metadata</code></li> <li>remove any <code>capo</code> directive</li> </ul> |
 
-<a name="Song+setKey"></a>
+<a name="Song+changeKey"></a>
 
-### song.setKey(key) ⇒ [<code>Song</code>](#Song)
+### song.changeKey(newKey) ⇒ [<code>Song</code>](#Song)
 <p>Returns a copy of the song with the key set to the specified key. It changes:</p>
 <ul>
 <li>the value for <code>key</code> in the <code>metadata</code> set</li>
@@ -709,8 +739,71 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 | Param | Type | Description |
 | --- | --- | --- |
-| key | <code>string</code> | <p>The new key.</p> |
+| newKey | <code>string</code> | <p>The new key.</p> |
+
+<a name="Song+changeMetadata"></a>
 
+### song.changeMetadata(name, value)
+<p>Returns a copy of the song with the directive value set to the specified value.</p>
+<ul>
+<li>when there is a matching directive in the song, it will update the directive</li>
+<li>when there is no matching directive, it will be inserted
+If <code>value</code> is <code>null</code> it will act as a delete, any directive matching <code>name</code> will be removed.</li>
+</ul>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| name | <code>string</code> | <p>The directive name</p> |
+| value | <code>string</code> \| <code>null</code> | <p>The value to set, or <code>null</code> to remove the directive</p> |
+
+<a name="Song+mapItems"></a>
+
+### song.mapItems(func) ⇒ [<code>Song</code>](#Song)
+<p>Change the song contents inline. Return a new [Item](Item) to replace it. Return <code>null</code> to remove it.</p>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>the changed song</p>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| func | <code>MapItemsCallback</code> | <p>the callback function</p> |
+
+**Example**  
+```js
+// transpose all chords:
+song.mapItems((item) => {
+  if (item instanceof ChordLyricsPair) {
+    return item.transpose(2, 'D');
+  }
+
+  return item;
+});
+```
+<a name="Song+mapLines"></a>
+
+### song.mapLines(func) ⇒ [<code>Song</code>](#Song)
+<p>Change the song contents inline. Return a new [Line](Line) to replace it. Return <code>null</code> to remove it.</p>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>the changed song</p>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| func | <code>MapLinesCallback</code> | <p>the callback function</p> |
+
+**Example**  
+```js
+// remove lines with only Tags:
+song.mapLines((line) => {
+  if (line.items.every(item => item instanceof Tag)) {
+    return null;
+  }
+
+  return line;
+});
+```
 <a name="Tag"></a>
 
 ## Tag
@@ -1335,7 +1428,8 @@ Can be deserialized using [deserialize](deserialize)</p>
 <a name="KEY"></a>
 
 ## KEY : <code>string</code>
-<p>Key meta directive. See https://www.chordpro.org/chordpro/directives-key/</p>
+<p>_Key meta directive. Reflects the key as transposed by the capo value
+See https://www.chordpro.org/chordpro/directives-key/</p>
 
 **Kind**: global variable  
 <a name="_KEY"></a>