NameTools.php

<?php

declare(strict_types=1);

require_once 'constants.php';    // @codeCoverageIgnore

/* junior_test - tests a name for a Junior appellation
 * Input: $name - the name to be tested
 * Output: array ($name without Jr, if $name ends in Jr, Jr)
 */

/** @return array<string> */
function junior_test(string $name): array {
  $junior = substr($name, -3) === " Jr" ?" Jr" : "";
  if ($junior) {
    $name = substr($name, 0, -3);
  } else {
    $junior = substr($name, -4) === " Jr." ? " Jr." : "";
    if ($junior) {
      $name = substr($name, 0, -4);
    }
  }
  if (substr($name, -1) === ",") {
    $name = substr($name, 0, -1);
  }
  return [$name, $junior];
}

/** @return array<string> */
function split_author(string $value): array {
  if (substr_count($value, ',') !== 1) {
    return [];
  }
  return explode(',', $value, 2);
}

function clean_up_full_names(string $value): string {
  $value = trim($value);
  $value = str_replace([",;", " and;", " and ", " ;", "  ", "+", "*"], [";", ";", " and ", ";", " ", "", ""], $value);
  $value = trim(straighten_quotes($value, true));
  if (mb_substr($value, -1) === '.') { // Do not lose last period
    $value = sanitize_string($value) . '.';
  } else {
    $value = sanitize_string($value);
  }
  return $value;
}

function clean_up_last_names(string $value): string {
  $value = trim($value);
  $value = str_replace([",;", " and;", " and ", " ;", "  ", "+", "*"], [";", ";", " ", ";", " ", "", ""], $value);
  $value = trim(straighten_quotes($value, true));
  if (mb_substr($value, -1) === '.') { // Do not lose last period
    $value = sanitize_string($value) . '.';
  } else {
    $value = sanitize_string($value);
  }
  $value = str_replace('..', '.', $value);
  return $value;
}

function clean_up_first_names(string $value): string {
  $value = trim($value);
  $value = str_replace([",;", " and;", " and ", " ;", "  ", "+", "*"], [";", ";", " ", ";", " ", "", ""], $value);
  $value = trim(straighten_quotes($value, true));
  if (mb_substr($value, -1) === '.') { // Do not lose last period
    $value = sanitize_string($value) . '.';
  } else {
    $value = sanitize_string($value);
  }
  if (mb_strlen($value) === 1) {
    $value .= '.';
  } elseif (mb_substr($value, -2, 1) === " ") {
    if (mb_strlen($value) === 3) { // Special case for "F M" -- add dots to both
      $value = mb_substr($value, 0, 1) . '. ' . mb_substr($value, -1, 1) . '.';
    } elseif (mb_strlen($value) > 3) { // Single character at end
       $value .= '.';
    }
  }
  return $value;
}

function format_surname(string $surname): string {
  $surname = trim($surname);
  if ($surname === '-') {
    return '';
  }
  if ($surname === '') {
    return '';
  }
  if (preg_match('~^\S\.?$~u', $surname)) {
    return mb_strtoupper($surname); // Just a single initial, with or without period
  }
  $surname = mb_convert_case(trim(mb_ereg_replace("-", " - ", $surname)), MB_CASE_LOWER);
  if (mb_substr($surname, 0, 2) === "o'") {
    return "O'" . format_surname_2(mb_substr($surname, 2));
  } elseif (mb_substr($surname, 0, 2) === "mc") {
    return "Mc" . format_surname_2(mb_substr($surname, 2));
  } elseif (mb_substr($surname, 0, 3) === "mac" && strlen($surname) > 5 && !mb_strpos($surname, "-") && mb_substr($surname, 3, 1) !== "h") {
    return "Mac" . format_surname_2(mb_substr($surname, 3));
  } elseif (mb_substr($surname, 0, 1) === "&") {
    return "&" . format_surname_2(mb_substr($surname, 1));
  } else {
    return format_surname_2($surname); // Case of surname
  }
}

function format_surname_2(string $surname): string {
  $ret = mb_ereg_replace(" - ", "-", $surname);
  $ret = preg_replace_callback("~(\p{L})(\p{L}+)~u",
    static function(array $matches): string {
        return mb_strtoupper($matches[1]) . mb_strtolower($matches[2]);
    },
    $ret);
  $ret = str_ireplace(['Von ', 'Und ', 'De La '], ['von ', 'und ', 'de la '], $ret);
  $ret = preg_replace_callback('~;\w~',
    static function(array $matches): string {
      return mb_strtolower($matches[0]);
     },
     $ret);
  return $ret;
}

function format_forename(string $forename): string {
  $forename = trim($forename);
  if ($forename === '-') {
    return '';
  }
  if ($forename === '') {
    return '';
  }
  return str_replace([" ."], "", trim(preg_replace_callback("~(\p{L})(\p{L}{3,})~u",
      static function(
        array $matches): string {
        return mb_strtoupper($matches[1]) . mb_strtolower($matches[2]);}
     , $forename)));
}

/* format_initials
 * Returns a string of initials
 *
 * $str: A series of initials, in any format.  NOTE! Do not pass a forename here!
 *
 */
function format_initials(string $str): string {
  $str = trim($str);
    if ($str === "") {
      return "";
    }
    $end = substr($str, strlen($str)-1) === ";" ? ";" : '';
    preg_match_all("~\w~u", $str, $match);
    return mb_strtoupper(implode(".",$match[0]) . ".") . $end;
}

function is_initials(string $str): bool {
    $str = trim($str);
    if (!$str) {
      return false;
    }
    if (strlen(str_replace(["-", ".", ";"], "", $str)) > 3) {
      return false;
    }
    if (strlen(str_replace(["-", ".", ";"], "", $str)) === 1) {
      return true;
    }
    if (mb_strtoupper($str) !== $str) {
      return false;
    }
    return true;
}

/*
 * author_is_human
 * Runs some tests to see if the full name of a single author is unlikely to be the name of a person.
 */
function author_is_human(string $author): bool {
  $author = trim($author);
  $chars = count_chars($author);
  if ($chars[ord(":")] > 0 || $chars[ord(" ")] > 3 || strlen($author) > 33
    || substr(strtolower($author), 0, 4) === "the "
    || (str_ireplace(NON_HUMAN_AUTHORS, '', $author) !== $author)  // This is the use a replace to see if a substring is present trick
    || preg_match("~[A-Z]{3}~", $author)
    || substr(strtolower($author),-4) === " inc"
    || substr(strtolower($author),-5) === " inc."
    || substr(strtolower($author),-4) === " llc"
    || substr(strtolower($author),-5) === " llc."
    || substr(strtolower($author),-5) === " book"
    || substr(strtolower($author),-6) === " books"
    || substr_count($author, ' ') > 3 // Even if human, hard to format
  ) {
    return false;
  }
  return true;
}

// Returns the author's name formatted as Surname, F.I.
function format_author(string $author): string {

  // Requires an author who is formatted as SURNAME, FORENAME or SURNAME FORENAME or FORENAME SURNAME. Substitute initials for forenames if needed
  $surname = '';
  // Google and Zotero sometimes have these (sir) and just sir
  $author = preg_replace("~ ?\((?i)sir(?-i)\.?\)~", "", html_entity_decode($author, ENT_COMPAT | ENT_HTML401, 'UTF-8'));
  $author = preg_replace("~^( ?sir )~", "", $author);
  $author = preg_replace("~^(, sir )~", ", ", $author);

  $ends_with_period = (substr(trim($author), -1) === ".");

  $author = preg_replace("~(^[;,.\s]+|[;,.\s]+$)~", "", trim($author)); //Housekeeping
  $author = preg_replace("~^[aA]nd ~", "", trim($author)); // Just in case it has been split from a Smith; Jones; and Western
  if ($author === "") {
      return "";
  }

  $auth = explode(",", $author);
  if (isset($auth[1])) {
    /* Possibilities:
    Smith, A. B.
    */
    $surname = $auth[0];
    $fore = $auth[1];
  } else { //Otherwise we've got no handy comma to separate; we'll have to use spaces and periods.
    $auth = explode(".", $author);
    if (isset($auth[1])){
      /* Possibilities are:
      M.A. Smith
      Smith M.A.
      Smith MA.
      Martin A. Smith
      MA Smith.
      Martin Smith.
      */
      $countAuth = count($auth);
      if ($ends_with_period) {
        $i = [];
        // it ends in a .
        if (is_initials($auth[$countAuth-1])) {
          // it's Conway Morris S.C.
          foreach (explode(" ", $auth[0]) as $bit){
            if (is_initials($bit)) {
              $i[] = format_initials($bit);
            } else {
              $surname .= "{$bit} ";
            }
          }
          unset($auth[0]);
          foreach ($auth as $bit){
            if (is_initials($bit)) {
              $i[] = format_initials($bit) . '.';
            } else {
              $i[] = $bit;
            }
          }
        } else {
          foreach ($auth as $A) {
            if (is_initials($A)) {
              $i[] = format_initials($A) . '.';
            } else {
              $i[] = $A;
            }
          }
        }
        $fore = mb_strtoupper(implode(" ", $i));
      } else {
        // it ends with the surname
        $surname = $auth[$countAuth-1];
        unset($auth[$countAuth-1]);
        $fore = implode(".", $auth);
      }
    } else {
      // We have no punctuation! Let's delimit with spaces.
      $chunks = array_reverse(explode(" ", $author));
      $i = [];
      foreach ($chunks as $chunk){
        if (!$surname && !is_initials($chunk)) {
          $surname = $chunk;
        } else {
          array_unshift($i, is_initials($chunk)?format_initials($chunk):$chunk);
        }
      }
      $fore = implode(" ", $i);
    }
  }
  // Special cases when code cannot fully determine things, or if the name is only Smith
  if (trim($surname) === '') { // get this with A. B. C.
    $full_name = format_forename($fore);
  } elseif (trim($fore) === '') {  // Get this with just Smith
    $full_name = format_surname($surname);
  } else {
    $full_name = format_surname($surname) . ", " . format_forename($fore);
  }
  $full_name = str_replace("..", ".", $full_name);  // Sometimes add period after period
  $full_name = str_replace(".", ". ", $full_name);  // Add spaces after all periods
  $full_name = str_replace(["   ", "  "], [" ", " "], $full_name); // Remove extra spaces
  return trim($full_name);
}

function format_multiple_authors(string $authors): string {
  $authors = html_entity_decode($authors, ENT_COMPAT | ENT_HTML401, "UTF-8");

  $return = [];
  ## Split the citation into an author by author account
  $authors = preg_replace(["~\band\b~iu", "~[\d\+\*]+~u"], ";", $authors); //Remove "and" and affiliation symbols

  $authors = str_replace(["&nbsp;", "(", ")"], [" "], $authors); //Remove spaces and weird punctuation
  $authors = str_replace([".,", "&", "  "], ";", $authors); //Remove "and"
  if (preg_match("~[,;]$~", trim($authors))) {
    $authors = substr(trim($authors), 0, strlen(trim($authors))-1); // remove trailing punctuation
  }

  $authors = trim($authors);
  if ($authors === "") {
    return '';
  }

  $authors = explode(";", $authors);
  $savedChunk = '';
  $bits = [];
  if (isset($authors[1])) {
    foreach ($authors as $A){
      if (trim($A) !== "") {
        $return[] = format_author($A);
      }
    }
  } else {
    //Use commas as delimiters
    $chunks = explode(",", $authors[0]);
    foreach ($chunks as $chunk){
      $chunk = trim($chunk);
      if ($chunk === '') {
        continue; // Odd things with extra commas
      }
      $bits = explode(" ", $chunk);
      $bitts = [];
      foreach ($bits as $bit){
        if ($bit) {
          $bitts[] = $bit;
        }
      }
      $bits = $bitts;
      unset($bitts);
      if (isset($bits[1]) || $savedChunk) {
        $return[] = format_author($savedChunk .  ($savedChunk?", ":"") . $chunk);
        $savedChunk = '';
      } else {
        $savedChunk = $chunk;// could be first author, or an author with no initials, or a surname with initials to follow.
      }
    }
  }
  if ($savedChunk) {
    $return[0] = (string) @$bits[0];
  }
  $return = implode("; ", $return);
  $frags = explode(" ", $return);
  $return = [];
  foreach ($frags as $frag){
    $return[] = is_initials($frag)?format_initials($frag):$frag;
  }
  return preg_replace("~;$~", "", trim(implode(" ", $return)));
}

function under_two_authors(string $text): bool {
  return !(strpos($text, ';') !== false  //if there is a semicolon
      || substr_count($text, ',') > 1  //if there is more than one comma
      || substr_count($text, ',') < substr_count(trim($text), ' ')  //if the number of commas is less than the number of spaces in the trimmed string
      );
}

/* split_authors
 * Assumes that there is more than one author to start with;
 * check this using under_two_authors()
 */
/** @return array<string> */
function split_authors(string $str): array {
  if (strpos($str, ';')) {
    return explode(';', $str);
  }
  return explode(',', $str);
}