Skip to content

Commit

Permalink
Minor changes. Update Usage.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@kirillt @tareknaser
kirillt authored and tareknaser committed Mar 14, 2024
1 parent a75f2cc commit 8133b6d
Show file tree
Hide file tree
Showing 3 changed files with 153 additions and 54 deletions.
182 changes: 144 additions & 38 deletions USAGE.md
View file
Original file line number Diff line number Diff line change
@@ -1,74 +1,180 @@
## Usage
# Usage

Beginning with the following dir structure
## Get started

Create an empty dir:
```
├───<root_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 <root_dir> http://google.com google hi`
We can use `ark-cli list` to see just created resources:
```
22-207093268
18-1909444406
```

`ark-cli link create <root_dir> 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 <root_dir> tags <resource_id> 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 <root_dir> scores <resource_id> 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 <root_dir> properties <resource_id> 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 <root_dir> properties <resource_id>`
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 <root_dir> scores <resource_id>`
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 <root_dir> 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 <root_dir> 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 <root_dir> 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 <root_dir>`
### 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
```
10 changes: 2 additions & 8 deletions src/main.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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"
),
Expand Down
15 changes: 7 additions & 8 deletions src/models/storage.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down

0 comments on commit 8133b6d

Please sign in to comment.