Merge pull request #27 from ideaconsult/fix-readme

Fixes on README

API.md

@@ -36,14 +36,14 @@ Constructs a new instance of XlsxDataFill with given options.
 | --- | --- | --- |
 | accessor | <code>object</code> | An instance of XLSX spreadsheet accessing class. |
 | opts | <code>Object</code> | Options to be used during processing. |
-| opts.templateRegExp | <code>RegExp</code> | The regular expression to be used for template recognizing.  Default is `/\{\{([^}]*)\}\}/`, i.e. Mustache. |
-| opts.fieldSplitter | <code>string</code> | The string to be expected as template field splitter. Default is `|`. |
-| opts.joinText | <code>string</code> | The string to be used when the extracted value for a single cell is an array,  and it needs to be joined. Default is `,`. |
-| opts.mergeCells | <code>string</code> \| <code>boolean</code> | Whether to merge the higher dimension cells in the output. Default is true. |
-| opts.duplicateCells | <code>string</code> \| <code>boolean</code> | Whether to duplicate the content of higher dimension cells, when not merged. Default is false. |
+| opts.templateRegExp | <code>RegExp</code> | The regular expression to be used for template recognizing. Default is `/\{\{([^}]*)\}\}/`, i.e. Mustache. |
+| opts.fieldSplitter | <code>string</code> \| <code>RegExo</code> | The string or regular expression to be used as template fields splitter. Default is `|`. |
+| opts.joinText | <code>string</code> | The string to be used when the extracted value for a single cell is an array, and it needs to be joined. Default is `,`. |
+| opts.mergeCells | <code>string</code> \| <code>boolean</code> | Whether to merge the higher dimension cells in the output. Default is true, but valid values are also `"both"`, `"vertical"` and `"horizontal"`. |
+| opts.duplicateCells | <code>string</code> \| <code>boolean</code> | Whether to duplicate the content of higher dimension cells, when not merged. Default is false. Same valud values as `mergeCells`. |
 | opts.followFormulae | <code>boolean</code> | If a template is located as a result of a formula, whether to still process it. Default is false. |
 | opts.copyStyle | <code>boolean</code> | Copy the style of the template cell when populating. Even when `false`, the template styling _is_ applied. Default is true. |
-| opts.callbacksMap | <code>object.&lt;string, function()&gt;</code> | A map of handlers to be used for data and value extraction. There is one default - the empty one, for object key extraction. |
+| opts.callbacksMap | <code>object.&lt;string, function()&gt;</code> | A map of handlers to be used for data and value extraction. |
 
 <a name="XlsxDataFill+options"></a>
 
@@ -52,11 +52,10 @@ Setter/getter for XlsxDataFill's options as set during construction.
 
 **Kind**: instance method of [<code>XlsxDataFill</code>](#XlsxDataFill)  
 **Returns**: [<code>XlsxDataFill</code>](#XlsxDataFill) \| <code>Object</code> - The required options (in getter mode) or XlsxDataFill (in setter mode) for chaining.  
-**See**: {@constructor}.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| newOpts | <code>Object</code> \| <code>null</code> | If set - the new options to be used. |
+| newOpts | <code>Object</code> \| <code>null</code> | If set - the new options to be used. Check [up here](#new-xlsxdatafillaccessor-opts). |
 
 <a name="XlsxDataFill+fillData"></a>
 

README.md

@@ -194,7 +194,7 @@ Here are the options and their defaults.
 {
     templateRegExp: new RegExp(/\{\{([^}]*)\}\}/),
     fieldSplitter: "|",
-    joinText: ",",
+    joinText: ",",                     
     mergeCells: true,
     duplicateCells: false,
     followFormulae: false,
@@ -207,6 +207,22 @@ Here are the options and their defaults.
 
 ```
 
+Check the [detailed description in the API](API.md#new-xlsxdatafillaccessor-opts). It is worth noting the `mergeCells` and `duplicateCells` behavior. 
+
+First, they both have the same set of possible values: `true`, `false`, `”both”`, `”vertical”`, `”horizontal”` – in which direction the cells need to be merged/duplicated. As expected `true` and `”both”` have the same meaning.
+
+Second, cells duplication is valid only when merging is disabled, in other words, if `mergeCells == true`, `duplicateCells` is ignored. Given these options:
+
+```js
+mergeCells: "vertical",
+duplicateCells: true
+```
+
+Is interpreted as follow:
+
+* If during data expansion a value in higher dimension occupies more than one cell in a **column**, they are merged – because these are _vertical_.
+* If a value from higher dimension occupies more than one cell in a **row**, then duplication options is taken into account and same value is duplicated on all these cells.
+
 ## <a id="formulae-handling">Formulae handling</a>
 
 As formulas are a key Excel feature, so `xlsx-datafill` is trying to keep them alive and meaningful. As a basic rule _Raw formulas are kept as they are, only those put in a template format, are handled_.

src/XlsxDataFill.js

@@ -26,19 +26,14 @@ class XlsxDataFill {
      * Constructs a new instance of XlsxDataFill with given options.
      * @param {object} accessor An instance of XLSX spreadsheet accessing class.
      * @param {{}} opts Options to be used during processing.
-     * @param {RegExp} opts.templateRegExp The regular expression to be used for template recognizing. 
-     * Default is `/\{\{([^}]*)\}\}/`, i.e. Mustache.
-     * @param {string} opts.fieldSplitter The string to be expected as template field splitter. Default is `|`.
-     * @param {string} opts.joinText The string to be used when the extracted value for a single cell is an array, 
-     * and it needs to be joined. Default is `,`.
-     * @param {string|boolean} opts.mergeCells Whether to merge the higher dimension cells in the output. Default is true.
-     * @param {string|boolean} opts.duplicateCells Whether to duplicate the content of higher dimension cells, when not merged. Default is false.
-     * @param {boolean} opts.followFormulae If a template is located as a result of a formula, whether to still process it.
-     * Default is false.
-     * @param {boolean} opts.copyStyle Copy the style of the template cell when populating. Even when `false`, the template
-     * styling _is_ applied. Default is true.
+     * @param {RegExp} opts.templateRegExp The regular expression to be used for template recognizing. Default is `/\{\{([^}]*)\}\}/`, i.e. Mustache.
+     * @param {string|RegExo} opts.fieldSplitter The string or regular expression to be used as template fields splitter. Default is `|`.
+     * @param {string} opts.joinText The string to be used when the extracted value for a single cell is an array, and it needs to be joined. Default is `,`.
+     * @param {string|boolean} opts.mergeCells Whether to merge the higher dimension cells in the output. Default is true, but valid values are also `"both"`, `"vertical"` and `"horizontal"`.
+     * @param {string|boolean} opts.duplicateCells Whether to duplicate the content of higher dimension cells, when not merged. Default is false. Same valud values as `mergeCells`.
+     * @param {boolean} opts.followFormulae If a template is located as a result of a formula, whether to still process it. Default is false.
+     * @param {boolean} opts.copyStyle Copy the style of the template cell when populating. Even when `false`, the template styling _is_ applied. Default is true.
      * @param {object.<string, function>} opts.callbacksMap A map of handlers to be used for data and value extraction.
-     * There is one default - the empty one, for object key extraction.
      */
     constructor(accessor, opts) {
         this._opts = _.defaultsDeep({}, opts, defaultOpts);
@@ -49,8 +44,7 @@ class XlsxDataFill {
 
     /**
      * Setter/getter for XlsxDataFill's options as set during construction.
-     * @param {{}|null} newOpts If set - the new options to be used. 
-     * @see {@constructor}.
+     * @param {{}|null} newOpts If set - the new options to be used. Check [up here]{@link #new-xlsxdatafillaccessor-opts}.
      * @returns {XlsxDataFill|{}} The required options (in getter mode) or XlsxDataFill (in setter mode) for chaining.
      */
     options(newOpts) {