path: root/Master/texmf-dist/tex/latex/biblatex-apa6/apa6.cbx

%% Copyright 2019 Philip Kime
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
%%   http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%% 
%% The Current Maintainer of this work is Philip Kime.

\ProvidesFile{apa6.cbx}[2019/09/07\space v8.0\space APA 6th ed. biblatex citation style]
\RequireBiber[3]

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.16) labelyear postfix is not emphasised or italic
%            Dashes between labelyear and non-numeric year (or pseudo-year)

\DeclareFieldFormat{extradate}{\iffieldnums{labelyear}{\mknumalph{#1}}{\apashortdash\mknumalph{#1}}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.11) requires comma separator between authors and years

\DeclareDelimFormat{nameyeardelim}{\addcomma\space}
\DeclareDelimFormat[textcite]{nameyeardelim}{\addcomma\space}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.12) No comma before "et al" if there is only one name
%            preceding it

\DeclareDelimFormat{andothersdelim}{\ifnum\value{listcount}>2 \finalandcomma\fi\addspace}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.12) ampersand separator in parenthetical cites

\DeclareDelimFormat[parencite]{finalnamedelim}
  {\ifnum\value{liststop}>2 \finalandcomma\fi\addspace\&\space}

\DeclareCiteCommand{\parencite}[\mkbibparens]
  {\usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \usebibmacro{cite}%
   \usebibmacro{cite:post}}
  {}
  {\usebibmacro{postnote}}

\DeclareCiteCommand*{\parencite}[\mkbibparens]
  {\usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \usebibmacro{citeyear}%
   \usebibmacro{cite:post}}
  {}
  {\usebibmacro{postnote}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.11) Suffices are not shown in citations
% (APA 6.12) 3-5 authors have "et al." after first cite
% (Blog https://blog.apastyle.org/apastyle/2014/01/when-to-use-author-initials-for-text-citations.html) Initials only for primary author and only when not unique across all *primary* authors

\newbibmacro*{labelname:doname}[8]{%
  \ifboolexpr{test {\ifnumcomp{\value{listcount}}{>}{1}}
              or
              test {\ifuniqueprimaryauthor}}
    {\setcounter{uniquename}{0}}
    {}%
  \ifcase\value{uniquename}%
    \ifuseprefix
      {\usebibmacro{name:family}{#1}{#3}{#5}{\relax}}
      {\usebibmacro{name:family}{#1}{#3}{\relax}{\relax}}%
  \or
     \ifuseprefix
       {\usebibmacro{name:given-family}{#1}{#4}{#5}{\relax}}
       {\usebibmacro{name:given-family}{#1}{#4}{\relax}{\relax}}%
  \or
     \ifuseprefix
       {\usebibmacro{name:given-family}{#1}{#3}{#5}{\relax}}
       {\usebibmacro{name:given-family}{#1}{#3}{\relax}{\relax}}%
  \fi
  \usebibmacro{name:andothers}}

% Can't do this with the built-in printnames format as APA requires truncation
% and disambiguation only after first cite
% We either use uniquelist or minnames for truncation. If uniquelist isn't
% defined, we fall back on minnames
%
% \printnames does different things depending on whether the format you are
% calling is the default for the name field or is a custom format:
%
% max/minnames truncation is done before calling the format so we have
% to do \printnames[format][-\value{listtotal}]{field} to ensure we get
% all of the names in the list to work on here
%
% Explicit "and others" is dealt with in labelname:doname via a custom name:andothers

\DeclareNameFormat{labelname}{%
  % First set the truncation point
  \ifthenelse{\value{uniquelist}>1}
    {\numdef\cbx@min{\value{uniquelist}}}
    {\numdef\cbx@min{\value{minnames}}}%
  % Always print the first name and the second if there are only two since
  % "et al" must always be plural
  \ifboolexpr{test {\ifnumcomp{\value{listcount}}{=}{1}}
              or test {\ifnumcomp{\value{listtotal}}{=}{2}}}
    {\usebibmacro{labelname:doname}%
      {\namepartfamily}%
      {\namepartfamilyi}%
      {\namepartgiven}%
      {\namepartgiveni}%
      {\namepartprefix}%
      {\namepartprefixi}%
      {\namepartsuffix}%
      {\namepartsuffixi}}
    % We are looking at name >=3
    % If the list is 6 or more names or we have seen citation before, potential truncation
    {\ifboolexpr{test {\ifnumcomp{\value{listtotal}}{>}{5}}
                 or test {\ifciteseen}}
     % Less than the truncation point, print normally
     {\ifnumcomp{\value{listcount}}{<}{\cbx@min + 1}
       {\usebibmacro{labelname:doname}%
         {\namepartfamily}%
         {\namepartfamilyi}%
         {\namepartgiven}%
         {\namepartgiveni}%
         {\namepartprefix}%
         {\namepartprefixi}%
         {\namepartsuffix}%
         {\namepartsuffixi}}
       {}%
      % At potential truncation point ...
      \ifnumcomp{\value{listcount}}{=}{\cbx@min + 1}
        % but enforce plurality of et al - only truncate here if there is at
        % least one more element after the current potential truncation point
        % so that "et al" covers at least two elements.
        {\ifnumcomp{\value{listcount}}{<}{\value{listtotal}}
          {\printdelim{andothersdelim}\bibstring{andothers}}
          {\usebibmacro{labelname:doname}%
            {\namepartfamily}%
            {\namepartfamilyi}%
            {\namepartgiven}%
            {\namepartgiveni}%
            {\namepartprefix}%
            {\namepartprefixi}%
            {\namepartsuffix}%
            {\namepartsuffixi}}}
        {}%
      % After truncation point, do not print name
      \ifnumcomp{\value{listcount}}{>}{\cbx@min + 1}
       {\relax}%
       {}}%
     % We are looking at name >=3
     % Name list is < 6 names or we haven't seen this citation before, print normally
     {\usebibmacro{labelname:doname}%
       {\namepartfamily}%
       {\namepartfamilyi}%
       {\namepartgiven}%
       {\namepartgiveni}%
       {\namepartprefix}%
       {\namepartprefixi}%
       {\namepartsuffix}%
       {\namepartsuffixi}}}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.13) Groups as names
%            SHORTAUTHOR brackets in parencites

\DeclareNameFormat{sabrackets}{%
  \mkbibbrackets{%
    \usebibmacro{labelname:doname}%
      {\namepartfamily}%
      {\namepartfamilyi}%
      {\namepartgiven}%
      {\namepartgiveni}%
      {\namepartprefix}%
      {\namepartprefixi}%
      {\namepartsuffix}%
      {\namepartsuffixi}}}

\DeclareFieldFormat{shorthand}{\ifciteseen
                                {#1}
                                {\mkbibbrackets{#1}}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.13) Deal with SHORTAUTHOR fields
% (APA 6.16) Multiple same author cites in a compact citation call do not
%            need to be repeated but the full years must be repeated with
%            their extradate postfixes
% (APA 6.18) Cite ORIGYEAR/YEAR if ORIGYEAR present
% (APA 6.28) ISSUE after year when available
\def\citeresetapa{\global\let\cbx@apa@names\@empty}
\citeresetapa
\def\cbx@apa@ifnamesaved{%
  \xifinlist{\thefield{fullhash}}{\cbx@apa@names}
    {\@firstoftwo}
    {\@secondoftwo}}

\newbibmacro*{cite:author}{%
  \iffieldequals{fullhash}{\cbx@lasthash}
% Multiple cites in one command
   {\setunit{\compcitedelim}%
    \usebibmacro{cite:plabelyear+extradate}}%
% Single cite
   {\ifthenelse{\ifnameundef{labelname}\OR\iffieldequalstr{entrytype}{patent}}
% No author/editor
     {\usebibmacro{cite:noname}%
       \savefield{fullhash}{\cbx@lasthash}}
% Normal cite
     {\ifnameundef{shortauthor}
        {\printnames[labelname][-\value{listtotal}]{labelname}}%
        {\cbx@apa@ifnamesaved
          {\printnames{shortauthor}}
          {\printnames[labelname][-\value{listtotal}]{author}\addspace\printnames[sabrackets]{shortauthor}}}%
      \savefield{fullhash}{\cbx@lasthash}}}%
   \setunit{\multicitedelim}}

% Using fullhash instead of namehash otherwise we may omit namelist for
% lists which are equal only because of minnames truncation i.e:
%
% X and Y and Z (2009)
% X and W and V (2010)
%
% which have the same namehash due to minnames visibility truncation to 1 
% would be printed incorrectly as
% \cite{one, two} -> X, Y & Z 2009, 2010
\newbibmacro*{cite}{%
  \iffieldequals{fullhash}{\cbx@lasthash}
% Multiple cites in one command
   {\setunit{\compcitedelim}%
    \usebibmacro{cite:plabelyear+extradate}}%
% Single cite
   {\ifthenelse{\ifnameundef{labelname}\OR\iffieldequalstr{entrytype}{patent}}
% No author/editor
     {\usebibmacro{cite:noname}%
       \setunit{\printdelim{nameyeardelim}}%
       \usebibmacro{cite:plabelyear+extradate}%
       \savefield{fullhash}{\cbx@lasthash}}
% Normal cite
     {\ifnameundef{shortauthor}
        {\printnames[labelname][-\value{listtotal}]{labelname}}%
        {\cbx@apa@ifnamesaved
          {\printnames{shortauthor}}
          {\printnames[labelname][-\value{listtotal}]{author}\addspace\printnames[sabrackets]{shortauthor}}}%
      \setunit{\printdelim{nameyeardelim}}%
      \usebibmacro{cite:plabelyear+extradate}%
      \savefield{fullhash}{\cbx@lasthash}}}%
   \setunit{\multicitedelim}}

\newbibmacro*{textcite}{%
  \iffieldequals{fullhash}{\cbx@lasthash}
% Compact cite - more than one thing for same author
    {\setunit{\compcitedelim}%
     \usebibmacro{cite:plabelyear+extradate}}
% New cite
    {%
    \ifbool{cbx:parens}
      {\bibcloseparen\global\boolfalse{cbx:parens}}
      {}%
      \setunit{\compcitedelim}%
      \ifthenelse{\ifnameundef{labelname}\OR\iffieldequalstr{entrytype}{patent}}
  % No author/editor or patent
       {\iffieldundef{shorthand}%
    % Cite using title
         {\usebibmacro{cite:noname}%
          \setunit{\ifbool{cbx:np}%
                   {\printdelim{nameyeardelim}}%
                   {\global\booltrue{cbx:parens}\addspace\bibopenparen}}%
          \usebibmacro{cite:plabelyear+extradate}}
    % Cite using shorthand
         {\usebibmacro{cite:shorthand}}}
  % Normal cite with author/editor
  % Normal full cite
       {\ifnameundef{shortauthor}%
    % Normal full cite
         {\printnames[labelname][-\value{listtotal}]{labelname}}
    % Cite using short author
         {\cbx@apa@ifnamesaved
           {\printnames{shortauthor}}
           {\printnames[labelname][-\value{listtotal}]{author}}}%
  % Year
        \setunit{\ifbool{cbx:np}
                  {\printdelim{nameyeardelim}}
                  {\global\booltrue{cbx:parens}\addspace\bibopenparen}}%
  % Put the shortauthor inside the year brackets if necessary
        \ifnameundef{shortauthor}
         {}
         {\cbx@apa@ifnamesaved
           {}
           {\printnames{shortauthor}\setunit{\printdelim{nameyeardelim}}}}%
  % Actual year printing
        \usebibmacro{cite:plabelyear+extradate}%
  % Save name hash for checks later
        \savefield{fullhash}{\cbx@lasthash}}}}

\newbibmacro*{cite:plabelyear+extradate}{%
  \iffieldundef{labelyear}{}
    {\printtext[bibhyperref]{%
        \clearfield{labelmonth}% don't want months in citations
        \clearfield{labelday}% don't want days in citations
        \clearfield{labelendmonth}% don't want months in citations
        \clearfield{labelendday}% don't want days in citations
        \iffieldsequal{labelyear}{labelendyear}% Don't want no-op year ranges
          {\clearfield{labelendyear}}
          {}%
        \iffieldundef{origyear}{}
          {\ifboolexpr{ test {\iforigdatecirca} or test {\iforigdateuncertain} }
            {\mkbibbrackets{\printorigdate}}
            {\printorigdate}%
           \setunit*{\addslash}}%
       \ifboolexpr{ test {\iflabeldatecirca} or test {\iflabeldateuncertain} }
         {\mkbibbrackets{\printlabeldateextra}}
         {\printlabeldateextra}}}%
  \iffieldundef{issue}
    {}
    {\addcomma\addspace\printfield{issue}}}

\newbibmacro*{cite:shorthand}{%
  \ifciteseen
    {\printfield{shorthand}}
    {\printnames[labelname][-\value{listtotal}]{labelname}%
     \setunit{\printdelim{nameyeardelim}}%
     \printfield{title}\space\printfield{shorthand}}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.15) Fall back to title for citations without authors

\DeclareFieldFormat{citetitle}{\mkbibquote{#1}}
\DeclareFieldFormat[online]{citetitle}{\mkbibquote{#1}}
\DeclareFieldFormat[inbook]{citetitle}{\mkbibquote{#1}}
\DeclareFieldFormat[book]{citetitle}{\mkbibemph{#1}}
\DeclareFieldFormat[report]{citetitle}{\mkbibemph{#1}}
\DeclareFieldFormat[periodical]{citetitle}{\mkbibemph{#1}}
\DeclareFieldFormat[patent]{citetitle}{#1}

\newbibmacro*{cite:noname}{%
    \printfield[citetitle]{labeltitle}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% (APA 6.21) No parens round year for cites when the cite is in
%            parentheses. Use new command \nptextcite for such cites.

\DeclareDelimFormat[nptextcite]{finalnamedelim}
  {\ifnum\value{liststop}>2 \finalandcomma\fi\addspace\&\space}

\DeclareMultiCiteCommand{\nptextcites}{\nptextcite}{\multicitedelim}
\DeclareCiteCommand{\nptextcite}
  {\usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \global\booltrue{cbx:np}%
   \usebibmacro{textcite}%
   \usebibmacro{cite:post}%
   \global\boolfalse{cbx:np}}%
  {}
  {\iffieldundef{postnote}
     {}
     {\printdelim{nameyeardelim}%
      \printfield{postnote}}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% No shorthand
% 
\newbibmacro*{citeyear}{%
  \iffieldundef{labelyear}
    {\usebibmacro{cite:init}}
    {\iffieldequals{fullhash}{\cbx@lasthash}
       {\setunit{\compcitedelim}%
        \usebibmacro{cite:plabelyear+extradate}}
       {\usebibmacro{cite:plabelyear+extradate}%
        \savefield{fullhash}{\cbx@lasthash}}}%
  \setunit{\multicitedelim}}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Fullcite should use "&"
% Also need to reset the global booleans which are normally done at
% every bib item but since these aren't bib items, they are not reset

\DeclareDelimFormat[fullcite,fullcitebib]{finalnamedelim}
   {\ifnum\value{liststop}>2 \finalandcomma\fi\addspace\&\space}

\DeclareCiteCommand{\fullcite}
  {\usebibmacro{prenote}}
  {\usedriver
    {\DeclareNameAlias{sortname}{default}%
      \global\boolfalse{bbx:parens}%
      \global\boolfalse{bbx:volseen}%
      \global\boolfalse{bbx:titleinauthpos}%
      \global\boolfalse{bbx:editorinauthpos}%
      \global\boolfalse{bbx:in}%
      \global\let\blx@related@loop\@empty}
    {\thefield{entrytype}}%
   \usebibmacro{cite:post}}
  {\multicitedelim}
  {\usebibmacro{postnote}}

\DeclareCiteCommand{\fullcitebib}
  {\list{}
   {\setlength{\leftmargin}{\bibhang}%
     \setlength{\itemindent}{-\leftmargin}%
     \setlength{\itemsep}{\bibitemsep}%
     \setlength{\parsep}{\bibparsep}}\item}
  {\usedriver
    {\DeclareNameAlias{sortname}{default}%
      \global\boolfalse{bbx:parens}%
      \global\boolfalse{bbx:volseen}%
      \global\boolfalse{bbx:titleinauthpos}%
      \global\boolfalse{bbx:editorinauthpos}%
      \global\boolfalse{bbx:in}}
    {\thefield{entrytype}}%
   \finentry
   \usebibmacro{cite:post}}
  {\item}
  {\endlist}

%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\newbool{cbx:parens} % boolean to say we're inside parens
\newbool{cbx:np} % boolean to say we're using a non-parentheses text cite

\newbibmacro*{textcite:postnote}{%
  \usebibmacro{postnote}%
  \ifbool{cbx:parens}
    {\bibcloseparen\global\boolfalse{cbx:parens}}
    {}}

\newbibmacro*{cite:init}{%
  \global\boolfalse{cbx:parens}%
  \global\undef\cbx@lasthash}

\newbibmacro*{cite:post}{%
  \xifinlist{\thefield{fullhash}}{\cbx@apa@names}
    {}
    {\listxadd{\cbx@apa@names}{\thefield{fullhash}}}}

\newbibmacro*{cite:labelyear}{%
  \printfield{labelyear}}

\newbibmacro*{cite:extradate}{%
  \printfield{extradate}}

\newbibmacro*{cite:labelyear+extradate}{%
  \iffieldundef{labelyear}
    {}
    {\printfield{labelyear}%
       \printfield{extradate}}}

\DeclareCiteCommand{\citeyear}
  {\boolfalse{citetracker}%
   \boolfalse{pagetracker}%
   \usebibmacro{prenote}}
  {\usebibmacro{cite:plabelyear+extradate}}
  {\multinamedelim}
  {\usebibmacro{postnote}}

\DeclareCiteCommand{\cite}
  {\usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \usebibmacro{cite}%
   \usebibmacro{cite:post}}
  {}
  {\usebibmacro{postnote}}

\DeclareCiteCommand*{\cite}
  {\usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \usebibmacro{citeyear}%
   \usebibmacro{cite:post}}
  {}
  {\usebibmacro{postnote}}

\DeclareCiteCommand{\footcite}[\mkbibfootnote]
  {\bibsentence
   \usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \usebibmacro{cite}%
   \usebibmacro{cite:post}}
  {}
  {\usebibmacro{postnote}}

\DeclareMultiCiteCommand{\textcites}{\textcite}{\compcitedelim}

\DeclareCiteCommand{\textcite}
  {\usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \usebibmacro{textcite}%
   \usebibmacro{cite:post}}
  {}
  {\usebibmacro{textcite:postnote}}

\DeclareCiteCommand{\citeauthor}
  {\usebibmacro{cite:init}%
   \usebibmacro{prenote}}
  {\usebibmacro{citeindex}%
   \usebibmacro{cite:author}%
   \usebibmacro{cite:post}}
  {}
  {\usebibmacro{postnote}}

\endinput