Support custom properties on themes

sunesimonsen · sunesimonsen · commit b7403abe95b4 · 2015-09-24T13:22:49.000+02:00
Fixes #18
diff --git a/README.md b/README.md
@@ -638,17 +638,18 @@ expect(pen.toString(), 'to equal', '******');
 
 ### installTheme(theme), installTheme(format, theme), installTheme(formats, theme)
 
-MagicPen has support for theming text styles differently for each
-format. A theme is just a hash of aliases to built in text styles or
-aliases to other theme entries. You install the theme for one or more
-formats.
+MagicPen has support for theming text styles differently for each format. A
+number of theme properties together with a `styles` hash with aliases to built in
+text styles or to aliases to other theme entries.
 
 ```js
 pen.installTheme({
-    keyword: 'yellow',
-    functionName: ['green', 'italic'],
-    primitive: '#FF8DFE',
-    number: 'primitive'
+    styles: {
+        keyword: 'yellow',
+        functionName: ['green', 'italic'],
+        primitive: '#FF8DFE',
+        number: 'primitive'
+    }
 });
 ```
 
@@ -688,28 +689,72 @@ usually use when outputting to the html format:
 Let's tweak the html colors without touching the ansi colors:
 
 ```js
-pen.installTheme('html', {
+pen.installTheme('html', { styles: {
     keyword: 'bold',
     functionName: ['#403298', 'italic', 'bold'],
     primitive: '#80417F'
-});
+}});
 ```
 
 ![Fibonacci html output](images/fib-theme-html.png "Fibonacci html output")
 
 You can even extend the current theme:
 
 ```js
-pen.installTheme('html', {
+pen.installTheme('html', { styles: {
     functionName: ['#5B9832', 'bold']
-});
+}});
 ```
 
 ![Fibonacci extended html output](images/fib-theme-extended-html.png "Fibonacci extended html output")
 
-The theme is applied at serialization time, so you can change the theme
-and serialize again with the theme applied without touching the
-content of the pen.
+The theme is applied at serialization time, so you can extend the theme and
+serialize again without touching the content of the pen.
+
+## theme(), theme(format)
+
+You can retrieve information about a theme the following way:
+
+```js
+pen.installTheme('html', {
+    accentColors: ['#D50000', '#C51162', '#AA00FF'],
+    styles: {}
+});
+
+pen.installTheme('ansi', {
+    accentColors: ['#F44336', '#E91E63', '#9C27B0'],
+    styles: {}
+});
+
+expect(pen.theme('html').accentColors,
+       'to equal',
+       ['#D50000', '#C51162', '#AA00FF']);
+
+expect(pen.theme('ansi').accentColors,
+       'to equal',
+       ['#F44336', '#E91E63', '#9C27B0']);
+```
+
+Calling the `theme` method will return the theme for the given format. If the
+format is not specified it will use the format of the pen.
+
+Notice you need a `styles` property even when you don't specify any styles.
+
+Let's use the accent colors define above to make a new style:
+
+```js
+pen.addStyle('colored', function (content) {
+    var accentColors = this.theme().accentColors;
+    var colorIndex = Math.round(Math.random() * (accentColors.length - 1));
+    var color = accentColors[colorIndex];
+    this.text(content, color);
+});
+
+console.log(pen.clone('ansi').colored('Colorful').toString());
+```
+
+The above style will color the given text with one of the accent colors of the
+theme.
 
 ## Aliases
 
diff --git a/lib/MagicPen.js b/lib/MagicPen.js
@@ -613,6 +613,17 @@ MagicPen.prototype.replaceText = function (regexp, cb) {
     return this;
 };
 
+MagicPen.prototype.theme = function (format) {
+    format = format || this.format;
+    if (!format) {
+        throw new Error("Could not detect which format you want to retrieve " +
+                        "theme information for. Set the format of the pen or " +
+                        "provide it as an argument to the theme method.");
+    }
+
+    return this._themes[format];
+};
+
 MagicPen.prototype.installTheme = function (formats, theme) {
     var that = this;
     if (arguments.length === 1) {
@@ -637,7 +648,13 @@ MagicPen.prototype.installTheme = function (formats, theme) {
                         "Install theme for a list of formats: pen.installTheme(['ansi', 'html'], { comment: 'gray' })");
     }
 
-    Object.keys(theme).forEach(function (themeKey) {
+    if (!theme.styles || typeof theme.styles !== 'object') {
+        theme = {
+            styles: theme
+        };
+    }
+
+    Object.keys(theme.styles).forEach(function (themeKey) {
         if (rgbRegexp.test(themeKey) || cssStyles[themeKey]) {
             throw new Error("Invalid theme key: '" + themeKey + "' you can't map build styles.");
         }
@@ -651,7 +668,10 @@ MagicPen.prototype.installTheme = function (formats, theme) {
 
     that._themes = extend({}, that._themes);
     formats.forEach(function (format) {
-        that._themes[format] = extend({}, that._themes[format] || {}, theme);
+        var baseTheme = that._themes[format] || { styles: {} };
+        var extendedTheme = extend({}, baseTheme, theme);
+        extendedTheme.styles = extend({}, baseTheme.styles, theme.styles);
+        that._themes[format] = extendedTheme;
     });
 
 
diff --git a/lib/themeMapper.js b/lib/themeMapper.js
@@ -3,8 +3,9 @@ module.exports = function (theme, styles) {
         var count = 0;
         var stack = [];
         var themeMapping = styles[0];
-        while(typeof themeMapping === 'string' && theme[themeMapping]) {
-            themeMapping = theme[themeMapping];
+        var themeStyles = theme.styles || {};
+        while(typeof themeMapping === 'string' && themeStyles[themeMapping]) {
+            themeMapping = themeStyles[themeMapping];
             count += 1;
             if (100 < count) {
                 var index = stack.indexOf(themeMapping);
diff --git a/test/magicpen.spec.js b/test/magicpen.spec.js
@@ -1514,9 +1514,12 @@ describe('magicpen', function () {
         beforeEach(function () {
             pen = magicpen();
             pen.installTheme('html', {
-                comment: ['#969896', 'italic'],
-                keyword: '#bf41ea',
-                string: 'keyword'
+                accentColors: ['#D50000', '#C51162', '#AA00FF'],
+                styles: {
+                    comment: ['#969896', 'italic'],
+                    keyword: '#bf41ea',
+                    string: 'keyword'
+                }
             });
 
             pen.text('// This is a comment', 'comment').nl();
@@ -1527,8 +1530,48 @@ describe('magicpen', function () {
             pen.text('}');
 
             pen.installTheme('ansi', {
-                comment: 'grey',
-                keyword: 'cyan'
+                accentColors: ['#F44336', '#E91E63', '#9C27B0'],
+                styles: {
+                    comment: 'grey',
+                    keyword: 'cyan'
+                }
+            });
+        });
+
+        describe('retrieving theme information', function () {
+            describe('without specifying the format', function () {
+                it('fails if the format of the pen is not decided', function () {
+                    expect(function () {
+                        pen.theme();
+                    }, 'to throw',
+                           "Could not detect which format you want to retrieve " +
+                           "theme information for. Set the format of the pen or " +
+                           "provide it as an argument to the theme method.");
+                });
+
+                it('retrieves the theme information for the format of the pen', function () {
+                    pen.format = 'html';
+                    expect(pen.theme(), 'to equal', {
+                        accentColors: ['#D50000', '#C51162', '#AA00FF'],
+                        styles: {
+                            comment: ['#969896', 'italic'],
+                            keyword: '#bf41ea',
+                            string: 'keyword'
+                        }
+                    });
+                });
+            });
+
+            describe('for at specific format', function () {
+                it('returns the theme information for the specified format', function () {
+                    expect(pen.theme('ansi'), 'to equal', {
+                        accentColors: ['#F44336', '#E91E63', '#9C27B0'],
+                        styles: {
+                            comment: 'grey',
+                            keyword: 'cyan'
+                        }
+                    });
+                });
             });
         });
 
@@ -1561,7 +1604,7 @@ describe('magicpen', function () {
         describe('when the theme is extended', function () {
             beforeEach(function () {
                 pen.installTheme(['ansi', 'html'], {
-                    'methodDefinition': '#55ab40'
+                    methodDefinition: '#55ab40'
                 });
 
                 pen.installTheme('html', {
@@ -1577,6 +1620,20 @@ describe('magicpen', function () {
                 });
             });
 
+            describe('retrieving theme information', function () {
+                it('returns the theme information for the extended theme for the specified format', function () {
+                    expect(pen.theme('ansi'), 'to equal', {
+                        accentColors: ['#F44336', '#E91E63', '#9C27B0'],
+                        styles: {
+                            comment: '#969896',
+                            keyword: 'cyan',
+                            methodDefinition: '#55ab40',
+                            method: ['#55ab40', 'bold']
+                        }
+                    });
+                });
+            });
+
             it('when serializing to html the output uses the extended html theme', function () {
                 expect(pen.toString('html'), 'to equal',
                        '<div style="font-family: monospace; white-space: nowrap">\n' +
