/* 
COMMENTS { { { { { { 
            XML Extensions For mIRC 0.1 {
              author: Mpdreamz
              date:July 18 2006
              description: { 
                "XML Extensions For mIRC 1.0" (XMLEX for short) provides a complete set of aliases to
                create,fetch,load,manipulate,navigate & transform XML documents
              }

            }
            # $xml.document([file|url]<,callBackAlias>)
            - purpose: returns a reference to a new xml document.
            - arguments:
            --- file|url: optional, when specified loads the xml at the specified location. (can be http)
            --- callBackAlias: optional, when specified mIRC will not wait for the document to load but instead 
            call the specified alias when its done. This will also be called if the document failed to load!

            # $xml.parseError(<documentReference>)[.property|print]
            - purpose: check if there where errors after doing an operation
            - returns: $true or $false.
            - arguments: documentReference, required. Pointer to an xml document as returned by $xml.document();
            - property: see http://msdn.microsoft.com/en-us/library/ms767720(VS.85).aspx
            ---- or print to get a pretty print back of all the properties 
            # $xml.save(<documentReference>,<location>)
            - purpose: save an xml document to a location
            - returns: $true or $false indicating success
            - arguments: 
            --- documentReference, required. Pointer to an xml document as returned by $xml.document();
            --- location, required. File location where to save it too. overwrites and creates by default;

            # $xml.selectNode(<reference>,<xpath>)
            - purpose: selects a node reference based on the xpath using the reference from $1 as reference.
            - returns: node reference.
            - arguments: 
            --- reference: a valid $xml reference, required.
            --- xpath: xpath query selecting the xml node;

            # $xml.selectNodeSet(<reference>,<xpath>)
            - purpose: selects a nodeset reference based on the xpath using the reference from $1 as reference.
            - returns: nodeset reference.
            - arguments: 
            --- reference: a valid $xml reference, required.
            --- xpath: xpath query selecting the xml nodeset;


            # $xml.nodeSet(<reference)<.property>
            - purpose: selects a nodeset and calls property on that nodeset while destroying the nodeset straight
            afterwards. useful for small operations.
            - returns: nothing.
            - arguments: 
            --- reference: a valid $xml reference, required.
            --- xpath: xpath query selecting the xml nodeset;
            - property: required. http://msdn.microsoft.com/en-us/library/ms767664(VS.85).aspx



            # $xml.node(<reference>[,xpath])<.property>
            - purpose: selects a node and calls property on that node while destroying the nodeset straight
            afterwards. useful for small operations.
            - returns: nothing.
            - arguments: 
            --- reference: a valid $xml reference, required.
            --- xpath: xpath query selecting the xml nodeset;
            - property: required. http://msdn.microsoft.com/en-us/library/ms761386(VS.85).aspx
            - NOTE: not all properties will work by design. Im interested in hearing which don't
            but please note some can never work due to $com.

            # $xml.destroy(<reference>)
            - purpose: destroys the reference from mIRC's memory and with it all of its open descendants.
            everytime you $xml.document or use selectNodeSet or SelectNode or createElement or setAttributes
            com objects are left open by design (references) allowing you to reuse nodes. These have to be closed.
            See the example aliases, calling destroy on the document reference is enough to close all references 
            asociated with that document.

            # $xml.setAttributes(<elementReference>,<attribute1Name,attribute1Value>[,..])
            - purpose: set or overwrite attribute values on an element.
            - returns: nothing
            -- arguments
            --- elementReference, required. pointer to a reference of node type element
            --- name, value, optional. key value pairs of the attribute can be 1 or many.

            # $xml.createElement(<reference>,<elementName>[,attribute1Name,attribute1Value,..])
            -- purpose: create an element in the document using <reference> as parent.
            -- returns: nothing.
            -- arguments: 
            --- reference, required. document or element reference that acts as parent of the to be created element.
            --- elementName, required. name of the element XML guidelines apply.
            --- ,attribute1Name,attribute1Value,.., optional. Key value pairs of the attributes on the element.

            # $xml.removeElement(<reference>)
            -- purpose: removes an element from the xml document.
            -- returns: nothing.
            -- arguments: 
            --- reference, required. document or element reference that should be removed.

            # $xml.reference (<reference>)
            -- purpose: check if $1 is a valid xml reference.
            -- returns: $true or $false.
            -- arguments: 
            --- reference, required. document or element reference to check.

            # $xml.instanceOf(<reference>)
            -- purpose: returns the type of the reference.
            -- returns: document, node, nodeSet, element or elementpointer.
            -- arguments: 
            --- reference, required. document or element reference to check.

*/

/* XML example functions
*/
;load hawkee's comments asynchronously 
alias hawkeeComments noop $xml.document(http://www.hawkee.com/comment.rss.php,hawkeeCommentsLoaded)

;this alias is called when hawkee's comments loaded wheter succesful or not.
alias hawkeeCommentsLoaded {
  ;first check if document loaded correctly, $1 is a reference to the document
  if (!$xml.parseError($1)) {
    ;lets echo the first <title>'s inner text
    echo -a $xml.node($1,//title).text

    ;now we select all the <items>' in to one convenient array
    var %itemNodes = $xml.selectNodeSet($1,//item)

    ;%itemNodes now holds a reference to a node array which you can access.
    ;you can request information on the nodeSet as a whole
    echo -a found: $xml.nodeSet(%itemNodes).length items.

    ;looping through the entire nodeSet  is easy as well.
    while ($xml.nodeSet(%itemNodes).nextItem)  echo -a -- $xml.node($v1,title).text

    ;you can also directly access the nodes in a nodeSet
    ;this selects the 2nd <item>
    var %2ndItem = $xml.nodeSet(%itemNodes,2)

    ;then we use the reference stored in %2ndItem to select the 2nd <item>'s <title> child.
    echo -a 4 $xml.node(%2ndItem,title).text
  }
  else echo -a $xml.parseError($1).print 
  ;remove document references and every reference that belonged to the document (%rootElement etc) from memory
  noop $xml.destroy($1)

}

alias createNewXml {
  ;create a new xml document
  var %document = $xml.document()

  ;give the document a rootNode element
  var %rootElement = $xml.createElement(%document,rootNode)

  ;give the rootNode element a childnode
  var %childElement = $xml.createElement(%rootElement,childNode)

  ;set some attributes on this child node
  noop $xml.setAttributes(%childElement,id,12,name,testing123)

  ;you can also combine the latter 2 into one
  var %childElement2 = $xml.createElement(%childElement,childNode,3 levels deep wtf! 3 whoh3434oo3123oo!,id,18,name,$ticks)

  ;lets add another child
  var %childElement3 = $xml.createElement(%childElement,childNode,3 levels deep wtf! 3 whoh3434oo3123oo!,id,18,name,$ticks)

  ;and remove it immediatly after adding (bit silly but oh well!)
  noop $xml.removeElement(%childElement3)

  ;save document
  if ($xml.save(%document,$scriptdirTest.xml)) echo -a successfully saved new XML: $scriptdirTest.xml 
  else echo -a Something bad happened while saving: $scriptdirTest.xml 

  ;removes document references and every reference that belonged to the document (%rootElement etc)
  ;Remember that this just removes to references mIRC has to the XML and not anything inside the XML!
  ;think of it as an /unset %var
  noop $xml.destroy(%document)
}

/* XML document functions
* - open, a new or excisting, and save an XML document (also supports http loading!)
*/
alias xml.document {
  var %document  = $xml._register(document),%error 
  .comopen %document MSXML.DOMDOCUMENT
  noop $com(%document,setProperty,3,bstr,SelectionLanguage,bstr,XPath)  $com(%document,async,5,bool,$iif($2,0,-1))
  if ($1) && (!$prop) { 
    if (($2) && (!$isalias($2))) %error = $2 is not an alias.
    else if ($2) noop $comcall(%document,$2 %document,load,3,bstr,$1)
    else { 
      noop $comcall(%document,$2,load,3,bstr,$1)
      if ($xml.parseError(%document)) %error = $xml.parseError(%document).print
    }
  }
  if ($1) && ($prop) return $nulleval($com($1,$prop,2)) $com($1).result
  :error
  if (($error) || (%error)) {
    echo -setqbfmrc info * $!xml.document: $iif($com(%document).errortext,$v1,$iif($error,$v1,%error))
    reseterror
    return
  }
  return %document
}
alias -l nulleval return $null
alias xml.parseError {
  var %parseError $1.parseError. $+ $ticks $+ $com(0)
  noop $com($1,parseError,3,dispatch* %parseError)
  if ($prop == print)  return errorCode: $nulleval($com(%parseError,errorCode,2)) $com(%parseError).result $&
    reason: $nulleval($com(%parseError,reason,2)) $com(%parseError).result $&
    line: $nulleval($com(%parseError,Line,2)) $com(%parseError).result $&
    linepos: $nulleval($com(%parseError,linepos,2)) $com(%parseError).result $&
    filepos: $nulleval($com(%parseError,filepos,2)) $com(%parseError).result  $& 
    resource: $nulleval($com(%parseError,url,2)) $com(%parseError).result 
  return $nulleval($com(%parseError,$iif($prop,$v1,errorCode),2)) $iif($com(%parseError).result != 0,$true,$false)
}
alias xml.save {
  if ($xml.instanceOf($1) == document) {
    noop $com($1,save,3,bstr,$$2)
    return $true
  }
  else return $false
  if ($error) {
    echo -setqbfmrc info * $!xml.save: $iif($com(%document).errortext,$v1,$iif($error,$v1,%error))
    reseterror
    return $false
  }
}


/* XML convenience functions 
*/
alias xml.loadXML if ($xml.instanceOf($1) == document) return $com($1,loadXML,3,bstr,$2-)


/* XML navigation functions 
*/
alias xml.selectNode return $iif($xml._register(node,$1) && $v1 != $com($1,selectSingleNode,3,bstr,$2,dispatch* $v1),$v1) 
alias xml.selectNodeSet return $iif($xml._register(nodeSet,$1) && $v1 != $com($1,selectNodes,3,bstr,$2,dispatch* $v1),$v1) 
alias xml.nodeSet {
  var %nodeSet = $xml._register(nodeSet,$1)
  if ($prop == nextItem) return $iif($com($1,nextNode,3,dispatch* %nodeSet) && $com(%nodeSet),%nodeSet)
  if ($prop == reset) return $com($1,$v2,3)
  if ($prop == length) return $iif($com($1,$v2,3),$com($1).result)
  if ($2 isnum) return $iif($com($1,item,3,int,$2,dispatch* %nodeSet) && $com(%nodeSet),%nodeSet)
}
alias xml.node {
  if ($2) return $iif($xml.selectNode($1,$2) && $v1 != $com($v1,$prop,2),$com($v1).result) $xml.destroy($v1)
  else return $iif($com($1,$prop,2),$com($1).result)
}

/* XML creation functions 
*/
alias xml.setAttributes {
  if ($$2) && ($com($1)) {
    var %i 2
    while (%i <= $0) { 
      noop $com($1,setAttribute,3,bstr,$(,$ $+ %i),bstr,$(,$ $+ $calc(%i + 1)))
      inc %i 2
    }
  }
}
alias xml.createElement { 
  if ($$2) && ($com($1)) {
    var %e =  $iif($xml._register(element,$1) && $v1 != $com($xml._ownerDocument($1),createElement,3,bstr,$2,dispatch* $v1),$v1), %ep = $xml._register(elementpointer,%e) 
    noop $com($1,appendChild,3,dispatch,%e,dispatch* %ep)
    if ($3) .comclose ~xml $com($xml._ownerDocument(%e),createTextNode,3,bstr,$3,dispatch* ~xml) $com(%ep,appendChild,3,dispatch,~xml)
    if ($4) noop $($!xml.setAttributes(%ep, $regsubex($str(.,$calc($0 - 3)),/(.)/g,$ $+ $calc(\n +3) $+ $iif(\2,$chr(44))) ),2) 
    return %ep
  }
}

/* XML node removal functions
* alias xml.removeElement if ($xml.reference($1)) noop $xml.remove($1) $xml.destroy($1)
*/
alias xml.removeElement if ($xml.reference($1)) noop $xml._remove($1) $xml.destroy($1)
alias xml.destroy { 
  if ($xml.reference($$1)) {
    var %nodes = $com(_xmlCom,selectNodes,3,bstr,$+(//*[@id=',$1'],//@id),dispatch* nodes)
    while ($iif($com(nodes,nextNode,3,dispatch* ~xml) && $com(~xml),~xml)) {
      var %comObject = $iif($com(~xml,text,2),$com(~xml).result)
      if ($com(%comObject)) .comclose %comObject
      .comclose ~xml
    }
    .comclose nodes $com(_xmlCom,selectSingleNode,3,bstr,$+(//*[@id=',$1']),dispatch* $+(node,$1)) $xml._remove($+(node,$1),$true)
  }
  else echo -a $1
}
alias xml._remove {
  if ($xml.reference($1) || node* iswm $1) {
    noop $com($1,parentNode,3,dispatch* $+(parent,$1))
    noop $com($+(parent,$1),removeChild,3,dispatch,$1)
    .comclose $+(parent,$1)
  }
}
/* XML node binding functions
* - to assist in keeping track of open COM objects;
*/
alias -l xml._register {
  if (!$hget(_xml,_constructed)) xml._constructor
  var %name = $xml._newName($1,$2)
  noop $com(_xmlCom,selectSingleNode,3,bstr,$iif($2,$+(//*[@id=',$2']),/*),dispatch* _parent)
  .comclose _parent $com(_xmlCom,createElement,3,bstr,$1,dispatch* _newNode) $com(_parent,appendChild,3,dispatch,_newNode)
  .comclose _newNode $com(_newNode,setAttribute,3,bstr,id,bstr,%name) 
  hadd -m _xml %name $1
  return %name
}
alias xml._newName {
  return $gettok($+($gettok($2,1,46),._xml,$ticks,$com(0)),1-,46)
}
alias xml.reference return $iif($hget(_xml,$1),$true,$false)
alias xml.instanceOf return $iif($hget(_xml,$1),$v1)
alias -l xml._ownerDocument return $gettok($1,1,46)

alias xml.resetAll {
  xml._destructor 
  xml._constructor
  echo -a removed all xml object references 
}
alias xml._constructor {
  .comopen _xmlCom MSXML.DOMDOCUMENT
  hadd -m _xml _constructed $com(_xmlCom,loadXML,3,bstr,<xmlComConnections />)
}
alias xml._destructor {
  if ($com(_xmlCom)) .comclose _xmlCom 
  hfree _xml 
  var %i = $com(0)
  while (%i > 0) { 
    if (_xml* iswm $com(%i)) .comclose $v2
    dec %i
  }
  hadd -m _xml _constructed 0
}