====== Constructor ======

The Karmagination constructors are ordered by how processing-intensive they are (during normal usage) with Karma() being the lightest and Karma(selector) being the heaviest.

===== Karma( ) =====
Karma() is an alias for Karma(document). Please view Karma(element) below for more information.

<code javascript>
alert(Karma()[0] === document); // true
</code>

===== Karma( element ) =====
Enable Karmagination's methods on the DOM element.

**Parameters:**
  * //element <HTMLElement>// The element that will be wrapped inside the Karmagination object

<code html>
<div id="example1">This is one</div>
</code>
<code javascript>
var $myDiv = Karma(document.getElementById('example1'));

alert($myDiv[0].innerHTML); // This is one
alert($myDiv[0].id);        // example1
alert($myDiv[0].nodeName);  // DIV
</code>

===== Karma( elements ) =====
Enable Karmagination's methods on the array of DOM elements.

**Parameters:**
  * //elements <Nodelist | Array>// The collection of elements that will be wrapped in Karmagination object.

<code html>
<div id="example1">This is one</div>
<div id="example2">This is two</div>
<div id="example3">This is three</div>
</code>
<code javascript>
var myDiv = [ document.getElementById('example1'), 
              document.getElementById('example2'), 
              document.getElementById('example3') ];

var $myDiv = Karma(myDiv);

alert($myDiv[0].innerHTML) // This is one
alert($myDiv[1].id)        // example2
alert($myDiv[2].nodeName)  // DIV
</code>

===== Karma( callback ) =====
Runs the callback function once the all the DOM structure in the current document is ready to be modified. Why not window.onload? Because usually the DOM is ready even before all the heavy images are loaded (FYI, images takes a long time to load).

**Parameters:**
  * //callback <Function>// The callback function to run onDOMready, with Karma being passed as the first argument.



<code javascript>
Karma(function($){
  alert($('#example1').html()); // Hi
});
</code>
<code html>
<div id="example1">Hi</div>
</code>

===== Karma( html, [context] ) =====
Creates DOM nodes within the context specified from the HTML provided. The created nodes will have access to Karmagination's methods. For this to work, the html must be well formed be encased in the tags. Due to performance issues, Karmagination will not check the validity of the HTML.

**Parameters:**
  * //html <String>// A valid HTML string
  * //context <HTMLElement>// The context document that will create elements from the HTML

This code will work.
<code javascript>
var created = Karma('<div class="madeup">Hi How are you</div>');
alert(created[0].nodeName); // DIV
</code>
This will throw an error because there are text not wrapped in HTML tags.
<code javascript>
var created = Karma('Goodbye<div class="madeup">Hi How are you</div>'); // error
</code>



===== Karma( selector, [root] ) =====
Gets all the elements that matches the CSS selector that exists under the root element. The selected elements will return gain access to Karmagination's methods. Here are the list of selectors supported by Karmagination, it has almost the same selector set as jQuery because Karmagination uses Sizzle.

**Parameters:**
  * //selector <String>// Valid CSS selectors as specified on the [[selectors]] section
  * //root <HTMLElement>// the root, or scope to find the elements

<code html>
<div class="not_selected">Hi</div>
<div id="root" class="root">
 <div class="selected">Hi</div>
 <div class="selected_also">Hi</div>
</div>
</code>
<code javascript>
var selected = Karma('div', document.getElementById('root'));

alert(selected[0].className); // selected
alert(selected[1].className); // selected_also

var allDiv = Karma('div');

alert(allDiv[0].className); // not_selected
alert(allDiv[1].className); // root
alert(allDiv[2].className); // selected
alert(allDiv[3].className); // selected_also
</code>