docs: function operator(optypeOrObj, argtype, transformfn, precedence, opts) {
    opts = opts || {};
    // the read function for all the operators just reads their symbol:
    var readfn = function(lexer, text) {
      // operators e.g. "--" need to return from e.g. "--x" even
      // though the "-" has been defined as a non-terminating
      // character (maybe this can be simplified!!??)
      var token = lexer.next_token(text, {matchPartial: true});
      return sl.atom(text, {token: token});
    };
    if(typeof optypeOrObj === 'string') {
      readfn.operator = {
        type: optypeOrObj,
        argtype: argtype,
        transform: transformfn,
        precedence: precedence,
        assoc: opts.assoc,
        options: opts
      };
    }
    else if(typeof optypeOrObj === 'object') {
      // this is an operator that is e.g. prefix and postfix,
      var opSpecObj = optypeOrObj;
      readfn.operator = {
        infix: (optypeOrObj.infix && optypeOrObj.infix.operator ?
                    optypeOrObj.infix.operator :
                    optypeOrObj.infix),
        prefix: (optypeOrObj.prefix && optypeOrObj.prefix.operator ?
                    optypeOrObj.prefix.operator :
                    optypeOrObj.prefix),
        postfix: (optypeOrObj.postfix && optypeOrObj.postfix.operator ?
                    optypeOrObj.postfix.operator :
                    optypeOrObj.postfix)
      };
    }
    return readfn;
  }