-- xml module
-- http://help.interfaceware.com/code/details/xml-lua
-- Helpful extensions to core xml library in Iguana.

-- find or create first text element
function node.text(X)
   for i=1,#X do
      if X[i]:nodeType() == 'text' then
         return X[i]
      end
   end
   return X:append(xml.TEXT, '')
end

-- set or create+set a text element
-- NOTE: uses node.text() to create element if needed
function node.setText(X, T)
   X:text():setInner(T)
end

-- set or create+set an XML attribute
function node.setAttr(N, K, V)
   if N:nodeType() ~= 'element' then
      error('Must be an element')
   end
   if not N[K] or N[K]:nodeType() ~= 'attribute' then
      N:append(xml.ATTRIBUTE, K)
   end
   N[K] = V
   return N
end

-- find an XML element by name
function xml.findElement(X, Name)
   if X:nodeName() == Name then
      return X
   end
   for i = 1, #X do
      local Y = xml.findElement(X[i], Name)
      if Y then return Y end
   end
   return nil
end

-- append an XML element
function node.addElement(X, Name)
   return X:append(xml.ELEMENT, Name)
end

local node_setText = {
   Title="node.setText",
   Usage="node.setText(target, value)",
   SummaryLine="Sets the text in an XML TEXT element.",
   Desc=[[Sets the text in an XML TEXT element. This works with a simple text element, 
   or a "complex element" (one with sub-elements). If a text element does not exist it
   is appended to the parent element.
   ]],
   ParameterTable= false,
   Parameters={
      {target={Desc='Parent XML Element to set the text for <u>xml element</u>'}},
      {value={Desc='Text string value for the element <u>string</u>'}}, 
   },
   Examples={[[   node.setText(CD.title, 'Good Health Clinic Consultation Note')
   --> &lt;title&gt;Good Health Clinic Consultation Note&lt;/title&gt;

   -- In this example we append a text element to a complex element
   node.setText(GP.name, 'Append a text element')

   -- Result:      
   &lt;name&gt;
       &lt;given&gt;Ralph&lt;/given&gt;
       &lt;family&gt;Jones&lt;/family&gt;
       Append a text element  -- appended text element
   &lt;/name&gt;
   ]]},
   SeeAlso={
      {
         Title="xml.lua - in our code repository",
         Link="http://help.interfaceware.com/code/details/xml-lua"
      },
      {
         Title="XML Techniques in the Protocols repository",
         Link="http://help.interfaceware.com/v6/xml-channel"
      },
      {
         Title="Working with X12",
         Link="http://help.interfaceware.com/v6/working-with-x12"
      }
   }
}

help.set{input_function=node.setText, help_data=node_setText}

local node_setAttr = {
   Title="node.setAttr",
   Usage="node.setAttr(target, atribute, value)",
   SummaryLine="Sets the named attribute to a specified value.",
   Desc=[[Sets the named attribute to a specified value. If a the specified attribute does 
   not exist it is appended to the parent element. 
   ]],
   ParameterTable= false,
   Parameters={
      {target={Desc='Parent XML Element to set the attribute for <u>xml element</u>'}},
      {attribute={Desc='The name of the attribute to set <u>string</u>'}}, 
      {value={Desc='Text string value for the attribute <u>string</u>'}}, 
   },
   Returns={{Desc="The updated parent element <u>xml element</u>"}},
   Examples={[[   -- append an attribute to the "playingEntity"
   node.setAttr(PE, 'classCode', 'PLC')

   Result:   
   &lt;playingEntity classCode="PLC"&gt;                     -- appended attribute
      &lt;name&gt;Community Urgent Care Center&lt;/name&gt;
   &lt;/playingEntity&gt;
      
   -- append a another attribute
   node.setAttr(PE, 'another', 'attribute')
      
   Result:
   &lt;playingEntity classCode="PLC" another="attribute"&gt; -- another appended attribute
      &lt;name>Community Urgent Care Center&lt;/name&gt;
   &lt;/playingEntity&gt;
   ]]},
   SeeAlso={
      {
         Title="xml.lua - in our code repository",
         Link="http://help.interfaceware.com/code/details/xml-lua"
      },
      {
         Title="XML Techniques in the Protocols repository",
         Link="http://help.interfaceware.com/v6/xml-channel"
      },
      {
         Title="Working with X12",
         Link="http://help.interfaceware.com/v6/working-with-x12"
      }
   }
}

help.set{input_function=node.setAttr, help_data=node_setAttr}

local node_addElement = {
   Title="node.addElement",
   Usage="node.addElement{target, element)",
   SummaryLine="Appends an empty named element .",
   Desc=[[Appends an empty named element to the specified target (parent) element.]],
   Returns={Desc={"The appended element <u>xml element</u>"}},
   Parameters={
      {target={Desc='Parent XML Element to add the element to <u>xml element</u>'}},
      {element={Desc='The name of the element to append <u>string</u>'}}, 
   },
   Examples={[[   local P = node.addElement(birthplace, 'place')
      
   -- Result:      
   &lt;birthplace&gt;
      &lt;place&gt;   -- place element added
      &lt;/place&gt;
   &lt;/birthplace&gt;]]},
   SeeAlso={
      {
         Title="xml.lua - in our code repository",
         Link="http://help.interfaceware.com/code/details/xml-lua"
      },
      {
         Title="XML Techniques in the Protocols repository",
         Link="http://help.interfaceware.com/v6/xml-channel"
      },
      {
         Title="Working with X12",
         Link="http://help.interfaceware.com/v6/working-with-x12"
      }
   }
}

help.set{input_function=node.addElement, help_data=node_addElement}

local xml_findElement = {
   Title="xml.findElement",
   Usage="xml.findElement(target, element)",
   SummaryLine="Find the first element of the specified name in the target.",
   Desc=[[Find the first element of the specified name in the target. 
   <p>If the target is a tree, it will do a depth-first search of tree. 
   <p><strong>Note</strong>: If there are multiple elements with the same name
   this function will only find the first one.
   ]],
   Returns={{Desc="The first element found that matches the name specified <u>xml element</u>"}},
   Parameters={
      {target={Desc='Element to search within <u>xml element</u>'}},
      {element={Desc='The name of the element to search for <u>string</u>'}}, 
   },
   Examples={"xml.findElement(G,'guardianPerson')"},
   SeeAlso={
      {
         Title="xml.lua - in our code repository",
         Link="http://help.interfaceware.com/code/details/xml-lua"
      },
      {
         Title="XML Techniques in the Protocols repository",
         Link="http://help.interfaceware.com/v6/xml-channel"
      },
      {
         Title="Working with X12",
         Link="http://help.interfaceware.com/v6/working-with-x12"
      }
   }
}

help.set{input_function=xml.findElement, help_data=xml_findElement}