notes, doces and some tweaking....

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

ADVANCED.md

@@ -54,7 +54,7 @@ For basics see [README.md](./README.md)
 			- [`<parser>.error(..)`](#parsererror-1)
 			- [`<parser>.off(..)`](#parseroff)
 			- [`<parser>(..)`](#parser-1)
-		- [`Parser.chain(..)` (EXPERIMENTAL)](#parserchain-experimental)
+		- [`Parser.chain(..)` _(EXPERIMENTAL)_](#parserchain-experimental)
 	- [Advanced parser API](#advanced-parser-api)
 		- [`<parser>.print(..)` / `<parser>.printError(..)`](#parserprint--parserprinterror)
 		- [`<parser>.handlerDefault(..)`](#parserhandlerdefault)
@@ -764,7 +764,7 @@ be ignored, otherwise the whole list is processed as if `<main>` was
 its head.
 
 
-### `Parser.chain(..)` (EXPERIMENTAL)
+### `Parser.chain(..)` _(EXPERIMENTAL)_
 
 Chain several parsers for staggering option/command processing.
 ```
@@ -779,15 +779,19 @@ that need to be processed out of order and before anything else.
 This is similar to chaining parsers via `.then(..)` but with additional setup:
 - all parsers except the last will have:
   - `.splitOptions` set to `false`
+  - `"-"` set to `undefined`
   - `"-help"` set to `undefined` enabling `-help` pass-through
   - `"-*"` and `"@*"` set to `undefined` enabling arguments pass-through
-- the last parser will have all the options from the other parsers merged into 
-  it for complete docs/`-help`
+- the last parser will have:
+  - all the options from the other parsers merged into it for complete 
+    docs/`-help`
+  - `.splitOptions` set to `false`
 
 
-XXX the resulting `<parsed>` object will only contain data from the last parser,
-this may change in the future.
+_XXX the resulting `<parsed>` object will only contain data from the last parser,
+this may change in the future..._
 
+_XXX not sure about the `.splitOptions` restriction on the last parser yet, but it definitely should not include the options from preceding parsers..._
 
 
 ## Advanced parser API

argv.js

@@ -320,15 +320,32 @@ object.Constructor('Parser', {
 	},
 
 	// XXX this does not merge the parse results... (???)
+	// XXX splitting the high priority args should not work...
+	// XXX object.deepKeys(..) ???
 	// XXX EXPERIMENTAL...
 	chain: function(...parsers){
 		var Parser = this
 		var [post, ...pre] = parsers.reverse()
 		pre.reverse()
 
+		// only update values that were not explicitly set...
+		var update = function(e, o){
+			return Object.assign(
+				e, 
+				Object.fromEntries(
+					Object.entries(o)
+						.map(function([k, v]){
+							return [k, 
+								e.hasOwnProperty(k) ?
+									e[k]
+									: v ] }) )) }
+
 		// prepare the final parser for merged doc...
-		// XXX object.deepKeys(..) ???
-		var final = Parser(Object.assign({}, 
+		// NOTE: pre values have priority over post values...
+		var final = Parser(Object.assign({
+				// XXX can we remove this restriction???
+				splitOptions: false,
+			}, 
 			// set attribute order...
 			// NOTE: this is here to set the attribute order according 
 			// 		to priority...
@@ -337,26 +354,29 @@ object.Constructor('Parser', {
 			post, 
 			...pre))
 
-		return pre
+		// build the chain...
+		pre = pre
 			// setup the chain for arg pass-through...
 			.map(function(e){
-				// XXX object.deepKeys(..) ???
 				return Parser(Object.assign({}, 
-					e, 
-					{
+					update(e, {
 						splitOptions: false,
 						'-help': undefined,
 						'-*': undefined,
 						'@*': undefined,
-					})) })
-			.concat([final])
+						'-': undefined,
+					}))) }) 
 		// chain...
+		pre
 			.reduce(function(res, cur){
 				return res ?
 					// NOTE: need to call .then(..) on each of the parsers, 
 					// 		so we return cur to be next...
 					(res.then(cur), cur)
-					: cur }, null) },
+					: cur }, null)
+   			.then(final) 
+
+		return pre[0] },
 }, {
 	// config...
 	//

examples/chain.js

@@ -67,7 +67,7 @@ argv.Parser.chain({
 	'-b': {
 		doc: 'medium priority option',
 		handler: function(){
-			console.log('### normal priority option') }},
+			console.log('### medium priority option') }},
 },{
 	'-c': {
 		doc: 'normal priority option',