Populates result members.

        Performs the merge algorithm using the specified config and fills in
        the members that provide stats about the merging procedure.

        Attributes:
            merged_root: The result of the merge.

            aligned_root, aligned_head, aligned_update: Copies of root, head
                and update in which all matched list entities have the same
                list index for easier diff viewing.

            head_stats, update_stats: Stats for each list field present in the
                head or update objects. Instance of
                :class:`json_merger.stats.ListMatchStats`

            conflicts: List of :class:`json_merger.conflict.Conflict` instances
                that occured during the merge.

        Raises:
            :class:`json_merger.errors.MergeError` : If conflicts occur during
                the call.

        Example:
            >>> from json_merger import Merger
            >>> # We compare people by their name
            >>> from json_merger.comparator import PrimaryKeyComparator
            >>> from json_merger.config import DictMergerOps, UnifierOps
            >>> from json_merger.errors import MergeError
            >>> # Use this only for doctest :)
            >>> from pprint import pprint as pp
            >>>
            >>> root = {'people': [{'name': 'Jimmy', 'age': 30}]}
            >>> head = {'people': [{'name': 'Jimmy', 'age': 31},
            ...                    {'name': 'George'}]}
            >>> update = {'people': [{'name': 'John'},
            ...                      {'name': 'Jimmy', 'age': 32}]}
            >>>
            >>> class NameComparator(PrimaryKeyComparator):
            ...     # Two objects are the same entitity if they have the
            ...     # same name.
            ...     primary_key_fields = ['name']
            >>> m = Merger(root, head, update,
            ...            DictMergerOps.FALLBACK_KEEP_HEAD,
            ...            UnifierOps.KEEP_UPDATE_AND_HEAD_ENTITIES_HEAD_FIRST,
            ...            comparators = {'people': NameComparator})
            >>> # We do a merge
            >>> try:
            ...     m.merge()
            ... except MergeError as e:
            ...     # Conflicts are the same thing as the exception content.
            ...     assert e.content == m.conflicts
            >>> # This is how the lists are aligned:
            >>> pp(m.aligned_root['people'], width=60)
            ['#$PLACEHOLDER$#',
             {'age': 30, 'name': 'Jimmy'},
             '#$PLACEHOLDER$#']
            >>> pp(m.aligned_head['people'], width=60)
            ['#$PLACEHOLDER$#',
             {'age': 31, 'name': 'Jimmy'},
             {'name': 'George'}]
            >>> pp(m.aligned_update['people'], width=60)
            [{'name': 'John'},
             {'age': 32, 'name': 'Jimmy'},
             '#$PLACEHOLDER$#']
            >>> # This is the end result of the merge:
            >>> pp(m.merged_root, width=60)
            {'people': [{'name': 'John'},
                        {'age': 31, 'name': 'Jimmy'},
                        {'name': 'George'}]}
            >>> # With some conflicts:
            >>> pp(m.conflicts, width=60)
            [('SET_FIELD', ('people', 1, 'age'), 32)]
            >>> # And some stats:
            >>> pp(m.head_stats[('people',)].in_result)
            [{'age': 31, 'name': 'Jimmy'}, {'name': 'George'}]
            >>> pp(m.update_stats[('people',)].not_in_result)
            []

        Note:
            Even if conflicts occur, merged_root, aligned_root, aligned_head
            and aligned_update are always populated by following the
            startegies set for the merger instance.

def merge(self):
        """Populates result members.

        Performs the merge algorithm using the specified config and fills in
        the members that provide stats about the merging procedure.

        Attributes:
            merged_root: The result of the merge.

            aligned_root, aligned_head, aligned_update: Copies of root, head
                and update in which all matched list entities have the same
                list index for easier diff viewing.

            head_stats, update_stats: Stats for each list field present in the
                head or update objects. Instance of
                :class:`json_merger.stats.ListMatchStats`

            conflicts: List of :class:`json_merger.conflict.Conflict` instances
                that occured during the merge.

        Raises:
            :class:`json_merger.errors.MergeError` : If conflicts occur during
                the call.

        Example:
            >>> from json_merger import Merger
            >>> # We compare people by their name
            >>> from json_merger.comparator import PrimaryKeyComparator
            >>> from json_merger.config import DictMergerOps, UnifierOps
            >>> from json_merger.errors import MergeError
            >>> # Use this only for doctest :)
            >>> from pprint import pprint as pp
            >>>
            >>> root = {'people': [{'name': 'Jimmy', 'age': 30}]}
            >>> head = {'people': [{'name': 'Jimmy', 'age': 31},
            ...                    {'name': 'George'}]}
            >>> update = {'people': [{'name': 'John'},
            ...                      {'name': 'Jimmy', 'age': 32}]}
            >>>
            >>> class NameComparator(PrimaryKeyComparator):
            ...     # Two objects are the same entitity if they have the
            ...     # same name.
            ...     primary_key_fields = ['name']
            >>> m = Merger(root, head, update,
            ...            DictMergerOps.FALLBACK_KEEP_HEAD,
            ...            UnifierOps.KEEP_UPDATE_AND_HEAD_ENTITIES_HEAD_FIRST,
            ...            comparators = {'people': NameComparator})
            >>> # We do a merge
            >>> try:
            ...     m.merge()
            ... except MergeError as e:
            ...     # Conflicts are the same thing as the exception content.
            ...     assert e.content == m.conflicts
            >>> # This is how the lists are aligned:
            >>> pp(m.aligned_root['people'], width=60)
            ['#$PLACEHOLDER$#',
             {'age': 30, 'name': 'Jimmy'},
             '#$PLACEHOLDER$#']
            >>> pp(m.aligned_head['people'], width=60)
            ['#$PLACEHOLDER$#',
             {'age': 31, 'name': 'Jimmy'},
             {'name': 'George'}]
            >>> pp(m.aligned_update['people'], width=60)
            [{'name': 'John'},
             {'age': 32, 'name': 'Jimmy'},
             '#$PLACEHOLDER$#']
            >>> # This is the end result of the merge:
            >>> pp(m.merged_root, width=60)
            {'people': [{'name': 'John'},
                        {'age': 31, 'name': 'Jimmy'},
                        {'name': 'George'}]}
            >>> # With some conflicts:
            >>> pp(m.conflicts, width=60)
            [('SET_FIELD', ('people', 1, 'age'), 32)]
            >>> # And some stats:
            >>> pp(m.head_stats[('people',)].in_result)
            [{'age': 31, 'name': 'Jimmy'}, {'name': 'George'}]
            >>> pp(m.update_stats[('people',)].not_in_result)
            []

        Note:
            Even if conflicts occur, merged_root, aligned_root, aligned_head
            and aligned_update are always populated by following the
            startegies set for the merger instance.
        """
        self.merged_root = self._recursive_merge(self.root, self.head,
                                                 self.update)
        if self.conflicts:
            raise MergeError('Conflicts Occurred in Merge Process',
                             self.conflicts)