User's guide: the CtsUrn

The CitableText module includes a panoply of functions for working with CtsUrns. (The API documentation has a more complete list than those illutrated here).

Top-level components

Include the CitableBase module to use its generic components and parts functions.

using CitableText, CitableBase
urn = CtsUrn("urn:cts:greekLit:tlg0012.tlg001.msA:1.1")
components(urn)

5-element Array{SubString{String},1}:
 "urn"
 "cts"
 "greekLit"
 "tlg0012.tlg001.msA"
 "1.1"

components(urn)[4] |> parts

3-element Array{SubString{String},1}:
 "tlg0012"
 "tlg001"
 "msA"

You can also use functions in CitableText to extract components by name, and work with parts of those components.

namespace(urn)

"greekLit"

workcomponent(urn)

"tlg0012.tlg001.msA"

passagecomponent(urn)

"1.1"

The work component

workdepth(urn)

3

workparts(urn)

3-element Array{SubString{String},1}:
 "tlg0012"
 "tlg001"
 "msA"

The passage component

passagedepth(urn)

2

passageparts(urn)

2-element Array{SubString{String},1}:
 "1"
 "1"

URN manipulation

Several functions take a CtsUrn as an argument, and create a new CtsUrn.

addversion(urn, "rev2")

urn:cts:greekLit:tlg0012.tlg001.rev2:1.1

dropversion(urn)

urn:cts:greekLit:tlg0012.tlg001:1.1

Similar functions are addworkid, dropversion, addversion, dropexemplar, addexemplar, collapsePassageTo, and collapsePassageBy.

You could, for example, chain together dropversion and addworkid to turn a reference to a specific version of Iliad 1.1 into a generic reference to Odyssey 1.1.

# change "tlg001" (Iliad) to "tlg002" (Odyssey)
addworkid(dropversion(urn), "tlg002")

urn:cts:greekLit:tlg0012.tlg002:1.1

URN comparison

In addition to comparing two CtsUrns for equality with ==, you can compare them for URN containment or URN similarity.

iliad1 =  CtsUrn("urn:cts:greekLit:tlg0012.tlg001:1")
urncontains(iliad1, urn)

true

Two CtsUrns are similar if they are equal, or if either URN contains the other.

urnsimilar(iliad1, urn)

true

Note that this definition means the function is symmetric.

urnsimilar(iliad1, urn) == urnsimilar(urn, iliad1)

true

Ranges

CtsUrns can identify passages of text as continuous ranges of citable passages.

openinglines = CtsUrn("urn:cts:greekLit:tlg0012.tlg001.msA:1.1-1.10")
isrange(openinglines)

true

The range_begin and range_end functions return string values.

range_begin(openinglines)

"1.1"

range_end(openinglines)

"1.10"

Extended identifiers ("subreferences")

CTS URNs can include an extended identifier to point into the text content of a specific version of a passage. You can determine if a CtsUrn includes an extended identifier, extract the subreference, or drop it.

wrath = CtsUrn("urn:cts:greekLit:tlg0012.tlg001.msA:1.1@μῆνιν")
hassubref(wrath)

true

subref(wrath)

"μῆνιν"

dropsubref(wrath) == urn

true