chordsheetjs 6.3.0 → 7.0.0

package/README.md

@@ -636,8 +636,10 @@ 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)
+    * [.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 +691,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)  
@@ -705,9 +723,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>
@@ -720,7 +738,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>
 

package/lib/bundle.js

@@ -1994,6 +1994,7 @@ function $21a34a464e7bc609$export$78d1711480f95c3e(string) {
     return string === null || string === undefined || string === '';
 }
 function $21a34a464e7bc609$export$595e981f61839426(string, constructor, regexes) {
+    if ($21a34a464e7bc609$export$78d1711480f95c3e(string)) return null;
     for(let i = 0, count = regexes.length; i < count; i += 1){
         const match = string.match(regexes[i]);
         if (match) return new constructor(match.groups);
@@ -4129,43 +4130,78 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
         return this.metadata[name] || null;
     }
     /**
-   * Returns a copy of the song with the capo value set to the specified capo. It changes:
+   * Returns a copy of the song with the key value set to the specified key. It changes:
+   * - the value for `key` in the `metadata` set
+   * - any existing `key` directive
+   * @param {number|null} key the key. Passing `null` will:
+   * - remove the current key from `metadata`
+   * - remove any `key` directive
+   * @returns {Song} The changed song
+   */ setKey(key) {
+        return this.changeMetadata($5e9ede69210ec54a$export$7167c830cefcb6b5, key);
+    }
+    /**
+   * Returns a copy of the song with the key value set to the specified capo. It changes:
    * - the value for `capo` in the `metadata` set
-   * - any existing `capo` directive)
+   * - any existing `capo` directive
    * @param {number|null} capo the capo. Passing `null` will:
    * - remove the current key from `metadata`
    * - remove any `capo` directive
    * @returns {Song} The changed song
    */ setCapo(capo) {
-        let updatedSong;
-        if (capo === null) updatedSong = this.removeItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === $5e9ede69210ec54a$export$866f445d49bad88e
+        return this.changeMetadata($5e9ede69210ec54a$export$866f445d49bad88e, capo);
+    }
+    setDirective(name, value) {
+        if (value === null) return this.removeItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === name
         );
-        else updatedSong = this.updateItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === $5e9ede69210ec54a$export$866f445d49bad88e
+        return this.updateItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === name
         , (item)=>item.set({
-                value: capo
+                value: value
             })
-        , (song)=>song.insertDirective($5e9ede69210ec54a$export$866f445d49bad88e, capo)
+        , (song)=>song.insertDirective(name, value)
         );
-        updatedSong.metadata.set('capo', capo);
-        return updatedSong;
     }
     /**
    * Returns a copy of the song with the key set to the specified key. It changes:
    * - the value for `key` in the `metadata` set
    * - any existing `key` directive
    * - all chords, those are transposed according to the distance between the current and the new key
-   * @param {string} key The new key.
+   * @param {string} newKey The new key.
    * @returns {Song} The changed song
-   */ setKey(key) {
-        const transpose = $bff5407e03fdc8ee$export$2e2bcd8739ae039.distance(this.key, key);
+   */ changeKey(newKey) {
+        const transpose = this.getTransposeDistance(newKey);
         const updatedSong = this.mapItems((item)=>{
             if (item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === $5e9ede69210ec54a$export$7167c830cefcb6b5) return item.set({
-                value: key
+                value: newKey
             });
-            if (item instanceof $d454f4215ba01af2$export$2e2bcd8739ae039) return item.transpose(transpose, key);
+            if (item instanceof $d454f4215ba01af2$export$2e2bcd8739ae039) return item.transpose(transpose, newKey);
             return item;
         });
-        updatedSong.metadata.set('key', key);
+        updatedSong.metadata.set('key', newKey);
+        return updatedSong;
+    }
+    getTransposeDistance(newKey) {
+        const wrappedKey = $bff5407e03fdc8ee$export$2e2bcd8739ae039.wrap(this.key);
+        if (!wrappedKey) throw new Error(`
+Cannot change song key, the original key is unknown.
+
+Either ensure a key directive is present in the song (when using chordpro):
+  \`{key: C}\`
+
+Or set the song key before changing key:
+  \`song.setKey('C');\``.substring(1));
+        return wrappedKey.distanceTo(newKey);
+    }
+    /**
+   * Returns a copy of the song with the directive value set to the specified value.
+   * - when there is a matching directive in the song, it will update the directive
+   * - when there is no matching directive, it will be inserted
+   * If `value` is `null` it will act as a delete, any directive matching `name` will be removed.
+   * @param {string} name The directive name
+   * @param {string | null} value The value to set, or `null` to remove the directive
+   */ changeMetadata(name, value) {
+        const updatedSong = this.setDirective(name, value);
+        updatedSong.metadata.set(name, value);
         return updatedSong;
     }
     insertDirective(name, value, { after: after = null  } = {}) {

package/lib/index.html

@@ -0,0 +1,40 @@
+<html>
+<head>
+  <script src="bundle.js"></script>
+</head>
+<body>
+  <script type="text/plain" id="chordSheet">
+{title: Let it be}
+{subtitle: ChordSheetJS example version}
+{composer: John Lennon}
+{composer: Paul McCartney}
+{Chorus}
+
+Written by: %{composer}
+
+Let it [Am]be, let it [C/G]be, let it [F]be, let it [C]be
+[C]Whisper words of [G]wisdom, let it [F]be [C/E] [Dm] [C]
+  </script>
+  <style>
+    body {
+      font-family: sans-serif;
+    }
+  </style>
+  <script>
+    const {
+      ChordProParser,
+      HtmlDivFormatter,
+    } = ChordSheetJS;
+
+    const parser = new ChordProParser();
+    const chordpro = document.getElementById("chordSheet").innerText;
+    const song = parser.parse(chordpro);
+    const formatter = new HtmlDivFormatter();
+    const disp = formatter.format(song);
+    const css = HtmlDivFormatter.cssString('.chordSheetViewer');
+
+    document.write(`<style>${css}</style>`);
+    document.write(`<div class="chordSheetViewer">${disp}</div>`);
+  </script>
+</body>
+</html>

package/lib/index.js

@@ -1993,6 +1993,7 @@ function $21a34a464e7bc609$export$78d1711480f95c3e(string) {
     return string === null || string === undefined || string === '';
 }
 function $21a34a464e7bc609$export$595e981f61839426(string, constructor, regexes) {
+    if ($21a34a464e7bc609$export$78d1711480f95c3e(string)) return null;
     for(let i = 0, count = regexes.length; i < count; i += 1){
         const match = string.match(regexes[i]);
         if (match) return new constructor(match.groups);
@@ -4128,43 +4129,78 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
         return this.metadata[name] || null;
     }
     /**
-   * Returns a copy of the song with the capo value set to the specified capo. It changes:
+   * Returns a copy of the song with the key value set to the specified key. It changes:
+   * - the value for `key` in the `metadata` set
+   * - any existing `key` directive
+   * @param {number|null} key the key. Passing `null` will:
+   * - remove the current key from `metadata`
+   * - remove any `key` directive
+   * @returns {Song} The changed song
+   */ setKey(key) {
+        return this.changeMetadata($5e9ede69210ec54a$export$7167c830cefcb6b5, key);
+    }
+    /**
+   * Returns a copy of the song with the key value set to the specified capo. It changes:
    * - the value for `capo` in the `metadata` set
-   * - any existing `capo` directive)
+   * - any existing `capo` directive
    * @param {number|null} capo the capo. Passing `null` will:
    * - remove the current key from `metadata`
    * - remove any `capo` directive
    * @returns {Song} The changed song
    */ setCapo(capo) {
-        let updatedSong;
-        if (capo === null) updatedSong = this.removeItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === $5e9ede69210ec54a$export$866f445d49bad88e
+        return this.changeMetadata($5e9ede69210ec54a$export$866f445d49bad88e, capo);
+    }
+    setDirective(name, value) {
+        if (value === null) return this.removeItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === name
         );
-        else updatedSong = this.updateItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === $5e9ede69210ec54a$export$866f445d49bad88e
+        return this.updateItem((item)=>item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === name
         , (item)=>item.set({
-                value: capo
+                value: value
             })
-        , (song)=>song.insertDirective($5e9ede69210ec54a$export$866f445d49bad88e, capo)
+        , (song)=>song.insertDirective(name, value)
         );
-        updatedSong.metadata.set('capo', capo);
-        return updatedSong;
     }
     /**
    * Returns a copy of the song with the key set to the specified key. It changes:
    * - the value for `key` in the `metadata` set
    * - any existing `key` directive
    * - all chords, those are transposed according to the distance between the current and the new key
-   * @param {string} key The new key.
+   * @param {string} newKey The new key.
    * @returns {Song} The changed song
-   */ setKey(key) {
-        const transpose = $bff5407e03fdc8ee$export$2e2bcd8739ae039.distance(this.key, key);
+   */ changeKey(newKey) {
+        const transpose = this.getTransposeDistance(newKey);
         const updatedSong = this.mapItems((item)=>{
             if (item instanceof $5e9ede69210ec54a$export$2e2bcd8739ae039 && item.name === $5e9ede69210ec54a$export$7167c830cefcb6b5) return item.set({
-                value: key
+                value: newKey
             });
-            if (item instanceof $d454f4215ba01af2$export$2e2bcd8739ae039) return item.transpose(transpose, key);
+            if (item instanceof $d454f4215ba01af2$export$2e2bcd8739ae039) return item.transpose(transpose, newKey);
             return item;
         });
-        updatedSong.metadata.set('key', key);
+        updatedSong.metadata.set('key', newKey);
+        return updatedSong;
+    }
+    getTransposeDistance(newKey) {
+        const wrappedKey = $bff5407e03fdc8ee$export$2e2bcd8739ae039.wrap(this.key);
+        if (!wrappedKey) throw new Error(`
+Cannot change song key, the original key is unknown.
+
+Either ensure a key directive is present in the song (when using chordpro):
+  \`{key: C}\`
+
+Or set the song key before changing key:
+  \`song.setKey('C');\``.substring(1));
+        return wrappedKey.distanceTo(newKey);
+    }
+    /**
+   * Returns a copy of the song with the directive value set to the specified value.
+   * - when there is a matching directive in the song, it will update the directive
+   * - when there is no matching directive, it will be inserted
+   * If `value` is `null` it will act as a delete, any directive matching `name` will be removed.
+   * @param {string} name The directive name
+   * @param {string | null} value The value to set, or `null` to remove the directive
+   */ changeMetadata(name, value) {
+        const updatedSong = this.setDirective(name, value);
+        updatedSong.metadata.set(name, value);
         return updatedSong;
     }
     insertDirective(name, value, { after: after = null  } = {}) {