▼Digital Ricœur TEI Library
►2 Bibliographic Information
On this page:
instance-info?
instance-info
get-plain-instance-info
instance-title
instance-title/  symbol
instance-citation
instance-publication-date
instance-orig-publication-date
instance-publication-original?
instance-language
language-symbol/  c
instance-book/  article
instance-get-resp-string
2.1 Instance Sets
instance-set?
instance-set
instance-set*
for/  instance-set
for*/  instance-set
instance-set->plain
instance-set-ref
instance-set-try-ref
instance-set/  c
in-instance-set
2.2 Derived Instance Info
prop:  instance-info
plain-instance-info?
2.2.1 Class-based Objects
instance-info-mixin
new
instance-info<%>
get-title
get-title/  symbol
get-citation
get-orig-publication-date
get-publication-date
get-publication-original?
get-language
get-book/  article
get-resp-string
0.5.91
  top  contents    up   

2 Bibliographic Information🔗ℹ

This section documents an API for accessing bibliographic information about instances. An instance is an abstraction for the most specific level of bibliographic information with which Digital Ricœur is concerned. The term “instance” is drawn from the BibFrame model for bibliographic data.

Concretely, Ricœur’s publications exist as particular physical objects, such as a specific copy of a book, housed on a particular shelf in a particular library. The “instance” abstraction refers to all concrete copies that are “the same” for Digital Ricœur’s purposes: that is, they are bibliographically identical, even to the extent of having exactly the same pagination. Digital Ricœur aims to prepare one TEI XML file for each instance.

An instance is an abstraction, not a kind of Racket value, but many kinds of Racket values (particularly TEI document values) are assosciated with an instance. Racket values that encapsulate bibliographic information about a particular instance are refered to as instance info values. This library defines a common interface for working with instance info values, and clients can implement additional types of instance info values that will support the same interface.

In the medium to long term, Digital Ricœur plans to transition to managing the corpus-level bibliographic data about instances in a database, rather than the TEI XML files. That transition will likely result in changes to this interface.

procedure

(instance-info? v) → any/c

  v : any/c
An instance info value encapsulates bibliographic information about an instance. The predicate instance-info? recognizes instance info values.

All instance info values support the same high-level API, and new kinds of values (including class-based objects) can implement the instance info interface. (See prop:instance-info and instance-info-mixin.)

match expander

(instance-info kw-pat ...)

 
kw-pat = #:title title-pat
  | #:title/symbol title/symbol-pat
  | #:citation citation-pat
  | #:orig-publication-date orig-publication-date-pat
  | #:publication-date publication-date-pat
  | #:publication-original? publication-original?-pat
  | #:language language-pat
  | #:book/article book/article-pat
Matches any instance info value, then matches any sub-patterns against the values that would be returned by the corresponding procedures documented below.

Each keyword may appear at most once.

procedure

(get-plain-instance-info info) → plain-instance-info?

  info : instance-info?
Converts any instance info value to a plain instance info value, which serves as a cannonical representation of the encapsulated information.

In addition to being needed with prop:instance-info to implement the instance info interface for new kinds of values, get-plain-instance-info can be useful to keep only a minimal representation of the instance info reachable, rather than, say, an entire TEI document value.

procedure

(instance-title info) → string-immutable/c

  info : instance-info?
Returns the title of the instance, including subtitles.

See also title<?.

procedure

(instance-title/symbol info) → symbol?

  info : instance-info?
Equivalent to (string->symbol (instance-title info)).

procedure

(instance-citation info) → string-immutable/c

  info : instance-info?
Returns a human-readable citation describing the instance.

procedure

(instance-publication-date info) → date?

  info : instance-info?
Returns the publication date of the instance.

procedure

(instance-orig-publication-date info) → date?

  info : instance-info?
Returns the date when the work (as a whole) was first published, which may or may not be the same as the result of instance-publication-date.

procedure

(instance-publication-original? info) → boolean?

  info : instance-info?
Indicates whether the version represented by info was the first instance of the work as a whole to be published. If instance-publication-original? returns a non-false value,
(equal? (instance-publication-date info)
        (instance-orig-publication-date info))
will allways be #true; however, it is possible for a non-original instance to be publised in the same year as the original, so the inverse does not hold.

procedure

(instance-language info) → language-symbol/c

  info : instance-info?

value

language-symbol/c : flat-contract? = (or/c 'en 'fr 'de)

Identifies the primary language of the instance. English, French, and German are currently supported.

The contract language-symbol/c recognizes symbols that identify one of the supported languages. The symbols are chosen from the IANA Language Subtag Registry, as specified by BCP 47.

procedure

(instance-book/article info) → (or/c 'book 'article)

  info : instance-info?
Indicates whether the instance is a book or an article.

procedure

(instance-get-resp-string info resp) → string-immutable/c

  info : instance-info?
  resp : symbol?
Returns a string, suitable for display to end users, naming the author or editor specified by the TEI XML element with an xml:id attribute value of (symbol->string resp). An exception is raised if resp does not identify such an element in Digital Ricœur’s TEI XML document for the instance represented by info.

This is a fairly low-level function: for most purposes, segment-resp-string is preferred.

2.1 Instance Sets🔗ℹ

procedure

(instance-set? v) → any/c

  v : any/c
Recognizes instance set values.

An instance set is an immutable set, in the sense of racket/set, of values which support the instance info interface (i.e. values for which instance-info? returns #true). All members of an instance set will be distinct in terms of instance-title/symbol.

procedure

(instance-set [init]) → (instance-set/c)

  init : (stream/c instance-info?) = '()
Constructs an instance set containing the instance info values from init.

procedure

(instance-set* info ...) → (instance-set/c)

  info : instance-info?
Equivalent to (instance-set (list info ...)).

syntax

(for/instance-set (for-clause ...) body-or-break ... body)

syntax

(for*/instance-set (for-clause ...) body-or-break ... body)

Like for/list and for*/list, respectively, except that the last body expression must produce an instance info value, and the result of the iteration is an instance set of the instance info values.

procedure

(instance-set->plain st) → (instance-set/c)

  st : (instance-set/c)
Produces an instance set like st, but with every member of the set converted to a plain instance info value using get-plain-instance-info. If st already contains only plain instance info values, it may or may not be returned directly.

procedure

(instance-set-ref st title/symbol) → instance-info?

  st : (instance-set/c)
  title/symbol : symbol?
Returns the member of st for which instance-title/symbol would return title/symbol. If no such member exists, an exception is raised.

procedure

(instance-set-try-ref st title/symbol)

 → (or/c #f instance-info?)
  st : (instance-set/c)
  title/symbol : symbol?
Like instance-set-ref, but returns #false when title/symbol is not found instead of raising an exception.

procedure

(instance-set/c elem/c) → chaperone-contract?

  elem/c : chaperone-contract?
(instance-set/c) → flat-contract?
Constructs a contract recognizing instance sets where the elements of the set satisfy elem/c. If elem/c is a flat contract, the result will be a flat contract; otherwise, the result will be a chaperone contract.

The contract produced by (instance-set/c) accepts all instance sets. Using (instance-set/c) may provide better error reporting than using instance-set? as a contract, and it may be checked more efficiently than (instance-set/c any/c) or (instance-set/c instance-info?), but any of those variants would accept the same values.

procedure

(in-instance-set st) → sequence?

  st : (instance-set/c)
Explicitly converts an instance set to a sequence for use with for-like forms. An in-instance-set application may provide better performance when it appears directly in a for clause.

2.2 Derived Instance Info🔗ℹ

value

prop:instance-info : 
(struct-type-property/c
 (-> any/c plain-instance-info?))
New kinds of values can support the instance info API through the structure type property prop:instance-info. The value for the prop:instance-info must be a function that, given an instance of the new structure type, returns a plain instance info value. The function should always return the same plain instance info value when called with the same argument: this requirement is not currently enforced, but may be in the future.

Special support is provided for using class-based objects as instance info values via instance-info-mixin.

procedure

(plain-instance-info? v) → any/c

  v : any/c
Recognizes plain instance info values.

2.2.1 Class-based Objects🔗ℹ

mixin

instance-info-mixin : (class? . -> . class?)

  result implements: instance-info<%>
An object that is an instance (in the sense of racket/class) of a class extended with instance-info-mixin can be used as an instance info value. This is the prefered way for class-based objects to support the instance info API.
The class returned by instance-info-mixin will implement the instance-info<%> interface, which also makes some of the instance info functions available as methods for use with inherit, send, etc. Note that all such methods are declared with public-final.

constructor

(new instance-info-mixin 
    [instance-info instance-info] 
    ...superclass-args...) 
 → (is-a?/c instance-info-mixin)
  instance-info : instance-info?
The instance-info initialization argument determines the behavior of an-instance-info when used as an instance info value.

Specifically, (get-plain-instance-info an-instance-info) will return the same plain instance info value as (get-plain-instance-info instance-info).

interface

instance-info<%> : interface?

Identifies classes returned by instance-info-mixin. Objects which satisfy (is-a?/c instance-info<%>) can be used as instance info values.
In addition to the methods documented below, instance-info<%> also includes additional, private methods: instance-info<%> can only be implemented using instance-info-mixin.

method

(send an-instance-info get-title) → string-immutable/c

This method is final, so it cannot be overridden.
Like (instance-title an-instance-info).

method

(send an-instance-info get-title/symbol) → symbol?

This method is final, so it cannot be overridden.
Like (instance-title/symbol an-instance-info).

method

(send an-instance-info get-citation) → string-immutable/c

This method is final, so it cannot be overridden.
Like (instance-citation an-instance-info).

method

(send an-instance-info get-orig-publication-date) → date?

This method is final, so it cannot be overridden.
Like (instance-orig-publication-date an-instance-info).

method

(send an-instance-info get-publication-date) → date?

This method is final, so it cannot be overridden.
Like (instance-publication-date an-instance-info).

method

(send an-instance-info get-publication-original?) → boolean?

This method is final, so it cannot be overridden.
Like (instance-publication-original? an-instance-info).

method

(send an-instance-info get-language) → (or/c 'en 'fr 'de)

This method is final, so it cannot be overridden.
Like (instance-language an-instance-info).

method

(send an-instance-info get-book/article)

 → (or/c 'book 'article)
This method is final, so it cannot be overridden.
Like (instance-book/article an-instance-info).

method

(send an-instance-info get-resp-string resp)

 → string-immutable/c
  resp : symbol?
This method is final, so it cannot be overridden.
Like (instance-get-resp-string an-instance-info resp).

  top  contents    up