A micro-library (4k minified) for DRY:ing up the boring boilerplate of user scripts.

README.md

on.js

The fun part of user scripting is deciding what happens. The boring part is scavenging the DOM for bits of templated data, or elements you want to mod.

Have on.js do it for you! MIT licensed, or Copyheart: copying is an act of love. Please copy and share!

Quick Example

Want to sift away noise at retailmenot?

// hide the noise at http://www.retailmenot.com/view/vayama.com
on({ dom: [ 'css* #offers li.offer'
          , { deal:   'xpath .'
            , coupon: 'css? .crux .code'
            }
          ]
   }).then(nukeCouponless);

function nukeCouponless(offers) {
  offers.forEach(function sift(a) {
    if (!a.coupon)
      a.deal.style.display = 'none';
  });
}

What's the benefit?

Separate logic from page structure.

I could talk all night about what this buys you – here are some highlights:

• Beautiful code

  Optimize for happiness! This is of course personal, but I love how clean on.js makes my user scripts.

  I can see what they do, at a moment's glance, and what data they depend on. Maintenance gets easier.

• Sane native javascript types

  The DOM API:s are not only verbose, but also cripple results with bad types! From on.js array selectors, you get a real Array that you can operate on with .forEach, .map, .some, .every, .filter, .reduce, .slice, .indexOf, and all the other really awesome Array.prototype methods.

• More complex scripts become feasible

  As a script's complexity grows, so does the burden of maintaining it. With on.js, this is still true – but it grows far slower!

  Seeing (and naming) the structure of the input your code operates on helps reading and writing the code operating on it.

• Reuse one script's page structure awareness

  Maybe you later want to whip up another script using the same data, or even make a shell web scraper for it?

  Copy, paste, done! You're in business – in seconds.

• Have your scripts magically self-deprecate

  Web sites change. This makes user scripts break, start doing the wrong thing, or filling your console with errors.

  When they change so your script no longer has the stuff it needs, your code will just never run instead of breaking the page.

  If you don't miss it, great! – that site has improved, and your script will never bother it.

  If you do – just update its on.js preamble, and your code just magically works again.

on.js

/* coffee-script example usage - at https://github.com/johan/dotjs/commits/johan

   on path_re: ['^/([^/]+)/([^/]+)(/?.*)', 'user', 'repo', 'rest']
      query: true
      dom:
        keyboard: 'css  .keyboard-shortcuts'
        branches: 'css+ .js-filter-branches h4 a'
        dates:    'css* .commit-group-heading'
        tracker:  'css? #gauges-tracker[defer]'
        johan_ci: 'xpath* //li[contains(@class,"commit")][.//a[.="johan"]]'
   .then ready = (path, query, dom) ->

   ...would make something like this call, as the path regexp matched, and there
   were DOM matches for the two mandatory "keyboard" and "branches" selectors:

   ready( { user: 'johan', repo: 'dotjs', rest: '/commits/johan' }
        , {} // would contain all query args (if any were present)
        , { keyboard: Node<a href="#keyboard_shortcuts_pane">
          , branches: [ Node<a href="/johan/dotjs/commits/coffee">
                      , Node<a href="/johan/dotjs/commits/dirs">
                      , Node<a href="/johan/dotjs/commits/gh-pages">
                      , Node<a href="/johan/dotjs/commits/johan">
                      , Node<a href="/johan/dotjs/commits/jquery-1.8.2">
                      , Node<a href="/johan/dotjs/commits/master">
                      ]
          , dates: [ Node<h3 class="commit-group-heading">Oct 07, 2012</h3>
                   , Node<h3 class="commit-group-heading">Aug 29, 2012</h3>
                   , ...
                   ]
          , tracker: null
          , johan_ci: [ Node<li class="commit">, ... ]
          }
        )

   A selector returns an array of matches prefixed for "css*" and "css+" (ditto
   xpath), and a single result if it is prefixed "css" or "css?":

   If your script should only run on pages with a particular DOM node (or set of
   nodes), use the 'css' or 'css+' (ditto xpath) forms - and your callback won't
   get fired on pages that lack them. The 'css?' and 'css*' forms would run your
   callback but pass null or [] respectively, on not finding such nodes. You may
   recognize the semantics of x, x?, x* and x+ from regular expressions.

   (see http://goo.gl/ejtMD for a more thorough discussion of something similar)

   The dom property is recursively defined so you can make nested structures.
   If you want a property that itself is an object full of matched things, pass
   an object of sub-dom-spec:s, instead of a string selector:

   on dom:
        meta:
          base:  'xpath? /head/base
          title: 'xpath  string(/head/title)'
        commits: 'css* li.commit'
   .then (dom) ->

   You can also deconstruct repeated templated sections of a page into subarrays
   scraped as per your specs, by picking a context node for a dom spec. This is
   done by passing a two-element array: a selector resolving what node/nodes you
   look at and a dom spec describing how you want it/them deconstructed for you:

   on dom:
        meta:
          [ 'xpath /head',
            base:  'xpath? base
            title: 'xpath  string(title)'
          ]
        commits:
          [ 'css* li.commit',
            avatar_url:  ['css img.gravatar', 'xpath string(@src)']
            author_name: 'xpath string(.//*[@class="author-name"])'
          ]
   .then (dom) ->

   The mandatory/optional selector rules defined above behave as you'd expect as
   used for context selectors too: a mandatory node or array of nodes will limit
   what pages your script gets called on to those that match it, so your code is
   free to assume it will always be there when it runs. An optional context node
   that is not found will instead result in that part of your DOM being null, or
   an empty array, in the case of a * selector.

   Finally, there is the xpath! keyword, which is similar to xpath, but it also
   mandates that whatever is returned is truthy. This is useful when you use the
   xpath functions returning strings, numbers and of course booleans, to assert
   things about the pages you want to run on, like 'xpath! count(//img) = 0', if
   you never want the script to run on pages with inline images, say.

   After you have called on(), you may call on.dom to do page scraping later on,
   returning whatever matched your selector(s) passed. Mandatory selectors which
   failed to match at this point will return undefined, optional selectors null:

     on.dom('xpath  //a[@id]') => undefined or <a id="...">
     on.dom('xpath? //a[@id]') => null      or <a id="...">
     on.dom('xpath+ //a[@id]') => undefined or [<a id="...">, <a id="...">, ...]
     on.dom('xpath* //a[@id]') => []        or [<a id="...">, <a id="...">, ...]

   A readable way to detect a failed mandatory match is on.dom(...) === on.FAIL;

   Github pjax hook: for re-running a script's on() block for every pjax request
   to a site - add a pushstate hook as per http://goo.gl/LNSv1 -- and be sure to
   make your script reentrant, so that it won't try to process the same elements
   again, if they are still sitting around in the page (see ':not([augmented])')

 */

function on(opts, plugins) { return new Promise(function(resolve, reject) {
  opts = opts || {};
  var Object_toString = Object.prototype.toString
    , Array_slice = Array.prototype.slice
    , FAIL = 'dom' in on ? undefined : (function() {
        var tests =
              { path_re: { fn: test_regexp }
              , query:   { fn: test_query }
              , dom:     { fn: test_dom
                         , my: { 'css*':   $c
                               , 'css+':   one_or_more($c)
                               , 'css?':   $C
                               , 'css':    not_null($C)
                               , 'xpath*': $x
                               , 'xpath+': one_or_more($x)
                               , 'xpath?': $X
                               , 'xpath!': truthy($x)
                               , 'xpath':  not_null($X)
                               }
                         }
              , inject: { fn: inject }
              }
          , name, test, me, my, mine
          ;

        for (name in tests) {
          test = tests[name];
          me = test.fn;
          if ((my = test.my))
            for (mine in my)
              me[mine] = my[mine];
          on[name] = me;
        }
      })()

    , input = [] // args for the callback(s?) the script wants to run
    , rules = Object.create(opts) // wraps opts in a pokeable inherit layer
    , debug = get('debug')
    , pushState = get('pushstate')
    , pjax_event = get('pjaxevent')
    , name, rule, test, result, retry, plugin
    ;

  if (plugins)
    for (name in plugins)
      if ((rule = plugins[name]) && (test = on[name]))
        for (plugin in rule)
          if (!(test[plugin])) {
            on._parse_dom_rule = null;
            test[plugin] = rule[plugin];
          }

  if (pushState && history.pushState &&
      (on.pushState = on.pushState || []).indexOf(opts) === -1) {
    on.pushState.push(opts); // make sure we don't re-register after navigation
    initPushState(pushState, pjax_event);
  }

  try {
    for (name in rules) {
      rule = rules[name];
      if (rule === undefined) continue; // was some callback or other non-rule
      test = on[name];
      if (!test) throw new Error('did not grok rule "'+ name +'"!');
      result = test(rule);
      if (result === FAIL) return false; // the page doesn't satisfy all rules
      input.push(result);
    }
  }
  catch (e) {
    if (debug) console.warn("on(debug): we didn't run because " + e.message);
    return reject(e);
  }

  return resolve.apply(on, input.concat(opts));

  function get(x) { rules[x] = undefined; return opts[x]; }
  function isArray(x)  { return Object_toString.call(x) === '[object Array]'; }
  function isObject(x) { return Object_toString.call(x) === '[object Object]'; }
  function array(a)    { return Array_slice.call(a, 0); } // array:ish => Array
  function arrayify(x) { return isArray(x) ? x : [x]; }  // non-array? => Array
  function inject(fn, args) {
    var script = document.createElement('script')
      , parent = document.documentElement;
    args = JSON.stringify(args || []).slice(1, -1);
    script.textContent = '('+ fn +')('+ args +');';
    parent.appendChild(script);
    parent.removeChild(script);
  }

  function initPushState(callback, pjax_event) {
    if (!history.pushState.armed) {
      inject(function(pjax_event) {
        function reportBack() {
          var e = document.createEvent('Events');
          e.initEvent('history.pushState', !'bubbles', !'cancelable');
          document.dispatchEvent(e);
        }
        var pushState = history.pushState;
        history.pushState = function on_pushState() {
          if (pjax_event && window.$ && $.pjax)
            $(document).one(pjax_event, reportBack);
          else
            setTimeout(reportBack, 0);
          return pushState.apply(this, arguments);
        };
      }, [pjax_event]);
      history.pushState.armed = pjax_event;
    }

    retry = function after_pushState() {
      rules = Object.create(opts);
      rules.pushstate = undefined;
      on(rules).then(callback);
    };

    document.addEventListener('history.pushState', function() {
      if (debug) console.log('on.pushstate', location.pathname);
      retry();
    }, false);
  }

  function test_query(spec) {
    var q = unparam(this === on || this === window ? location.search : this);
    if (spec === true || spec == null) return q; // decode the query for me!
    throw new Error('bad query type '+ (typeof spec) +': '+ spec);
  }

  function unparam(query) {
    var data = {};
    (query || '').replace(/\+/g, '%20').split('&').forEach(function(kv) {
      kv = /^\??([^=&]*)(?:=(.*))?/.exec(kv);
      if (!kv) return;
      var prop, val, k = kv[1], v = kv[2], e, m;
      try { prop = decodeURIComponent(k); } catch (e) { prop = unescape(k); }
      if ((val = v) != null)
        try { val = decodeURIComponent(v); } catch (e) { val = unescape(v); }
      data[prop] = val;
    });
    return data;
  }

  function test_regexp(spec) {
    if (!isArray(spec)) spec = arrayify(spec);
    var re = spec.shift();
    if (typeof re === 'string') re = new RegExp(re);
    if (!(re instanceof RegExp))
      throw new Error((typeof re) +' was not a regexp: '+ re);

    var ok = re.exec(this === on || this === window ? location.pathname : this);
    if (ok === null) return FAIL;
    if (!spec.length) return ok;
    var named = {};
    ok.shift(); // drop matching-whole-regexp part
    while (spec.length) named[spec.shift()] = ok.shift();
    return named;
  }

  function truthy(fn) { return function(s) {
    var x = fn.apply(this, arguments); return x || FAIL;
  }; }

  function not_null(fn) { return function(s) {
    var x = fn.apply(this, arguments); return x !== null ? x : FAIL;
  }; }

  function one_or_more(fn) { return function(s) {
    var x = fn.apply(this, arguments); return x.length ? x : FAIL;
  }; }

  function $c(css) { return array(this.querySelectorAll(css)); }
  function $C(css) { return this.querySelector(css); }

  function $x(xpath) {
    var doc = this.evaluate ? this : this.ownerDocument, next;
    var got = doc.evaluate(xpath, this, null, 0, null), all = [];
    switch (got.resultType) {
      case 1/*XPathResult.NUMBER_TYPE*/:  return got.numberValue;
      case 2/*XPathResult.STRING_TYPE*/:  return got.stringValue;
      case 3/*XPathResult.BOOLEAN_TYPE*/: return got.booleanValue;
      default: while ((next = got.iterateNext())) all.push(next); return all;
    }
  }
  function $X(xpath) {
    var got = $x.call(this, xpath);
    return got instanceof Array ? got[0] || null : got;
  }

  function quoteRe(s) { return (s+'').replace(/([-$(-+.?[-^{|}])/g, '\\$1'); }

  // DOM constraint tester / scraper facility:
  // "this" is the context Node(s) - initially the document
  // "spec" is either of:
  //   * css / xpath Selector "selector_type selector"
  //   * resolved for context [ context Selector, spec ]
  //   * an Object of spec(s) { property_name: spec, ... }
  function test_dom(spec, context) {
    // returns FAIL if it turned out it wasn't a mandated match at this level
    // returns null if it didn't find optional matches at this level
    // returns Node or an Array of nodes, or a basic type from some XPath query
    function lookup(rule) {
      switch (typeof rule) {
        case 'string': break; // main case - rest of function
        case 'object': if ('nodeType' in rule || rule.length) return rule;
          // fall-through
        default: throw new Error('non-String dom match rule: '+ rule);
      }
      if (!on._parse_dom_rule) on._parse_dom_rule = new RegExp('^(' +
        Object.keys(on.dom).map(quoteRe).join('|') + ')\\s*(.*)');
      var match = on._parse_dom_rule.exec(rule), type, func;
      if (match) {
        type = match[1];
        rule = match[2];
        func = test_dom[type];
      }
      if (!func) throw new Error('unknown dom match rule '+ type +': '+ rule);
      return func.call(this, rule);
    }

    var results, result, i, property_name;
    if (context === undefined) {
      context = this === on || this === window ? document : this;
    }

    // validate context:
    if (context === null || context === FAIL) return FAIL;
    if (isArray(context)) {
      for (results = [], i = 0; i < context.length; i++) {
        result = test_dom.call(context[i], spec);
        if (result !== FAIL)
          results.push(result);
      }
      return results;
    }
    if (typeof context !== 'object' || !('nodeType' in context))
      throw new Error('illegal context: '+ context);

    // handle input spec format:
    if (typeof spec === 'string') return lookup.call(context, spec);
    if (isArray(spec)) {
      context = lookup.call(context, spec[0]);
      if (context === null || context === FAIL) return context;
      return test_dom.call(context, spec[1]);
    }
    if (isObject(spec)) {
      results = {};
      for (property_name in spec) {
        result = test_dom.call(context, spec[property_name]);
        if (result === FAIL) return FAIL;
        results[property_name] = result;
      }
      return results;
    }

    throw new Error("dom spec was neither a String, Object nor Array: "+ spec);
  }
}); }

on.min.js

;function on(t,n){return new Promise(function(e,r){function o(n){return V[n]=void 0,t[n]}function i(t){return"[object Array]"===R.call(t)}function u(t){return"[object Object]"===R.call(t)}function a(t){return k.call(t,0)}function c(t){return i(t)?t:[t]}function s(t,n){var e=document.createElement("script"),r=document.documentElement;n=JSON.stringify(n||[]).slice(1,-1),e.textContent="("+t+")("+n+");",r.appendChild(e),r.removeChild(e)}function l(n,e){history.pushState.armed||(s(function(t){function n(){var t=document.createEvent("Events");t.initEvent("history.pushState",!1,!1),document.dispatchEvent(t)}var e=history.pushState;history.pushState=function(){return t&&window.$&&$.pjax?$(document).one(t,n):setTimeout(n,0),e.apply(this,arguments)}},[e]),history.pushState.armed=e),A=function(){V=Object.create(t),V.pushstate=void 0,on(V).then(n)},document.addEventListener("history.pushState",function(){I&&console.log("on.pushstate",location.pathname),A()},!1)}function f(t){var n=h(this===on||this===window?location.search:this);if(t===!0||null==t)return n;throw Error("bad query type "+typeof t+": "+t)}function h(t){var n={};return(t||"").replace(/\+/g,"%20").split("&").forEach(function(t){if(t=/^\??([^=&]*)(?:=(.*))?/.exec(t)){var e,r,o=t[1],i=t[2];try{e=decodeURIComponent(o)}catch(u){e=unescape(o)}if(null!=(r=i))try{r=decodeURIComponent(i)}catch(u){r=unescape(i)}n[e]=r}}),n}function p(t){i(t)||(t=c(t));var n=t.shift();if("string"==typeof n&&(n=RegExp(n)),!(n instanceof RegExp))throw Error(typeof n+" was not a regexp: "+n);var e=n.exec(this===on||this===window?location.pathname:this);if(null===e)return q;if(!t.length)return e;var r={};for(e.shift();t.length;)r[t.shift()]=e.shift();return r}function d(t){return function(){var n=t.apply(this,arguments);return n||q}}function m(t){return function(){var n=t.apply(this,arguments);return null!==n?n:q}}function y(t){return function(){var n=t.apply(this,arguments);return n.length?n:q}}function v(t){return a(this.querySelectorAll(t))}function g(t){return this.querySelector(t)}function w(t){var n,e=this.evaluate?this:this.ownerDocument,r=e.evaluate(t,this,null,0,null),o=[];switch(r.resultType){case 1:return r.numberValue;case 2:return r.stringValue;case 3:return r.booleanValue;default:for(;n=r.iterateNext();)o.push(n);return o}}function x(t){var n=w.call(this,t);return n instanceof Array?n[0]||null:n}function E(t){return(t+"").replace(/([-$(-+.?[-^{|}])/g,"\\$1")}function b(t,n){function e(t){switch(typeof t){case"string":break;case"object":if("nodeType"in t||t.length)return t;default:throw Error("non-String dom match rule: "+t)}on._parse_dom_rule||(on._parse_dom_rule=RegExp("^("+Object.keys(on.dom).map(E).join("|")+")\\s*(.*)"));var n,e,r=on._parse_dom_rule.exec(t);if(r&&(n=r[1],t=r[2],e=b[n]),!e)throw Error("unknown dom match rule "+n+": "+t);return e.call(this,t)}var r,o,a,c;if(void 0===n&&(n=this===on||this===window?document:this),null===n||n===q)return q;if(i(n)){for(r=[],a=0;a<n.length;a++)o=b.call(n[a],t),o!==q&&r.push(o);return r}if("object"!=typeof n||!("nodeType"in n))throw Error("illegal context: "+n);if("string"==typeof t)return e.call(n,t);if(i(t))return n=e.call(n,t[0]),null===n||n===q?n:b.call(n,t[1]);if(u(t)){r={};for(c in t){if(o=b.call(n,t[c]),o===q)return q;r[c]=o}return r}throw Error("dom spec was neither a String, Object nor Array: "+t)}t=t||{};var S,j,_,O,A,C,R=Object.prototype.toString,k=Array.prototype.slice,q="dom"in on?void 0:function(){var t,n,e,r,o,i={path_re:{fn:p},query:{fn:f},dom:{fn:b,my:{"css*":v,"css+":y(v),"css?":g,css:m(g),"xpath*":w,"xpath+":y(w),"xpath?":x,"xpath!":d(w),xpath:m(x)}},inject:{fn:s}};for(t in i){if(n=i[t],e=n.fn,r=n.my)for(o in r)e[o]=r[o];on[t]=e}}(),T=[],V=Object.create(t),I=o("debug"),N=o("pushstate"),U=o("pjaxevent");if(n)for(S in n)if((j=n[S])&&(_=on[S]))for(C in j)_[C]||(on._parse_dom_rule=null,_[C]=j[C]);N&&history.pushState&&-1===(on.pushState=on.pushState||[]).indexOf(t)&&(on.pushState.push(t),l(N,U));try{for(S in V)if(j=V[S],void 0!==j){if(_=on[S],!_)throw Error('did not grok rule "'+S+'"!');if(O=_(j),O===q)return!1;T.push(O)}}catch(D){return I&&console.warn("on(debug): we didn't run because "+D.message),r(D)}return e.apply(on,T.concat(t))})}

on.user.js

// lib usable from Control Freak or similar Chrome extensions running in an Isolated World context

// scrape this and export it and on.js as a "scraper" / "scraped" object pair in chrome devtools
const scrape = (scraper) => {
  exportToPage({on, scraper});
  evalInPage((scraper) => {
    let spec = 'dom' in scraper ? scraper : { dom: scraper };
    on(spec).then((scraped) => {
      console.info('on.dom scraped:', {scraper, scraped});
      window.scraped = scraped;
    });
  }, scraper);
};

// expose the properties of `obj` onto the chrome devtools window object, including self-contained functions
const exportToPage = (obj) => {
  const markFunctions = (o) => {
    if (typeof o === 'function') return 1;
    if (typeof o !== 'object') return 0;
    const res = Array.isArray(o) ? [] : {};
    for (const k in o)
      res[k] = markFunctions(o[k]);
    return res;
  };

  evalInPage((obj, fns) => {
    const thawFunctions = (o, f) => {
      if (f === 1) return eval(`f=${o}`);
      if (typeof o !== 'object') return o;
      const res = Array.isArray(o) ? [] : {};
      for (const k in o)
        res[k] = thawFunctions(o[k], f[k]);
      return res;
    };
    Object.assign(window, thawFunctions(obj, fns));
  }, obj, markFunctions(obj));
};

// run fn.apply(null, args) in the window context, outside of the chrome isolated world
const evalInPage = (fn, ...args) => {
  const {toJSON} = Function.prototype;
  Function.prototype.toJSON = function() { return this + ''; };
  args = JSON.stringify(args).slice(1, -1);
  Function.prototype.toJSON = toJSON;

  const script = document.createElement('script');
  script.textContent = `(${fn + ''})(${args});`;
  document.head.appendChild(script).remove();
};

// https://git.io/on.js:
function on(opts, plugins) { return new Promise(function(resolve, reject) {
  opts = opts || {};
  var Object_toString = Object.prototype.toString
    , Array_slice = Array.prototype.slice
    , FAIL = 'dom' in on ? undefined : (function() {
        var tests =
              { path_re: { fn: test_regexp }
              , query:   { fn: test_query }
              , dom:     { fn: test_dom
                         , my: { 'css*':   $c
                               , 'css+':   one_or_more($c)
                               , 'css?':   $C
                               , 'css':    not_null($C)
                               , 'xpath*': $x
                               , 'xpath+': one_or_more($x)
                               , 'xpath?': $X
                               , 'xpath!': truthy($x)
                               , 'xpath':  not_null($X)
                               }
                         }
              , inject: { fn: inject }
              }
          , name, test, me, my, mine
          ;

        for (name in tests) {
          test = tests[name];
          me = test.fn;
          if ((my = test.my))
            for (mine in my)
              me[mine] = my[mine];
          on[name] = me;
        }
      })()

    , input = [] // args for the callback(s?) the script wants to run
    , rules = Object.create(opts) // wraps opts in a pokeable inherit layer
    , debug = get('debug')
    , pushState = get('pushstate')
    , pjax_event = get('pjaxevent')
    , name, rule, test, result, retry, plugin
    ;

  if (plugins)
    for (name in plugins)
      if ((rule = plugins[name]) && (test = on[name]))
        for (plugin in rule)
          if (!(test[plugin])) {
            on._parse_dom_rule = null;
            test[plugin] = rule[plugin];
          }

  if (pushState && history.pushState &&
      (on.pushState = on.pushState || []).indexOf(opts) === -1) {
    on.pushState.push(opts); // make sure we don't re-register after navigation
    initPushState(pushState, pjax_event);
  }

  try {
    for (name in rules) {
      rule = rules[name];
      if (rule === undefined) continue; // was some callback or other non-rule
      test = on[name];
      if (!test) throw new Error('did not grok rule "'+ name +'"!');
      result = test(rule);
      if (result === FAIL) return false; // the page doesn't satisfy all rules
      input.push(result);
    }
  }
  catch (e) {
    if (debug) console.warn("on(debug): we didn't run because " + e.message);
    return reject(e);
  }

  return resolve.apply(on, input.concat(opts));

  function get(x) { rules[x] = undefined; return opts[x]; }
  function isArray(x)  { return Object_toString.call(x) === '[object Array]'; }
  function isObject(x) { return Object_toString.call(x) === '[object Object]'; }
  function array(a)    { return Array_slice.call(a, 0); } // array:ish => Array
  function arrayify(x) { return isArray(x) ? x : [x]; }  // non-array? => Array
  function inject(fn, args) {
    var script = document.createElement('script')
      , parent = document.documentElement;
    args = JSON.stringify(args || []).slice(1, -1);
    script.textContent = '('+ fn +')('+ args +');';
    parent.appendChild(script);
    parent.removeChild(script);
  }

  function initPushState(callback, pjax_event) {
    if (!history.pushState.armed) {
      inject(function(pjax_event) {
        function reportBack() {
          var e = document.createEvent('Events');
          e.initEvent('history.pushState', !'bubbles', !'cancelable');
          document.dispatchEvent(e);
        }
        var pushState = history.pushState;
        history.pushState = function on_pushState() {
          if (pjax_event && window.$ && $.pjax)
            $(document).one(pjax_event, reportBack);
          else
            setTimeout(reportBack, 0);
          return pushState.apply(this, arguments);
        };
      }, [pjax_event]);
      history.pushState.armed = pjax_event;
    }

    retry = function after_pushState() {
      rules = Object.create(opts);
      rules.pushstate = undefined;
      on(rules).then(callback);
    };

    document.addEventListener('history.pushState', function() {
      if (debug) console.log('on.pushstate', location.pathname);
      retry();
    }, false);
  }

  function test_query(spec) {
    var q = unparam(this === on || this === window ? location.search : this);
    if (spec === true || spec == null) return q; // decode the query for me!
    throw new Error('bad query type '+ (typeof spec) +': '+ spec);
  }

  function unparam(query) {
    var data = {};
    (query || '').replace(/\+/g, '%20').split('&').forEach(function(kv) {
      kv = /^\??([^=&]*)(?:=(.*))?/.exec(kv);
      if (!kv) return;
      var prop, val, k = kv[1], v = kv[2], e, m;
      try { prop = decodeURIComponent(k); } catch (e) { prop = unescape(k); }
      if ((val = v) != null)
        try { val = decodeURIComponent(v); } catch (e) { val = unescape(v); }
      data[prop] = val;
    });
    return data;
  }

  function test_regexp(spec) {
    if (!isArray(spec)) spec = arrayify(spec);
    var re = spec.shift();
    if (typeof re === 'string') re = new RegExp(re);
    if (!(re instanceof RegExp))
      throw new Error((typeof re) +' was not a regexp: '+ re);

    var ok = re.exec(this === on || this === window ? location.pathname : this);
    if (ok === null) return FAIL;
    if (!spec.length) return ok;
    var named = {};
    ok.shift(); // drop matching-whole-regexp part
    while (spec.length) named[spec.shift()] = ok.shift();
    return named;
  }

  function truthy(fn) { return function(s) {
    var x = fn.apply(this, arguments); return x || FAIL;
  }; }

  function not_null(fn) { return function(s) {
    var x = fn.apply(this, arguments); return x !== null ? x : FAIL;
  }; }

  function one_or_more(fn) { return function(s) {
    var x = fn.apply(this, arguments); return x.length ? x : FAIL;
  }; }

  function $c(css) { return array(this.querySelectorAll(css)); }
  function $C(css) { return this.querySelector(css); }

  function $x(xpath) {
    var doc = this.evaluate ? this : this.ownerDocument, next;
    var got = doc.evaluate(xpath, this, null, 0, null), all = [];
    switch (got.resultType) {
      case 1/*XPathResult.NUMBER_TYPE*/:  return got.numberValue;
      case 2/*XPathResult.STRING_TYPE*/:  return got.stringValue;
      case 3/*XPathResult.BOOLEAN_TYPE*/: return got.booleanValue;
      default: while ((next = got.iterateNext())) all.push(next); return all;
    }
  }
  function $X(xpath) {
    var got = $x.call(this, xpath);
    return got instanceof Array ? got[0] || null : got;
  }

  function quoteRe(s) { return (s+'').replace(/([-$(-+.?[-^{|}])/g, '\\$1'); }

  // DOM constraint tester / scraper facility:
  // "this" is the context Node(s) - initially the document
  // "spec" is either of:
  //   * css / xpath Selector "selector_type selector"
  //   * resolved for context [ context Selector, spec ]
  //   * an Object of spec(s) { property_name: spec, ... }
  function test_dom(spec, context) {
    // returns FAIL if it turned out it wasn't a mandated match at this level
    // returns null if it didn't find optional matches at this level
    // returns Node or an Array of nodes, or a basic type from some XPath query
    function lookup(rule) {
      switch (typeof rule) {
        case 'string': break; // main case - rest of function
        case 'object': if ('nodeType' in rule || rule.length) return rule;
          // fall-through
        default: throw new Error('non-String dom match rule: '+ rule);
      }
      if (!on._parse_dom_rule) on._parse_dom_rule = new RegExp('^(' +
        Object.keys(on.dom).map(quoteRe).join('|') + ')\\s*(.*)');
      var match = on._parse_dom_rule.exec(rule), type, func;
      if (match) {
        type = match[1];
        rule = match[2];
        func = test_dom[type];
      }
      if (!func) throw new Error('unknown dom match rule '+ type +': '+ rule);
      return func.call(this, rule);
    }

    var results, result, i, property_name;
    if (context === undefined) {
      context = this === on || this === window ? document : this;
    }

    // validate context:
    if (context === null || context === FAIL) return FAIL;
    if (isArray(context)) {
      for (results = [], i = 0; i < context.length; i++) {
        result = test_dom.call(context[i], spec);
        if (result !== FAIL)
          results.push(result);
      }
      return results;
    }
    if (typeof context !== 'object' || !('nodeType' in context))
      throw new Error('illegal context: '+ context);

    // handle input spec format:
    if (typeof spec === 'string') return lookup.call(context, spec);
    if (isArray(spec)) {
      context = lookup.call(context, spec[0]);
      if (context === null || context === FAIL) return context;
      return test_dom.call(context, spec[1]);
    }
    if (isObject(spec)) {
      results = {};
      for (property_name in spec) {
        result = test_dom.call(context, spec[property_name]);
        if (result === FAIL) return FAIL;
        results[property_name] = result;
      }
      return results;
    }

    throw new Error("dom spec was neither a String, Object nor Array: "+ spec);
  }
}); }