mod id;
mod locate;
mod quote;
use crate::errors::SpanRefusal;
use crate::rfc3339;
use crate::text_offsets::Offsets;
use crate::types::{
Agent, AnchoredText, Annotation, AnnotationBodies, AnnotationBody, AnnotationGenerator,
AnnotationSelector, AnnotationTarget, AnnotationTargetType, AnnotationTargetValue, BodyPurpose,
FragmentSelector, Motivation, PdfTextItem, ResourceId, Selector, TextPositionSelector,
TextQuoteSelector,
};
use quote::Place;
use std::time::SystemTime;
fn items(body: Option<&AnnotationBodies>) -> &[AnnotationBody] {
match body {
None => &[],
Some(AnnotationBodies::AnnotationBody(one)) => std::slice::from_ref(one),
Some(AnnotationBodies::List(several)) => several,
}
}
fn selectors(selector: &AnnotationSelector) -> &[Selector] {
match selector {
AnnotationSelector::Selector(one) => std::slice::from_ref(one),
AnnotationSelector::List(several) => several,
}
}
pub fn body_source(body: Option<&AnnotationBodies>) -> Option<&ResourceId> {
items(body).iter().find_map(|item| match item {
AnnotationBody::SpecificResource(resource) => Some(&resource.source),
AnnotationBody::TextualBody(_) => None,
})
}
pub fn is_body_resolved(body: Option<&AnnotationBodies>) -> bool {
body_source(body).is_some()
}
pub fn target_source(target: &AnnotationTargetValue) -> &ResourceId {
match target {
AnnotationTargetValue::ResourceId(resource) => resource,
AnnotationTargetValue::AnnotationTarget(target) => &target.source,
}
}
pub fn target_selector(target: &AnnotationTargetValue) -> Option<&AnnotationSelector> {
match target {
AnnotationTargetValue::ResourceId(_) => None,
AnnotationTargetValue::AnnotationTarget(target) => target.selector.as_ref(),
}
}
pub fn is_highlight(annotation: &Annotation) -> bool {
annotation.motivation == Motivation::Highlighting
}
pub fn is_reference(annotation: &Annotation) -> bool {
annotation.motivation == Motivation::Linking
}
pub fn is_assessment(annotation: &Annotation) -> bool {
annotation.motivation == Motivation::Assessing
}
pub fn is_comment(annotation: &Annotation) -> bool {
annotation.motivation == Motivation::Commenting
}
pub fn is_tag(annotation: &Annotation) -> bool {
annotation.motivation == Motivation::Tagging
}
pub fn comment_text(annotation: &Annotation) -> Option<&str> {
if !is_comment(annotation) {
return None;
}
match items(annotation.body.as_ref()).first()? {
AnnotationBody::TextualBody(text) => Some(&text.value),
AnnotationBody::SpecificResource(_) => None,
}
}
pub fn is_stub_reference(annotation: &Annotation) -> bool {
is_reference(annotation) && !is_body_resolved(annotation.body.as_ref())
}
pub fn is_resolved_reference(annotation: &Annotation) -> bool {
is_reference(annotation) && is_body_resolved(annotation.body.as_ref())
}
pub fn text_quote_selector(selector: &AnnotationSelector) -> Option<&TextQuoteSelector> {
selectors(selector).iter().find_map(|item| match item {
Selector::TextQuoteSelector(quote) => Some(quote),
_ => None,
})
}
pub fn exact_text(selector: Option<&AnnotationSelector>) -> &str {
selector
.and_then(text_quote_selector)
.map_or("", |quote| quote.exact.as_str())
}
pub fn annotation_exact_text(annotation: &Annotation) -> &str {
exact_text(target_selector(&annotation.target))
}
fn texts_for(annotation: &Annotation, purpose: BodyPurpose) -> impl Iterator<Item = &str> {
items(annotation.body.as_ref())
.iter()
.filter_map(move |item| match item {
AnnotationBody::TextualBody(text) if text.purpose == Some(purpose) => {
Some(text.value.as_str())
}
_ => None,
})
}
pub fn entity_types(annotation: &Annotation) -> Vec<&str> {
texts_for(annotation, BodyPurpose::Tagging)
.filter(|text| !text.is_empty())
.collect()
}
pub fn tag_category(annotation: &Annotation) -> Option<&str> {
if is_tag(annotation) {
texts_for(annotation, BodyPurpose::Tagging).next()
} else {
None
}
}
pub fn tag_schema_id(annotation: &Annotation) -> Option<&str> {
if is_tag(annotation) {
texts_for(annotation, BodyPurpose::Classifying).next()
} else {
None
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct QuotedText {
pub exact: String,
pub prefix: Option<String>,
pub suffix: Option<String>,
}
impl QuotedText {
pub fn new(exact: impl Into<String>) -> Self {
Self {
exact: exact.into(),
prefix: None,
suffix: None,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TextSpan {
pub start: u64,
pub end: u64,
pub exact: String,
pub prefix: Option<String>,
pub suffix: Option<String>,
}
impl TextSpan {
pub fn new(start: u64, end: u64, exact: impl Into<String>) -> Self {
Self {
start,
end,
exact: exact.into(),
prefix: None,
suffix: None,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum MatchQuality {
Normalized,
CaseInsensitive,
Fuzzy,
}
impl MatchQuality {
pub const fn as_str(&self) -> &'static str {
match self {
MatchQuality::Normalized => "normalized",
MatchQuality::CaseInsensitive => "case-insensitive",
MatchQuality::Fuzzy => "fuzzy",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AnchorMethod {
UniqueMatch,
ContextRecovered,
FirstOfMany,
FuzzyMatch(MatchQuality),
}
impl AnchorMethod {
pub const fn as_str(&self) -> &'static str {
match self {
AnchorMethod::UniqueMatch => "unique-match",
AnchorMethod::ContextRecovered => "context-recovered",
AnchorMethod::FirstOfMany => "first-of-many",
AnchorMethod::FuzzyMatch(_) => "fuzzy-match",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReconciledSpan {
pub span: TextSpan,
pub anchor_method: AnchorMethod,
}
fn hint(given: Option<&str>) -> Option<&str> {
given.filter(|given| !given.trim().is_empty())
}
fn window(hint: &str) -> usize {
hint.chars().count().max(32)
}
pub fn reconcile(text: &str, quoted: &QuotedText) -> Option<ReconciledSpan> {
if quoted.exact.trim().is_empty() {
return None;
}
let offsets = Offsets::of(text);
let (prefix, suffix) = (
hint(quoted.prefix.as_deref()),
hint(quoted.suffix.as_deref()),
);
let fits = |place: &Place| {
let before =
|prefix: &str| offsets.between(place.start.saturating_sub(window(prefix)), place.start);
let after = |suffix: &str| {
offsets.between(place.end, (place.end + window(suffix)).min(offsets.len()))
};
prefix.is_none_or(|prefix| {
before(prefix)
.is_some_and(|before| before.ends_with(prefix) || before.contains(prefix.trim()))
}) && suffix.is_none_or(|suffix| {
after(suffix)
.is_some_and(|after| after.starts_with(suffix) || after.contains(suffix.trim()))
})
};
let hinted = |places: &[Place]| {
places
.iter()
.find(|&place| (prefix.is_some() || suffix.is_some()) && fits(place))
.copied()
};
let places = quote::places_of(&offsets, "ed.exact);
let (place, anchor_method) = match places.as_slice() {
[only] => (*only, AnchorMethod::UniqueMatch),
[first, ..] => match hinted(&places) {
Some(chosen) => (chosen, AnchorMethod::ContextRecovered),
None => (*first, AnchorMethod::FirstOfMany),
},
[] => {
let (places, quality) = quote::places_like(text, "ed.exact)?;
let place = hinted(&places).or_else(|| places.first().copied())?;
(place, AnchorMethod::FuzzyMatch(quality))
}
};
let (prefix, suffix) = quote::context_of(&offsets, place);
Some(ReconciledSpan {
span: TextSpan {
start: place.start as u64,
end: place.end as u64,
exact: offsets.between(place.start, place.end)?.to_owned(),
prefix: prefix.map(str::to_owned),
suffix: suffix.map(str::to_owned),
},
anchor_method,
})
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Spanned<'a> {
Text(&'a str),
Pdf(&'a AnchoredText),
}
impl<'a> From<&'a str> for Spanned<'a> {
fn from(text: &'a str) -> Self {
Spanned::Text(text)
}
}
impl<'a> From<&'a String> for Spanned<'a> {
fn from(text: &'a String) -> Self {
Spanned::Text(text)
}
}
impl<'a> From<&'a AnchoredText> for Spanned<'a> {
fn from(anchored: &'a AnchoredText) -> Self {
Spanned::Pdf(anchored)
}
}
const RFC_3778: &str = "http://tools.ietf.org/rfc/rfc3778";
fn spaced_once(text: &str) -> String {
text.split_whitespace().collect::<Vec<_>>().join(" ")
}
fn fragments(
anchored: &AnchoredText,
offsets: &Offsets<'_>,
span: &TextSpan,
) -> Result<Vec<Selector>, SpanRefusal> {
let located = locate::locate(anchored, span.start, span.end);
if located.rects.is_empty() {
return Err(SpanRefusal::NothingLocated);
}
let from = located.overlapping.iter().map(|item| item.start).min();
let to = located.overlapping.iter().map(|item| item.end).max();
let covered = from.zip(to).and_then(|(from, to)| {
offsets.between(usize::try_from(from).ok()?, usize::try_from(to).ok()?)
});
if !covered.is_some_and(|covered| spaced_once(covered).contains(&spaced_once(&span.exact))) {
return Err(SpanRefusal::ExactNotCovered);
}
Ok(located
.rects
.iter()
.map(|rect| {
Selector::from(FragmentSelector {
conforms_to: Some(RFC_3778.to_owned()),
..FragmentSelector::new(rect.fragment())
})
})
.collect())
}
fn annotation(
target: AnnotationTarget,
motivation: Motivation,
anchor: &str,
generator: Option<&Agent>,
body: Option<AnnotationBodies>,
) -> Annotation {
let id = id::annotation_id(&target.source, motivation, anchor, body.as_ref());
Annotation {
body,
generator: generator.cloned().map(AnnotationGenerator::Agent),
..Annotation::new(
id,
motivation,
target.into(),
rfc3339::to_the_millisecond(SystemTime::now()),
)
}
}
pub fn annotation_of_span<'a>(
spanned: impl Into<Spanned<'a>>,
span: &TextSpan,
resource_id: &ResourceId,
motivation: Motivation,
generator: &Agent,
body: Option<AnnotationBodies>,
) -> Result<Annotation, SpanRefusal> {
let spanned = spanned.into();
let text = match spanned {
Spanned::Text(text) => text,
Spanned::Pdf(anchored) => anchored.text.as_str(),
};
let offsets = Offsets::of(text);
if let Spanned::Pdf(anchored) = spanned {
let is_a_stretch = |item: &PdfTextItem| {
item.start <= item.end
&& usize::try_from(item.end).is_ok_and(|end| end <= offsets.len())
};
if !anchored.items.iter().all(is_a_stretch) {
return Err(SpanRefusal::ItemOutOfRange);
}
}
let (start, end) = match (usize::try_from(span.start), usize::try_from(span.end)) {
(Ok(start), Ok(end)) if start <= end && end <= offsets.len() => (start, end),
_ => return Err(SpanRefusal::SpanOutOfRange),
};
let mut selectors = match spanned {
Spanned::Text(_) => {
if offsets.between(start, end) != Some(span.exact.as_str()) {
return Err(SpanRefusal::ExactMismatch);
}
vec![Selector::from(TextPositionSelector::new(
span.start, span.end,
))]
}
Spanned::Pdf(anchored) => fragments(anchored, &offsets, span)?,
};
if let Some(prefix) = &span.prefix {
let from = start.saturating_sub(prefix.chars().count());
if offsets.between(from, start) != Some(prefix.as_str()) {
return Err(SpanRefusal::PrefixMismatch);
}
}
if let Some(suffix) = &span.suffix {
let to = (end + suffix.chars().count()).min(offsets.len());
if offsets.between(end, to) != Some(suffix.as_str()) {
return Err(SpanRefusal::SuffixMismatch);
}
}
let stated = |context: &Option<String>| context.clone().filter(|context| !context.is_empty());
selectors.push(Selector::from(TextQuoteSelector {
prefix: stated(&span.prefix),
suffix: stated(&span.suffix),
..TextQuoteSelector::new(span.exact.as_str())
}));
let target = AnnotationTarget {
r#type: Some(AnnotationTargetType::SpecificResource),
selector: Some(AnnotationSelector::List(selectors)),
..AnnotationTarget::new(resource_id.clone())
};
let anchor = format!("{}:{}:{}", span.start, span.end, span.exact);
Ok(annotation(
target,
motivation,
&anchor,
Some(generator),
body,
))
}
pub fn annotation_of_resource(
resource_id: &ResourceId,
motivation: Motivation,
generator: Option<&Agent>,
body: Option<AnnotationBodies>,
) -> Annotation {
annotation(
AnnotationTarget::new(resource_id.clone()),
motivation,
"",
generator,
body,
)
}