Crate atomic_lib

source · [−]
Expand description

atomic_lib helps you to get, store, serialize, parse and validate Atomic Data.

See the Atomic Data Docs for more information.

Features

  • Two stores for Atomic Data:
    • In-memory Store for getting / setting data. Useful for client applications.
    • On disk [Db], powered by Sled. Useful for applications that persist Atomic Data, such as atomic-server.
  • serialize and parse tools for JSON-AD, plain JSON, RDF, Turtle, N-Triples and JSON-LD.
  • Resource with getters, setters and a .save function that creates Commits.
  • Value converts Atomic Data to Rust native types
  • Validate Atomic Schema
  • Commits (transactions / delta’s / changes / updates / versioning / history).
  • [plugins] system (although not very mature)
  • collections (pagination, sorting, filtering)
  • Querying (using triple pattern fragments) (see storelike::Query)
  • [plugins::invite] for sharing
  • hierarchy for authorization
  • [crate::endpoints::Endpoint] for custom API endpoints
  • [config::Config] files.

Getting started

// Import the `Storelike` trait to get access to most functions
use atomic_lib::Storelike;
// Start with initializing the in-memory store
let store = atomic_lib::Store::init().unwrap();
// Pre-load the default Atomic Data Atoms (from atomicdata.dev),
// this is not necessary, but will probably make your project a bit faster
store.populate().unwrap();
// We can create a new Resource, linked to the store.
// Note that since this store only exists in memory, it's data cannot be accessed from the internet.
// Let's make a new Property instance! Let's create "age".
let mut new_property = atomic_lib::Resource::new_instance("https://atomicdata.dev/classes/Property", &store).unwrap();
// And add a description for that Property
new_property.set_propval_shortname("description", "the age of a person", &store).unwrap();
// A subject URL for the new resource has been created automatically.
let subject = new_property.get_subject().clone();
// Now we need to make sure these changes are also applied to the store.
// In order to change things in the store, we should use Commits,
// which are signed pieces of data that contain state changes.
// Because these are signed, we need an Agent, which has a private key to sign Commits.
let agent = store.create_agent(Some("my_agent")).unwrap();
store.set_default_agent(agent);
let _fails   = new_property.save_locally(&store);
// But.. when we commit, we get an error!
// Because we haven't set all the properties required for the Property class.
// We still need to set `shortname` and `datatype`.
new_property.set_propval_shortname("shortname", "age", &store).unwrap();
new_property.set_propval_shortname("datatype", atomic_lib::urls::INTEGER, &store).unwrap();
new_property.save_locally(&store).unwrap();
// Now the changes to the resource applied to the store, and we can fetch the newly created resource!
let fetched_new_resource = store.get_resource(&subject).unwrap();
assert!(fetched_new_resource.get_shortname("description", &store).unwrap().to_string() == "the age of a person");

Re-exports

pub use atoms::Atom;
pub use commit::Commit;
pub use errors::AtomicError;
pub use errors::AtomicErrorType;
pub use resources::Resource;
pub use store::Store;
pub use storelike::Storelike;
pub use values::Value;

Modules

agents

Logic for Agents Agents are actors (such as users) that can edit content. https://docs.atomicdata.dev/commits/concepts.html

atoms

The smallest units of data, consiting of a Subject, a Property and a Value

authentication

Check signatures in authentication headers, find the correct agent. Authorization is done in Hierarchies

client

Functions for interacting with an Atomic Server

collections

Collections are dynamic resources that refer to multiple resources. They are constructed using a TPF query

commit

Describe changes / mutations to data

datatype

Datatypes constrain values of Atoms

errors

The Error type that you can expect when using this library

hierarchy

The Hierarchy model describes how Resources are structed in a tree-like shape. It deals with authorization (read / write permissions, rights, grants) See

mapping

Because writing full URLs is error prone and time consuming, we map URLs to shortnames. These are often user-specific. This section provides tools to store, share and resolve these Mappings.

parse

Parsing / deserialization / decoding

populate

Populating a Store means adding resources to it. Some of these are the core Atomic Data resources, such as the Property class. These base models are required for having a functioning store. Other populate methods help to set up an Atomic Server, by creating a basic file hierarcy and creating default collections.

resources

A resource is a set of Atoms that share a URL

schema

Structs and models at the core of Atomic Schema (Class, Property, Datatype).

serialize

Serialization / formatting / encoding (JSON, RDF, N-Triples)

store

In-memory store of Atomic data. This provides many methods for finding, changing, serializing and parsing Atomic Data.

storelike

The Storelike Trait contains many useful methods for maniupulting / retrieving data.

urls

Contains some of the most important Atomic Data URLs.

utils

Helper functions for dealing with URLs

validate

Validate the Store and create a ValidationReport. Might be deprecated soon, as Validation hasn’t been necessary since parsing has built-in data validation.

values

A value is the part of an Atom that contains the actual information.