chordsheetjs 6.2.0 → 7.0.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
@@ -631,10 +633,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 +669,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 +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)  
@@ -694,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>
@@ -709,8 +738,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

package/lib/bundle.js

@@ -1,4 +1,5 @@
 (function(f){if(typeof exports==="object"&&typeof module!=="undefined"){module.exports=f()}else if(typeof define==="function"&&define.amd){define([],f)}else{var g;if(typeof window!=="undefined"){g=window}else if(typeof global!=="undefined"){g=global}else if(typeof self!=="undefined"){g=self}else{g=this}g.ChordSheetJS = f()}})(function(){var define,module,exports;return (function(){function r(e,n,t){function o(i,f){if(!n[i]){if(!e[i]){var c="function"==typeof require&&require;if(!f&&c)return c(i,!0);if(u)return u(i,!0);var a=new Error("Cannot find module '"+i+"'");throw a.code="MODULE_NOT_FOUND",a}var p=n[i]={exports:{}};e[i][0].call(p.exports,function(r){var n=e[i][1][r];return o(n||r)},p,p.exports,r,e,n,t)}return n[i].exports}for(var u="function"==typeof require&&require,i=0;i<t.length;i++)o(t[i]);return o}return r})()({1:[function(require,module,exports){
+var $988mA$process = require("process");
 var $988mA$lodashget = require("lodash.get");
 var $988mA$handlebars = require("handlebars");
 
@@ -1944,6 +1945,7 @@ var $6ebb068142750218$export$2e2bcd8739ae039 = {
 };
 
 
+
 const $21a34a464e7bc609$export$13215d9ce4923f76 = (collection, Klass)=>{
     const newObject = new Klass();
     collection.push(newObject);
@@ -1981,11 +1983,10 @@ ${scopedSelector} {
     }).join('\n\n');
 }
 function $21a34a464e7bc609$export$b680e6b2c82f8c2f(message) {
-    const { process: process  } = this;
     try {
         throw new Error(`DEPRECATION: ${message}`);
     } catch (e) {
-        if (typeof process === 'object' && typeof process.emitWarning === 'function') process.emitWarning(`${message}\n${e.stack}`);
+        if (typeof $988mA$process === 'object' && typeof $988mA$process.emitWarning === 'function') $988mA$process.emitWarning(`${message}\n${e.stack}`);
         else console.warn(`${message}\n${e.stack}`);
     }
 }
@@ -1993,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);
@@ -3387,6 +3389,11 @@ var $26f57998457eb2d4$export$2e2bcd8739ae039 = $26f57998457eb2d4$var$Chord;
     set(properties) {
         return new $d454f4215ba01af2$var$ChordLyricsPair(properties.chords || this.chords, properties.lyrics || this.lyrics);
     }
+    setLyrics(lyrics) {
+        return this.set({
+            lyrics: lyrics
+        });
+    }
     transpose(delta, key) {
         const chordObj = $26f57998457eb2d4$export$2e2bcd8739ae039.parse(this.chords);
         if (chordObj) return this.set({
@@ -3563,6 +3570,11 @@ const $5e9ede69210ec54a$var$translateTagNameAlias = (name)=>{
     set({ value: value  }) {
         return new $5e9ede69210ec54a$var$Tag(this._originalName, value);
     }
+    setValue(value) {
+        return this.set({
+            value: value
+        });
+    }
 }
 var $5e9ede69210ec54a$export$2e2bcd8739ae039 = $5e9ede69210ec54a$var$Tag;
 
@@ -3961,12 +3973,7 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
    * The {@link Line} items of which the song consists
    * @member {Line[]}
    */ lines = [];
-    /**
-   * The {@link Paragraph} items of which the song consists
-   * @member {Paragraph[]}
-   */ paragraphs = [];
     currentLine = null;
-    currentParagraph = null;
     warnings = [];
     sectionType = $af8d31735c159a26$export$c53d0f541b41b88e;
     currentKey = null;
@@ -4015,37 +4022,35 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
         this.ensureLine();
         this.currentLine.lyrics(chr);
     }
-    addLine() {
-        this.ensureParagraph();
-        this.flushLine();
-        this.currentLine = $21a34a464e7bc609$export$13215d9ce4923f76(this.lines, $bc411321e9739719$export$2e2bcd8739ae039);
+    addLine(line) {
+        this.currentLine = line || $21a34a464e7bc609$export$13215d9ce4923f76(this.lines, $bc411321e9739719$export$2e2bcd8739ae039);
         this.setCurrentLineType(this.sectionType);
         this.currentLine.transposeKey = this.transposeKey ?? this.currentKey;
         this.currentLine.key = this.currentKey || this.metadata.getSingle($5e9ede69210ec54a$export$7167c830cefcb6b5);
         return this.currentLine;
     }
+    /**
+   * The {@link Paragraph} items of which the song consists
+   * @member {Paragraph[]}
+   */ get paragraphs() {
+        let currentParagraph = new $0c3420c6a3e8a9d7$export$2e2bcd8739ae039();
+        const paragraphs = [
+            currentParagraph
+        ];
+        this.lines.forEach((line)=>{
+            if (line.isEmpty()) {
+                currentParagraph = new $0c3420c6a3e8a9d7$export$2e2bcd8739ae039();
+                paragraphs.push(currentParagraph);
+            } else if (line.hasRenderableItems()) currentParagraph.addLine(line);
+        });
+        return paragraphs;
+    }
     setCurrentLineType(sectionType) {
         this.currentLine.type = sectionType;
     }
-    flushLine() {
-        if (this.currentLine !== null) {
-            if (this.currentLine.isEmpty()) this.addParagraph();
-            else if (this.currentLine.hasRenderableItems()) this.currentParagraph.addLine(this.currentLine);
-        }
-    }
-    finish() {
-        this.flushLine();
-    }
     ensureLine() {
         if (this.currentLine === null) this.addLine();
     }
-    addParagraph() {
-        this.currentParagraph = $21a34a464e7bc609$export$13215d9ce4923f76(this.paragraphs, $0c3420c6a3e8a9d7$export$2e2bcd8739ae039);
-        return this.currentParagraph;
-    }
-    ensureParagraph() {
-        if (this.currentParagraph === null) this.addParagraph();
-    }
     addTag(tagContents) {
         const tag = $5e9ede69210ec54a$export$2e2bcd8739ae039.parse(tagContents);
         if (tag.isMetaTag()) this.setMetadata(tag.name, tag.value);
@@ -4107,7 +4112,8 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
    * Returns a deep clone of the song
    * @returns {Song} The cloned song
    */ clone() {
-        return this.mapItems(null);
+        return this.mapItems((item)=>item
+        );
     }
     setMetadata(name, value) {
         this.metadata.add(name, value);
@@ -4124,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  } = {}) {
@@ -4178,19 +4219,53 @@ var $ce1dd7d0f2cd2369$export$2e2bcd8739ae039 = $ce1dd7d0f2cd2369$var$ParserWarni
         ];
         return clonedSong;
     }
-    mapItems(func) {
+    /**
+   * Change the song contents inline. Return a new {@link Item} to replace it. Return `null` to remove it.
+   * @example
+   * // transpose all chords:
+   * song.mapItems((item) => {
+   *   if (item instanceof ChordLyricsPair) {
+   *     return item.transpose(2, 'D');
+   *   }
+   *
+   *   return item;
+   * });
+   * @param {MapItemsCallback} func the callback function
+   * @returns {Song} the changed song
+   */ mapItems(func) {
         const clonedSong = new $6f653df65dfdf4ef$var$Song();
-        clonedSong.lines = this.lines.map((line)=>line.mapItems(func)
-        );
-        clonedSong.metadata = this.metadata.clone();
+        this.lines.forEach((line)=>{
+            clonedSong.addLine();
+            line.items.forEach((item)=>{
+                const changedItem = func(item);
+                if (changedItem) clonedSong.addItem(changedItem);
+            });
+        });
         return clonedSong;
     }
-    mapLines(func) {
+    /**
+   * Change the song contents inline. Return a new {@link Line} to replace it. Return `null` to remove it.
+   * @example
+   * // remove lines with only Tags:
+   * song.mapLines((line) => {
+   *   if (line.items.every(item => item instanceof Tag)) {
+   *     return null;
+   *   }
+   *
+   *   return line;
+   * });
+   * @param {MapLinesCallback} func the callback function
+   * @returns {Song} the changed song
+   */ mapLines(func) {
         const clonedSong = new $6f653df65dfdf4ef$var$Song();
-        clonedSong.lines = this.lines.map((line)=>func(line.clone())
-        ).filter((line)=>line
-        );
-        clonedSong.metadata = this.metadata.clone();
+        this.lines.forEach((line)=>{
+            const changedLine = func(line);
+            if (changedLine) {
+                clonedSong.addLine();
+                changedLine.items.forEach((item)=>clonedSong.addItem(item)
+                );
+            }
+        });
         return clonedSong;
     }
     updateItem(findCallback, updateCallback, notFoundCallback) {
@@ -4393,7 +4468,6 @@ const $1c14afc274b727b7$var$LINE = 'line';
    * @returns {Song} The deserialized song
    */ deserialize(serializedSong) {
         this.parseAstComponent(serializedSong);
-        this.song.finish();
         return this.song;
     }
     parseAstComponent(astComponent) {
@@ -4527,7 +4601,6 @@ const $c049675f48c823b2$var$CHORD_LINE_REGEX = /^\s*((([A-G])(#|b)?([^/\s]*)(\/(
             this.parseLine(line);
         }
         this.endOfSong();
-        this.song.finish();
         return this.song;
     }
     endOfSong() {}
@@ -6288,7 +6361,7 @@ var $882b6d93070905b3$export$2e2bcd8739ae039 = {
 
 
 
-},{"handlebars":35,"lodash.get":36}],2:[function(require,module,exports){
+},{"handlebars":35,"lodash.get":36,"process":48}],2:[function(require,module,exports){
 
 },{}],3:[function(require,module,exports){
 'use strict';
@@ -15349,5 +15422,8 @@ exports.SourceMapGenerator = require('./lib/source-map-generator').SourceMapGene
 exports.SourceMapConsumer = require('./lib/source-map-consumer').SourceMapConsumer;
 exports.SourceNode = require('./lib/source-node').SourceNode;
 
-},{"./lib/source-map-consumer":43,"./lib/source-map-generator":44,"./lib/source-node":45}]},{},[1])(1)
+},{"./lib/source-map-consumer":43,"./lib/source-map-generator":44,"./lib/source-node":45}],48:[function(require,module,exports){
+module.exports = {"browser": true}
+
+},{}]},{},[1])(1)
 });

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>