Functions - CiteURL

# Functions

Most of CiteURL's core features can be accessed through the Citator class. But if you plan to perform multiple operations with the same set of citations, you can use these module-wide functions without generating a whole new list of citations every time.

## insert_links()

###

Given a text and a list of citations found in it, return a text with an HTML hyperlink inserted for each citation.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`citations` | `list` | A list of citation objects found in the text | required
`text` | `str` | The text the citations were found in | required
`attrs` | `dict` | HTML tag attributes (like css class, rel, etc) to give each inserted hyperlink. | `{'class': 'citation'}`
`link_detailed_ids` | `bool` | Whether to insert hyperlinks for citations like "Id. at 30." | `True`
`link_plain_ids` | `bool` | Whether to insert hyperlinks for simple repeat citations like "id." | `False`
`url_optional` | `bool` | Whether to insert link elements for citations that do not have an associated URL | `False`

Returns:

Type | Description
--- | ---
`str` | The input text, with HTML links inserted for each citation

Source code in `citeurl/__init__.py`

    def insert_links(
        citations: list,
        text: str,
        attrs: dict={'class': 'citation'},
        link_detailed_ids: bool=True,
        link_plain_ids: bool=False,
        url_optional: bool=False
    ) -> str:
        """
        Given a text and a list of citations found in it, return a text
        with an HTML hyperlink inserted for each citation.

        Arguments:
            citations: A list of citation objects found in the text
            text: The text the citations were found in
            attrs: HTML tag attributes (like css class, rel, etc)
                to give each inserted hyperlink.
            link_detailed_ids: Whether to insert hyperlinks for citations
                like "Id. at 30."
            link_plain_ids: Whether to insert hyperlinks for simple repeat
                citations like "id."
            url_optional: Whether to insert link elements for citations that
                do not have an associated URL
        Returns:
            The input text, with HTML links inserted for each citation
        """
        offset = 0
        for citation in citations:
            if not citation.URL and not url_optional:
                continue
            if citation.schema.is_id:
                if citation.schema._compiled_re().groupindex:
                    if not link_detailed_ids:
                        continue
                elif not link_plain_ids:
                    continue
            link = citation.get_link(attrs=attrs)
            cite_start = citation.span[0] + offset
            cite_end = citation.span[1] + offset
            text = ''.join([text[:cite_start], link, text[cite_end:]])
            offset += len(link) - len(citation.text)
        return text

## list_authorities()

###

Combine a list of citations into a list of authorities, each of which represents all the citations to a particular source.

As a side-effect, this also gives each citation an `authority` attribute referring to the proper authority.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`citations` | `list` | The list of citations to combine | required
`unimportant_tokens` | `` | A list of tokens whose values may differ among citations to the same authority. | required

Returns:

Type | Description
--- | ---
`list` | A list of authority objects, sorted by the number of citations that refer to each, from most to least.

Source code in `citeurl/__init__.py`

    def list_authorities(
        citations: list,
        irrelevant_tokens: list=NON_AUTHORITY_TOKENS
    ) -> list:
        """
        Combine a list of citations into a list of authorities, each
        of which represents all the citations to a particular source.

        As a side-effect, this also gives each citation an `authority`
        attribute referring to the proper authority.

        Arguments:
            citations: The list of citations to combine
            unimportant_tokens: A list of tokens whose values may
                differ among citations to the same authority.
        Returns:
            A list of authority objects, sorted by the number of citations
            that refer to each, from most to least.
        """
        authorities = []
        for citation in citations:
            for authority in authorities:
                if authority.matches(citation):
                    authority.include(citation)
                    break
            else:
                authorities.append(Authority(citation, irrelevant_tokens))
        def authority_sort_key(authority):
            return 0 - len(authority.citations)
        return sorted(authorities, key=authority_sort_key)