chordsheetjs 6.3.0 → 7.2.0

package/README.md

@@ -424,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>
@@ -636,8 +637,13 @@ If not, it returns [INDETERMINATE](#INDETERMINATE)</p>
     * [.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)
+    * [.transpose(delta)](#Song+transpose) ⇒ [<code>Song</code>](#Song)
+    * [.transposeUp()](#Song+transposeUp) ⇒ [<code>Song</code>](#Song)
+    * [.transposeDown()](#Song+transposeDown) ⇒ [<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)
 
@@ -689,13 +695,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 [metadata](metadata) 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 [metadata](metadata)</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>the value for <code>capo</code> in the [metadata](metadata) set</li>
+<li>any existing <code>capo</code> directive</li>
 </ul>
 
 **Kind**: instance method of [<code>Song</code>](#Song)  
@@ -703,14 +725,55 @@ if you want to skip the &quot;header lines&quot;: the lines that only contain me
 
 | Param | Type | Description |
 | --- | --- | --- |
-| 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> |
+| capo | <code>number</code> \| <code>null</code> | <p>the capo. Passing <code>null</code> will:</p> <ul> <li>remove the current key from [metadata](metadata)</li> <li>remove any <code>capo</code> directive</li> </ul> |
 
-<a name="Song+setKey"></a>
+<a name="Song+transpose"></a>
 
-### song.setKey(key) ⇒ [<code>Song</code>](#Song)
+### song.transpose(delta) ⇒ [<code>Song</code>](#Song)
+<p>Transposes the song by the specified delta. It will:</p>
+<ul>
+<li>transpose all chords, see: [transpose](#Chord+transpose)</li>
+<li>transpose the song key in [metadata](metadata)</li>
+<li>update any existing <code>key</code> directive</li>
+</ul>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| delta | <code>number</code> | <p>The number of semitones (positive or negative) to transpose with</p> |
+
+<a name="Song+transposeUp"></a>
+
+### song.transposeUp() ⇒ [<code>Song</code>](#Song)
+<p>Transposes the song up by one semitone. It will:</p>
+<ul>
+<li>transpose all chords, see: [transpose](#Chord+transpose)</li>
+<li>transpose the song key in [metadata](metadata)</li>
+<li>update any existing <code>key</code> directive</li>
+</ul>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
+<a name="Song+transposeDown"></a>
+
+### song.transposeDown() ⇒ [<code>Song</code>](#Song)
+<p>Transposes the song down by one semitone. It will:</p>
+<ul>
+<li>transpose all chords, see: [transpose](#Chord+transpose)</li>
+<li>transpose the song key in [metadata](metadata)</li>
+<li>update any existing <code>key</code> directive</li>
+</ul>
+
+**Kind**: instance method of [<code>Song</code>](#Song)  
+**Returns**: [<code>Song</code>](#Song) - <p>The transposed song</p>  
+<a name="Song+changeKey"></a>
+
+### 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>
+<li>the value for <code>key</code> in the [metadata](metadata) set</li>
 <li>any existing <code>key</code> directive</li>
 <li>all chords, those are transposed according to the distance between the current and the new key</li>
 </ul>
@@ -720,7 +783,24 @@ 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>
 
@@ -1392,7 +1472,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>