-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #50 from cite-architecture/dev
Major redesign of package
- Loading branch information
Showing
38 changed files
with
1,788 additions
and
288 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,21 +1,24 @@ | ||
# API documentation | ||
|
||
```@meta | ||
CurrentModule = CiteEXchange | ||
``` | ||
|
||
## Exported functions and types | ||
## Exported types and functions | ||
|
||
### The `Block` data type | ||
|
||
```@docs | ||
Block | ||
blocktypes | ||
cexversion | ||
``` | ||
|
||
### The `blocks` function | ||
|
||
```@docs | ||
blocks | ||
blocktypes | ||
blocksfortype | ||
datafortype | ||
``` | ||
|
||
## Internals | ||
### The `data` function | ||
|
||
```@docs | ||
blocktype | ||
``` | ||
data | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
```@setup blocks | ||
root = pwd() |> dirname |> dirname | ||
f = joinpath(root, "test", "assets", "burneyex.cex") | ||
``` | ||
|
||
|
||
# The `blocks` function | ||
|
||
The `blocks` function can: | ||
|
||
- parse a CEX data source into `Block`s, optionally filtering it by block type | ||
- filter a list of `Block`s by block type | ||
|
||
It always returns a (possibly empty) Vector of `Block`s. | ||
|
||
## Parsing a CEX data source | ||
|
||
The following examples parse a CEX source with two blocks, one a `ctscatalog` block, the other a `ctsdata` block. They parse identical data from a URL, a file (`f` in the example below is `test/assets/burneyex.cex` in this github repository), and a string value using `blocks` with a specified "reader". | ||
|
||
Parse CEX from a URL: | ||
|
||
```@example blocks | ||
using CiteEXchange | ||
url = "https://raw.githubusercontent.com/cite-architecture/CiteEXchange.jl/main/test/assets/burneyex.cex" | ||
urlblocks = blocks(url, CiteEXchange.UrlReader) | ||
``` | ||
|
||
From a file: | ||
|
||
```@example blocks | ||
fileblocks = blocks(f, CiteEXchange.FileReader) | ||
``` | ||
|
||
From a string: | ||
|
||
```@example blocks | ||
cexstring = read(f, String) | ||
stringblocks = blocks(cexstring, CiteEXchange.StringReader) | ||
``` | ||
|
||
The default is to parse from a string. | ||
|
||
```@example blocks | ||
defaultblocks = blocks(cexstring) | ||
``` | ||
|
||
The results are equivalent. | ||
|
||
```@example blocks | ||
urlblocks == fileblocks == stringblocks == defaultblocks | ||
``` | ||
|
||
|
||
## Filter CEX source by type | ||
|
||
Specify the String value of a CEX block type as an additional parameter to filter the resulting Vector of `Block`s to include only blocks of that type. | ||
|
||
|
||
```@example blocks | ||
urlcatalog = blocks(url, CiteEXchange.UrlReader, "ctscatalog") | ||
filecatalog = blocks(f, CiteEXchange.FileReader, "ctscatalog") | ||
stringcatalog = blocks(cexstring, CiteEXchange.StringReader, "ctscatalog") | ||
defaultcatalog = blocks(cexstring, "ctscatalog") | ||
``` | ||
|
||
|
||
```@example blocks | ||
urlcatalog == filecatalog == stringcatalog == defaultcatalog | ||
``` | ||
|
||
|
||
## Filter a list of `Block`s by type | ||
|
||
The `blocks` function can also be used to select blocks of a given type from a list of `Block`s. | ||
|
||
|
||
```@example blocks | ||
filteredcatalog = blocks(fileblocks, "ctscatalog") | ||
``` | ||
|
||
|
||
```@example blocks | ||
filteredcatalog == filecatalog | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,138 @@ | ||
```@setup data | ||
root = pwd() |> dirname |> dirname | ||
f = joinpath(root, "test", "assets", "burneyex.cex") | ||
using CitableBase | ||
using CiteEXchange | ||
struct UnstructuredUrn <: Urn | ||
id::AbstractString | ||
end | ||
import Base: show | ||
function show(io::IO, u::UnstructuredUrn) | ||
print(io, u.id) | ||
end | ||
struct MyComparable <: UrnComparisonTrait end | ||
import CitableBase: urncomparisontrait | ||
function urncomparisontrait(::Type{UnstructuredUrn}) | ||
MyComparable() | ||
end | ||
import CitableBase: urnequals | ||
function urnequals(::MyComparable, u1::UnstructuredUrn, u2::UnstructuredUrn) | ||
u1 == u2 | ||
end | ||
import CitableBase: urncontains | ||
function urncontains(::MyComparable, u1::UnstructuredUrn, u2::UnstructuredUrn) | ||
c1 = components(u1.id) | ||
c2 = components(u2.id) | ||
c1[3] == c2[3] | ||
end | ||
import CitableBase: urnsimilar | ||
function urnsimilar(::MyComparable, u1::UnstructuredUrn, u2::UnstructuredUrn) | ||
urncontains(u1, u2) | ||
end | ||
root = pwd() |> dirname |> dirname | ||
f = joinpath(root, "test", "assets", "laxlibrary1.cex") | ||
``` | ||
|
||
# The `data` function | ||
|
||
The `data` function can: | ||
|
||
- select data lines for a specified block type from a CEX source or from a list of `Block`s | ||
- optionally filter data by a URN value | ||
|
||
It always returns a (possibly empty) Vector of string values representing CEX data lines. | ||
|
||
## Select data lines from CEX sources | ||
|
||
In this example, we work with a CEX source that has several different kinds of CEX blocks, and two `ctsdata` blocks with passages from two different texts. We can collect all of the text datalines using the same syntax as for the `blocks` function. | ||
|
||
|
||
```@example data | ||
url = "https://raw.githubusercontent.com/cite-architecture/CiteEXchange.jl/dev/test/assets/laxlibrary1.cex" | ||
str = read(f, String) | ||
lines1 = data(f, CiteEXchange.FileReader, "ctsdata") | ||
lines2 = data(url, CiteEXchange.UrlReader, "ctsdata") | ||
lines3 = data(str, CiteEXchange.StringReader, "ctsdata") | ||
lines4 = data(str, "ctsdata") | ||
``` | ||
```@example data | ||
lines1 == lines2 == lines3 == lines4 | ||
``` | ||
|
||
|
||
Note in particular that `citerelationset` blocks have three lines of metadata before the relations data. These three lines appear in the `lines` field of a block, but are not included in the output of `data`. | ||
|
||
```@example data | ||
relblocks = blocks(str, "citerelationset") | ||
relblocks[1].lines | ||
``` | ||
|
||
```@example data | ||
data(str, "citerelationset") | ||
``` | ||
|
||
## Select data lines from a list of `Block`s | ||
|
||
Instead of a CEX source, you can also directly supply a list of blocks (without a "reader" type). | ||
|
||
```@example data | ||
blockgroup = blocks(str) | ||
blocklines = data(blockgroup, "ctsdata") | ||
``` | ||
|
||
```@example data | ||
blocklines == lines3 | ||
``` | ||
|
||
## Filter data lines by URN | ||
|
||
The `data` function optionally accepts a third parameter with a URN value to filter on by URN containment. The background setup for this page has defined a subtype of `Urn` called `UnstructuredUrn` that accepts any kind of URN string, and has implemented the `UrnComparisonTrait` for the type, so we can use `UnstructuredUrn` values to filter the data from blocks in our source. | ||
|
||
!!! note "Realistic URN types" | ||
|
||
The `UnstructuredUrn` is used solely for the purposes of testing the `CiteEXchange` package. In our experience, we can cover all needs for scholarly citation with either the `CtsUrn` type of [the `CitableText` package](https://cite-architecture.github.io/CitableText.jl/stable/), or the `Cite2Urn` of [the `CitableObject` package](https://github.com/cite-architecture/CitableObject.jl). | ||
|
||
|
||
When we collected all the `ctsdata` lines, we got five passages from two different texts. Now we'll filter the request to get data from a single text. | ||
|
||
```@example data | ||
urn = UnstructuredUrn("urn:cts:citedemo:gburg") | ||
textdata = data(str, "ctsdata", urn) | ||
``` | ||
|
||
URN filtering can be used with any of the variations of the `data` function, including filtering `Block`s. | ||
|
||
```@example data | ||
blks = blocks(f, CiteEXchange.FileReader) | ||
textfromblocks = data(blks, "ctsdata", urn) | ||
``` | ||
|
||
### Negating a URN filter | ||
|
||
To collect all data lines that are *not* contained by a URN filter, set the optional parameter `complement` to `true`. | ||
|
||
```@example data | ||
urn = UnstructuredUrn("urn:cts:citedemo:gburg") | ||
textdata = data(str, "ctsdata", urn, complement=true) | ||
``` | ||
|
||
|
||
### Filtering `citerelationset`s | ||
|
||
Note that when filtering `citerelationset`s by URN value, the filter applies to the URN for an entire relation set, *not* to URNs in individual relations. | ||
|
||
```@example data | ||
relsetfilter = UnstructuredUrn("urn:cite2:hmt:dse.v1:") | ||
data(str, "citerelationset", relsetfilter) | ||
``` | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.