diff --git a/USAGE.md b/USAGE.md index 3802cb4..1e8d4e5 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,74 +1,180 @@ -## Usage +# Usage -Beginning with the following dir structure +## Get started +Create an empty dir: ``` -├─── -│ └───.ark -│ ├───cache -│ │ ├───metadata -│ │ └───previews -│ └───user -│ ├───properties -│ ├───scores -│ └───tags +mkdir /tmp/test +cd /tmp/test ``` -First create some sample links +Let's fill it with something. One of the simplest ways to create resources it is to save a link to web page using `ark-cli link` command: +``` +$ ark-cli link create . http://google.com goo +$ ark-cli link create . http://duckduckgo.com duck +``` -`ark-cli link create http://google.com google hi` +We can use `ark-cli list` to see just created resources: +``` +22-207093268 +18-1909444406 +``` -`ark-cli link create http://bing.com bing hello` +These are just ids, derived from the URLs themselves. -Then add some tags to the links +Now, the dir structure should resemble this: +``` +/tmp/test +└───.ark + ├───cache + │ ├───metadata + │ └───previews + │ + └───user + ├───properties + ├───scores + └───tags +``` -`ark-cli file append tags search,engine` +### Label your data -The same way we can append scores +You can attach various metadata to your data, e.g. tags: +``` +$ ark-cli file append . tags 22-207093268 search,engine +``` -`ark-cli file append scores 15` +The same way we can append scores: +``` +$ ark-cli file append . scores 22-207093268 15 +``` + +Generic metadata is possible using JSON-based properties: +``` +$ ark-cli file append . properties 22-207093268 favorites:false,ai:true --format=json +``` -We can also append json data +### Navigate your data -`ark-cli file append properties favorites:false,ai:true --format=json` +The simplest command to observe your resources is `list`: +``` +$ ark-cli list + +18-1909444406 +22-207093268 +``` -You can read these properties +You can also target this command to other folders: +``` +$ ark-cli list ~/Pictures/ -`ark-cli file read properties ` +58922-3276384608 +62591-2492670715 +723145-720506115 +125308-3041567246 +``` -Or the scores +But it's a bit boring and doesn't really tell anything, right? Various flags should be used to gain more knowledge about your collections of resources: +* `--entry=id|path|both` to show the path,the id or both of a resource +* `--timestamp=true` to show or not the last modified timestamp of a resource +* `--tags=true` to show or not the tags for every resource +* `--scores=true` to show or not the scores for every resource +* `--sort=asc|desc` to sort resources by asc or dsc order of scores +* `--filter=query` to filter resources by their tags -`ark-cli file read scores ` +For instance, you can list files with their paths and attached tags: +``` +$ ark-cli list -pt -You can list the entries for a storage like this +30-4257856154 with tags search +18-1909444406 with tags hello +22-207093268 with tags search,engine +38-103010298 with tags NO_TAGS +``` -`ark-cli storage list properties` +Or, sort by score: +``` +$ ark-cli list -s --sort=asc -For more info you can add the versions flag +30-4257856154 with score NO_SCORE +18-1909444406 with score 2 +38-103010298 with score 10 +22-207093268 with score 15 +``` -`ark-cli storage list properties --versions=true` +Finally, you can filter resources using their tags: +``` +$ /tmp/ark-cli list -t --filter=search -Also works for file storages +30-4257856154 with tags search +22-207093268 with tags search,engine +``` -`ark-cli storage list scores --versions=true` +## :zap: Low-level utilities :zap: -List the files in the index using +There are commands which could be useful with time, when you grasp the basic concepts. Some of these commands also can be useful for debugging [ArkLib](https://github.com/ARK-Builders/ark-rust). -`ark-cli list ` +### Retrieve the metadata -`--entry=id|path|both` -> to show the path,the id or both of a resource +You can read these properties: +``` +$ ark-cli file read . properties 22-207093268 +{"ai":"true","desc":null,"favorites":"false","title":"duck"} +``` -`--timestamp=true` -> to show or not the last modified timestamp of a resource +As well as scores or tags: +``` +$ ark-cli file read . scores 22-207093268 +15 +$ ark-cli file read . tags 22-207093268 +search,engine +``` -`--tags=true` -> to show or not the tags for every resource +### Inspect storages -`--scores=true` -> to show or not the scores for every resource +It's also possible to list resources having some metadata in a particular storage: +``` +$ ark-cli storage list . properties +22-207093268 +18-1909444406 -`--sort=asc|desc` -> to sort resources by asc or dsc order of scores +$ ark-cli storage list . tags +22-207093268 -`--filter=query` -> to filter resources by their tags +$ ark-cli storage list . scores +22-207093268 +``` +Note that, in this example, resource with id `18-1909444406` is listed only in `properties` storage since it lacks any metadata in `tags` and `scores` storages. The `ark-cli storage list` command only lists entries of a particular storage, not all resources. +### Inspect versions +For delving into history of storage mutations, we made `--versions` flag: +``` +$ ark-cli storage list . properties --versions=true +version name machine path +2 22-207093268 0592a937-a5d1-4843-8f03-ae0d6a9e77b5 ./.ark/user/properties/22-207093268/22-207093268_0592a937-a5d1-4843-8f03-ae0d6a9e77b5.2 +1 18-1909444406 0592a937-a5d1-4843-8f03-ae0d6a9e77b5 ./.ark/user/properties/18-1909444406/18-1909444406_0592a937-a5d1-4843-8f03-ae0d6a9e77b5.1 +``` +Each storage mutation made by `ark-cli file append` or `ark-cli file insert` commands increases the number in `version` column. Versions help to prevent dirty-writes caused by using same storages by separate apps, or devices. +The `properties` storage is _folder-based_, but same command can be used with _file-based_ storages like `tags`: +``` +$ ark-cli storage list . tags --versions=true +Loading app id at /home/kirill/.ark... +id value +22-207093268 search,engine + +$ ark-cli file append . tags 22-207093268 wow +$ ark-cli storage list . tags --versions=true +id value +22-207093268 search,engine +22-207093268 wow + +$ ark-cli file append . tags 22-207093268 one_more_time +$ ark-cli storage list . tags --versions=true +id value +22-207093268 search,engine +22-207093268 wow +22-207093268 one_more_time +``` diff --git a/src/main.rs b/src/main.rs index 39191fa..3375f30 100644 --- a/src/main.rs +++ b/src/main.rs @@ -5,13 +5,7 @@ use std::str::FromStr; use arklib::id::ResourceId; use arklib::pdf::PDFQuality; -use arklib::{app_id, provide_index, INDEX_PATH}; -use arklib::{ - modify, AtomicFile, APP_ID_FILE, ARK_FOLDER, FAVORITES_FILE, - METADATA_STORAGE_FOLDER, PREVIEWS_STORAGE_FOLDER, - PROPERTIES_STORAGE_FOLDER, SCORE_STORAGE_FILE, STATS_FOLDER, - TAG_STORAGE_FILE, THUMBNAILS_STORAGE_FOLDER, -}; +use arklib::{app_id, provide_index}; use chrono::prelude::DateTime; use chrono::Utc; @@ -78,7 +72,7 @@ async fn main() { (None, true, false) => &EntryOutput::Id, (None, false, true) => &EntryOutput::Path, (None, true, true) => &EntryOutput::Both, - (None, false, false) => &EntryOutput::Id, // default value + (None, false, false) => &EntryOutput::Id, // default mode _ => panic!( "incompatible entry output options, please choose only one" ), diff --git a/src/models/storage.rs b/src/models/storage.rs index 8f5d3a9..f9ed932 100644 --- a/src/models/storage.rs +++ b/src/models/storage.rs @@ -128,14 +128,13 @@ impl Storage { ) -> Result<(), String> { match self.storage_type { StorageType::File => { - let atomic_file = AtomicFile::new(&self.path) - // .expect("ERROR: Could not create atomic file"); - .map_err(|e| { - format!( - "Failed to create atomic file at {} with error: {:?}", - self.path.display(), e - ) - })?; + let atomic_file = AtomicFile::new(&self.path).map_err(|e| { + format!( + "Failed to create atomic file at {} with error: {:?}", + self.path.display(), + e + ) + })?; let content = match format { Format::KeyValue => return Err(