[−][src]Crate owoof

I have a wordy post on my blog that talks a little bit about why this is and how it was designed. But it's very high-level and you shouldn't read that. This is terse and to-the-point; so read this instead.

How is this organized?

lib.rs (this file) defines a Session which wraps and owns an active database transaction. Can be used to Session::assert Session::retract or Session::find data. Probably a good starting point.
types has a few things used to model the database and our "datoms", like types::EntityId, types::AttributeName, and types::Value. These are used by & designed for a projection::Projection<types::Value>.
projection contains a bunch of stuff for taking entity-attribute-value patterns and selecting on them in order to find things in the database. The projection::Projection is pretty cool.
explain just has some implementation for running EXPLAIN and EXPLAIN PLAN queries in SQLite. Those are accessible through Session::explain & Session::explain_plan.
sql just has a bunch of SQL query string building stuff.

Why & How?

The point of the library is to interact with a SQLite-backed database using entity-attribute-value "datoms" and pattern matching.

If you didn't read the blog post I linked above (I don't blame you), here's a tldr.

Consider a database that looks like ...

100 :animal/name  "Cat"
100 :pet/name     "Garfield"
101 :animal/name  "Dog"
101 :pet/name     "Odie"
102 :person/name  "John Arbuckle"
100 :pet/human    102
101 :pet/human    102

And consider this pattern ...

?_ :pet/name ?_

If we were to match datoms using this pattern, we'd be asking for datoms with: any entity, for the :pet/name attribute, and any value. And we would get the following two datoms.

100 :pet/name    "Garfield"
101 :pet/name    "Odie"

Those are the datoms that exist that match that pattern.

Now consider two patterns together ...

?a :pet/name     ?_
?a :animal/name  "Cat"

The first pattern matches the set of two datoms from earlier. The second matches just:

100 :animal/name "Cat"

But we are not interested in every combination of datoms matched by both patterns. So we related the patterns by constraining the entity to the same variable, ?a. This means that we only match the combinations of datoms between either set when they have the same entity. So we end up with one result with two datoms.

100 :pet/name    "Garfield"
100 :animal/name "Cat"

It's like if we were to say:

Match every datom having the attribute :pet/name with any value and for some any entity named ?a, match also datoms on the same entity ?a having the attribute :animal/name with the value "Cat".

Another one might be:

?p :person/name ?person
?a :pet/human   ?p
?a :pet/name    ?pet

Here, the variables ?human and ?pet don't relate datoms together, but they're there so we can refer to them when we want to get information out.

These patterns are saying:

Given each entity ?a having the :pet/name ?pet and each entity ?p having the :person/name ?person, match only combinations of these where there exists some datom ?a :pet/human ?p. That is, where ?a's human is ?p.

The point of this library/program is to allow us to use the above expression to pattern match on our database and read values by querying variables; like ?person and ?pet to get the two results:

"John Arbuckle" "Garfield"
"John Arbuckle" "Odie"

Check out the projection module for more fun documentation.

Re-exports

pub use projection::AttributeMap;

pub use projection::Location;

pub use projection::Match;

pub use projection::Ordering;

pub use projection::Pattern;

pub use projection::Projection;

pub use projection::Selection;

pub use types::Affinity;

pub use types::Attribute;

pub use types::AttributeName;

pub use types::Entity;

pub use types::EntityId;

pub use types::FromAffinityValue;

pub use types::HasAffinity;

pub use types::RowIdOr;

pub use types::Value;

Modules

explain
projection	So if you read the essay over in lib.rs we saw that sequence of patterns could be used to gather sets of datoms and relate them to each other.
sql
types

Macros

_varorval
pat

Structs

Session

Wraps a rusqlite::Transaction to provide this crate's features.

Enums

Error