Next / Previous / Contents / Shipman's homepage

12. Sox.start(): Start an element

sox.py
# - - -   S o x . s t a r t

    def start(self, tag, *p, **kw):
        '''Start an element.
        '''

The first order of business is to check all the arguments. The tag argument must be an xml-name; this is checked by Section 13, “Sox._nameCheck(): Is this a valid xml-name?”. Then we go through the positional arguments and the keyword arguments and, assuming all are valid, separate them into content (contentList, a list of Unicode values) and attributes (attribs, a dictionary); see Section 16, “Sox._sortParams(): Classify content and attribute arguments”.

sox.py
        #-- 1
        # [ if tag is an xml-name ->
        #     uTag  :=  tag as unicode
        #   else -> raise SoxError ]
        uTag = self._nameCheck(tag)

        #-- 2
        # [ if p and kw are valid ->
        #     contentList  :=  a list of unicode values made from
        #         the non-dictionary elements of p
        #     attribs  :=  a dictionary made from the dictionary
        #         elements of p, plus the elements of kw
        #   else -> raise SoxError ]
        contentList, attribs = self._sortParams(p, kw)

Next we write the start tag: see Section 28, “Sox._startTag(): Write a start tag”.

sox.py
        #-- 3
        # [ sys.stdout  +:=  (an XML start tag with name (tag)
        #       and attributes made from (attribs)) ]
        self._startTag(uTag, attribs)

Following the start tag comes the initial content, if any.

sox.py
        #-- 4
        # [ if contentList is nonempty ->
        #     sys.stdout  +:=  concatenated elements of contentList
        #   else -> I ]
        if len(contentList) > 0:
            self.outFile.write(u''.join(contentList).encode('utf-8'))

Finally, fabricate the Elt instance, push it on the stack, and also return it.

sox.py
        #-- 5
        # [ self._stack  :=  a new Elt instance with name (tag)
        #   return that Elt instance ]
        elt = Elt(self, uTag)
        self._stack.append(elt)
        return elt