Implement behaviors for subreferences, and versioning, and add `urnty…

…pe` function

Project.toml

@@ -1,7 +1,7 @@
 name = "CitableBase"
 uuid = "d6f014bd-995c-41bd-9893-703339864534"
 authors = ["Neel Smith <[email protected]>"]
-version = "8.1.0"
+version = "9.0.0"
 
 [deps]
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"

docs/src/citable.md

@@ -138,12 +138,17 @@ citabletrait(typeof(distantbook))
 citable(distantbook)
 ```
 
-### Implementing the required functions `urn` and `label`
+### Implementing the required functions `urntype`, `urn`, `label`
 
-Implementing `urn` and `label` is now trivial.  The `urn` function just returns the `urn` field of the book.  In Julia, `Base.show` underlies the `string` function, so since we have already implemented `show` for our book type, we can just return `string(book)` for the `label` function.
+Implementing `urntype`, `urn` and `label` is now trivial.  The `urntype` function will report the type of URN we cite this object with. The `urn` function just returns the `urn` field of the book.  In Julia, `Base.show` underlies the `string` function, so since we have already implemented `show` for our book type, we can just return `string(book)` for the `label` function.
 
 
 ```@example book
+import CitableBase: urntype
+function urntype(book::CitableBook)
+    Isbn10Urn
+end
+
 import CitableBase: urn
 function urn(book::CitableBook)
     book.urn
@@ -155,6 +160,11 @@ function label(book::CitableBook)
 end
 ```
 
+
+```@example book
+urntype(distantbook)
+```
+
 ```@example book
 urn(distantbook)
 ```

docs/src/collections.md

@@ -208,6 +208,20 @@ Use the `citablecollection` function to test if a specific object is a citable c
 citablecollection(rl)
 ```
 
+Like citable objects, citable collections should report the type of URN they use for citation.
+
+```@example collections
+import CitableBase: urntype
+function urntype(readingList::ReadingList)
+    Isbn10Urn
+end
+```
+
+
+```@example collections
+urntype(rl)
+```
+
 The promise we now need to fulfill is that our collection will implement three further traits for URN comparison, serialization and iteration.
 
 ## Implementing the `UrnComparisonTrait`

docs/src/urns.md

@@ -197,8 +197,39 @@ wrong = Isbn10Urn("urn:isbn10:1108922036")
 urncontains(distanthorizons, wrong)
 ```
 
+## Optional methods
 
+The `CtsUrn` (from `CitableText`) and the `Cite2Urn` (from `CitableObject`) illustrate two optional behaviors: support for versioning of URNs, and support for subreferences.  Although our ISBN numbers don't require either of those features, we'll illustrate how they are implemented.
 
+### Versioning
+
+The three relevant functions are `supportsversion`, `addversion` and `dropversion`.  We'll indicate that our URN type supports versioning but for this demonstration will just pass the URN through unchanged.
+
+```@example urns
+import CitableBase: supportsversion
+function supportsversion(u::Isbn10Urn)
+    true
+end
+
+import CitableBase: addversion
+function addversion(u::Isbn10Urn, versioninfo::AbstractString)
+    u
+end
+
+import CitableBase: dropversion
+function dropversion(u::Isbn10Urn)
+    u
+end
+```
+```@example urns
+supportsversion(wrong)
+```
+```@example urns
+addversion(wrong, "v2")
+```
+```@example urns
+dropversion(wrong)
+```
 
 ## Recap: identifiers
 

src/CitableBase.jl

@@ -21,7 +21,7 @@ export urnsimilar, urncontains, urnequals
 
 export CitableTrait, NotCitable
 export citabletrait, citable
-export urn, label
+export urntype, urn, label
 
 export CexTrait, NotCexSerializable 
 export cextrait, cexserializable

src/citable.jl

@@ -23,6 +23,16 @@ Define delegation for the 2 functions of the CitableTrait:
 2. label
 =#
 
+
+"""Delegate `urntype` to specific functions based on 
+type's citable trait value.
+
+$(SIGNATURES)
+"""
+function urntype(x::T) where {T} 
+    urntype(citabletrait(T), x)
+end
+
 """Delegate `urn` to specific functions based on 
 type's citable trait value.
 
@@ -58,3 +68,12 @@ $(SIGNATURES)
 function label(::NotCitable, x)
     throw(DomainError(x, string(typeof(x), " does not implement the label function.")))
 end
+
+
+"""It is an error to invoke the `urn` function on material that is not citable.
+
+$(SIGNATURES)
+"""
+function urntype(::NotCitable, x)
+    throw(DomainError(x, string( typeof(x), " does not implement the urn function.")))
+end

src/urns.jl

@@ -53,17 +53,63 @@ function parts(componentString::AbstractString)
 end
 
 
+"""True for URN types that support versioning.
+$(SIGNATURES)
+"""
+function supportsversion(u::Type{<:Urn})
+    false
+end
+
+
 """Urn subtypes should implement `dropversion(urn::U)::U`.
 
 $(SIGNATURES)
 """
-function dropversion  end
+function dropversion(u::Type{<:Urn})  
+    if !(supportsversion)
+        @warn("URNs of type $(typeof(u)) do not support versions.")
+        u
+    else
+        throw(DomainError(u, 
+        "`dropversion` not implemented for type $(typeof(u))"))
+    end
+end
 
 
 """Urn subtypes should implement `addversion(urn::U, versionid)::U`.  
 
 $(SIGNATURES)
 """
-function addversion end
+function addversion(u::Type{<:Urn}, versioninfo::AbstractString)  
+    if !(supportsversion)
+        @warn("URNs of type $(typeof(u)) do not support versions.")
+        u
+    else
+        throw(DomainError(u, 
+        "`addversion` not implemented for type $(typeof(u))"))
+    end
+end
+
+"""True for URN types that support subreferences.
+$(SIGNATURES)
+"""
+function supportssubref(u::Type{<:Urn})
+    false
+end
+
 
 
+"""Urn subtypes should implement `dropversion(urn::U)::U`.
+
+$(SIGNATURES)
+"""
+function dropsubref(u::Type{<:Urn})  
+    if !(supportssubref)
+        @warn("URNs of type $(typeof(u)) do not support subreferences.")
+        u
+    else
+        throw(DomainError(u, 
+        "`dropsubref` not implemented for type $(typeof(u))"))
+    end
+end
+