Authoritex behaviour (Authoritex v1.2.0)

Elixir authority lookup behavior

Summary

Types

authority()

fetch_result()

search_result()

Callbacks

can_resolve?(t)

Returns true if the module can resolve the given identifier

code()

Returns the unique short code for the authority

description()

Returns a human-readable description of the authority

fetch(t)

Fetches a label (and optional hint string) for a specified resource

search(t, integer)

Returns a list of search results (and optional hints) matching a query

Functions

authorities()

Lists the available authories, returning a list of {implementation_module, authority_code, authority_description}

authority_for(id)

fetch(id)

Returns a label given an id.

search(authority_code, query)

Returns search results for a given query.

search(authority_code, query, max_results)

Like Authoritex.search/2 but with a specific maximum number of results

Types

authority()

@type authority() :: {module(), String.t(), String.t()}

fetch_result()

@type fetch_result() :: %{
  id: String.t(),
  label: String.t(),
  qualified_label: String.t(),
  hint: String.t() | nil,
  variants: [String.t()]
}

search_result()

@type search_result() :: %{id: String.t(), label: String.t(), hint: String.t() | nil}

Callbacks

can_resolve?(t)

@callback can_resolve?(String.t()) :: true | false

Returns true if the module can resolve the given identifier

code()

@callback code() :: String.t()

Returns the unique short code for the authority

description()

@callback description() :: String.t()

Returns a human-readable description of the authority

fetch(t)

@callback fetch(String.t()) :: {:ok, :fetch_result} | {:error, term()}

Fetches a label (and optional hint string) for a specified resource

search(t, integer)

@callback search(String.t(), integer()) :: {:ok, [:search_result]} | {:error, term()}

Returns a list of search results (and optional hints) matching a query

Functions

authorities()

@spec authorities() :: [authority()]

Lists the available authories, returning a list of {implementation_module, authority_code, authority_description}

Example:

  iex> Authoritex.authorities()
  [
    {Authoritex.FAST.CorporateName, "fast-corporate-name", "Faceted Application of Subject Terminology -- Corporate Name"},
    {Authoritex.FAST.EventName, "fast-event-name", "Faceted Application of Subject Terminology -- Event Name"},
    {Authoritex.FAST.Form, "fast-form", "Faceted Application of Subject Terminology -- Form/Genre"},
    {Authoritex.FAST.Geographic, "fast-geographic", "Faceted Application of Subject Terminology -- Geographic"},
    {Authoritex.FAST.Personal, "fast-personal", "Faceted Application of Subject Terminology -- Personal"},
    {Authoritex.FAST.Topical, "fast-topical", "Faceted Application of Subject Terminology -- Topical"},
    {Authoritex.FAST.UniformTitle, "fast-uniform-title", "Faceted Application of Subject Terminology -- Uniform Title"},
    {Authoritex.FAST, "fast", "Faceted Application of Subject Terminology"},
    {Authoritex.GeoNames, "geonames", "GeoNames geographical database"},
    {Authoritex.Getty.AAT, "aat", "Getty Art & Architecture Thesaurus (AAT)"},
    {Authoritex.Getty.TGN, "tgn", "Getty Thesaurus of Geographic Names (TGN)"},
    {Authoritex.Getty.ULAN, "ulan", "Getty Union List of Artist Names (ULAN)"},
    {Authoritex.Getty, "getty", "Getty Vocabularies"},
    {Authoritex.LOC.Languages, "lclang", "Library of Congress MARC List for Languages"},
    {Authoritex.LOC.Names, "lcnaf", "Library of Congress Name Authority File"},
    {Authoritex.LOC.SubjectHeadings, "lcsh", "Library of Congress Subject Headings"},
    {Authoritex.LOC, "loc", "Library of Congress Linked Data"}
  ]

authority_for(id)

@spec authority_for(binary()) :: authority() | nil

fetch(id)

@spec fetch(binary()) :: {:ok, fetch_result()} | {:error, term()}

Returns a label given an id.

Examples:

  iex> Authoritex.fetch("http://id.loc.gov/authorities/names/no2011087251")
  {:ok, "Valim, Jose"}

  iex> Authoritex.fetch("http://id.loc.gov/authorities/names/unknown-id")
  {:error, 404}

  iex> Authoritex.fetch("http://fake.authority.org/not-a-real-thing")
  {:error, :unknown_authority}

search(authority_code, query)

@spec search(binary(), binary()) :: {:ok, [search_result()]} | {:error, term()}

Returns search results for a given query.

Examples:

  iex> Authoritex.search("lcnaf", "valim")
  {:ok,
  [
    %{id: "info:lc/authorities/names/n2013200729", label: "Valim, Alexandre Busko"},
    %{id: "info:lc/authorities/names/nb2006000541", label: "Levitin, Valim"},
    %{id: "info:lc/authorities/names/n88230271", label: "Valim, Anthony Terra, 1919-"},
    %{id: "info:lc/authorities/names/no2019037344", label: "Melo, Glenda Cristina Valim de"},
    %{id: "info:lc/authorities/names/no2012078919", label: "Mansan, Jaime Valim"},
    %{id: "info:lc/authorities/names/no2001072420", label: "Lucisano-Valim, Yara Maria"},
    %{id: "info:lc/authorities/names/no2011087251", label: "Valim, Jose"},
    %{id: "info:lc/authorities/names/no2019110111", label: "Valim, Patrícia"},
    %{id: "info:lc/authorities/names/n2014206721", label: "Valim, Rafael"},
    %{id: "info:lc/authorities/names/no2009021335", label: "Melo, Cimara"}
  ]}

  iex> Authoritex.search("lcnaf", "blergh")
  {:ok, []}

  iex> Authoritex.search("blergh", "valim")
  {:error, "Unknown authority: blergh"}

search(authority_code, query, max_results)

@spec search(binary(), binary(), integer()) ::
  {:ok, [search_result()]} | {:error, term()}

Like Authoritex.search/2 but with a specific maximum number of results