lightquery Documentation

lightquery_doc.md

Lightquery - Documentation

lightquery and aliases

You can use lightquery via its many aliases, such as :

• µ
• lq
• lQuery
• lightQuery
• LightQuery

immutableLightQuery and why is it so important

immutableLightQuery is a clone of lightquery made using the createOtherLightquery on lightquery (cf. cloning lightquery) that is completely immutable (cannot be reassigned, properties cannot be modified, etc...).

It serves as a reference for cloning and plugin management.

Creating a plugin

There are a few assets for creating a plugin for lightquery : The first set of assets is the plugin system, it is composed of two parts : the creation and the removal.

You can create a plugin using the method usePlugin (aliases: registerPlugin and addPlugin) on your lightquery like so :

µ.usePlugin(/*parameters*/)

You can also remove a plugin by calling removePlugin on your lightquery like so:

µ.removePlugin(/*parameters*/)

Another set of assets is the set of tools that are useful for creating a plugin, for instance :

• You can return an updated version of the current lightquery object (for chaining) using (inside of the method of an instance plugin) return this.lightqueryID(this.selector).
• You can return a lightquery object from data (if it is already a lightquery object, use its selector as the data) using return this.lightqueryID(data).
• You can use Array.prototype's methods on the this object inside of your plugin WARNING: I would avoid any side effect (for instance using splice since it is marked as undefined behavior)

The last set of assets is lqHelpers, it is an object that is available to you that provides several methods that ease your job (for instance lqHelpers.spacedListString.toArray that transforms i am parameter one into ["i", "am", "parameter", "one"]).

Those are great words but, we need to see that in action. Here's a demo of how to create an instance plugin for lightquery : Filter.

µ.registerPlugin("Filter", function(truthTestCallback){
  if(this.length){
        //const data = this.filter(truthTestCallback); //V1 - way more efficient
        
        let data = [];//V2 - less efficient, better for the example
        
        for(let i = 0 ; i < this.length ; i+=1)
         if(truthTestCallback.call(this[i]/*thisArg*/, this[i]/*elem*/, i/*index*/, this/*array*/))
           data.push(this[i]);
           
        return this.lightqueryID(data);
    }else
      return null; //or this.lightqueryID(this.selector)
});

//Now use the plugin
µ("*").Filter(elem=>elem.tagName == "SPAN");

And now a demo of how to create a global plugin : compose

µ.registerPlugin("compose", function(...fn){
    return function composed(...args){
        let r;
        for(let f of fn)
            r = (r ? f(r) : f(...args))
    }
}, "global");

//now use it
const alertHello = µ.compose( ()=>"Hello !", alert );

Cloning lightquery and independent instances

It is possible to have multiple independent "instances" of lightquery. Those are create using the method createOtherLightquery (which can receive a string that can be used as the instance's name in certain errors) on your lightquery.

As stated before, immutableLightquery is an independent instance of lightquery that is immutable.

Here's an example of how and why it can be used:

/* some code, uses lightquery as lq */

//You are about to use a plugin that is crucial to your application but is  also known for fucking up many other plugins, you might need a backup in case this happens, therefore :
const backupLightquery = lq.createOtherLightquery("backupLightquery");
require("dangerous-light_query-plugin")(lq);

/* some code, uses lq until it fucks up and can use backupLightquery instead */

One nice feature is that you can totally clean your ligthquery instance of all its plugins easily, letting the garbage collector do the rest of the job :

let x = lq.createOtherLightquery("x");
//some plugins
//some use
let x = immutableLightquery.createOtherLightquery("x");
//x is now clean of all plugins