stam 0.18.7

STAM is a powerful library for dealing with stand-off annotations on text. This is the Rust library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

/*
    STAM Library (Stand-off Text Annotation Model)
        by Maarten van Gompel <proycon@anaproy.nl>
        Digital Infrastucture, KNAW Humanities Cluster

        Licensed under the GNU General Public License v3

        https://github.com/annotation/stam-rust
*/

//! ## Introduction
//!
//! STAM is a standalone data model for stand-off text annotation. This is a software library to work with the
//! model from Rust, and is the primary library/reference implementation for STAM. It aims to
//! implement the full model as per the [STAM specification](https://github.com/annotation/stam) and most of the
//! extensions.
//!
//! **What can you do with this library?**
//!
//! * Keep, build and manipulate an efficient in-memory store of texts and annotations on texts
//! * Search in annotations, data and text, either programmatically or via the [STAM Query Language](https://github.com/annotation/stam/tree/master/extensions/stam-query).
//!    * Search annotations by data, textual content, relations between text fragments (overlap, embedding, adjacency, etc).
//!    * Search in text (incl. via regular expressions) and find annotations targeting found text selections.
//!    * Elementary text operations with regard for text offsets (splitting text on a delimiter, stripping text).
//!    * Search in data (set,key,value) and find annotations that use the data.
//!    * Convert between different kind of offsets (absolute, relative to other structures, UTF-8 bytes vs unicode codepoints, etc)
//! * Read and write resources and annotations from/to STAM JSON, STAM CSV, or an optimised binary (CBOR) representation.
//!     * The underlying [STAM model](https://github.com/annotation/stam) aims to be clear and simple. It is flexible and
//!       does not commit to any vocabulary or annotation paradigm other than stand-off annotation.
//!
//! This STAM library is intended as a foundation upon which further applications
//! can be built that deal with stand-off annotations on text. We implement all the
//! low-level logic in dealing this so you no longer have to and can focus on your
//! actual application. The library is written with performance in mind.
//!
//! This is the root module for the STAM library. The STAM library consists of two APIs, a
//! low-level API and a high-level API, the latter is of most interest to end users and is
//! implemented in `api/*.rs`.
//!
//! ## Table of Contents (abridged)
//!
//! * [`AnnotationStore`] - The main annotation store that holds everything together.
//! * **Result items:** - These encapsulate the underlying primary structures and is the main way in which things are returned throughout the high-level API.
//!     * [`ResultItem<Annotation>`](struct.ResultItem.html#impl-ResultItem<'store,+Annotation>)
//!     * [`ResultItem<AnnotationDataSet>`](struct.ResultItem.html#impl-ResultItem<'store,+AnnotationDataSet>)
//!     * [`ResultItem<AnnotationData>`](struct.ResultItem.html#impl-ResultItem<'store,+AnnotationData>)
//!     * [`ResultItem<DataKey>`](struct.ResultItem.html#impl-ResultItem<'store,+DataKey>)
//!     * [`ResultItem<TextResource>`](struct.ResultItem.html#impl-ResultItem<'store,+TextResource>)
//!     * [`ResultTextSelection`]
//! * **Values and Operators:**
//!     * [`DataValue`] - Encapsulates an actual value and its type.
//!     * [`DataOperator`] - Defines a test done on a [`DataValue`]
//!     * [`TextSelectionOperator`] - Performs a particular comparison of text selections (e.g. overlap, embedding, adjacency, etc..)
//! * **Iterators:**
//!     * [`AnnotationIterator`] - Iterator trait to iterate over annotations, typically produced by an `annotations()` method.
//!     * [`DataIterator`] - Iterator trait to iterate over annotation data, typically produced by a `data()` method.
//!     * [`TextSelectionIterator`] - iterator (trait), typically produced by a `textselections()` or `related_text()` method.
//!     * [`ResourcesIterator`] - iterator (trait), typically produced by a `resources()` method.
//!     * [`KeyIterator`] - iterator (trait), typically produced by a `keys()` method.
//!     * [`TextIter`] - iterator over actual text, typically produced by a `text()` method.
//! * **Text operations:**
//!     * [`FindText`]  - Trait available on textresources and text selections to provide text-searching methods
//!     * [`Text`] - Lower-level API trait to obtain text.
//! * **Collections:**
//!     * [`Annotations`] == [`Handles<Annotation>`] - Arbitrary collection of [`Annotation`] (by reference)
//!     * [`Data`] == [`Handles<AnnotationData>`] - Arbitrary collection of [`AnnotationData`] (by reference)
//!     * [`Resources`] ==  [`Handles<TextResource>`] - Arbitrary collection of [`TextResource`] (by reference).
//!     * [`Keys`] == [`Handles<DataKey>`] - Arbitrary collection of [`DataKey`] (by reference).
//! * **Querying:**
//!     * [`Query`] - Holds a query, may be parsed from [STAMQL](https://github.com/annotation/stam/tree/master/extensions/stam-query).
//!     * [`QueryResultItems`]
//!     * [`QueryResultItem`]
//! * **Referencing Text (both high and low-level API):**
//!     * [`Cursor`] - Points to a text position, position may be relative.
//!     * [`Offset`] - Range (two cursors) that can be used to selects a text, positions may be relative.
//! * **Primary structures (low level API)**:
//!     * [`Annotation`]
//!     * [`AnnotationDataSet`]
//!     * [`AnnotationData`]
//!     * [`TextSelection`]
//!     * [`TextResource`]
//!     * [`DataKey`]

mod annotation;
mod annotationdata;
mod annotationdataset;
mod annotationstore;
mod api;
mod cbor;
mod config;
mod datakey;
mod datavalue;
mod error;
mod file;
mod json;
mod resources;
mod selector;
mod store;
mod substore;
mod text;
mod textselection;
mod types;

#[cfg(feature = "csv")]
mod csv;

#[cfg(feature = "textvalidation")]
mod textvalidation;

// Our internal crate structure is not very relevant to the outside world,
// expose all structs and traits in the root namespace, and be explicit about it:

#[cfg(feature = "csv")]
pub use crate::csv::{FromCsv, ToCsv};

pub use annotation::{Annotation, AnnotationBuilder, AnnotationHandle, ReannotateMode};
pub use annotationdata::{AnnotationData, AnnotationDataBuilder, AnnotationDataHandle};
pub use annotationdataset::{AnnotationDataSet, AnnotationDataSetBuilder, AnnotationDataSetHandle};
pub use annotationstore::AnnotationStore;
pub use api::*;
pub use config::{Config, Configurable};
pub use datakey::{DataKey, DataKeyHandle};
pub use datavalue::{DataOperator, DataValue};
pub use error::StamError;
pub use file::*;
pub use json::{FromJson, ToJson};
pub use resources::{
    PositionMode, TextResource, TextResourceBuilder, TextResourceHandle, TextSelectionIter,
};
pub use selector::{
    Offset, OffsetMode, Selector, SelectorBuilder, SelectorIter, SelectorKind, SelfSelector,
};
pub use store::{
    generate_id, regenerate_id, BuildItem, IdStrategy, Request, ResultItem, StamResult, Storable,
    Store, StoreFor,
};
pub use substore::{AnnotationSubStore, AnnotationSubStoreHandle, AssociateSubStore};
pub use text::Text;
pub use textselection::{
    ResultTextSelection, ResultTextSelectionSet, TestTextSelection, TextSelection,
    TextSelectionHandle, TextSelectionOperator, TextSelectionSet, TextSelectionSetIntoIter,
    TextSelectionSetIter,
};
pub use types::*;

pub use chrono::{DateTime, FixedOffset, Local, Utc};
pub use regex::{Regex, RegexBuilder, RegexSet};

mod tests;