"""sgmltag.py:  SGML tag processing module

    $Revision: 1.9 $  $Date: 2002/08/01 07:15:12 $

  Exports:
    giStartCset:  a Cset object representing the characters that can
                  be the first character of a Generic Identifier (GI)
    giCset:       a Cset object representing the characters that can
                  be the non-first characters of a Generic Identifier (GI)
    class SGMLTag:  Represents one opening or closing tag
    def SGML_Tag_Scan():  Scans one tag from a Scan object
    class TagAttr:  Represents one attribute of a tag
    def Tag_Attr_Scan():  Scans one attribute from a Scan object
"""

import string               # Standard string module
from cset import *          # Author's Icon cset type

giStartCset  =  letters
giCset       =  Cset("_-").union(digits).union(letters)

SGML_TAG_OPEN      =  "<"
SGML_COMMENT_GI    =  "!"       # Appears in the GI position of a comment
SGML_COMMENT_HEAD  =  "!--"     # Starts a comment
SGML_COMMENT_TAIL  =  "-->"     # Ends a comment

class SGMLTag:
    """Represents one opening or closing SGML tag.

      Exports:
        SGMLTag ( gi, isClose, attrList, text=None ):
          [ if (gi is the Generic Identifier as a nonempty string)
            and (isClose is 0 an opening tag, 1 for a closing tag)
            and (attrList is a list of TagAttr objects representing
            zero or more attributes, if not a comment, else None)
            and (text is a string contain the comment text, if a comment,
            else None) ->
              return a new SGMLTag with those values ]
        .gi:        [ as passed to constructor ]
        .isClose:   [ as passed to constructor ]
        .attrList:
          [ if the attrList argument passed to the constructor was None ->
              an empty list
            else -> as passed to constructor ]
        .text:      [ as passed to constructor ]
        str():
          [ returns self reconstituted as a text string ]
    """


# - - -    S G M L T a g . _ _ i n i t _ _   - - -

    def __init__ ( self, gi, isClose, attrList, text=None ):
        self.gi        =  gi
        self.isClose   =  isClose
        self.text      =  text

        if  attrList:
            self.attrList  =  attrList
        else:
            self.attrList  =  []


# - - -   S G M L T a g . _ _ s t r _ _   - - -

    def __str__ ( self ):
        """Reconstitute self as a string
        """

        #-- 1 --
        if  self.gi == SGML_COMMENT_GI:
            return "<%s%s%s" % ( SGML_COMMENT_HEAD,
                                 self.text, SGML_COMMENT_TAIL )

        #-- 2 --
        L  =  ["<"]

        #-- 3 --
        if  self.isClose:
            L.append ( "/" )

        #-- 4 --
        L.append ( self.gi )

        #-- 5 --
        for attr in self.attrList:
            L.append ( " " )
            L.append ( str ( attr ) )

        #-- 6 --
        L.append ( ">" )

        #-- 7 --
        return string.join ( L, "" )


# - - -   S G M L _ T a g _ S c a n   - - -

def SGML_Tag_Scan ( scan ):
    """Parses an SGML tag from a Scan object.

      [ if scan is a Scan object ->
          if scan starts with a syntactically valid SGML tag ->
            scan  :=  scan advanced past that tag
            return a new SGMLTag object representing the tag
          else if scan appears to start with a tag but it is
          syntactically invalid ->
            scan   :=   scan advanced past the valid-looking part, but at
                        least one character
            Log()  +:=  error message(s)
            return None
          else ->
            return None ]
    """

    #-- 1 --
    # [ if scan starts with SGML_TAG_OPEN ->
    #     scan  :=  scan advanced one
    #   else ->
    #     return None ]
    if  not scan.tabMatch ( SGML_TAG_OPEN ):
        return None

    #-- 2 --
    # [ if scan starts with SGML_COMMENT_HEAD followed by arbitrary
    #   text and then, possibly on a different line, SGML_COMMENT_TAIL ->
    #     scan  :=  scan advanced past the first occurrence of
    #               SGML_COMMENT_TAIL
    #     return a new SGMLTag object representing a comment whose text
    #     is all text between scan's current position and the first
    #     occurrence of SGML_COMMENT_TAIL
    #   else if scan starts with SGML_COMMENT_HEAD but there is no
    #   SGML_COMMENT_TAIL anywhere in scan ->
    #     scan   :=   scan advanced to EOF
    #     Log()  +:=  error message(s)
    #     return None
    #   else -> I ]
    if  scan.tabMatch ( SGML_COMMENT_HEAD ):
        return SGML_Tag_Scan_Comment ( scan )

    #-- 3 --
    # [ if the next character in scan is "/" ->
    #     scan     :=  scan advanced one
    #     isClose  :=  1
    #   else ->
    #     isClose  :=  0 ]
    if  scan.tabMatch ( "/" ):
        isClose  =  1
    else:
        isClose  =  0

    #-- 4 --
    # [ if scan starts with a valid GI ->
    #     scan  :=  scan advanced past that GI
    #     gi    :=  that GI as a string
    #   else ->
    #     Log()  +:=  error message(s)
    #     return None ]
    gi  =  SGML_Tag_Scan_GI ( scan )

    if  gi is None:
        return None

    #-- 5 --
    # [ scan      :=  scan advanced past all leading whitespace, including
    #                 any number of newlines
    #   attrList  :=  an empty list ]
    scan.deblank()
    attrList  =  []

    #-- 6 --
    # [ if scan contains one or more attributes separated by whitespace ->
    #     scan      :=   scan advanced past all attributes and whitespace
    #     attrList  :=   attrList with TagAttr objects appended representing
    #                    those attributes
    #     Log()     +:=  error messages about badly formed attributes, if any
    #   else -> I ]
    SGML_Tag_Scan_Attr_List ( scan, attrList )

    #-- 7 --
    # [ if scan starts with ">" ->
    #     scan  :=  scan advanced by one
    #     return a new SGMLTag object with .name=name, .isClose=isClose,
    #     .attrList=attrList, and .text=None
    #   else ->
    #     Log()  +:=  error message
    #     return None ]
    if  not scan.tabMatch ( ">" ):
        scan.error ( "Expecting the `>' at the end of an SGML tag." )
        return None
    else:
        return SGMLTag ( gi, isClose, attrList )


# - - -   S G M L _ T a g _ S c a n _ C o m m e n t   - - -

def SGML_Tag_Scan_Comment ( scan ):
    """Scan an SGML comment, after the opening `<!--'

      [ if there is at least one occurrence of SGML_COMMENT_TAIL
        somewhere in scan, possibly on a different line ->
          scan  :=  scan advanced past the first such occurrence
          return an SGMLTag with gi=SGML_COMMENT_GI
        else ->
          scan   :=   scan advanced to EOF
          Log()  +:=  error message
          return None ]
    """

    #-- 1 --
    L  =  []

    #-- 2 --
    # [ if SGML_COMMENT_TAIL occurs somewhere in scan, possibly on a
    #   different line ->
    #     scan  :=   scan advanced past the first such occurrence
    #     L     +:=  all text, including newlines, up to the first occurrence
    #     done  :=   1
    #   else ->
    #     scan   :=   scan advanced to EOF
    #     done   :=   0 ]
    done  =  0
    while ( ( not scan.atEndFile ) and
            ( not done ) ):

        #-- 2.1 --
        # [ if current line in scan contains SGML_COMMENT_TAIL ->
        #     endPos  :=  the position where it starts
        #   else ->
        #     endPos  :=  None ]
        endPos  =  scan.find ( SGML_COMMENT_TAIL )

        #-- 2.2 --
        # [ if endPos is None ->
        #     scan  :=   scan advanced to the start of the next line
        #     L     +:=  (remainder of the current line) + "\n"
        #   else ->
        #     scan  :=   scan advanced up to endPos, plus the length
        #                of SGML_COMMENT_TAIL
        #     L     +:=  text from scan up to endPos
        #     done  :=   1 ]
        if  endPos is not None:
            L.append ( scan.tab ( endPos ) )
            scan.move ( len ( SGML_COMMENT_TAIL ) )
            done  =  1
        else:
            L.append ( scan.tab ( -1 ) )
            L.append ( "\n" )
            scan.nextLine()

    #-- 3 --
    # [ if done ->
    #     return a new SGMLTag object with .gi=SGML_COMMENT_GI, .isClose=0,
    #     .attrList=None, and .text=(elements of L, concatenated)
    #   else ->
    #     Log()  +:=  error message
    #     return None ]
    if  done:
        return SGMLTag ( SGML_COMMENT_GI, 0, None, string.join ( L, "" ) )
    else:
        scan.error ( "SGML comments must end with `%s'." %
                     SGML_COMMENT_TAIL )
        return None


# - - -   S G M L _ T a g _ S c a n _ G I   - - -

def SGML_Tag_Scan_GI ( scan ):
    """Parse the Generic Identifier (GI) of an SGML tag from a Scan object

      [ if scan is a Scan object ->
          if scan starts with a valid GI ->
            scan  :=  scan advanced past that GI
            return the GI as a string, lowercased
          else ->
            Log()  +:=  error message(s)
            return None ]
    """
    #-- 1 --
    # [ if the next character in scan is in giStartCset ->
    #     scan  :=  scan advanced one
    #     gi    :=  next character from scan
    #   else ->
    #     Log()  +:=  error message
    #     return None ]
    gi  =  scan.tabAny ( giStartCset )
    if  gi is None:
        scan.error ( "Expecting the Generic Identifier (GI) of an SGML tag." )
        return None

    #-- 2 --
    # [ if scan starts with a character in giCset ->
    #     scan  :=  scan advanced past all leading letters in giCset
    #     gi    :=  gi + all leading letters in giCset
    #   else -> I ]
    rest  =  scan.tabMany ( giCset )

    if  rest:
        gi  =  gi + rest

    #-- 3 --
    return string.lower ( gi )


# - - -   S G M L _ T a g _ S c a n _ A t t r _ L i s t   - - -

def SGML_Tag_Scan_Attr_List ( scan, attrList ):
    """Scan any SGML attributes and add them as TagAttr objects to attrList.

      [ if scan contains one or more attributes separated by whitespace ->
          scan      :=   scan advanced past all attributes and whitespace
          attrList  :=   attrList with TagAttr objects appended representing
                         those attributes
          Log()     +:=  error messages about badly formed attributes, if any
        else -> I ]
    """
    #-- 1 --
    # [ if scan starts with a valid attribute ->
    #     scan  :=  scan advanced past that attribute and any trailing
    #               whitespace
    #     attr  :=  a TagAttr representing that attribute
    #     done  :=  0
    #   else if scan starts with a badly formed attribute ->
    #     scan   :=   scan advanced past that attribute, at least one
    #                 character
    #     Log()  +:=  error message(s)
    #     attr   :=   None
    #     done   :=   0
    #   else ->
    #     attr   :=  None
    #     done   :=  1 ]
    (attr, done)  =  Tag_Attr_Scan ( scan )

    #-- 2 --
    while  not done:
        if  attr:
            attrList.append ( attr )

        (attr, done)  =  Tag_Attr_Scan ( scan )


# - - - - -   c l a s s   T a g A t t r   - - -

class TagAttr:
    """Represents one attribute, with optional value, in an SGML tag.

      Exports:
        TagAttr ( name, value, isQuoted ):
          [ if (name is an attribute name as a string)
            and (value is an attribute value as a string, or None
            if the attribute has no value)
            and (isQuoted is 1 for a value in quotes, 0 if no quotes) ->
              return a new TagAttr object with those values ]
        .name:      [ as passed to constructor ]
        .value:     [ as passed to constructor ]
        .isQuoted:  [ as passed to constructor ]
        str():      [ return self as a string ]
    """


# - - -   T a g A t t r . _ _ i n i t _ _   - - -

    def __init__ ( self, name, value, isQuoted ):
        self.name      =  string.lower ( name )
        self.value     =  value
        self.isQuoted  =  isQuoted


# - - -   T a g A t t r . _ _ s t r _ _   - - -

    def __str__ ( self ):
        """Return self displayed as a string.
        """

        #-- 1 --
        L  =  [ self.name ]

        #-- 2 --
        if  self.value:
            L.append ( "=" )
            if  self.isQuoted:
                L.append ( '"' )
                L.append ( self.value )
                L.append ( '"' )
            else:
                L.append ( self.value )

        #-- 3 --
        return string.join ( L, "" )


# - - -   T a g _ A t t r _ S c a n   - - -

def Tag_Attr_Scan ( scan ):
    """Parse one SGML attribute from a Scan object.

      [ if scan is a Scan object ->
          if scan starts with a valid attribute ->
            scan  :=  scan advanced past that attribute and any
                      trailing whitespace
            return (a TagAttr representing that attribute, 0)
          else if scan starts with a badly formed attribute ->
            scan   :=   scan advanced past that attribute, at least one
            Log()  +:=  error message(s)
            return (None, 0)
          else ->
            return (None, 1) ]
    """

    #-- 1 --
    # [ if scan starts with a character in giStartCset ->
    #     scan    :=  scan advanced one
    #     result  :=  next character from scan
    #   else ->
    #     return (None, 1) ]
    name  =  scan.tabAny ( giStartCset )

    if  name is None:
        return (None, 1)

    #-- 2 --
    # [ if scan starts with one or more characters in giCset ->
    #     scan    :=  scan advanced after all leading characters in giCset
    #     result  :=  result + all leading characters in giCset
    #   else -> I ]
    tail  =  scan.tabMany ( giCset )

    if  tail:
        name  =  name + tail

    #-- 3 --
    scan.deblank()
    name  =  string.lower ( name )

    #-- 4 --
    # [ if scan starts with "=" ->
    #     scan  :=  scan advanced past the "=" and any following whitespace 
    #   else ->
    #     return (TagAttr (name, None, 0), 0) ]
    pastEqual  =  scan.match ( "=" )
    if  not pastEqual:
        return (TagAttr ( name, None, 0), 0)
    else:
        scan.tab ( pastEqual )
        scan.deblank()
        
    #-- 5 --
    # [ if scan starts with a quoted string or unquoted token ->
    #     scan      :=  scan advanced past all that and any following
    #                   whitespace
    #     value     :=  the contents of the quoted string or token
    #     isQuoted  :=  1 if a quoted string, 0 if unquoted
    #   else ->
    #     scan      :=   scan advanced past the valid part, if any
    #     value     :=   None
    #     isQuoted  :=   <anything>
    #     Log()     +:=  error message ]
    (value, isQuoted)  =  Tag_Attr_Scan_Value ( scan )

    #-- 6 --
    if  value is not None:
        return (TagAttr ( name, value, isQuoted ), 0)
    else:
        return (None, 0)


# - - -   T a g _ A t t r _ S c a n _ V a l u e   - - -

def Tag_Attr_Scan_Value ( scan ):
    """Process the <value> part of "<gi [name=value ...]>"

      [ if scan is a Scan object ->
          if scan starts with a quoted string ->
            scan  :=  scan advanced past that string and any trailing
                      whitespace
            return (string contents, 1)
          else if scan starts with an unquoted token ->
            scan  :=  scan advanced past that token and any trailing
                      whitespace
            return (token as a string, 0)
          else ->
            Log()  +:=  error message
            return (None, 0) ]
    """
    #-- 1 --
    # [ if scan starts with character in giStartCset ->
    #     scan      :=  scan advanced past that and any following characters
    #                   in giCset
    #     value     :=  next character and any following characters in giCset
    #     isQuoted  :=  0
    #   else if scan starts with '"' and the closing '"' is on the same line ->
    #     scan      :=  scan advanced past the closing '"'
    #     value     :=  all characters between quotes
    #     isQuoted  :=  1
    #   else if scan starts with '"' but there is no closing '"' on the
    #   same line ->
    #     scan   :=   scan advanced past the opening '"'
    #     Log()  +:=  error message
    #     return (None, 0) ]
    pastFirst  =  scan.any ( giCset )
    if  pastFirst:
        value  =  scan.tab ( pastFirst )
        tail   =  scan.tabMany ( giCset )
        if  tail:
            value  =  value + tail
        isQuoted  =  0
    else:
        pastOpen  =  scan.match ( '"' )
        if  pastOpen:
            scan.tab ( pastOpen )
            closePos  =  scan.find ( '"' )
            if  not closePos:
                scan.error ( "The closing quote must be on the same "
                             "input line." )
                return (None, 0)
            value     =  scan.tab ( closePos )
            scan.move ( 1 )
            isQuoted  =  1
        else:
            scan.error ( "Tag attribute values must be alphanumeric "
                         "or enclosed in double-quotes ('\"')." )
            return (None, 0)

    #-- 2 --
    # [ scan  :=  scan advanced past all leading whitespace ]
    scan.deblank()

    #-- 3 --
    return ( value, isQuoted )