# $Id: references.py 5018 2007-03-12 21:39:31Z wiemann $

# Author: David Goodger <goodger@python.org>

# Copyright: This module has been placed in the public domain.

"""

Transforms for resolving references.

"""

__docformat__ = 'reStructuredText'

import sys

import re

from docutils import nodes, utils

from docutils.transforms import TransformError, Transform

class PropagateTargets(Transform):

    """

    Propagate empty internal targets to the next element.

    Given the following nodes::

        <target ids="internal1" names="internal1">

        <target anonymous="1" ids="id1">

        <target ids="internal2" names="internal2">

        <paragraph>

            This is a test.

    PropagateTargets propagates the ids and names of the internal

    targets preceding the paragraph to the paragraph itself::

        <target refid="internal1">

        <target anonymous="1" refid="id1">

        <target refid="internal2">

        <paragraph ids="internal2 id1 internal1" names="internal2 internal1">

            This is a test.

    """

    default_priority = 260

    def apply(self):

        for target in self.document.traverse(nodes.target):

            # Only block-level targets without reference (like ".. target:"):

            if (isinstance(target.parent, nodes.TextElement) or

                (target.hasattr('refid') or target.hasattr('refuri') or

                 target.hasattr('refname'))):

                continue

            assert len(target) == 0, 'error: block-level target has children'

            next_node = target.next_node(ascend=1)

            # Do not move names and ids into Invisibles (we'd lose the

            # attributes) or different Targetables (e.g. footnotes).

            if (next_node is not None and

                ((not isinstance(next_node, nodes.Invisible) and

                  not isinstance(next_node, nodes.Targetable)) or

                 isinstance(next_node, nodes.target))):

                next_node['ids'].extend(target['ids'])

                next_node['names'].extend(target['names'])

                # Set defaults for next_node.expect_referenced_by_name/id.

                if not hasattr(next_node, 'expect_referenced_by_name'):

                    next_node.expect_referenced_by_name = {}

                if not hasattr(next_node, 'expect_referenced_by_id'):

                    next_node.expect_referenced_by_id = {}

                for id in target['ids']:

                    # Update IDs to node mapping.

                    self.document.ids[id] = next_node

                    # If next_node is referenced by id ``id``, this

                    # target shall be marked as referenced.

                    next_node.expect_referenced_by_id[id] = target

                for name in target['names']:

                    next_node.expect_referenced_by_name[name] = target

                # If there are any expect_referenced_by_... attributes

                # in target set, copy them to next_node.

                next_node.expect_referenced_by_name.update(

                    getattr(target, 'expect_referenced_by_name', {}))

                next_node.expect_referenced_by_id.update(

                    getattr(target, 'expect_referenced_by_id', {}))

                # Set refid to point to the first former ID of target

                # which is now an ID of next_node.

                target['refid'] = target['ids'][0]

                # Clear ids and names; they have been moved to

                # next_node.

                target['ids'] = []

                target['names'] = []

                self.document.note_refid(target)

class AnonymousHyperlinks(Transform):

    """

    Link anonymous references to targets.  Given::

        <paragraph>

            <reference anonymous="1">

                internal

            <reference anonymous="1">

                external

        <target anonymous="1" ids="id1">

        <target anonymous="1" ids="id2" refuri="http://external">

    Corresponding references are linked via "refid" or resolved via "refuri"::

        <paragraph>

            <reference anonymous="1" refid="id1">

                text

            <reference anonymous="1" refuri="http://external">

                external

        <target anonymous="1" ids="id1">

        <target anonymous="1" ids="id2" refuri="http://external">

    """

    default_priority = 440

    def apply(self):

        anonymous_refs = []

        anonymous_targets = []

        for node in self.document.traverse(nodes.reference):

            if node.get('anonymous'):

                anonymous_refs.append(node)

        for node in self.document.traverse(nodes.target):

            if node.get('anonymous'):

                anonymous_targets.append(node)

        if len(anonymous_refs) \

              != len(anonymous_targets):

            msg = self.document.reporter.error(

                  'Anonymous hyperlink mismatch: %s references but %s '

                  'targets.\nSee "backrefs" attribute for IDs.'

                  % (len(anonymous_refs), len(anonymous_targets)))

            msgid = self.document.set_id(msg)

            for ref in anonymous_refs:

                prb = nodes.problematic(

                      ref.rawsource, ref.rawsource, refid=msgid)

                prbid = self.document.set_id(prb)

                msg.add_backref(prbid)

                ref.replace_self(prb)

            return

        for ref, target in zip(anonymous_refs, anonymous_targets):

            target.referenced = 1

            while 1:

                if target.hasattr('refuri'):

                    ref['refuri'] = target['refuri']

                    ref.resolved = 1

                    break

                else:

                    if not target['ids']:

                        # Propagated target.

                        target = self.document.ids[target['refid']]

                        continue

                    ref['refid'] = target['ids'][0]

                    self.document.note_refid(ref)

                    break

class IndirectHyperlinks(Transform):

    """

    a) Indirect external references::

           <paragraph>

               <reference refname="indirect external">

                   indirect external

           <target id="id1" name="direct external"

               refuri="http://indirect">

           <target id="id2" name="indirect external"

               refname="direct external">

       The "refuri" attribute is migrated back to all indirect targets

       from the final direct target (i.e. a target not referring to

       another indirect target)::

           <paragraph>

               <reference refname="indirect external">

                   indirect external

           <target id="id1" name="direct external"

               refuri="http://indirect">

           <target id="id2" name="indirect external"

               refuri="http://indirect">

       Once the attribute is migrated, the preexisting "refname" attribute

       is dropped.

    b) Indirect internal references::

           <target id="id1" name="final target">

           <paragraph>

               <reference refname="indirect internal">

                   indirect internal

           <target id="id2" name="indirect internal 2"

               refname="final target">

           <target id="id3" name="indirect internal"

               refname="indirect internal 2">

       Targets which indirectly refer to an internal target become one-hop

       indirect (their "refid" attributes are directly set to the internal

       target's "id"). References which indirectly refer to an internal

       target become direct internal references::

           <target id="id1" name="final target">

           <paragraph>

               <reference refid="id1">

                   indirect internal

           <target id="id2" name="indirect internal 2" refid="id1">

           <target id="id3" name="indirect internal" refid="id1">

    """

    default_priority = 460

    def apply(self):

        for target in self.document.indirect_targets:

            if not target.resolved:

                self.resolve_indirect_target(target)

            self.resolve_indirect_references(target)

    def resolve_indirect_target(self, target):

        refname = target.get('refname')

        if refname is None:

            reftarget_id = target['refid']

        else:

            reftarget_id = self.document.nameids.get(refname)

            if not reftarget_id:

                # Check the unknown_reference_resolvers

                for resolver_function in \

                        self.document.transformer.unknown_reference_resolvers:

                    if resolver_function(target):

                        break

                else:

                    self.nonexistent_indirect_target(target)

                return

        reftarget = self.document.ids[reftarget_id]

        reftarget.note_referenced_by(id=reftarget_id)

        if isinstance(reftarget, nodes.target) \

               and not reftarget.resolved and reftarget.hasattr('refname'):

            if hasattr(target, 'multiply_indirect'):

                #and target.multiply_indirect):

                #del target.multiply_indirect

                self.circular_indirect_reference(target)

                return

            target.multiply_indirect = 1

            self.resolve_indirect_target(reftarget) # multiply indirect

            del target.multiply_indirect

        if reftarget.hasattr('refuri'):

            target['refuri'] = reftarget['refuri']

            if target.has_key('refid'):

                del target['refid']

        elif reftarget.hasattr('refid'):

            target['refid'] = reftarget['refid']

            self.document.note_refid(target)

        else:

            if reftarget['ids']:

                target['refid'] = reftarget_id

                self.document.note_refid(target)

            else:

                self.nonexistent_indirect_target(target)

                return

        if refname is not None:

            del target['refname']

        target.resolved = 1

    def nonexistent_indirect_target(self, target):

        if self.document.nameids.has_key(target['refname']):

            self.indirect_target_error(target, 'which is a duplicate, and '

                                       'cannot be used as a unique reference')

        else:

            self.indirect_target_error(target, 'which does not exist')

    def circular_indirect_reference(self, target):

        self.indirect_target_error(target, 'forming a circular reference')

    def indirect_target_error(self, target, explanation):

        naming = ''

        reflist = []

        if target['names']:

            naming = '"%s" ' % target['names'][0]

        for name in target['names']:

            reflist.extend(self.document.refnames.get(name, []))

        for id in target['ids']:

            reflist.extend(self.document.refids.get(id, []))

        naming += '(id="%s")' % target['ids'][0]

        msg = self.document.reporter.error(

              'Indirect hyperlink target %s refers to target "%s", %s.'

              % (naming, target['refname'], explanation), base_node=target)

        msgid = self.document.set_id(msg)

        for ref in utils.uniq(reflist):

            prb = nodes.problematic(

                  ref.rawsource, ref.rawsource, refid=msgid)

            prbid = self.document.set_id(prb)

            msg.add_backref(prbid)

            ref.replace_self(prb)

        target.resolved = 1

    def resolve_indirect_references(self, target):

        if target.hasattr('refid'):

            attname = 'refid'

            call_method = self.document.note_refid

        elif target.hasattr('refuri'):

            attname = 'refuri'

            call_method = None

        else:

            return

        attval = target[attname]

        for name in target['names']:

            reflist = self.document.refnames.get(name, [])

            if reflist:

                target.note_referenced_by(name=name)

            for ref in reflist:

                if ref.resolved:

                    continue

                del ref['refname']

                ref[attname] = attval

                if call_method:

                    call_method(ref)

                ref.resolved = 1

                if isinstance(ref, nodes.target):

                    self.resolve_indirect_references(ref)

        for id in target['ids']:

            reflist = self.document.refids.get(id, [])

            if reflist:

                target.note_referenced_by(id=id)

            for ref in reflist:

                if ref.resolved:

                    continue

                del ref['refid']

                ref[attname] = attval

                if call_method:

                    call_method(ref)

                ref.resolved = 1

                if isinstance(ref, nodes.target):

                    self.resolve_indirect_references(ref)

class ExternalTargets(Transform):

    """

    Given::

        <paragraph>

            <reference refname="direct external">

                direct external

        <target id="id1" name="direct external" refuri="http://direct">

    The "refname" attribute is replaced by the direct "refuri" attribute::

        <paragraph>

            <reference refuri="http://direct">

                direct external

        <target id="id1" name="direct external" refuri="http://direct">

    """

    default_priority = 640

    def apply(self):

        for target in self.document.traverse(nodes.target):

            if target.hasattr('refuri'):

                refuri = target['refuri']

                for name in target['names']:

                    reflist = self.document.refnames.get(name, [])

                    if reflist:

                        target.note_referenced_by(name=name)

                    for ref in reflist:

                        if ref.resolved:

                            continue

                        del ref['refname']

                        ref['refuri'] = refuri

                        ref.resolved = 1

class InternalTargets(Transform):

    default_priority = 660

    def apply(self):

        for target in self.document.traverse(nodes.target):

            if not target.hasattr('refuri') and not target.hasattr('refid'):

                self.resolve_reference_ids(target)

    def resolve_reference_ids(self, target):

        """

        Given::

            <paragraph>

                <reference refname="direct internal">

                    direct internal

            <target id="id1" name="direct internal">

        The "refname" attribute is replaced by "refid" linking to the target's

        "id"::

            <paragraph>

                <reference refid="id1">

                    direct internal

            <target id="id1" name="direct internal">

        """

        for name in target['names']:

            refid = self.document.nameids[name]

            reflist = self.document.refnames.get(name, [])

            if reflist:

                target.note_referenced_by(name=name)

            for ref in reflist:

                if ref.resolved:

                    continue

                del ref['refname']

                ref['refid'] = refid

                ref.resolved = 1

class Footnotes(Transform):

    """

    Assign numbers to autonumbered footnotes, and resolve links to footnotes,

    citations, and their references.

    Given the following ``document`` as input::

        <document>

            <paragraph>

                A labeled autonumbered footnote referece:

                <footnote_reference auto="1" id="id1" refname="footnote">

            <paragraph>

                An unlabeled autonumbered footnote referece:

                <footnote_reference auto="1" id="id2">

            <footnote auto="1" id="id3">

                <paragraph>

                    Unlabeled autonumbered footnote.

            <footnote auto="1" id="footnote" name="footnote">

                <paragraph>

                    Labeled autonumbered footnote.

    Auto-numbered footnotes have attribute ``auto="1"`` and no label.

    Auto-numbered footnote_references have no reference text (they're

    empty elements). When resolving the numbering, a ``label`` element

    is added to the beginning of the ``footnote``, and reference text

    to the ``footnote_reference``.

    The transformed result will be::

        <document>

            <paragraph>

                A labeled autonumbered footnote referece:

                <footnote_reference auto="1" id="id1" refid="footnote">

                    2

            <paragraph>

                An unlabeled autonumbered footnote referece:

                <footnote_reference auto="1" id="id2" refid="id3">

                    1

            <footnote auto="1" id="id3" backrefs="id2">

                <label>

                    1

                <paragraph>

                    Unlabeled autonumbered footnote.

            <footnote auto="1" id="footnote" name="footnote" backrefs="id1">

                <label>

                    2

                <paragraph>

                    Labeled autonumbered footnote.

    Note that the footnotes are not in the same order as the references.

    The labels and reference text are added to the auto-numbered ``footnote``

    and ``footnote_reference`` elements.  Footnote elements are backlinked to

    their references via "refids" attributes.  References are assigned "id"

    and "refid" attributes.

    After adding labels and reference text, the "auto" attributes can be

    ignored.

    """

    default_priority = 620

    autofootnote_labels = None

    """Keep track of unlabeled autonumbered footnotes."""

    symbols = [

          # Entries 1-4 and 6 below are from section 12.51 of

          # The Chicago Manual of Style, 14th edition.

          '*',                          # asterisk/star

          u'\u2020',                    # dagger †

          u'\u2021',                    # double dagger ‡

          u'\u00A7',                    # section mark §

          u'\u00B6',                    # paragraph mark (pilcrow) ¶

                                        # (parallels ['||'] in CMoS)

          '#',                          # number sign

          # The entries below were chosen arbitrarily.

          u'\u2660',                    # spade suit ♠

          u'\u2665',                    # heart suit ♥

          u'\u2666',                    # diamond suit ♦

          u'\u2663',                    # club suit ♣

          ]

    def apply(self):

        self.autofootnote_labels = []

        startnum = self.document.autofootnote_start

        self.document.autofootnote_start = self.number_footnotes(startnum)

        self.number_footnote_references(startnum)

        self.symbolize_footnotes()

        self.resolve_footnotes_and_citations()

    def number_footnotes(self, startnum):

        """

        Assign numbers to autonumbered footnotes.

        For labeled autonumbered footnotes, copy the number over to

        corresponding footnote references.

        """

        for footnote in self.document.autofootnotes:

            while 1:

                label = str(startnum)

                startnum += 1

                if not self.document.nameids.has_key(label):

                    break

            footnote.insert(0, nodes.label('', label))

            for name in footnote['names']:

                for ref in self.document.footnote_refs.get(name, []):

                    ref += nodes.Text(label)

                    ref.delattr('refname')

                    assert len(footnote['ids']) == len(ref['ids']) == 1

                    ref['refid'] = footnote['ids'][0]

                    footnote.add_backref(ref['ids'][0])

                    self.document.note_refid(ref)

                    ref.resolved = 1

            if not footnote['names'] and not footnote['dupnames']:

                footnote['names'].append(label)

                self.document.note_explicit_target(footnote, footnote)

                self.autofootnote_labels.append(label)

        return startnum

    def number_footnote_references(self, startnum):

        """Assign numbers to autonumbered footnote references."""

        i = 0

        for ref in self.document.autofootnote_refs: