Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
domNode(n)							    domNode(n)

______________________________________________________________________________

NAME
       domNode - Manipulates an	instance of a DOM node object

SYNOPSIS
       $nodeObject method arg arg ...
       domNode nodeToken method	arg arg	...
_________________________________________________________________

 DESCRIPTION
       This  command manipulates one particular	instance of a DOM node object.
       method indicates	a specific method of the  node	class.	These  methods
       should closely conform to the W3C recommendation	"Document Object Model
       (Core)	Level	1"    (http://www.w3.org/TR/REC-DOM-Level-1/level-one-
       core.html)  as  well  to	 parts	of the W3C draft "XML Pointer Language
       (XPointer)" (http://www.w3.org/TR/1998/WD-xptr-19980303).  Please note,
       that  the XPointer methods are deprecated. Use DOM methods or XPath ex-
       pressions instead of them.

       The selectNodes method implements the "XML Path Language	 (XPath)  Ver-
       sion	 1.0"	   W3C	   recommendation     16     November	  1999
       (http://www.w3.org/TR/1999/REC-xpath-19991116). Look at these documents
       for a deeper understanding of the functionality.

       The valid methods are:

       nodeType
	      Returns  the  node  type	of that	node object. This can be: ELE-
	      MENT_NODE, TEXT_NODE, CDATA_SECTION_NODE,	COMMENT_NODE  or  PRO-
	      CESSING_INSTRUCTION_NODE.

       nodeName
	      Returns  the  node name of that node object. This	is the element
	      (tag) name for element nodes (type ELEMENT_NODE),	 the  process-
	      ing-instruction  target for processing-instructions, "#text" for
	      text node, "#comment" for	comment	nodes or  "#cdata"  for	 cdata
	      section nodes.

       nodeValue ?newValue?
	      Returns  the  value of that node object. This is the text	or the
	      data for element nodes of	type TEXT_NODE,	COMMENT_NODE, PROCESS-
	      ING_INSTRUCTION_NODE  or	CDATA_SECTION_NODE).  Otherwise	 it is
	      empty. If	the node is  a	TEXT_NODE,  COMMENT_NODE  or  PROCESS-
	      ING_INSTRUCTION_NODE  and	 the  optional	argument  newValue  is
	      given, the node is set to	that value.

       hasChildNodes
	      Returns 1	if the node has	children. Otherwise 0 is returned.

       parentNode ?objVar?
	      Returns the parent node.

       childNodes
	      Returns a	list of	direct children	node objects.

       childNodesLive
	      Returns a	"live" nodeList	object of the child nodes of the  node
	      in  the sense of the DOM recommendation. This nodeList object is
	      "live" in	the sense that,	for instance, changes to the  children
	      of  the node object that it was created from are immediately re-
	      flected in the nodes returned by the NodeList accessors;	it  is
	      not a static snapshot of the content of the node.	The two	acces-
	      sors known by the	nodeList object	are "item <index>", which  re-
	      turns  the  indexth  item	in the collection, and "length", which
	      returns the number of nodes in the list.

       firstChild ?objVar?
	      Returns the first	child as a node	object.

       lastChild ?objVar?
	      Returns the last child as	a node object.

       nextSibling  ?objVar?
	      Returns the next sibling relative	to the current node as a  node
	      object.

       previousSibling ?objVar?
	      Returns  the next	sibling	relative to the	current	node as	a node
	      object.

       getElementsByTagName name
	      Returns a	list of	all elements in	 the  subtree  matching	 (glob
	      style) name.

       getElementsByTagNameNS uri localname
	      Returns  a  list	of  all	elements in the	subtree	matching (glob
	      style) localname and having the given namespace uri.

       getElementById id
	      Returns the node having an id attribute with  value  id  or  the
	      empty string if no node has an id	attribute with that value.

       hasAttribute attributeName
	      Returns 1	if the object node contains an attribute with name at-
	      tributeName . Otherwise 0	is returned.

       getAttribute attributeName  ?defaultValue?
	      Returns the value	of the attribute attributeName.	If the	attri-
	      bute is not available defaultValue is returned.

       setAttribute attributeName newValue  ?attributeName newValue ...?
	      Sets  the	 value for one or more attributes. Every attributeName
	      is set to	the corresponding newValue. If there isn't  an	attri-
	      bute for one or more of the attributeName, this will create that
	      attribute.  It is	not recommended	to set	attributes  that  look
	      like xml namespace declarations.

       removeAttribute attributeName
	      Removes the attribute attributeName.

       hasAttributeNS uri localName
	      Returns  1 if the	object node contains an	attribute with the lo-
	      cal name localName within	the namespace uri.  Otherwise 0	is re-
	      turned.

       getAttributeNS uri localName ?defaultValue?
	      Returns the value	of the attribute with the local	name localName
	      within the namespace URI uri. If the node	dosn't have  that  at-
	      tribute the defaultValue is returned.

       setAttributeNS  uri  qualifiedName newValue ?uri	qualifiedName newValue
       ...?

	      Sets the value for one or	more full qualified attributes.	 Every
	      attribute	 qualifiedName	with the namespace URI uri will	be set
	      to newValue. This	will create a  new  attribute,	if  it	wasn't
	      avialble	before.	If you want to set an attribute	within a name-
	      space you	must specify the attribute name	with prefix,  even  if
	      you  want	 to  set an already existing attribute to a new	value.
	      While searching, if the attribute	already	exists,	only the given
	      uri and the localname of the qualifiedName is used.

		     $node setAttributeNS "http://some.uri.com/wow" prefix:attr1 attrValue

	      If  the  uri is the empty	string and the attribute name hasn't a
	      prefix, this method has the same effect  as  the	method	setAt-
	      tribute.

		     $node setAttributeNS "" attri "some Value"

	      With  the	 exceptions  of	the special prefixes "xmlns" and "xml"
	      you always must provide a	non empty uri, if  your	 qualifiedName
	      has  a prefix. It	is not recommended to set xml namespace	decla-
	      rations. The effects are complicated and not always  obvious  up
	      to resulting a not well-formed serializations after further pro-
	      cessing.

       removeAttributeNS uri localName
	      Removes the attribute with the local name	localName  within  the
	      namespace	uri.

       attributes ?attributeNamePattern?
	      Returns information about	the attriubtes matching	the attribute-
	      NamePattern. If attributeNamePattern  isn't  given,  information
	      about  all  attributes  are returned.  The return	value is a Tcl
	      list, the	elements just the  attriubute  name  in	 case  of  non
	      namespaced  attriubtes and three element sublists	for namespaced
	      attributes. n case of an "ordinary"  namespaced  attribute,  the
	      sublist  elements	are {<localname> <prefix> <namespace_uri>}. In
	      the special case of an xml namespace  declaration	 it  is	 {<the
	      prefix defined> <localname> ""}.

       attributeNames ?attributeNamePattern?
	      Returns a	flat list of all attributes names (as found in the XML
	      source) matching the attributeNamePattern. If  attributeNamePat-
	      tern  isn't  given,  all	attribute  names are returned as a Tcl
	      list.

       appendChild newChild
	      Appends newChild to the end of the child list of the node.

       insertBefore newChild  refChild
	      Inserts newChild before the refChild into	the list  of  children
	      of node. If refChild is the empty	string,	insert newChild	at the
	      end of the child nodes list of that node.

       replaceChild newChild  oldChild
	      Replaces oldChild	with newChild in the list of children of  that
	      node.  The  oldChild  node will be part of the document fragment
	      list after this operation.

       removeChild child
	      Removes child from the list of children  of  that	 node.	 child
	      will be part of the document fragment list after this operation.

       delete Deletes the given	node and its complete child tree and frees the
	      complete internal	memory.	The affected nodes are not  accessible
	      through the document fragment list.

       cloneNode ?-deep?
	      Clones  this node	and adds the new create	node into the document
	      fragment list. If	the -deep option is specified, all  descendant
	      nodes are	also cloned.

       ownerDocument ?domObjVar?
	      Returns  the  document  object of	the document this node belongs
	      to.

       find attrName attrVal ?objVar?
	      Finds the	node with the attribute	name attrName,	and  attribute
	      value attrVal in the subtree starting the	current	node.

       child number|all	type attrName attrValue
	      (XPointer) child

       descendant number|all type attrName attrValue
	      (XPointer) descendant

       ancestor	number|all type	attrName attrValue
	      (XPointer) ancestor

       fsibling	number|all type	attrName attrValue
	      (XPointer) fsibling

       psibling	number|all type	attrName attrValue
	      (XPointer) psibling

       root  objVar
	      (XPointer) root

       text   Returns  all  text  node children	of that	current	node combined,
	      i.e. appended into one string.

       target For a processing instruction node	the target part	 is  returned.
	      Otherwise	an error is generated.

       data   For a processing instruction node	the data part is returned. For
	      a	text node, comment node	or cdata section node the value	is re-
	      turned.  Otherwise an error is generated.

       prefix Returns the namespace prefix.

       namespaceURI
	      Returns the namespace URI.

       localName
	      Returns the localName from the tag name of the given node.

       selectNodes  ?-namespaces  prefixUriList? ?-cache <boolean>? xpathQuery
       ?typeVar?

	      Returns the result of applying the XPath query xpathQuery	to the
	      subtree.	This  can be a string/value, a list of strings,	a list
	      of nodes or a list of attribute name / value pairs.  If  typeVar
	      is  given	 the  result  type  name  is stored into that variable
	      (empty, bool, number, string, nodes, attrnodes or	mixed).

	      The argument xpathQuery has to  be  a  valid  XPath  expression.
	      However  there  are  a few exceptions to that rule. Tcl variable
	      references (in the usual tcl syntax: $varname) may appear	in the
	      XPath  statement	at any position	where it is legal according to
	      the rules	of the XPath syntax to put an XPath variable. Ignoring
	      the syntax rules of XPath	the Tcl	variable name may be any legal
	      Tcl var name: local variables, global variables,	array  entries
	      and  so  on.  The	value will always be seen as string literal by
	      the xpath	engine.	Cast the value explicitly with	the  according
	      xpath  functions	(number(), boolean()) to another data type, if
	      needed.

	      Similar to the way described above to inject literals in	a  se-
	      cure way into the	XPath expression using tcl variable references
	      there is a syntax	to inject element names	from tcl variables. At
	      every  place  where  the	XPath  syntax allows a node test there
	      could be a tcl variable reference	(in any	form), just the	 lead-
	      ing  $  replaced	with  %.  This allows one to select nodes with
	      'strange'	(invalid, according to the appropriate XML  production
	      rule)  node  names  which	 may be	needed in case of working with
	      JSON data.

	      The option -namespaces expects a tcl list	with  prefix  /	 name-
	      space  pairs  as argument. If this option	is not given, then any
	      namespace	prefix within the xpath	expression will	be  first  re-
	      solved against the list of prefix	/ namespace pairs set with the
	      selectNodesNamespaces method for the document, the node  belongs
	      to.  If  this  fails, then the namespace definitions in scope of
	      the context node will be used to resolve the prefix. If this op-
	      tion  is given, any namespace prefix within the xpath expression
	      will be first resolved against that given	list (and ignoring the
	      document	global prefix /	namespace list). If the	list binds the
	      same prefix to different namespaces, then	the first binding will
	      win.   If	this fails, then the namespace definitions in scope of
	      the context node will be used to resolve the prefix, as usual.

	      If the -cache option is used with	a true value, then the	xpath-
	      Query  will  be  looked  up in a document	specific cache.	If the
	      query is found, then the stored pre-compiled query will be used.
	      If  the query isn't found, it will be compiled and stored	in the
	      cache, for use in	further	calls. Please note that	the xpathQuery
	      given  as	 string	is used	as key for the cache. This means, that
	      equal XPath expressions, which differ only in  white  space  are
	      treated  as  different cache entries. Special care is needed, if
	      the XPath	expression includes namespace prefixes	or  references
	      to tcl variables.	 Both namespace	prefixes and tcl variable ref-
	      erences will be resolved according to the	XML  prefix  namespace
	      mappings and tcl variable	values at expression compilation time.
	      If the same XPath	expression is used later on in a context  with
	      other  XML  prefix  namespace mappings or	values of the used tcl
	      variables, make sure to first  remove  the  compiled  expression
	      from  the	cache with the help of the deleteXPathCache method, to
	      force a recompilation.  Without using  the  -cache  option  such
	      consideration is never needed.

	      Examples:

		     set paragraphNodes	[$node selectNodes {chapter[3]//para[@type='warning' or	@type='error'} ]
		     foreach paragraph $paragraphNodes {
			 lappend  values [$paragraph selectNodes attribute::type]
		     }

		     set doc [dom parse	{<doc xmlns="http://www.defaultnamespace.org"><child/></doc>}]
		     set root [$doc documentElement]
		     set childNodes [$root selectNodes -namespaces {default http://www.defaultnamespace.org} default:child]

       getLine
	      Returns  the  line  number of that node in the originally	parsed
	      XML.

       getColumn
	      Returns the column number	of that	node in	the originally	parsed
	      XML.

       asList Returns  the  DOM	 substree  starting form the current node as a
	      nested Tcl list.

       asXML  ?-indent	none/1..8?  ?-channel	channelId?   ?-escapeNonASCII?
       -xmlDeclaration	<boolean>?  -encString <string>	?-escapeAllQuot? ?-in-
       dentAttrs? ?-nogtescape?	?-noEmptyElementTag?

	      Returns the DOM substree starting	from the current node  as  the
	      root  node of the	result as an (optional indented) XML string or
	      sends the	output directly	to the given channelId.

	      If the option -escapeNonASCII is given, every non	 7  bit	 ASCII
	      character	 in attribute values or	element	PCDATA content will be
	      escaped as character reference in	decimal	representation.

	      The flag -xmlDeclaration determines whether there	will be	an XML
	      Declaration  and a newline emitted before	anything else. The de-
	      fault is,	to do not. If this flag	is given with a	true  argument
	      then

	      -encString  sets the encoding value in the XML Declaration. Oth-
	      erwise, this option is ignored. Please note,  that  this	option
	      just enhance the string representation of	the generated XML Dec-
	      laration with an encoding	information string, nothing more. It's
	      up  to the user to handle	encoding in case of writing to a chan-
	      nel or reparsing.

	      If the option -escapeAllQuot is given, quotation marks  will  be
	      escaped with &quot; even in text content of elements.

	      If  the  option -indentAttrs is given, then attributes will each
	      be separated with	newlines and indented to the same level	as the
	      parent  node  plus  the  value given as argument to -indentAttrs
	      (0..8).

	      If the option -nogtescape	is given then the character '>'	 won't
	      get  escaped  in	attribute values and text content of elements.
	      The default is to	escape this character.

	      If the option -noEmptyElementTag is given	then no	empty tag syn-
	      tax  will	 be  used. Instead, if an element has empty content it
	      will be serialized with an element start tag and an  immediately
	      following	element	end tag.

       asHTML ?-channel	channelId? ?-escapeNonASCII?  ?-htmlEntities?
	      Returns  the  DOM	substree starting from the current node	as the
	      root node	of the result serialized according to HTML rules (HTML
	      elements are recognized regardless of case, without end tags for
	      empty HTML elements etc.), as string or  sends  the  output  di-
	      rectly  to the given channelId. If the option -escapeNonASCII is
	      given, every non 7 bit ASCII character in	 attribute  values  or
	      element PCDATA content will be escaped as	character reference in
	      decimal representation. If the option -htmlEntities is given,  a
	      character	is written using its HTML 4.01 character entity	refer-
	      ence, if one is defined for it.

       asText For ELEMENT_NODEs, the asText method outputs the string-value of
	      every text node descendant of node in document order without any
	      escaping.	For every other	node type,  this  method  outputs  the
	      XPath string value of that node.

       appendFromList list
	      Parses  list , creates an	according DOM subtree and appends this
	      subtree to the current node.

       appendFromScript	tclScript
	      Appends the nodes	created	in the	tclScript  by  Tcl  functions,
	      which  have  been	 built	using  dom createNodeCmd, to the given
	      node.

       insertBeforeFromScript tclScript	refChild
	      Inserts the nodes	created	in the	tclScript  by  Tcl  functions,
	      which  have  been	 built using dom createNodeCmd,	before the re-
	      fChild into the list of children of node.	 If  refChild  is  the
	      empty string, the	new nodes will be appended.

       appendXML XMLstring
	      Parses  XMLstring,  creates an according DOM subtree and appends
	      this subtree to the current node.

       simpleTranslate outputVar specifications
	      Translates the subtree starting at the object node according  to
	      the  specifications  in specifications and outputs the result in
	      the variable outputVar . The translation is very similar to Cost
	      Simple mode.

       toXPath ?-legacy?
	      Returns  an XPath, which exactly addresses the given node	in its
	      document.	This XPath is only valid as there are  no  changes  to
	      DOM  tree	 made  later one. With the -legacy option, other XPath
	      expressions are returned,	which doesn't work in all cases.

       getBaseURI
	      Returns the baseURI of the node. This method  is	deprecated  in
	      favor of the baseURI method.

       baseURI ?URI?
	      Returns  the  present baseURI of the node. If the	optional argu-
	      ment URI is given, it sets the base URI of the node and  of  all
	      of  its  child nodes out of the same entity as node to the given
	      URI.

       disableOutputEscaping ?boolean?
	      This method works	only for text nodes; for every other  node  it
	      returns error. Without the optional argument it returns, if dis-
	      abling output escaping is	on. The	 return	 value	0  means,  the
	      characters  of  the text node will be escaped, to	generate valid
	      XML, if serialized. This is the default for every	parsed or cre-
	      ated  text  node (with the exception of that text	nodes in a re-
	      sult tree	of an XSLT transformation, for which disabling	output
	      escaping was requested explicitly	in the stylesheet). The	return
	      value 1 means, that output escaping is disabled  for  this  text
	      node.  If	such a text node is serialized (with asXML or asHTML),
	      it is literally written, without escaping	 of  the  special  XML
	      characters.  If the optional boolean value boolean is given, the
	      flag is set accordingly. You should not set this flag to 1 until
	      you really know what you do.

       precedes	refnode
	      Compares	the relative order of the node and refnode. Both nodes
	      must be part of the same documents and not out of	 the  fragment
	      list  of the document. Returns true if node is in	document order
	      (in the sense of the XPath 1.0 recommendation)  before  refnode,
	      and false	otherwise.

       normalize ?-forXPath?
	      Puts all Text nodes in the full depth of the sub-tree underneath
	      this Node	into a "normal"	form where only	structure (e.g.,  ele-
	      ments,  comments,	 processing  instructions  and CDATA sections)
	      separates	Text nodes, i.e.,  there  are  neither	adjacent  Text
	      nodes  nor  empty	 Text nodes. If	the option -forXPath is	given,
	      all CDATA	sections in the	nodes are converted to text nodes,  as
	      a	first step before the normalization.

       xslt ?-parameters parameterList?	?-ignoreUndeclaredParameters? ?-maxAp-
       plyDepth	int? ?-xsltmessagecmd script? stylesheet ?outputVar?
	      Applies an XSLT transformation on	the document  using  the  XSLT
	      stylesheet (given	as domDoc). Returns a document object contain-
	      ing the result document of that transformation and stores	it  in
	      the optional outputVar.

	      The  optional  -parameters  option sets top level	<xsl:param> to
	      string values. The parameterList has to be a tcl list consisting
	      of parameter name	and value pairs.

	      If the option -ignoreUndeclaredParameters	is given, then parame-
	      ter names	in the parameterList given to the -parameters  options
	      that  are	not declared as	top-level parameters in	the stylesheet
	      are silently ignored. Without this option, an error is raised if
	      the  user	 tries	to  set	a top-level parameter which is not de-
	      clared in	the stylesheet.

	      The option -maxApplyDepth	expects	a positive  integer  as	 argu-
	      ment.  By	default, the xslt engine allows	xslt templates to nest
	      up to 3000 levels	(and raises error if they nest	deeper).  This
	      limit can	be set by the -maxApplyDepth option.

	      The -xsltmessagecmd option sets a	callback for xslt:message ele-
	      ments in the stylesheet. The  actual  command  consists  of  the
	      script,  given  as argument to the option, appended with the XML
	      Fragment from instantiating the xsl:message element  content  as
	      string  (as  if  the XPath string() function would have been ap-
	      plied to the XML Fragment) and a flag, which  indicates  whether
	      the  xsl:message	has  an	 attribute  "terminate"	with the value
	      "yes". If	the called script returns anything  else  then	TCL_OK
	      then  the	 xslt transformation will be aborted, returning	error.
	      If the called script returns -code break the  error  message  is
	      empty,  otherwise	the result code	is reported. In	case of	termi-
	      nated transformation the outputVar, if  given,  is  set  to  the
	      empty string.

       @attrName
	      Returns  the  value  of  the  attribute attrName.	 Short cut for
	      getAttribute.

       jsonType	?OBJECT|ARRAY|NONE)|(STRING|NUMBER|TRUE|FALSE|NULL|NONE)?
	      Only element and text nodes may have a JSON type and  only  this
	      types of nodes support the jsonType method; the other node types
	      return error if called with this method.	Returns	 the  jsonType
	      of the node. If the optional argument is given, the JSON type of
	      the node is set to the given type	and returned. Valid type argu-
	      ments  for  element nodes	are OBJECT, ARRAY and NONE. Valid type
	      arguments	for text nodes are STRING, NUMBER, TRUE,  FALSE,  NULL
	      and NONE.

       Otherwise,  if  an  unknown  method name	is given, the command with the
       same name as the	given method within the	 namespace  ::dom::domNode  is
       tried to	be executed. This allows quick method additions	on Tcl level.

SEE ALSO
       dom, domDoc

KEYWORDS
       XML, DOM, document, node, parsing

Tcl								    domNode(n)

NAME | SYNOPSIS | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=domNode&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help