API

@_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)
    @staticmethod
    def to_source_symbol(cite_key: str) -> str:
        """Produces a Python symbol for the reference."""
        return cite_key.upper()

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

        base = f"{BibtexReference.to_source_symbol(self.cite_key)} = {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}={BibtexReference.to_source_symbol(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')