Citable passages

Published

June 12, 2024

A CitablePassage represents a single canonically citable unit of text which you construct with a CtsUrn and a string value. Here we create a CitablePassage for the opening sentence of the Gettysburg Address in the version of John Hay, now in the Library of Congress.

using CitableCorpus
using CitableText

hay_urn = CtsUrn("urn:cts:citedemo:gburg.hay.v2:1")
hay_txt = "Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."
hay_psg = CitablePassage(hay_urn, hay_txt)

<urn:cts:citedemo:gburg.hay.v2:1> Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.

Use the text function to find the text content of a passage.

text(hay_psg)

"Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."

CitablePassages can be compared used the == function of Julia Base.

duplicate = hay_psg
hay_psg == duplicate

true

Note that two passages are equal only if both their text and URNs match. Here is the opening sentence of Lincoln’s address in the version of Edward Everett, the principal speaker at Gettysburg.

everett_urn = CtsUrn("urn:cts:citedemo:gburg.everett.v2:1")
everett_txt = "Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."
everett_psg = CitablePassage(everett_urn, everett_txt)

<urn:cts:citedemo:gburg.everett.v2:1> Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.

Two different passages may have identical text content.

text(hay_psg) == text(everett_psg)

true

hay_psg == everett_psg

false

A citable object

A CitablePassage follows CtsBase’s definition of a citable object. It therefore must implement three traits defining behavior for citation, comparison based on URN logic, and serialization to/from CEX format.

using CitableBase
citable(everett_psg)

true

urncomparable(everett_psg)

true

cexserializable(everett_psg)

true

Citation

The urntype, label and urn functions are available from CitableBase.

urn(everett_psg)

urn:cts:citedemo:gburg.everett.v2:1

label(everett_psg)

"<urn:cts:citedemo:gburg.everett.v2:1> Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."

urn(everett_psg)

urn:cts:citedemo:gburg.everett.v2:1

Since CitablePassages are cited by CtsUrn, you can use any functions from the CitableText package.

urn(everett_psg) |> passagecomponent

"1"

URN comparison

CitablePassages can be compared to URNs using URN logic for equality, containment and similarity. Note that in each function, the first parameter is the passage of text, and the second a URN to compare the text to.

urnequals(everett_psg, everett_urn)

true

urnequals(everett_psg, hay_urn)

false

lincoln_generic = CtsUrn("urn:cts:citedemo:gburg:")
hay_generic = CtsUrn("urn:cts:citedemo:gburg.hay:")
urncontains(hay_psg, lincoln_generic)

true

urncontains(everett_psg, lincoln_generic)

true

urncontains(everett_psg, hay_generic)

false

urncontains(hay_psg, hay_generic)

true

urnsimilar(everett_psg, lincoln_generic)

true

CEX serialization

CitablePassages can be lossly roundtripped to and from objects and delimited-text strings in CEX format using the cex and fromcex functions of CitableBase.

cex(everett_psg)

"urn:cts:citedemo:gburg.everett.v2:1|Four score and seven years ago our fathers brought forth, upon this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal."

everett_cex = cex(everett_psg)
everett_psg == fromcex(everett_cex, CitablePassage)

true