API

class CitationRenderer:
    """A builder of reference renderers:

    1. the function, class and symbol decorator
    2. the function to invoque at module loading
    """

    def format(self, refs: list) -> str:
        """Formats a citation list.

        Args:
            *refs: a list of bibliographical reference symbols

        Returns: a string rendering the list of the input reference symbols
        """

    def _doc_core(self, doc: str, *refs: Any | list) -> str:
        """Manages the documentation modification in various use cases:

        1. If the documentation is None, inits it to an empty string.
        2. Then, handles the cases the refs are a single instance, a list or a varargs of bibliographical symbols.

        Args:
            *refs (Any | list): a series of bibliographical reference symbols
        """
        if doc is None:
            doc = ''

        if len(refs) == 1:
            ref0 = refs[0]
            if isinstance(ref0, list):
                doc += self.format(ref0)
            else:
                doc += self.format([ref0])
        else:
            doc += self.format([*refs])

        return doc

    def cite_module(self, *refs: Any | list) -> None:
        """The bibliographical reference function to invoque at module loading to add a reference rendering to its
        documentation.

        Args:
            *refs (Any | list): a series of bibliographical reference symbols
        """
        frm = inspect.stack()[1]
        mod = inspect.getmodule(frm[0])
        mod.__doc__ = self._doc_core(mod.__doc__, *refs)

    def decorator(self, *refs: Any) -> "Returns a function to handle a function, a class or a method.":
        """The bibliographical reference decorator to use for functions, classes and methods.

        Args:
            *refs (Any | list[Any]): a series of bibliographical reference symbols

        Returns: a function to handle a function, a class or a method documentation which to render the bibliographical
        references into
        """

        def internal(obj):
            """
            Renders the bibliographical references given to the decorator into the parameter documentation.

            Args:
                obj: a function, a class or a method which documentation has to be added in

            Returns: the very input function, class or method
            """
            obj.__doc__ = self._doc_core(obj.__doc__, *refs)
            return obj

        return internal

@dataclass(frozen=True)
class Format:
    """A format representation."""
    title: str | None
    command: str | None
    io_extension: list[str]

class Formats(Format, Enum):
    """Supported bibliography formats."""
    BIBTEX = ('Bibtex', 'bibtex', ['bib', 'bibtex'])
    RIS2001 = ('RIS (2001)', 'ris2001', ['ris'])
    RIS2011 = ('RIS (2011)', 'ris2011', ['ris'])
    REFER = ('refer', 'refer', ['refer'])
    ENDNOTE = ('Endnote', 'endnote', ['enw'])
    PUBMED = ('PubMed', 'pubmed', ['nbib', 'txt'])
    YML = (None, None, ['yml', 'yaml'])
    JSON = (None, None, ['json'])
    PYTHON = (None, None, ['py'])

    @staticmethod
    def as_command(format_id: str):
        """Gets a supported format enum instance from a supported process argument string."""
        for f in Formats:
            if format_id == f.command:
                return f
        raise ValueError(f'unexpected format {format_id}')

    def as_io_extension(self, format_id: str):
        """Gets a supported format enum instance from a supported process argument string."""
        for f in Formats:
            if f.command is None and format_id in f.io_extension:
                return f

        if format_id in self.io_extension:
            return self

        raise ValueError(f'unexpected format {format_id}')

class InputFormat:
    """InputFormat interface to deserialize a bibliography."""

    def __init__(self, source: Format, standard: Format):
        self._source = source
        self._standard = standard

    def from_yml(self, i: TextIO):
        """Reads from yml representation."""

    def from_json(self, i: TextIO):
        """Reads from json representation."""

    def from_standard(self, i: TextIO):
        """Reads from standard format."""

    def source(self) -> Format:
        """The source format."""
        return self._source

    def standard(self) -> Format:
        """The standard format."""
        return self._standard

    def read(self, i: TextIO):
        """Deserialization method."""
        if self.source() is Formats.YML:
            return self.from_yml(i)
        if self.source() is Formats.JSON:
            return self.from_json(i)
        if self.source() is self.standard():
            return self.from_standard(i)

        raise ValueError(f'unsupported configuration format {self.source()}')

class OutputFormat:
    """Output format to serialize a bibliography."""

    def __init__(self, params: OutputParams, standard: Format):
        self._target = params.target
        self._symbolizer = params.symbolizer
        self._standard = standard

    def to_yml(self, o: TextIO):
        """Writes to yml representation."""

    def to_json(self, o: TextIO):
        """Writes to json representation."""

    def to_standard(self, o: TextIO):
        """Writes to standard format."""

    def to_py(self, o: TextIO):
        """Writes to python representation."""

    def target(self):
        """The file extension."""
        return self._target

    def standard(self) -> Format:
        """The standard format."""
        return self._standard

    def write(self, o: TextIO):
        """Serialization method."""
        if self.target() is Formats.YML:
            return self.to_yml(o)
        if self.target() is Formats.JSON:
            return self.to_json(o)
        if self.target() is Formats.PYTHON:
            return self.to_py(o)
        if self.target() is self.standard():
            return self.to_standard(o)

        raise ValueError(f'unsupported configuration format {self.target()}')

@dataclass
class OutputParams:
    """Output stream params."""
    target: Formats
    symbolizer: Symbolizer

class Symbolizer:
    """Builds a Python symbol for a given entry in a given format."""

    def to_symbol(self, fmt: Format, bib_entry) -> str:
        """Produces a python symbol from a bibliographical reference entry."""

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Article(BibtexReference):
    """any article published in a periodical like a journal article or magazine article

    An article from a journal or magazine.
    Required fields: author, title, journal, year.
    Optional fields: volume, number, pages, month, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values"""
        return {
            'author': self.author,
            'title': self.title,
            'journal': self.journal,
            'year': self.year
        }

@dataclass(frozen=True, repr=False)
class BibtexReference:
    """A bibliography reference."""

    CITE_KEY_FIELD = 'cite_key'
    NON_STANDARD_FIELD = 'non_standard'
    SCOPE_FIELD = 'scope'
    CROSSREF_FIELD = 'crossref'

    cite_key: str

    address: str | None
    """address of the publisher or the institution

    not used in article, misc and unpublished
    optional everywhere else
    https://www.bibtex.com/f/address-field/"""

    annote: str | None
    """an annotation

    https://www.bibtex.com/f/annote-field/"""

    author: str | None
    """ist of authors of the work

    optional for booklet, manual and misc
    required everywhere else
    https://www.bibtex.com/f/author-field/"""

    booktitle: str | None
    """title of the book

    required for incollection and inproceedings
    not used everywhere else
    https://www.bibtex.com/f/booktitle-field/"""

    chapter: str | None
    """number of a chapter in a book

    required for inbook and incollection
    not used everywhere else
    https://www.bibtex.com/f/chapter-field/"""

    crossref: str | None
    """The database key of the entry being cross referenced."""

    edition: str | None
    """edition number of a book

    optional for book, inbook, incollection and manual
    not used everywhere else
    https://www.bibtex.com/f/edition-field/"""

    editor: str | None
    """list of editors of a book

    required for book and inbook
    optional for incollection and inproceedings
    not used everywhere else
    https://www.bibtex.com/f/editor-field/"""

    howpublished: str | None
    """a publication notice for unusual publications

    optional for booklet and misc
    not used everywhere else
    https://www.bibtex.com/f/howpublished-field/"""

    institution: str | None
    """name of the institution that published and/or sponsored the report

    required for techreport
    not used everywhere else
    https://www.bibtex.com/f/institution-field/
    """

    journal: str | None
    """name of the journal or magazine the article was published in

    required for article
    not used everywhere else
    https://www.bibtex.com/f/journal-field/
    """

    month: str | None
    """the month during the work was published

    optional
    https://www.bibtex.com/f/month-field/"""

    note: str | None
    """
    notes about the reference

    required for unpublished
    optional everywhere else
    https://www.bibtex.com/f/note-field/"""

    number: str | int | None
    """number of the report or the issue number for a journal article

    optional for article, book, inbook, incollection, inproceedings and techreport
    not used everywhere else
    https://www.bibtex.com/f/number-field/"""

    organization: str | None
    """name of the institution that organized or sponsored the conference or that published the manual

    optional for inproceedings and manual
    not used everywhere else
    https://www.bibtex.com/f/organization-field/"""

    pages: str | int | None
    """page numbers or a page range

    required for inbook
    optional for article, incollection and inproceedings
    not used everywhere else
    https://www.bibtex.com/f/pages-field/"""

    publisher: str | None
    """name of the publisher

    required for book, inbook and incollection
    optional for inproceedings
    not used everywhere else
    https://www.bibtex.com/f/publisher-field/"""

    school: str | None
    """name of the university or degree awarding institution

    required for masterthesis and phdthesis
    not used everywhere else
    https://www.bibtex.com/f/school-field/"""

    series: str | None
    """name of the series or set of books

    optional for book, inbook, incollection and inproceedings
    not used everywhere else
    https://www.bibtex.com/f/series-field/"""

    title: str | None
    """title of the work

    optional for misc
    required everywhere else
    https://www.bibtex.com/f/title-field/"""

    type: str | None
    """type of the technical report or thesis

    optional for inbook, incollection, masterthesis and techreport
    not used everywhere else
    https://www.bibtex.com/f/type-field/"""

    volume: str | int | None
    """volume number

    optional for article, book, inbook, incollection and inproceedings
    not used everywhere else
    https://www.bibtex.com/f/volume-field/"""

    year: str | int | None
    """year the book was published

    required for article, book, inbook, incollection, inproceedings, masterthesis, phdthesis, techreport
    optional for booklet, misc and unpublished
    not used for manual
    https://www.bibtex.com/f/year-field/"""

    non_standard: NonStandard | None
    """Non standard fields."""

    scope: dict[str, BibtexReference] | None
    """Environnement de résolution des références croisées."""

    def _hierarchy(self) -> list[BibtexReference]:
        """Calcul de la hiérarchie par références croisées."""
        current: BibtexReference | None = self

        hierarchy: list[BibtexReference] = [current]
        while current is not None:
            if current.crossref is not None and current.scope is not None and current.crossref in current.scope:
                parent: BibtexReference = current.scope[current.crossref]
                hierarchy.append(parent)
                current = parent
            else:
                current = None
        return hierarchy

    def cross_resolved(self) -> BibtexReference:
        """Calcul de la référence héritant des champs des références croisées parentes."""
        hierarchy = self._hierarchy()

        if len(hierarchy) == 1:
            return self

        resolved_standard_dict: dict[str, Any] = {}
        for f in dataclasses.fields(type(self)):

            if f.name in [BibtexReference.NON_STANDARD_FIELD, BibtexReference.SCOPE_FIELD]:
                continue

            for i in hierarchy:
                v = getattr(i, f.name)
                if v is not None:
                    resolved_standard_dict[f.name] = v
                    break

        resolved_non_standard_dict: dict[str, Any] = {}
        for f in dataclasses.fields(NonStandard):

            for i in hierarchy:
                if i.non_standard is not None:
                    v = getattr(i.non_standard, f.name)
                    if v is not None:
                        resolved_non_standard_dict[f.name] = v
                        break

        resolved_standard_dict[BibtexReference.NON_STANDARD_FIELD] = NonStandard.from_dict(resolved_non_standard_dict)

        # il ne faut pas ajouter dans le scope cette instance résolue par références croisées car sa clef étant la même
        # que celle de la référence explicite, les deux entreraient en conflit dans le scope
        # seule la référence explicite doit être ajoutée au scope
        # si on souhaite disposer des champs hérités par références croisées, il faut utiliser l'instance résolue
        return type(self).from_dict(source=resolved_standard_dict,
                                    scope=None)

    def to_py(self, scope_symbol: str | None, symbolizer: Symbolizer) -> str:
        """Serialization of the reference in processed python code."""

        base = f"{symbolizer.to_symbol(Formats.BIBTEX, self)} = {type(self).__name__}.generic("

        fields = []
        for f in dataclasses.fields(type(self)):

            if BibtexReference.SCOPE_FIELD == f.name:
                continue

            value = getattr(self, f.name)

            if f.name == BibtexReference.CROSSREF_FIELD and value is not None:
                fields.append(f"{f.name}={symbolizer.to_symbol(Formats.BIBTEX, value)}")
            elif isinstance(value, str):
                if "'" in value:
                    fields.append(f'{f.name}="{value}"')
                else:
                    fields.append(f"{f.name}='{value}'")
            elif isinstance(value, NonStandard):
                fields.append(f'{f.name}={value.to_py()}')
            elif value is not None:
                fields.append(f'{f.name}={value}')

        if scope_symbol is not None:
            fields.append(f'{BibtexReference.SCOPE_FIELD}={scope_symbol}')

        # argument indentation management
        sep = ',\n'
        for _ in range(len(base)):
            sep += ' '

        return f"\n{base}{sep.join(fields)})"

    def to_bib(self) -> dict:
        """converts to a bibtex parser dict"""
        result = {}
        for f in dataclasses.fields(type(self)):

            if BibtexReference.SCOPE_FIELD == f.name:
                continue

            if BibtexReference.CITE_KEY_FIELD == f.name:
                field_name = ID_FIELD_IN_MODEL_DICT
            else:
                field_name = f.name

            value = getattr(self, f.name)

            if isinstance(value, str):
                result[field_name] = value
            elif isinstance(value, NonStandard):
                ns = {}
                for f in dataclasses.fields(NonStandard):
                    v = getattr(value, f.name)
                    if v is not None:
                        ns[f.name] = str(v)

                result = result | ns

            elif value is not None:
                result[field_name] = str(value)

        result[ENTRYTYPE_FIELD_IN_MODEL_DICT] = type(self).bibtex_entry_type()
        return result

    def _mandatory_values(self) -> dict[str, Any]:
        """Checks if standard mandatory fields are not None."""
        raise NotImplementedError

    @classmethod
    def bibtex_entry_type(cls):
        """Gets the bibtex entrytype name"""
        for bibtex, internal_type in TYPES.items():
            if internal_type == cls:
                return bibtex
        raise ValueError

    @classmethod
    def generic(cls,
                cite_key: str,
                address: str | None = None,
                annote: str | None = None,
                booktitle: str | None = None,
                author: str | None = None,
                chapter: str | None = None,
                crossref: str | BibtexReference | None = None,
                edition: str | None = None,
                editor: str | None = None,
                howpublished: str | None = None,
                institution: str | None = None,
                journal: str | None = None,
                month: str | None = None,
                note: str | None = None,
                number: str | None = None,
                organization: str | None = None,
                pages: str | int | None = None,
                publisher: str | None = None,
                school: str | None = None,
                series: str | None = None,
                title: str | None = None,
                type: str | None = None,
                volume: str | int | None = None,
                year: str | int | None = None,
                non_standard: NonStandard | None = None,
                scope: dict[str, BibtexReference] | None = None) -> BibtexReference:
        """builds a generic reference, allowing to init each field"""
        instance = cls(cite_key=cite_key,
                       address=address,
                       annote=annote,
                       booktitle=booktitle,
                       author=author,
                       chapter=chapter,
                       crossref=crossref.cite_key if isinstance(crossref, BibtexReference) else crossref,
                       edition=edition,
                       editor=editor,
                       howpublished=howpublished,
                       institution=institution,
                       journal=journal,
                       month=month,
                       note=note,
                       number=number,
                       organization=organization,
                       pages=pages,
                       publisher=publisher,
                       school=school,
                       series=series,
                       title=title,
                       type=type,
                       volume=volume,
                       year=year,
                       non_standard=non_standard,
                       scope=scope)

        if any(v is None for k, v in instance._mandatory_values().items()):
            if all(v is not None for k, v in instance.cross_resolved()._mandatory_values().items()):
                LOG.info('all mandatory values resolved in scope cross references')
            else:
                raise ValueError(f'missing mandatory field for {cls.__name__} {instance.cite_key}')

        # scope management for crossref
        if scope is not None:
            # les chaines vides doivent être ignorées car elles représentent l'unique clef des citations anonymes
            if cite_key != '' and cite_key in scope:
                raise ValueError(f'{cite_key} is already present in bibliograpy scope for {scope[cite_key]}')

            scope[cite_key] = instance

        return instance

    @classmethod
    def from_dict(cls, source: dict[str, Any], scope: dict[str, BibtexReference] | None) -> BibtexReference:
        """Builds a reference from a dict."""
        return cls.generic(
            cite_key=source[BibtexReference.CITE_KEY_FIELD],
            address=source['address'] if 'address' in source else None,
            annote=source['annote'] if 'annote' in source else None,
            author=source['author'] if 'author' in source else None,
            booktitle=source['booktitle'] if 'booktitle' in source else None,
            chapter=source['chapter'] if 'chapter' in source else None,
            crossref=source['crossref'] if 'crossref' in source else None,
            edition=source['edition'] if 'edition' in source else None,
            editor=source['editor'] if 'editor' in source else None,
            howpublished=source['howpublished'] if 'howpublished' in source else None,
            institution=source['institution'] if 'institution' in source else None,
            journal=source['journal'] if 'journal' in source else None,
            month=source['month'] if 'month' in source else None,
            note=source['note'] if 'note' in source else None,
            number=source['number'] if 'number' in source else None,
            organization=source['organization'] if 'organization' in source else None,
            pages=source['pages'] if 'pages' in source else None,
            publisher=source['publisher'] if 'publisher' in source else None,
            school=source['school'] if 'school' in source else None,
            series=source['series'] if 'series' in source else None,
            title=source['title'] if 'title' in source else None,
            type=source['type'] if 'type' in source else None,
            volume=source['volume'] if 'volume' in source else None,
            year=source['year'] if 'year' in source else None,
            non_standard=NonStandard.from_dict(source),
            scope=scope)

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Book(BibtexReference):
    """a book

    A book with an explicit publisher.
    Required fields: author or editor, title, publisher, year.
    Optional fields: volume or number, series, address, edition, month, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author or editor': self.author or self.editor,
            'title': self.title,
            'publisher': self.publisher,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Booklet(BibtexReference):
    """like a book but without a designated publisher

    A work that is printed and bound, but without a named publisher or sponsoring institution.
    Required field: title.
    Optional fields: author, howpublished, address, month, year, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {'title': self.title}

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Conference(Inproceedings):
    """The same as INPROCEEDINGS, included for Scribe compatibility."""

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Inbook(BibtexReference):
    """a section or chapter in a book

    A part of a book, which may be a chapter (or section or whatever)and/or a range of pages.
    Required fields: author or editor, title, chapter and/or pages, publisher, year.
    Optional fields: volume or number, series, type, address, edition, month, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author or editor': self.author or self.editor,
            'title': self.title,
            'chapter or pages': self.chapter or self.pages,
            'publisher': self.publisher,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Incollection(BibtexReference):
    """an article in a collection

    A part of a book having its own title.
    Required fields: author, title, booktitle, publisher, year.
    Optional fields: editor, volume or number, series, type, chapter, pages, address, edition, month, note"""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author': self.author,
            'title': self.title,
            'booktitle': self.booktitle,
            'publisher': self.publisher,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Inproceedings(BibtexReference):
    """a conference paper (same as the conference entry type)

    An article in a conference proceedings.
    Required fields: author, title, booktitle, year.
    Optional fields: editor, volume or number, series, pages, address, month, organization, publisher, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author': self.author,
            'title': self.title,
            'booktitle': self.booktitle,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Manual(BibtexReference):
    """a technical manual

    manual Technical documentation.
    Required field: title.
    Optional fields: author, organization, address, edition, month, year, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {'title': self.title}

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Mastersthesis(BibtexReference):
    """a Masters thesis

    mastersthesis A Master’s thesis.
    Required fields: author, title, school, year.
    Optional fields: type, address, month, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author': self.author,
            'title': self.title,
            'school': self.school,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Misc(BibtexReference):
    """used if nothing else fits

    misc Use this type when nothing else fits.
    Required fields: none.
    Optional fields: author, title, howpublished, month, year, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {}

@dataclass(frozen=True)
class NonStandard:
    """Non-standard bibtex bibliography reference fields."""

    doi: str | None = None
    """DOI number"""

    issn: str | None = None
    """ISSN number"""

    eissn: str | None = None
    """ISSN number"""

    isbn: str | None = None
    """ISBN number"""

    url: str | None = None
    """URL of a web page"""

    @staticmethod
    def from_dict(source: dict) -> NonStandard | None:
        """Builds a non-standard reference field set from a dict."""
        if any(f in source for f in ['doi', 'issn', 'eisssn', 'isbn', 'url']):
            return NonStandard(
                doi=source['doi'] if 'doi' in source else None,
                issn=source['issn'] if 'issn' in source else None,
                eissn=source['eissn'] if 'eissn' in source else None,
                isbn=source['isbn'] if 'isbn' in source else None,
                url=source['url'] if 'url' in source else None)
        return None


    def to_py(self) -> str:
        """Serialization of the non-standard reference field set in processed python code."""

        base = f"{type(self).__name__}("

        fields = []
        for f in dataclasses.fields(type(self)):
            value = getattr(self, f.name)

            if value is not None:
                fields.append(f"{f.name}='{value}'")

        return f"{base}{', '.join(fields)})"

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Phdthesis(BibtexReference):
    """a PhD thesis

    phdthesis A PhD thesis.
    Required fields: author, title, school, year.
    Optional fields: type, address, month, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author': self.author,
            'title': self.title,
            'school': self.school,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Proceedings(BibtexReference):
    """the whole conference proceedings

    proceedings The proceedings of a conference.
    Required fields: title, year.
    Optional fields: editor, volume or number, series, address, month, organization, publisher, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'title': self.title,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class TechReport(BibtexReference):
    """a technical report, government report or white paper

    techreport A report published by a school or other institution, usually numbered within a series.
    Required fields: author, title, institution, year.
    Optional fields: type, number, address, month, note."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author': self.author,
            'title': self.title,
            'institution': self.institution,
            'year': self.year
        }

@_bibtex_package
@_bibtex_com
@dataclass(frozen=True, repr=False)
class Unpublished(BibtexReference):
    """a work that has not yet been officially published

    unpublished A document having an author and title, but not formally published.
    Required fields: author, title, note.
    Optional fields: month, year."""

    def _mandatory_values(self):
        """Returns all the mandatory values."""
        return {
            'author': self.author,
            'title': self.title,
            'note': self.note
        }

@dataclass(frozen=True)
class Tag:
    """A field tag."""
    auto: auto
    repeating: bool = False

@_cite(RIS_2001)
class Tags(Tag, Enum):
    """
    RIS fields.
    """

    TY = auto()
    """Type of reference. 
    This must contain one of the following field names as defined in the section, Reference Type field names."""

    ER = auto()
    """End of reference.
    Must be the last tag in a reference."""

    ID = auto()
    """Reference ID.
    The Reference ID can consist of any alphanumeric characters—up to 20 characters in length."""

    T1 = auto()
    """Title Primary.
    Note that the BT tag maps to this field only for Whole Book and Unpublished Work references.
    This field can contain alphanumeric characters; there is no practical length limit to this field."""
    TI = auto()  # synonym of T1
    CT = auto()  # synonym of T1

    BT = auto()

    T2 = auto()
    """Title Secondary.
    Note that the BT tag maps to this field for all reference types except for Whole Book and Unpublished Work 
    references.
    There is no practical limit to the length of this field."""

    T3 = auto()
    """Title Series.
    This field can contain alphanumeric characters; there is no practical length limit to this field."""

    A1 = (auto(), True)
    """Author Primary.
    Each author must be on a separate line, preceded by this tag. Each reference can contain unlimited author fields, 
    and can contain up to 255 characters for each field. The author name must be in the following syntax:

    Lastname, Firstname, Suffix

    For Firstname, you can use full names, initials, or both. The format for the author’s first name is as follows:

    Phillips,A.J

    Phillips,Albert John

    Phillips,Albert

    Lastname = Any string of letters, spaces, and hyphens

    Firstname = Any string of letters, spaces, and hyphens

    Initial = Any single letter followed by a period

    Full Name = Any string of letters, spaces, and hyphens

    Suffix = Jr/Sr/II/III/MD etc. (Phillips,A.J.,Sr.); use of the suffix is optional"""
    AU = (auto(), True)  # synonym of A1

    A2 = (auto(), True)
    """Author Secondary.
    Each author must be on a separate line, preceded by this tag. There is no practical limit to the number of authors
    in this field. The author name must be in the correct syntax (refer to A1 and AU fields).
    This author name can be up to 255 characters long."""
    ED = (auto(), True)  # synonym of A2

    A3 = (auto(), True)
    """Author Series. 
	Each author must be on a separate line, preceded by this tag. There is no practical limit to the number of authors 
	in this field. The author name must be in the correct syntax (refer to A1 and AU fields).
	Each author name can be up to 255 characters long."""

    Y1 = auto()
    """Date Primary.
    This date must be in the following format:

    YYYY/MM/DD/other info

    The year, month and day fields are all numeric. The other info field can be any string of letters, spaces and
    hyphens. Note that each specific date information is optional, however the slashes ("/") are not. For example, if
    you just had the <year> and <other info>, then the output would look like: "1998///Spring."
    """
    PY = auto()  # synonym of Y1

    Y2 = auto()
    """Date Secondary. (Refer to Y1 and PY fields)."""

    N1 = auto()
    """Notes.
    These are free text fields and can contain alphanumeric characters; there is no practical length limit to this
    field."""
    AB = auto()  # synonym of Y1

    N2 = auto()
    """Abstract.
    This is a free text field and can contain alphanumeric characters; there is no practical length limit to this field.
    """

    KW = (auto(), True)
    """Keywords.
    Each keyword or phrase must be on its own line, preceded by this tag. A keyword can consist of multiple words
    (phrases) and can be up to 255 characters long. There is no limit to the amount of keywords in a single reference.
    """

    RP = auto()
    """Reprint status.
    This optional field can contain one of three status notes. Each must be in uppercase,
    and the date after "ON REQUEST" must be in the US date format, in parentheses: (MM/DD/YY). 
    If this field is blank in your downloaded text file, the import function assumes the reprint status is 
    “NOT IN FILE.”

    The three options are:

    IN FILE - This is for references that you have a physical copy of in your files.
    NOT IN FILE - This is for references that you do not have physical copies of in your files.
    ON REQUEST (MM/DD/YY) - This means that you have sent for a reprint of the reference; the date is the date on which
    the reprint was requested (in MM/DD/YY format)."""

    JF = auto()
    """Periodical name: full format.
    This is an alphanumeric field of up to 255 characters."""
    JO = auto()  # synonym of JF

    JA = auto()
    """Periodical name: standard abbreviation.
    This is the periodical in which the article was (or is to be, in the case of in-press references) published.
    This is an alphanumeric field of up to 255 characters.

    If possible, periodical names should be abbreviated in the Index Medicus style, with periods after the
    abbreviations. If this is not possible (your large bibliography file in WordPerfect has no periods after
    abbreviations), you can use the "RIS Format (Adds periods)" Import Filter definition. This definition uses the
    Periodical Word Dictionary."""

    J1 = auto()
    """Periodical name: user abbreviation 1.
	This is an alphanumeric field of up to 255 characters."""

    J2 = auto()
    """Periodical name: user abbreviation 2.
    This is an alphanumeric field of up to 255 characters."""

    VL = auto()
    """Volume number.
    There is no practical limit to the length of this field."""

    IS = auto()
    """Issue.
    There is no practical limit to the length of this field."""
    CP = auto()  # synonym of IS

    SP = auto()
    """Start page number; an alphanumeric string.
    There is no practical limit to the length of this field."""

    EP = auto()
    """Ending page number, as above."""

    CY = auto()
    """City of publication; this is an alphanumeric field.
    There is no practical limit to the length of this field."""

    PB = auto()
    """Publisher; this is an alphanumeric field.
    There is no practical limit to the length of this field."""

    SN = auto()
    """ISSN/ISBN. This is an alphanumeric field.
    There is no practical limit to the length of this field."""

    AD = auto()
    """Address.
    This is a free text field and contain alphanumeric characters; there is no practical length limit to this field."""

    AV = auto()
    """Availability.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    M1 = auto()
    """Miscellaneous 1.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    M2 = auto()
    """Miscellaneous 2.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    M3 = auto()
    """Miscellaneous 3.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    U1 = auto()
    """User definable 1.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    U2 = auto()
    """User definable 2.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    U3 = auto()
    """User definable 3.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    U4 = auto()
    """User definable 4.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    U5 = auto()
    """User definable 5.
    This is an alphanumeric field and there is no practical limit to the length of this field."""

    UR = auto()
    """Web/URL.
	There is no practical limit to the length of this field.
	URL addresses can be entered individually, one per tag or multiple addresses can be entered on one line
	using a semi-colon as a separator."""

    L1 = auto()
    """Link to PDF.
    There is no practical limit to the length of this field.
    URL addresses can be entered individually, one per tag or multiple addresses can be entered on one line
    using a semi-colon as a separator."""

    L2 = auto()
    """Link to Full-text.
    There is no practical limit to the length of this field.
    URL addresses can be entered individually, one per tag or multiple addresses can be entered on one line
    using a semi-colon as a separator."""

    L3 = auto()
    """Related Records.
    There is no practical limit to the length of this field."""

    L4 = auto()
    """Image(s).
    There is no practical limit to the length of this field."""

    @staticmethod
    def parse(tag_str: str):
        """Parses a tag name into an enum value."""
        for n in Tags:
            if tag_str == n.name:
                return n
        raise ValueError(f'unknown {tag_str} tag')

@_cite(RIS_2001)
class TypeFieldName(Enum):
    """Reference Type Field Names

    The following describes the valid reference type field names that can be used with for the reference type field when
    importing references into Reference Manager."""

    ABST = auto()
    """Abstract"""

    ADVS = auto()
    """Audiovisual material"""

    ART = auto()
    """Art Work"""

    BILL = auto()
    """Bill/Resolution"""

    BOOK = auto()
    """Book, Whole"""

    CASE = auto()
    """Case"""

    CHAP = auto()
    """Book chapter"""

    COMP = auto()
    """Computer program"""

    CONF = auto()
    """Conference proceeding"""

    CTLG = auto()
    """Catalog"""

    DATA = auto()
    """Data file"""

    ELEC = auto()
    """Electronic Citation"""

    GEN = auto()
    """Generic"""

    HEAR = auto()
    """Hearing"""

    ICOMM = auto()
    """Internet Communication"""

    INPR = auto()
    """In Press"""

    JFULL = auto()
    """Journal (full)"""

    JOUR = auto()
    """Journal"""

    MAP = auto()
    """Map"""

    MGZN = auto()
    """Magazine article"""

    MPCT = auto()
    """Motion picture"""

    MUSIC = auto()
    """Music score"""

    NEWS = auto()
    """Newspaper"""

    PAMP = auto()
    """Pamphlet"""

    PAT = auto()
    """Patent"""

    PCOMM = auto()
    """Personal communication"""

    RPRT = auto()
    """Report"""

    SER = auto()
    """Serial (Book, Monograph)"""

    SLIDE = auto()
    """Slide"""

    SOUND = auto()
    """Sound recording"""

    STAT = auto()
    """Statute"""

    THES = auto()
    """Thesis/Dissertation"""

    UNBILL = auto()
    """Unenacted bill/resolution"""

    UNPB = auto()
    """Unpublished work"""

    VIDEO = auto()
    """Video recording"""

    @staticmethod
    def parse(entry_type: str):
        """Parses an entry type name into an enum value."""
        for n in TypeFieldName:
            if entry_type == n.name:
                return n
        raise ValueError(f'unknown {entry_type} type')

@dataclass(frozen=True)
class Tag:
    """A field tag."""
    auto: auto
    repeating: bool = False

@_cite(RIS_2011)
class Tags(Tag, Enum):
    """
    RIS fields.
    """

    TY = auto()
    """Type of reference. 
    This must contain the abbreviation for the reference type as found in the next section. This will determine how all 
    other fields are interpreted."""

    ER = auto()
    """End of reference.
    Must be the last tag in a reference."""

    AU = (auto(), True)
    """Authors, Editors, Translators. 
    Each author must be on a separate line, preceded by the tag that corresponds to the author role (see individual ref 
    type matrix for role definitions). Each reference can contain unlimited author fields, and can contain up to 255 
    characters for each field. The author name must be in the following syntax:

    Lastname, Firstname, Suffix

    For Firstname, you can use full names, initials, or both. The format for the author’s first name is as follows:

    Phillips, A.J

    Phillips, Albert John

    Phillips, Albert

    Lastname = Any string of letters, spaces, and hyphens

    Firstname = Any string of letters, spaces, and hyphens

    Initial = Any single letter followed by a period

    Full Name = Any string of letters, spaces, and hyphens

    Suffix = Jr/Sr/II/III/MD etc. (Phillips,A.J.,Sr.); use of the suffix is optional"""

    A2 = (auto(), True)
    """Secondary Author"""

    A3 = (auto(), True)
    """Tertiary Author"""

    A4 = (auto(), True)
    """Subsidiary Author"""

    AB = auto()
    """Abstract"""

    AD = auto()
    """Author address"""

    AN = auto()
    """Accession Number"""

    C1 = auto()
    """Custom 1"""

    C2 = auto()
    """Custom 2"""

    C3 = auto()
    """Custom 3"""

    C4 = auto()
    """Custom 4"""

    C5 = auto()
    """Custom 5"""

    C6 = auto()
    """Custom 6"""

    C7 = auto()
    """Custom 7"""

    C8 = auto()
    """Custom 8"""

    CA = auto()
    """Caption"""

    CN = auto()
    """Call Number"""

    CY = auto()
    """Place Published"""

    DB = auto()
    """Name of Database"""

    DO = auto()
    """DOI"""

    DP = auto()
    """Database provider"""

    ET = auto()
    """Edition"""

    ID = auto()
    """The characters allowed in the reference ID fields can be in the set "0" through "9," or "A" through "Z.\""""

    PY = auto()
    """This is the publication year. 
    It must be four numeric characters. Dates prior to 1000 should use “0” in the positions before the intended date. 
    For example, the year 765 would be represented as 0765."""

    DA = auto()
    """Dates must be in the following format:

    YYYY/MM/DD/other info

    The year, month and day fields are all numeric. The other info field can be any string of letters, spaces and 
    hyphens.

    Note that each specific date information is optional, however the slashes (“/”) are not. For example, if you just 
    had the <year> and <other info>, then the output would look like: “1993///Spring.”

    Date information should be set forth in the following format:

    YYYY or
    YYYY/MM or
    YYYY/MM/DD or
    YYYY/MM/DD/other info"""

    KW = (auto(), True)
    """Keywords.
    Each keyword or phrase must be on its own line, preceded by this tag. A keyword can consist of multiple words 
    (phrases) and can be up to 255 characters long. There can be unlimited keywords in a reference."""

    RP = auto()
    """Reprint status.
    This optional field can contain one of three status notes. Each must be in uppercase, and the date after 
    “ON REQUEST” must be in USA format, in parentheses (MM/DD/YY). If this field is blank the Import function assumes 
    the reprint status is “NOT IN FILE.”

    The three options are:

    IN FILE – The data provider has a corresponding physical copy for the reference.
    NOT IN FILE – The data provider does not have a corresponding physical copy.
    ON REQUEST (mm/dd/yy) - This means that the data provider has requested a reprint of the reference; the date is the 
    date on which the reprint was requested (in mm/dd/yy format)."""

    J2 = auto()
    """Periodical name: standard abbreviation. 
    This is the abbreviation of the periodical in which the article is published. If possible, periodical names should 
    be abbreviated in the Index Medicus® style, with periods after the abbreviations. This field is mapped to the full 
    journal name in T2 and is used as the journal abbreviation in output styles."""

    L1 = auto()
    """File attachment"""

    L4 = auto()
    """Figure"""

    LA = auto()
    """Language"""

    LB = auto()
    """Label"""

    IS = auto()
    """Number"""

    M3 = auto()
    """Type of Work"""

    N1 = auto()
    """Notes"""

    NV = auto()
    """Number of Volumes"""

    OP = auto()
    """Original Publication"""

    PB = auto()
    """Publisher"""

    UR = auto()
    """Web/URL.
    There is no practical length limit to this field. URL addresses can be entered individually, one per tag, or
    multiple addresses can be entered on one line using a semi-colon as a separator."""

    # following fields are for implicit RIS 2001 retrocompatibility in RIS 2011 samples
    T3 = auto()
    CT = auto()
    U3 = auto()
    L3 = auto()
    T1 = auto()
    CP = auto()
    AV = auto()
    EP = auto()
    JO = auto()
    U1 = auto()
    U5 = auto()
    VL = auto()
    L2 = auto()
    JF = auto()
    U4 = auto()
    ED = (auto(), True)
    J1 = auto()
    SN = auto()
    Y1 = auto()
    T2 = auto()
    N2 = auto()
    TI = auto()
    BT = auto()
    A1 = (auto(), True)
    JA = auto()
    M2 = auto()
    U2 = auto()
    M1 = auto()
    Y2 = auto()
    SP = auto()

    @staticmethod
    def parse(tag_str: str):
        """Parses a tag name into an enum value."""
        for n in Tags:
            if tag_str == n.name:
                return n
        raise ValueError(f'unknown {tag_str} tag')

@_cite(RIS_2011)
class TypeFieldName(Enum):
    """Reference Type Field Names

    The following describes the valid reference type field names that can be used with for the reference type field when
    importing references into Reference Manager."""

    ABST = auto()
    """Abstract"""

    AGGR = auto()
    """Aggregated Database"""

    ANCIENT = auto()
    """Ancient Text"""

    ADVS = auto()
    """Audiovisual material"""

    ART = auto()
    """Art Work"""

    BILL = auto()
    """Bill"""

    BLOG = auto()
    """Blog"""

    BOOK = auto()
    """Book, Whole"""

    CASE = auto()
    """Case"""

    CHAP = auto()
    """Book Section"""

    CHART = auto()
    """Chart"""

    CLSWK = auto()
    """Classical Work"""

    COMP = auto()
    """Computer program"""

    CONF = auto()
    """Conference proceeding"""

    CPAPER = auto()
    """Conference Paper"""

    CTLG = auto()
    """Catalog"""

    DATA = auto()
    """Dataset"""

    DICT = auto()
    """Dictionary"""

    EDBOOK = auto()
    """Edited book"""

    EBOOK = auto()
    """Electronic book"""

    ECHAP = auto()
    """Electronic Book Section"""

    EJOUR = auto()
    """Electronic Article"""

    ENCYC = auto()
    """Encyclopedia"""

    EQUA = auto()
    """Equation"""

    FIGURE = auto()
    """Figure"""

    GEN = auto()
    """Generic"""

    GOVDOC = auto()
    """Government Document"""

    GRNT = auto()
    """Grant"""

    HEAR = auto()
    """Hearing"""

    ICOMM = auto()
    """Internet Communication"""

    INPR = auto()
    """In Press Article"""

    JFULL = auto()
    """Full Journal"""

    JOUR = auto()
    """Journal"""

    LEGAL = auto()
    """Legal Rule"""

    MAP = auto()
    """Map"""

    MGZN = auto()
    """Magazine article"""

    MANSCPT = auto()
    """Manuscript"""

    MUSIC = auto()
    """Music"""

    NEWS = auto()
    """Newspaper"""

    DBASE = auto()
    """Online Database"""

    MULTI = auto()
    """Online Multimedia"""

    PAMP = auto()
    """Pamphlet"""

    PAT = auto()
    """Patent"""

    PCOMM = auto()
    """Personal communication"""

    RPRT = auto()
    """Report"""

    SER = auto()
    """Serial (Book, Monograph)"""

    SLIDE = auto()
    """Slide"""

    SOUND = auto()
    """Sound recording"""

    STAND = auto()
    """Standard"""

    STAT = auto()
    """Statute"""

    THES = auto()
    """Thesis/Dissertation"""

    UNBILL = auto()
    """Unenacted bill/resolution"""

    UNPD = auto()
    """Unpublished work"""

    VIDEO = auto()
    """Video recording"""

    ELEC = auto()
    """Web Page"""

    @staticmethod
    def parse(entry_type: str):
        """Parses an entry type name into an enum value."""
        for n in TypeFieldName:
            if entry_type == n.name:
                return n
        raise ValueError(f'unknown {entry_type} type')

@dataclass(frozen=True)
class Tag:
    """A field tag."""
    auto: auto
    repeating: bool = False

@_cite(REFER_MAN)
class Tags(Tag, Enum):
    """
    REFER fields.
    """

    A = (auto(), True)
    """The name of an author.  If the name contains a title such as Jr.
    at the end, it should be separated  from  the  last  name  by  a
    comma.   There can be multiple occurrences of the %A field.  The
    order is significant.  It is a good idea always to supply an  %A
    field or a %Q field."""

    B = auto()
    """For an article that is part of a book, the title of the book."""

    C = auto()
    """The place (city) of publication."""

    D = auto()
    """The  date of publication.  The year should be specified in full.
    If the month is specified, the name rather than  the  number  of
    the  month  should be used, but only the first three letters are
    required.  It is a good idea always to supply a %D field; if the
    date  is  unknown,  a  value  such as in press or unknown can be
    used."""

    E = (auto(), True)
    """For an article that is part of a book, the name of an editor  of
    the  book.  Where the work has editors and no authors, the names
    of the editors should be  given  as  %A  fields  and  , (ed)  or
    , (eds) should be appended to the last author."""

    G = auto()
    """US Government ordering number."""

    I = auto()
    """The publisher (issuer)."""

    J = auto()
    """For an article in a journal, the name of the journal."""

    K = auto()
    """Keywords to be used for searching."""

    L = auto()
    """Label."""

    N = auto()
    """Journal issue number."""

    O = auto()
    """Other  information.   This  is usually printed at the end of the
    reference."""

    P = auto()
    """Page number.  A range of pages can be specified as m-n."""

    Q = (auto(), False)
    """The name of the author, if the author is  not  a  person.   This
    will  only be used if there are no %A fields.  There can only be
    one %Q field."""

    R = auto()
    """Technical report number."""

    S = auto()
    """Series name."""

    T = auto()
    """Title.  For an article in a book or journal, this should be  the
    title of the article."""

    V = auto()
    """Volume number of the journal or book."""

    X = auto()
    """Annotation."""

    @staticmethod
    def parse(tag_str: str):
        """Parses a tag name into an enum value."""
        for n in Tags:
            if tag_str in (n.name, "%" + n.name):
                return n
        raise ValueError(f'unknown {tag_str} tag')

@_cite(PUBMED_FORMAT, PUBMED_PUBLICATION_TYPES, MESH_PUBLICATION_TYPES)
class MeshPublicationType(Enum):
    """Mesh publication types."""

    ABBREVIATIONS = 'Abbreviations'
    """Works consisting of lists of shortened forms of written words or phrases used for brevity. 
    Acronyms are included here."""

    ABSTRACTS = 'Abstracts'
    """Works consisting of lists of publications on a subject and that provide full annotated bibliographical 
    information together with substantive summaries or condensations of the facts, ideas, or opinions presented in each 
    publication listed. (From LC Subject Cataloging Manual)."""

    ACADEMIC_DISSERTATION = 'Academic Dissertation'
    """Work consisting of formal presentations made usually to fulfill requirements for an academic degree."""

    ACCOUNT_BOOK = 'Account Book'
    """Book in which personal or commercial accounts of financial transactions are recorded. 
    (From Random House Unabridged Dictionary, 2d ed)"""

    ADAPTIVE_CLINICAL_TRIAL = 'Adaptive Clinical Trial'
    """Clinical study in which a prospectively planned opportunity is included to modify trial designs and hypotheses 
    based on analysis of data from subjects in the study."""

    ADDRESS = 'Address'
    """Work consisting of speeches, orations, or written statements, usually formal, directed to a particular group of 
    persons. These are different from a LECTURE that is usually delivered to classes for instructional purposes."""

    ADVERTISEMENT = 'Advertisement'
    """Work consisting of publicly distributed notices, usually as paid announcements in mass media such as newspapers, 
    magazines, or on billboards. They include those in motion picture, television advertising, radio, or electronic 
    media. """

    ALMANAC = 'Almanac'
    """Work consisting of a calendar of days, weeks, and months, together with information such as astronomical data, 
    various statistics, etc. 
    (From Genre Terms: A Thesaurus for Use in Rare Book and Special Collections Cataloguing, 2d ed)"""

    ANECDOTES = 'Anecdotes'
    """Works consisting of brief accounts or narratives of incidents or events."""

    ANIMATION = 'Animation'
    """A film or video wholly or partially created by photographing drawings, sculptures, or other inanimate things in 
    sequence to create the illusion of motion. Animations are also generated by computers. 
    (From Moving Image Materials: Genre Terms, 1988)."""

    ANNUAL_REPORT = 'Annual Report'
    """Annual statements concerning the administrative and operational functions of an institution or organization."""

    APHORISMS_AND_PROVERBS = 'Aphorisms and Proverbs'
    """Short memorable sayings in common use. They express in simple language an obvious truth, familiar experience, or 
    advice."""

    ARCHITECTURAL_DRAWING = 'Architectural Drawing'
    """Work consisting of drawings of architecture and architectural projects, whether the project was executed or not. 
    (Art & Architecture Thesaurus, 1990, v.2)."""

    ATLAS = 'Atlas'
    """Work consisting of collections of illustrative plates, charts, etc., usually with explanatory captions."""

    AUTOBIOGRAPHY = 'Autobiography'
    """Self-described narratives of a person's life."""

    BIBLIOGRAPHY = 'Bibliography'
    """A work consisting of a list of books, articles, documents, publications, and other items, usually on a single 
    subject or related subjects."""

    BIOBIBLIOGRAPHY = 'Biobibliography'
    """Works consisting of biographical information as well as lists of the writings of those persons."""

    BIOGRAPHY = 'Biography'
    """Works consisting of an account of the events, works, and achievements, personal and professional, during a 
    person's life."""

    BLOG = 'Blog'
    """A website that contains conversational personal reflections, comments and sometimes links to other sites; 
    typically run by an individual or small group."""

    BOOK_ILLUSTRATIONS = 'Book Illustrations'
    """Works consisting of photographs, prints, drawings, portraits, plates, diagrams, facsimiles, maps, tables, or 
    other representations or systematic arrangements of data designed to elucidate or decorate the contents of a 
    publication. 
    (From The ALA Glossary of Library and Information Science, 1983, p114)."""

    BOOK_REVIEW = 'Book Review'
    """Work consisting of critical analyses of books or other monographic works."""

    BOOKPLATE = 'Bookplate'
    """Works consisting of book owner's identification labels. They are usually intended for attaching inside a book or 
    similar object. (From Thesaurus for Graphic Materials II: Genre and Physical Characteristic Terms, 1995)."""

    BROADSIDE = 'Broadside'
    """Work consisting of published pieces of paper or other material, usually printed on one side and intended to be 
    read unfolded and usually intended to be posted, publicly distributed, or sold, e.g., proclamations, handbills, 
    newssheets, etc. (From Genre Terms: A Thesaurus for Use in Rare Book and Special Collections Cataloguing, 2d ed)."""

    CALENDAR = 'Calendar'
    """Document or chart that shows days, weeks, and months of a year."""

    CARICATURE = 'Caricature'
    """Work portraying in a critical or facetious way a real individual or group, or a figure representing a social, 
    political, ethnic, or racial type. The effect is usually achieved through distortion or exaggeration of 
    characteristics. 
    (Genre Terms: A Thesaurus for Use in Rare Book and Special Collection Cataloguing, 2d ed)."""

    CARTOON = 'Cartoon'
    """Image used to comment on such things as contemporary events, social habits, or political trends; usually 
    executed in a broad or abbreviated manner."""

    CASE_REPORTS = 'Case Reports'
    """Clinical presentations that may be followed by evaluative studies that eventually lead to a diagnosis."""

    CATALOG = 'Catalog'
    """Work consisting of bibliographic records, created according to specific and uniform principles of construction 
    and under the control of an authority file, which describe the materials contained in a collection, library, or 
    group of libraries. Catalogs include also lists of materials prepared for a particular purpose, such as exhibition 
    catalogs, sales catalogs, garden catalogs, medical supply catalogs. 
    (From The ALA Glossary of Library and Information Sciences, 1983)."""

    CATALOG_BOOKSELLER = 'Catalog, Bookseller'
    """Lists of books for sale by a specific seller."""

    CATALOG_COMMERCIAL = 'Catalog, Commercial'
    """Lists of merchandise for sale."""

    CATALOG_DRUG = 'Catalog, Drug'
    """Lists of drugs for sale."""

    CATALOG_PUBLISHER = 'Catalog, Publisher'
    """Lists of books or other titles produced by a specific entity."""

    CATALOG_UNION = 'Catalog, Union'
    """Lists of books and other information sources held among a cooperating group of LIBRARIES."""

    CHART = 'Chart'
    """Work consisting of information presented in graphic form, for example, graphs or diagrams."""

    CHRONOLOGY = 'Chronology'
    """Works consisting of lists of events arranged in chronological order."""

    CLASSICAL_ARTICLE = 'Classical Article'
    """Works consisting of a current presentation of a previously printed seminal article marking a milestone in the 
    history of medicine or science. It is usually accompanied by introductory remarks heralding its reprinting, often 
    on the anniversary of its original publication or on an anniversary of the author's birth or death. It is usually 
    reprinted in full, with complete bibliographical reference to the original appearance."""

    CLINICAL_CONFERENCE = 'Clinical Conference'
    """Work that consists of a conference of physicians on their observations of a patient at the bedside, regarding 
    the physical state, laboratory and other diagnostic findings, clinical manifestations, results of current therapy, 
    etc. A clinical conference usually ends with a confirmation or correction of clinical findings by a pathological 
    diagnosis performed by a pathologist. "Clinical conference" is often referred to as a "clinico-pathological 
    conference."
    """

    CLINICAL_STUDY = 'Clinical Study'
    """A work that reports on the results of a research study to evaluate interventions or exposures on biomedical or 
    health-related outcomes.  The two main types of clinical studies are interventional studies (clinical trials) and 
    observational studies. While most clinical studies concern humans, this publication type may be used for clinical 
    veterinary articles meeting the requisites for humans."""

    CLINICAL_TRIAL = 'Clinical Trial'
    """A work that reports on the results of a clinical study in which participants are assigned to receive one or more 
    interventions so that researchers can evaluate the interventions on biomedical or health-related outcomes. The 
    assignments are determined by the study protocol. Participants may receive diagnostic, therapeutic, or other types 
    of interventions. For clinical trials on  veterinary animals see CLINICAL TRIAL, VETERINARY. Clinical Trials was 
    used for both humans and non-humans prior to 2019."""

    CLINICAL_TRIAL_PROTOCOL  = 'Clinical Trial Protocol'
    """The written description of a clinical study. It contains the study's objectives, design, and methods including 
    subject target and/or enrollment criteria. It may also present relevant scientific background and statistical 
    information."""

    CLINICAL_TRIAL_PHASE_I = 'Clinical Trial, Phase I'
    """Work that is the report of a pre-planned, usually controlled, clinical study of the safety and efficacy of 
    diagnostic, therapeutic, or prophylactic drugs, devices, or techniques based on a small number of healthy persons 
    and conducted over the period of about a year in either the United States or a foreign country."""

    CLINICAL_TRIAL_PHASE_II = 'Clinical Trial, Phase II'
    """Work that is a report of a pre-planned, usually controlled, clinical study of the safety and efficacy of 
    diagnostic, therapeutic, or prophylactic drugs, devices, or techniques based on several hundred volunteers, 
    including a limited number of patients, and conducted over a period of about two years in either the United States 
    or a foreign country."""

    CLINICAL_TRIAL_PHASE_III = 'Clinical Trial, Phase III'
    """Work that is a report of a pre-planned, usually controlled, clinical study of the safety and efficacy of 
    diagnostic, therapeutic, or prophylactic drugs, devices, or techniques after phase II trials. A large enough group 
    of patients is studied and closely monitored by physicians for adverse response to long-term exposure, over a 
    period of about three years in either the United States or a foreign country."""

    CLINICAL_TRIAL_PHASE_IV = 'Clinical Trial, Phase IV'
    """Work that is a report of a planned post-marketing study of diagnostic, therapeutic, or prophylactic drugs, 
    devices, or techniques that have been approved for general sale after clinical trials, phases I, II, and III. These 
    studies, conducted in the United States or a foreign country, often garner additional data about the safety and 
    efficacy of a product."""

    CLINICAL_TRIAL_VETERINARY = 'Clinical Trial, Veterinary'
    """A work that is a veterinary clinical study in which animal participants are assigned to receive one or more 
    interventions so that researchers can evaluate the interventions on biomedical or health-related outcomes. The 
    assignments are determined by the study protocol. Animal participants may receive diagnostic, therapeutic, or other 
    types of interventions."""

    COLLECTED_CORRESPONDENCE = 'Collected Correspondence'
    """Written communication between persons or between institutions or organizations."""

    COLLECTED_WORK = 'Collected Work'
    """Work consisting of collections of previously published works."""

    COLLECTION = 'Collection'
    """Items gathered and assembled in some order to facilitate access or use."""

    COMMENT = 'Comment'
    """Work consisting of a critical or explanatory note written to discuss, support, or dispute an article or other 
    presentation previously published. It may take the form of an article, letter, editorial, etc. It appears in 
    publications under a variety of names: comment, commentary, editorial comment, viewpoint, etc."""

    COMPARATIVE_STUDY = 'Comparative Study'
    """Comparison of outcomes, results, responses, etc for different techniques, therapeutic approaches or other inputs.
    """

    CONGRESS = 'Congress'
    """Published record of the papers delivered at or issued on the occasion of individual congresses, symposia, and 
    meetings; abstracts of papers delivered at such congresses; reports of the officers and delegates of such 
    congresses; combinations of the foregoing; or proceedings of the conference of a society if they are not limited to 
    matters of internal organization."""

    CONSENSUS_DEVELOPMENT_CONFERENCE = 'Consensus Development Conference'
    """Official statements of the findings or recommendations expressing the outcome of a meeting convened to evaluate 
    current thought and research on a subject of interest."""

    CONSENSUS_DEVELOPMENT_CONFERENCE_NIH = 'Consensus Development Conference, NIH'
    """Official statements of the finding or recommendations expressing the outcome from a conference sponsored by NIH.
    """

    CONTROLLED_CLINICAL_TRIAL = 'Controlled Clinical Trial'
    """A work that reports on a clinical trial involving one or more test treatments, at least one control treatment, 
    specified outcome measures for evaluating the studied intervention, and a bias-free method for assigning patients 
    to the test treatment. The treatment may be drugs, devices, or procedures studied for diagnostic, therapeutic, or 
    prophylactic effectiveness. Control measures include placebos, active medicine, no-treatment, dosage forms and 
    regimens, historical comparisons, etc. When randomization using mathematical techniques, such as the use of a 
    random numbers table, is employed to assign patients to test or control treatments, the trial is characterized as a 
    RANDOMIZED CONTROLLED TRIAL."""

    COOKBOOK = 'Cookbook'
    """Collection of recipes or instructions for preparation of food and organization of meals."""

    CORRECTED_AND_REPUBLISHED_ARTICLE = 'Corrected and Republished Article'
    """Work that is the republication of an article to correct, amplify, or restore text and data of the originally 
    published article."""

    DATABASE = 'Database'
    """A structured file of information or a set of logically related data stored and retrieved using computer-based 
    means."""

    DATASET = 'Dataset'
    """Works consisting of organized collections of data, which have been stored permanently in a formalized manner 
    suitable for communication, interpretation, or processing."""

    DIARY = 'Diary'
    """Work consisting of records, usually private, of writers' experiences, observations, feelings, attitudes, etc. 
    They may also be works marked in calendar order in which to note appointments and the like. 
    (From Random House Unabridged Dictionary, 2d ed)."""

    DICTIONARY = 'Dictionary'
    """A reference book containing a list of words - usually in alphabetical order - giving information about form, 
    pronunciation, etymology, grammar, and meaning. A foreign-language dictionary is an alphabetical list of words of 
    one language with their meaning and equivalents in another language."""

    DICTIONARY_CHEMICAL = 'Dictionary, Chemical'
    """A reference book containing a list of words related to chemistry-usually in alphabetic order-giving information 
    about form, pronunciation, etymology, grammar, and meaning."""

    DICTIONARY_CLASSICAL = 'Dictionary, Classical'
    """A reference work containing a list of words related to the Greco-Roman World giving information about form, 
    pronunciation, etymology, grammar, and meaning."""

    DICTIONARY_DENTAL = 'Dictionary, Dental'
    """A reference book containing a list of words related to dentistry-usually in alphabetic order-giving information 
    about form, pronunciation, etymology, grammar, and meaning."""

    DICTIONARY_MEDICAL = 'Dictionary, Medical'
    """A reference book containing a list of words related to medicine-usually in alphabetic order-giving information 
    about form, pronunciation, etymology, grammar, and meaning."""

    DICTIONARY_PHARMACEUTIC = 'Dictionary, Pharmaceutic'
    """A reference book containing a list of words related to pharmacy-usually in alphabetic order-giving information 
    about form, pronunciation, etymology, grammar, and meaning."""

    DICTIONARY_POLYGLOT = 'Dictionary, Polyglot'
    """Reference list of definitions of words repeated in several languages."""

    DIRECTORY = 'Directory'
    """Work consisting of an alphabetical or classified list of names, organizations, subjects, etc., giving usually 
    titles, addresses, affiliations, and other professional data."""

    DISPENSATORY = 'Dispensatory'
    """Systematic description of the drugs and preparations used generally or in a specific setting."""

    DOCUMENTARIES_AND_FACTUAL_FILMS = 'Documentaries and Factual Films'
    """Works consisting of films, videos, and programs which depict actual persons or actual events. They do not 
    include frank historical re-creations and do not attempt to judge the truth of the depiction in a film purporting 
    to be factual or documentary in character. (From Moving Image Materials: Genre Terms, 1988)."""

    DRAWING = 'Drawing'
    """Work consisting of graphic representations of objects or ideas by lines."""

    DUPLICATE_PUBLICATION = 'Duplicate Publication'
    """Work consisting of an article or book of identical or nearly identical material published simultaneously or 
    successively to material previously published elsewhere, without acknowledgment of the prior publication."""

    EDITORIAL = 'Editorial'
    """Work consisting of a statement of the opinions, beliefs, and policy of the editor or publisher of a journal, 
    usually on current matters of medical or scientific significance to the medical community or society at large. The 
    editorials published by editors of journals representing the official organ of a society or organization are 
    generally substantive."""

    ELECTRONIC_SUPPLEMENTARY_MATERIALS = 'Electronic Supplementary Materials'
    """Supporting content or information, such as animation, datasets, multimedia files, video, movies, audio files, 
    text files, or software, which is submitted for publication in an online journal or an online edition of a journal. 
    This information may be referenced in the text of the article with a link to the supplementary data provided. 
    CATALOG: do not use."""

    ENCYCLOPEDIA = 'Encyclopedia'
    """Work containing informational articles on subjects in every field of knowledge, usually arranged in alphabetical 
    order, or a similar work limited to a special field or subject."""

    ENGLISH_ABSTRACT = 'English Abstract'
    """Identifier for English language abstracts provided with non-English language works."""

    EPHEMERA = 'Ephemera'
    """Works consisting of transient everyday items, usually printed on paper, that are produced for a specific limited 
    use and then often thrown away. (From Genre Terms: A Thesaurus for Use in Rare Book and Special Collections 
    Cataloguing, 2d ed & The ALA Glossary of Library and Information Science, 1983)."""

    EQUIVALENCE_TRIAL = 'Equivalence Trial'
    """Trial that aims to show a new treatment is no better and no worse than the standard treatment."""

    ESSAY = 'Essay'
    """Short literary prose composition, usually dealing with a single theme."""

    EULOGY = 'Eulogy'
    """Work consisting of speeches or writings in praise of a person or thing, especially a set oration in honor of a 
    deceased person. They differ from FUNERAL SERMON which are delivered at ceremonies for the deceased prior to their 
    burial or cremation. (From Random House Unabridged Dictionary, 2d ed)."""

    EVALUATION_STUDY = 'Evaluation Study'
    """Works consisting of studies determining the effectiveness or utility of processes, personnel, and equipment."""

    EXAMINATION_QUESTIONS = 'Examination Questions'
    """Work consisting of compilations of questions and answers pertaining to a particular subject, used for study and 
    review."""

    EXHIBITION = 'Exhibition'
    """Objects publicly displayed."""

    EXPRESSION_OF_CONCERN = 'Expression of Concern'
    """A notification about the integrity of a published article that is typically written by an editor and should be 
    labelled prominently in the item title. It is the responsibility of the editor to initiate appropriate 
    investigative procedures, discover the outcome of the investigation, and notify readers of that outcome in a 
    subsequent published item. The outcome may require the publication of a retraction notice."""

    FESTSCHRIFT = 'Festschrift'
    """Work consisting of a collection of essays or other writings contributed by students, teachers, colleagues, and 
    associates to honor a person or institution, usually on the occasion of an anniversary celebration or other event 
    of importance."""

    FICTIONAL_WORK = 'Fictional Work'
    """Work consisting of creative writing, not presented as factual."""

    FORM = 'Form'
    """Document used for acquiring particular information or for presenting particular information in a prescribed 
    sequence and format, often with blank spaces or lines or other methods to prompt for insertion of the requested 
    information."""

    FORMULARY = 'Formulary'
    """Work that consists of lists of drugs or collections of recipes, formulas, and prescriptions for the compounding 
    of medicinal preparations."""

    FORMULARY_DENTAL = 'Formulary, Dental'
    """Works on or about reference lists of descriptions and uses of drugs related to oral medicine and dentistry."""

    FORMULARY_HOMEOPATHIC = 'Formulary, Homeopathic'
    """Work about Formulary concerned with HOMEOPATHIC REMEDIES."""

    FORMULARY_HOSPITAL = 'Formulary, Hospital'
    """Formulary concerned with PHARMACEUTICAL PREPARATIONS prescribed in hospitals."""

    FUNERAL_SERMON = 'Funeral Sermon'
    """Work consisting of sermons delivered at ceremonies for a dead person prior to burial or cremation. 
    (From Random House Unabridged Dictionary, 2d ed)."""

    GOVERNMENT_PUBLICATION = 'Government Publication'
    """Work consisting of publications issued by local, regional, or national governments or by their agencies or 
    subdivisions."""

    GRAPHIC_NOVEL = 'Graphic Novel'
    """Book-length narratives told using a combination of words and sequential art, often presented in comic book 
    style. from (Fletcher-Spear et al., ALA Review, Winter 2005)."""

    GUIDEBOOK = 'Guidebook'
    """Work consisting of publications for travelers that give information about a city, region, or country, or similar 
    handbooks about buildings, museums, etc. (The ALA Glossary of Library and Information Science, 1983)."""

    GUIDELINE = 'Guideline'
    """Work consisting of a set of statements, directions, or principles presenting current or future rules or policy. 
    Guidelines may be developed by government agencies at any level, institutions, organizations such as professional 
    societies or governing boards, or by the convening of expert panels. The text may be cursive or in outline form, 
    but it is generally a comprehensive guide to problems and approaches in any discipline or activity. This concept 
    relates to the general conduct and administration of health care activities rather than to specific decisions for a 
    particular clinical condition. For that aspect, PRACTICE GUIDELINE is available."""

    HANDBOOK = 'Handbook'
    """Work consisting of concise reference works in which facts and information pertaining to a certain subject or 
    field are arranged for ready reference and consultation rather than for continuous reading and study."""

    HERBAL = 'Herbal'
    """Work such as books on herbs or plants usually describing their medicinal value. 
    (Random House Unabridged Dictionary, 2d ed)."""

    HISTORICAL_ARTICLE = 'Historical Article'
    """An article or portion of an article giving an account of past events or circumstances significant in a field of 
    study, a profession, a discovery, an invention, etc. The concept of history is very wide, ranging from the dawn of 
    time to the present. This publication type is often checked in conjunction with BIOGRAPHY."""

    INCUNABULA = 'Incunabula'
    """Books printed before 1501."""

    INDEX = 'Index'
    """Work providing an analytical subject approach to materials in a field of knowledge."""

    INSTRUCTIONAL_FILM_AND_VIDEO = 'Instructional Film and Video'
    """Works consisting of nonfiction films and video designed to teach, instruct, or train. 
    (From Moving Image Materials: Genre Terms, 1988)."""

    INTERACTIVE_TUTORIAL = 'Interactive Tutorial'
    """Video recordings or other files in which the progress of the instruction or content is determined by user 
    response."""

    INTERVIEW = 'Interview'
    """Work consisting of a conversation with an individual regarding his or her background and other personal and 
    professional details, opinions on specific subjects posed by the interviewer, etc."""

    INTRODUCTORY_JOURNAL_ARTICLE = 'Introductory Journal Article'
    """Prefatory summary to a special issue or section of a journal devoted to a specific topic. This introductory text 
    can be of varying length and substance."""

    JOURNAL_ARTICLE = 'Journal Article'
    """The predominant publication type for articles and other items indexed for NLM databases."""

    JUVENILE_LITERATURE = 'Juvenile Literature'
    """Works produced for children through age 15 or through the ninth grade."""

    LABORATORY_MANUAL = 'Laboratory Manual'
    """Work containing concise background information and directions for activities, including conducting experiments 
    or diagnostic tests in the laboratory."""

    LECTURE = 'Lecture'
    """Work consisting of speeches read or delivered before an audience or class, especially for instruction or to set 
    forth some subject. They are differentiated from an ADDRESS which are less didactic and more informational, 
    entertaining, inspirational, or polemic. (From Random House Unabridged Dictionary, 2d ed)."""

    LECTURE_NOTE = 'Lecture Note'
    """Work consisting of notes taken at the delivery or reading of a speech before an audience or class, usually given 
    to instruct. (From Random House Unabridged Dictionary, 2d ed)."""

    LEGAL_CASE = 'Legal Case'
    """Work consisting of collections of law reports or the published reports of decided cases and documents or filings 
    related to those cases."""

    LEGISLATION = 'Legislation'
    """Works consisting of the text of proposed or enacted legislation that may be in the form of bills, laws, 
    statutes, ordinances, or government regulations."""

    LETTER = 'Letter'
    """Work consisting of written or printed communication between individuals or between persons and representatives 
    of corporate bodies. The correspondence may be personal or professional. In medical and other scientific 
    publications the letter is usually from one or more authors to the editor of the journal or book publishing the 
    item being commented upon or discussed. LETTER is often accompanied by COMMENT."""

    MANUSCRIPT = 'Manuscript'
    """Work written by hand, as one written before the invention or adoption of printing."""

    MANUSCRIPT_MEDICAL = 'Manuscript, Medical'
    """Medical works prepared by hand including handwritten or typescript drafts of pre-publication papers or works not 
    otherwise reproduced in multiple copies."""

    MAP = 'Map'
    """Works consisting of representations, normally to scale and on a flat medium, of a selection of material or 
    abstract features on the surface of the earth. They may be used also in delineating the heavens and celestial 
    bodies. (From Anglo-American Cataloguing Rules, 2d ed, p619."""

    MEETING_ABSTRACT = 'Meeting Abstract'
    """Individual abstracts of presentations at meetings, congresses, conferences, symposia, colloquia, seminars, 
    workshops, round tables, and other professional gatherings."""

    META_ANALYSIS = 'Meta-Analysis'
    """Works consisting of studies using a quantitative method of combining the results of independent studies 
    (usually drawn from the published literature) and synthesizing summaries and conclusions which may be used to 
    evaluate therapeutic effectiveness, plan new studies, etc. It is often an overview of clinical trials. It is 
    usually called a meta-analysis by the author or sponsoring body and should be differentiated from reviews of 
    literature."""

    MONOGRAPH = 'Monograph'
    """Work that is any publication that is not a serial or integrating resource. In cataloging usage, It is usually on 
    a single subject or related subjects and is complete in itself, whether constructed of chapters, sections, or 
    parts. While any article encountered in indexing journals can be, strictly speaking, a monograph, as a publication 
    type, a monograph will refer to a cataloging. item."""

    MOVABLE_BOOKS = 'Movable Books'
    """Books having mechanisms or parts that move, or are moved by the reader."""

    MULTICENTER_STUDY = 'Multicenter Study'
    """A work that reports on a study executed by several cooperating institutions."""

    NEWS = 'News'
    """Works consisting of an announcement or statement of recent or current events of new data and matters of interest 
    in the field of medicine or science. In some publications, such as "Nature" or "Science," the news reports are 
    substantively written and herald medical and scientific data of vital or controversial importance."""

    NEWSPAPER_ARTICLE = 'Newspaper Article'
    """Work consisting of a news item appearing in a general-interest newspaper or other general news periodical, 
    containing information of current and timely interest in the field of medicine or science. This publication type 
    should not be confused with NEWS Publication Type, reserved for news reports published in various medical or other 
    scientific journals, such as "Nature".)"""

    NURSES_INSTRUCTION = 'Nurses Instruction'
    """Work consisting of materials developed for a nursing audience."""

    OBSERVATIONAL_STUDY = 'Observational Study'
    """A work that reports on the results of a clinical study in which participants may receive diagnostic, 
    therapeutic, or other types of interventions, but the investigator does not assign participants to specific 
    interventions (as in an interventional study)."""

    OBSERVATIONAL_STUDY_VETERINARY = 'Observational Study, Veterinary'
    """Reports on studies of the results of a clinical study in which animal subjects may receive diagnostic, 
    therapeutic, or other types of interventions, where the investigator does not assign participants to specific 
    interventions."""

    OUTLINE = 'Outline'
    """Work consisting of brief statements of the principal elements of a subject, usually arranged by heads and 
    subheads."""

    OVERALL = 'Overall'
    """A single citation covering papers or abstracts presented at a meeting. The publication type may be used for a 
    single citation with or without the additional indexing or cataloging of individual papers. The individual papers, 
    however, are not labeled OVERALL."""

    PATENT = 'Patent'
    """Work consisting of documents granted by a government giving exclusive rights to an inventor or assignee to 
    manufacture, use, or sell an invention for a certain number of years."""

    PATIENT_EDUCATION_HANDOUT = 'Patient Education Handout'
    """Works consisting of a handout or self-contained informative material used to explain a procedure or a condition 
    or the contents of a specific article in a biomedical journal and written in non-technical language for the patient 
    or consumer."""

    PERIODICAL = 'Periodical'
    """Publication intended to be issued on an ongoing basis, generally more frequently than annually, containing 
    separate articles, stories, or writings."""

    PERIODICAL_INDEX = 'Periodical Index'
    """Work consisting of a subject approach to the contents of a periodical issuing an annual, biennial, quinquennial, 
    decennial, etc., index. The heading is used for the overall body of articles published by a periodical in the same 
    sense that BIBLIOGRAPHY is useful when published as a single article."""

    PERSONAL_NARRATIVE = 'Personal Narrative'
    """Work consisting of accounts of individual experience in relation to a particular field or of participation in 
    related activities."""

    PHARMACOPOEIA = 'Pharmacopoeia'
    """Authoritative work containing lists of drugs and preparations, their description, formulation, analytic 
    composition, main chemical properties, standards for strength, purity, and dosage, chemical tests for determining 
    identity, etc. They have the status of a standard."""

    PHARMACOPOEIA_HOMEOPATHIC = 'Pharmacopoeia, Homeopathic'
    """Authoritative resource describing the composition, properties, manufacture, and quality control of HOMEOPATHIC 
    REMEDIES."""

    PHOTOGRAPH = 'Photograph'
    """Still image produced from radiation-sensitive materials (sensitive to light, electron beams, or nuclear 
    radiation), generally by means of the chemical action of light on a sensitive film, paper, glass, or metal. 
    Photographs may be positive or negative, opaque or transparent."""

    PHRASES  = 'Phrases'
    """Work consisting of common terms, phrases, idioms, and typical conversations, e.g., between health professional 
    and patients. These are often intended for use by non-native speakers of a language."""

    PICTORIAL_WORK = 'Pictorial Work'
    """Work consisting exclusively or mainly of pictures but not technical drawings."""

    POETRY = 'Poetry'
    """Works that consist of literary and oral genre expressing meaning via symbolism and following formal or informal 
    patterns."""

    POPULAR_WORK = 'Popular Work'
    """Work written for non-professional or lay audiences."""

    PORTRAIT = 'Portrait'
    """Work consisting of graphic representations, especially of the face, of real persons, usually posed, living or 
    dead. They are pictures whose purpose is the portrayal of an individual or group of individuals, not pictures which 
    merely include people as part of an event or scene. (From Thesaurus for Graphic Materials II, p540, 1995)."""

    POSTCARD = 'Postcard'
    """Card on which a message may be written or printed for mailing without an envelope. Art & Architectural Thesaurus 
    Online www.getty.edu/research/conducting_research/vocabularies/aat/ accessed 12/18/2008"""

    POSTER = 'Poster'
    """Work consisting of single or multi-sheet notices made to attract attention to events, activities, causes, goods, 
    or services. They are for posting, usually in a public place and are chiefly pictorial. They are intended to make 
    an immediate impression from a distance. Posters do not include poster presentations at conferences and meetings. 
    (From Thesaurus for Graphic Materials II: Genre and Physical Characteristic Headings, 1995)."""

    PRACTICE_GUIDELINE = 'Practice Guideline'
    """Work consisting of a set of directions or principles to assist the health care practitioner with patient care 
    decisions about appropriate diagnostic, therapeutic, or other clinical procedures for specific clinical 
    circumstances. Practice guidelines may be developed by government agencies at any level, institutions, 
    organizations such as professional societies or governing boards, or by the convening of expert panels. They can 
    provide a foundation for assessing and evaluating the quality and effectiveness of health care in terms of 
    measuring improved health, reduction of variation in services or procedures performed, and reduction of variation 
    in outcomes of health care delivered."""

    PRAGMATIC_CLINICAL_TRIAL = 'Pragmatic Clinical Trial'
    """Randomized clinical trials that compare interventions in clinical settings and which look at a range of 
    effectiveness outcomes and impacts."""

    PREPRINT = 'Preprint'
    """Scientific manuscript made available prior to PEER REVIEW."""

    PRICE_LIST = 'Price List'
    """Work consisting of lists giving the prices of items for sale, including drugs, equipment, books, etc. Price 
    lists are less detailed than catalogs and not as long."""

    PROBLEMS_AND_EXERCISES = 'Problems and Exercises'
    """Works consisting of collections of practice questions and drills, generally for instructional or review use."""

    PROGRAM = 'Program'
    """Works consisting of lists of the events, pieces, performers, speakers, etc., of an entertainment, ceremony, or 
    the like. (From: Genre Terms: A Thesaurus for Use in Rare Book and Special Collections Cataloging, 2d ed)."""

    PROGRAMMED_INSTRUCTION = 'Programmed Instruction'
    """Works consisting of sequenced self-correction texts."""

    PROSPECTUS = 'Prospectus'
    """Work consisting of advertisements separately printed and distributed by a publisher to describe and solicit 
    orders for a recent or forthcoming publication. In the case of books, they may include sample pages. 
    (From: ALA Glossary of Library and Information Science, 1983)."""

    PUBLIC_SERVICE_ANNOUNCEMENT = 'Public Service Announcement'
    """Work consisting of announcements which promote programs, activities, or services of federal, state, or local 
    governments or those of non-profit organizations and other announcements regarded as serving community interests.
    """

    PUBLICATION_COMPONENTS = 'Publication Components'
    """Specific parts of publications."""

    PUBLICATION_FORMATS = 'Publication Formats'
    """Specific genre of publication."""

    PUBLISHED_ERRATUM = 'Published Erratum'
    """Work consisting of an acknowledgment of an error, issued by a publisher, editor, or author. It customarily cites 
    the source where the error occurred, giving complete bibliographic data for retrieval. In the case of books and 
    monographs, author, title, imprint, paging, and other helpful references will be given; in the case of journal 
    articles, the author, title, paging, and journal reference will be shown. An erratum notice is variously cited as 
    Errata or Corrigenda."""

    RANDOMIZED_CONTROLLED_TRIAL = 'Randomized Controlled Trial'
    """A work that reports on a clinical trial that involves at least one test treatment and one control treatment, 
    concurrent enrollment and follow-up of the test- and control-treated groups, and in which the treatments to be 
    administered are selected by a random process, such as the use of a random-numbers table."""

    RANDOMIZED_CONTROLLED_TRIAL_VETERINARY = 'Randomized Controlled Trial, Veterinary'
    """A work that reports on a clinical trial with animal subjects that involves at least one test treatment and one 
    control treatment, concurrent enrollment and follow-up of the test- and control-treated groups, and in which the 
    treatments to be administered are selected by a random process, such as the use of a random-numbers table."""

    RESEARCH_SUPPORT_AMERICAN_RECOVERY_AND_REINVESTMENT_ACT = 'Research Support, American Recovery and Reinvestment Act'
    """Acknowledgement that funding support is from the American Recovery and Reinvestment Act."""

    RESEARCH_SUPPORT_NIH_EXTRAMURAL = 'Research Support, N.I.H., Extramural'
    """A designation for publications of research resulting from extramural research funded by the National Institutes 
    of Health."""

    RESEARCH_SUPPORT_NIH_INTRAMURAL = 'Research Support, N.I.H., Intramural'
    """A designation for publications of research resulting from intramural research at the National Institutes of 
    Health."""

    RESEARCH_SUPPORT_NON_US_GOVT = "Research Support, Non-U.S. Gov't"
    """Acknowledgement that funding support is from any non-US government agency, for example state and local 
    governments, foreign governments, and private organizations."""

    RESEARCH_SUPPORT_US_GOVT_NON_PHS = "Research Support, U.S. Gov't, Non-P.H.S."
    """Acknowledgment that funding support is from any US government agency other than the Public Health Service, such 
    as the National Science Foundation, NASA, Department of Energy, etc."""

    RESEARCH_SUPPORT_US_GOVT_PHS = "Research Support, U.S. Gov't, P.H.S."
    """Acknowledgement that funding support is from any component of the Public Health Service."""

    RESEARCH_SUPPORT_US_GOVERNMENT = 'Research Support, U.S. Government'
    """For publications noted as supported by US Government."""

    RESOURCE_GUIDE = 'Resource Guide'
    """Work listing and describing various sources of information, from multiple media or in different formats, on a 
    given subject."""

    RETRACTED_PUBLICATION = 'Retracted Publication'
    """Work consisting of the designation of an article or book as retracted in whole or in part by an author or 
    authors or an authorized representative. It identifies a citation previously published and now retracted through a 
    formal issuance from the author, publisher, or other authorized agent, and is distinguished from RETRACTION OF 
    PUBLICATION, which identifies the citation retracting the original published item."""

    RETRACTION_OF_PUBLICATION = 'Retraction of Publication'
    """Work consisting of a statement issued by one or more authors of an article or a book, withdrawing or disavowing 
    acknowledgment of their participation in performing research or writing the results of their study. In indexing, 
    the retraction is sent to the editor of the publication in which the article appeared and is published under the 
    rubric "retraction" or in the form of a letter. This publication type designates the author's statement of 
    retraction: it should be differentiated from RETRACTED PUBLICATION which labels the retracted publication."""

    REVIEW = 'Review'
    """An article or book published after examination of published material on a subject. It may be comprehensive to 
    various degrees and the time range of material scrutinized may be broad or narrow, but the reviews most often 
    desired are reviews of the current literature. The textual material examined may be equally broad and can 
    encompass, in medicine specifically, clinical material as well as experimental research or case reports. 
    State-of-the-art reviews tend to address more current matters. A review of the literature must be differentiated 
    from HISTORICAL ARTICLE on the same subject, but a review of historical literature is also within the scope of this 
    publication type."""

    SCIENTIFIC_INTEGRITY_REVIEW = 'Scientific Integrity Review'
    """Work consisting of reports by the United States Office of Research Integrity, identifying questionable research 
    published in articles or books. Notification of the questionable data is carried in the NIH Guide for Grants and 
    Contracts."""

    SERMON = 'Sermon'
    """Work consisting of discourses for the purpose of religious instruction or exhortation, especially one based on a 
    text of Scripture and delivered by a member of the clergy, as part of a religious service. (From: Random House 
    Unabridged Dictionary, 2d ed)."""

    STATISTICS = 'Statistics'
    """Works consisting of presentations of numerical data on particular subjects."""

    STURY_CHARACTERISTICS = 'Study Characteristics'
    """Type of empirical method used."""

    STUEY_GUIDE = 'Study Guide'
    """Tool used to help facilitate learning and comprehension of a topic or to help prepare for an examination."""

    SUPPORT_OF_RESEARCH = 'Support of Research'
    """Organizational source for funding of research activity."""

    SYSTEMATIC_REVIEW = 'Systematic Review'
    """A review of primary literature in health and health policy that attempts to identify, appraise, and synthesize 
    all the empirical evidence that meets specified eligibility criteria to answer a given research question.  Its 
    conduct uses explicit methods aimed at minimizing bias in order to produce more reliable findings regarding the 
    effects of interventions for prevention, treatment, and rehabilitation that can be used to inform decision making.
    """

    TABLES = 'Tables'
    """Presentations of data in tabular form."""

    TECHNICAL_REPORT = 'Technical Report'
    """Work consisting of a formal report giving details of the investigation and results of a medical or other 
    scientific problem. When issued by a government agency or comparable official body, its contents may be classified, 
    unclassified, or declassified with regard to security clearance. This publication type may also cover a scientific 
    paper or article that records the current state or current position of scientific research and development. If so 
    labeled by the editor or publisher, this publication type may be properly used for journal articles."""

    TERMINOLOGY = 'Terminology'
    """Work consisting of lists of the technical terms or expressions used in a specific field. These lists may or may 
    not be formally adopted or sanctioned by usage."""

    TEXTBOOK = 'Textbook'
    """Book intended for use in the study of specific subjects, containing systematic presentation of the principles 
    and essential knowledge of the subjects."""

    TWIN_STUDY = 'Twin Study'
    """Work consisting of reporting using a method of detecting genetic causes in human traits and genetic factors in 
    behavior using sets of twins."""

    UNEDITED_FOOTAGE = 'Unedited Footage'
    """Work consisting of untitled raw motion picture and video footage which has not been edited or assembled into a 
    finished work. (From: Moving Image Materials: Genre Terms, 1988)"""

    UNION_LIST = 'Union List'
    """Works consisting of records of the holdings or items owned by two or more libraries."""

    UNPUBLISHED_WORK = 'Unpublished Work'
    """Work that has not been formally published."""

    VALIDATION_STUDY = 'Validation Study'
    """Works consisting of research using processes by which the reliability and relevance of a procedure for a 
    specific purpose are established"""

    VIDEO_AUDIO_MEDIA = 'Video-Audio Media'
    """Used with articles which include video files or clips, or for articles which are entirely video."""

    WEB_ARCHIVE  = 'Web Archive'
    """Collection of preserved web pages."""

    WEBCAST = 'Webcast'
    """Content from transmission of live or pre-recorded audio or video via connection or download from the INTERNET."""

    WIT_AND_HUMOR = 'Wit and Humor'

    @staticmethod
    def parse(entry_type: str | list[str]):
        """Parses an entry type name into an enum value."""
        if isinstance(entry_type, list):
            return [MeshPublicationType.parse(v) for v in entry_type]
        for n in MeshPublicationType:
            if entry_type == n.value:
                return n
        raise ValueError(f'unknown {entry_type} type')

@dataclass(frozen=True)
class Tag:
    """A field tag."""
    auto: auto
    repeating: bool = False

@_cite(PUBMED_FORMAT)
class Tags(Tag, Enum):
    """
    Pubmed fields.
    """

    AB = auto()
    """Abstract 	

    English language abstract taken directly from the published article"""

    AD = auto()
    """Affiliation

    Author or corporate author addresses"""

    AID = auto()
    """Article Identifier

    Article ID values supplied by the publisher may include the pii (controlled publisher identifier), doi (digital 
    object identifier), or book accession"""

    AU = (auto(), True)
    """Author

    Authors"""

    AUID = auto()
    """Author Identifier

    Unique identifier associated with an author, corporate author, or investigator name"""

    BTI = auto()
    """Book Title

    Book Title"""

    CI = auto()
    """Copyright Information

    Copyright statement provided by the publisher"""

    CIN = auto()
    """Comment In

    Reference containing a comment about the article"""

    CN = auto()
    """Corporate Author

    Corporate author or group names with authorship responsibility"""

    COI = auto()
    """Conflict of Interest

    Conflict of interest statement"""

    CON = auto()
    """Comment On

    Reference upon which the article comments"""

    CP = auto()
    """Chapter

    Book chapter"""

    CRDT = auto()
    """Create Date

    The date the citation record was first created"""

    CRF = auto()
    """Corrected and republished from

    Final, correct version of an article"""

    CRI = auto()
    """Corrected and republished in

    Original article that was republished in corrected form"""

    CTDT = auto()
    """Contribution Date

    Book contribution date"""

    CTI = auto()
    """Collection Title

    Collection Title"""

    DCOM = auto()
    """Completion Date

    NLM internal processing completion date"""

    DDIN = auto()
    """Dataset described in

    Citation for the primary article resulting from a dataset"""

    DRIN = auto()
    """Dataset use reported in

    Citation for an article that uses a dataset from another scientific article"""

    DEP = auto()
    """Date of Electronic Publication

    Electronic publication date"""

    DP = auto()
    """Publication Date

    The date the article was published"""

    DRDT = auto()
    """Date Revised

    Book Revision Date"""

    ECF = auto()
    """Expression of Concern For

    Reference containing an expression of concern for an article"""

    ECI = auto()
    """Expression of Concern In

    Cites the original article for which there is an expression of concern"""

    EDAT = auto()
    """Entry Date

    The date the citation was added to PubMed; the date is set to the publication date if added more than 1 year after 
    the date published"""

    EFR = auto()
    """Erratum For

    Cites the original article for which there is a published erratum; as of 2016, partial retractions are considered 
    errata """

    EIN = auto()
    """Erratum In

    Cites a published erratum to the article"""

    ED = auto()
    """Editor

    Book editors"""

    EN = auto()
    """Edition

    Book edition"""

    FAU = auto()
    """Full Author Name

    Full author names"""

    FED = auto()
    """Full Editor Name

    Full editor names"""

    FIR = auto()
    """Full Investigator Name

    Full investigator or collaborator names"""

    FPS = auto()
    """Full Personal Name as Subject

    Full Personal Name of the subject of the article"""

    GN = auto()
    """General Note

    Supplemental or descriptive information related to the document"""

    GR = auto()
    """Grants and Funding

    Grant numbers, contract numbers, and intramural research identifiers associated with a publication"""

    GS = auto()
    """Gene Symbol

    Abbreviated gene names (used 1991 through 1996)"""

    IP = auto()
    """Issue

    The number of the issue, part, or supplement of the journal in which the article was published"""

    IR = auto()
    """Investigator

    Investigator or collaborator"""

    IRAD = auto()
    """Investigator Affiliation

    Investigator or collaborator addresses"""

    IS = auto()
    """ISSN

    International Standard Serial Number of the journal"""

    ISBN = auto()
    """ISBN

    International Standard Book Number"""

    JID = auto()
    """NLM Unique ID

    Unique journal ID in the NLM catalog of books, journals, and audiovisuals"""

    JT = auto()
    """Full Journal Title

    Full journal title from NLM cataloging data"""

    LA = auto()
    """Language

    The language in which the article was published"""

    LID = auto()
    """Location ID

    The pii or doi that serves the role of pagination"""

    LR = auto()
    """Modification Date

    Citation last revision date"""

    MH = (auto(), True)
    """MeSH Terms

    NLM Medical Subject Headings (MeSH) controlled vocabulary"""

    MHDA = auto()
    """MeSH Date

    The date MeSH terms were added to the citation. The MeSH date is the same as the Entrez date until MeSH are added"""

    MID = auto()
    """Manuscript Identifier

    Identifier assigned to an author manuscript submitted to the NIH Manuscript Submission System"""

    NM = auto()
    """Substance Name

    Supplementary Concept Record (SCR) data"""

    OAB = auto()
    """Other Abstract

    Abstract supplied by an NLM collaborating organization"""

    OABL = auto()
    """Other Abstract Language

    Language of an abstract available from the publisher"""

    OCI = auto()
    """Other Copyright Information

    Copyright owner"""

    OID = auto()
    """Other ID

    Identification numbers provided by organizations supplying citation data"""

    ORI = auto()
    """Original Report In

    Cites the original article associated with the patient summary"""

    OT = auto()
    """Other Term

    Non-MeSH subject terms (keywords) either assigned by an organization identified by the Other Term Owner, or 
    generated by the author and submitted by the publisher"""

    OTO = auto()
    """Other Term Owner

    Organization that may have provided the Other Term data"""

    OWN = auto()
    """Owner

    Organization acronym that supplied citation data"""

    PB = auto()
    """Publisher

    Publishers of Books & Documents citations"""

    PG = auto()
    """Pagination

    The full pagination of the article"""

    PHST = auto()
    """Publication History Status Date

    Publisher supplied dates regarding the article publishing process and PubMed date stamps:

        received: manuscript received for review
        revised: manuscript revised by publisher or author
        accepted: manuscript accepted for publication
        aheadofprint: published electronically prior to final publication
        entrez: PubMed Create Date [crdt]
        pubmed: PubMed Entry Date [edat]
        medline: PubMed MeSH Date [mhda]"""

    PL = auto()
    """Place of Publication

    Journal's (country only) or book’s place of publication"""

    PMC = auto()
    """PubMed Central Identifier

    Unique identifier for the cited article in PubMed Central (PMC)"""

    PMCR = auto()
    """PMC Release

    Availability of PMC article"""

    PMID = auto()
    """PubMed Unique Identifier

    Unique number assigned to each PubMed citation"""

    PS = auto()
    """Personal Name as Subject

    Individual is the subject of the article"""

    PST = auto()
    """Publication Status

    Publication status"""

    PT = (auto(), True) #  seems to be repeatable as seen in downloaded examples on the internet
    """Publication Type

    The type of material the article represents"""

    RF = auto()
    """Number of References

    Number of bibliographic references for Review articles"""

    RIN = auto()
    """Retraction In

    Retraction of the article"""

    RN = (auto(), True)
    """EC/RN Number

    Includes chemical, protocol or disease terms. May also include a number assigned by the Enzyme Commission or by the 
    Chemical Abstracts Service."""

    ROF = auto()
    """Retraction Of

    Article being retracted"""

    RPF = auto()
    """Republished From

    Article being cited has been republished or reprinted in either full or abridged form from another source"""

    RPI = auto()
    """Republished In

    Article being cited also appears in another source in either full or abridged form"""

    RRI = auto()
    """Retracted and Republished In

    Final, republished version of an article"""

    RRF = auto()
    """Retracted and Republished From

    Original article that was retracted and republished"""

    SB = auto()
    """Subset

    Journal or citation subset values representing specialized topics"""

    SFM = auto()
    """Space Flight Mission

    NASA-supplied data space flight/mission name and/or number"""

    SI = auto()
    """Secondary Source ID

    Identifies secondary source databanks and accession numbers of molecular sequences discussed in articles"""

    SO = auto()
    """Source

    Composite field containing bibliographic information"""

    SPIN = auto()
    """Summary For Patients In

    Cites a patient summary article"""

    STAT = auto()
    """Status Tag

    Used for internal processing at NLM"""

    TA = auto()
    """Journal Title Abbreviation

    Standard journal title abbreviation"""

    TI = auto()
    """Title

    The title of the article"""

    TT = auto()
    """Transliterated Title

    Title of the article originally published in a non-English language, in that language"""

    UIN = auto()
    """Update In

    Update to the article"""

    UOF = auto()
    """Update Of

    The article being updated"""

    VI = auto()
    """Volume

    Volume number of the journal"""

    VTI = auto()
    """Volume Title

Book Volume Title"""

    @staticmethod
    def parse(tag_str: str):
        """Parses a tag name into an enum value."""
        for n in Tags:
            if tag_str == n.name:
                return n
        raise ValueError(f'unknown {tag_str} tag')

class DefaultCitationRenderer(CitationRenderer):
    """Default citation renderer allowing to define and override a specific rendering by format."""

    def __init__(self, prefix: str, itemize: str):
        self._prefix = prefix
        self._itemize = itemize

    def format(self, refs: list) -> str:

        if len(refs) == 1:
            return f"\n\n{self._prefix} {self._by_type(refs[0])}\n"

        result = f"\n\n{self._prefix}\n\n"
        for r in refs:
            result += f"{self._itemize} {self._by_type(r)}\n"
        return result

    def _by_type(self, r):
        if isinstance(r, BibtexReference):
            return self.bibtex(r)

        if isinstance(r, dict):
            if Ris2001.TY in r:
                return self.ris2001(r)
            if Ris2011.TY in r:
                return self.ris2011(r)
            if Refer.L in r:
                return self.refer(r)
            if Endnote.A in r or Endnote.T in r:
                return self.endnote(r)
            if Pubmed.PT in r:
                return self.pubmed(r)

        raise ValueError('unexpected reference type')

    def bibtex(self, r: BibtexReference):
        """Bibtex reference formatter."""
        return default_bibtex_formatter(r)

    def ris2001(self, r: dict[Ris2001, str | list[str] | Ris2001Field]):
        """RIS 2001 reference formatter."""
        return default_ris2001_formatter(r)

    def ris2011(self, r: dict[Ris2011, str | list[str] | Ris2011Field]):
        """RIS 2011 reference formatter."""
        return default_ris2011_formatter(r)

    def refer(self, r: dict[Refer, str | list[str]]):
        """refer reference formatter."""
        return default_refer_formatter(r)

    def endnote(self, r: dict[Endnote, str | list[str]]):
        """endnote reference formatter."""
        return default_endnote_formatter(r)

    def pubmed(self, r: dict[Endnote, str | list[str]]):
        """pubmed reference formatter."""
        return default_pubmed_formatter(r)