0.3.0: Updated README and version

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tvrank"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 description = "Query and sort information about movies and series"
 authors = ["Fred Morcos <[email protected]>"]

README.md

@@ -6,7 +6,7 @@
 [![CI](https://img.shields.io/github/workflow/status/fredmorcos/tvrank/CI?label=Master&style=for-the-badge)](https://github.com/fredmorcos/tvrank/actions)
 </br>
 [![Crates.io](https://img.shields.io/crates/v/tvrank?style=for-the-badge)](https://crates.io/crates/tvrank)
-[![docs.rs](https://img.shields.io/docsrs/tvrank?style=for-the-badge)](https://docs.rs/tvrank/0.2.0/tvrank/)
+[![docs.rs](https://img.shields.io/docsrs/tvrank?style=for-the-badge)](https://docs.rs/tvrank/0.3.0/tvrank/)
 
 [Github Repository](https://github.com/fredmorcos/tvrank)
 
@@ -18,8 +18,9 @@ Currently, `tvrank` only supports IMDB's TSV dumps which it automatically downlo
 caches and periodically updates. More work is required to be able to support and cache
 live-query services like TMDB.
 
-Additionally, the in-memory database can be vastly improved through indexing. Also, the
-library's documentation is missing but there is an example on how to use it.
+Additionally, the "in-memory database" could use improvements through indexing and through
+adding support for a persistent cache. Also, the library's documentation is missing but
+there is an example on how to use it.
 
 For now, the command-line utility of `tvrank` works well and fast enough to be usable.
 
@@ -32,62 +33,57 @@ mode is built with debugging information enabled for convenience during developm
 
 For information on how to use the library, see below.
 
-The `tvrank` command-line interface has two modes modeled as sub-commands: `title` to
-query a single title given on the command-line, and `dir` to make batch queries based on
-directory scans.
+The `tvrank` command-line interface has a few modes enabled by the use of sub-commands:
+`title "TITLE (YYYY)"` to search for titles (by title and year), `title "keyword1 keyword2
+..."` to search titles based on keywords, `movies-dir` and `series-dir` to make batch
+queries based on directory scans.
 
 To query a single title:
 
-```sh
-tvrank title "the great gatsby"
-```
-
-or
-
 ```sh
 tvrank title "the great gatsby (2013)"
 ```
 
-To query a directory:
+To query based on keywords:
 
 ```sh
-tvrank dir <MEDIA_DIR>
+tvrank title "the great gatsby"
 ```
 
-By default `tvrank` will query the movies database, to instead query the series database,
-`--series` can be passed before any sub-command:
+To query a series directory:
 
 ```sh
-tvrank --series dir <MEDIA_DIR>
+tvrank series-dir <MEDIA_DIR>
 ```
 
-Also, by default `tvrank` will sort by year, rating and title. To instead sort by rating,
-year and title, `--sort-by-rating` can be passed before any sub-command:
+Also, by default `tvrank` will sort by rating, year and title. To instead sort by year,
+rating and title, `--sort-by-year` can be passed before any sub-command:
 
 ```sh
-tvrank --sort-by-rating --series title "house of cards"
+tvrank --sort-by-year title "house of cards"
 ```
 
 To print out more information about what the application is doing, use `-v` before any
 sub-command. Multiple occurrences of `-v` on the command-line will increase the verbosity
 level:
 
 ```sh
-tvrank -vvv --sort-by-rating "city of god"
+tvrank -vvv --sort-by-year title "city of god"
 ```
 
 To find help, see the `help` sub-command:
 
 ```sh
 tvrank help
 tvrank help title
-tvrank help dir
+tvrank help series-dir
+tvrank help movies-dir
 ```
 
 ### Screencast
 
-Please note that the screencast is slightly outdated. Please use the `dir` sub-command
-instead of `-d` as used in the screencast.
+Please note that the screencast is slightly outdated. Please use the `movies-dir` or
+`series-dir` sub-commands instead of `-d` as used in the screencast.
 
 <p align="center">
     <img src="screencasts/screencast_2021-11-22.gif">
@@ -99,7 +95,7 @@ Add the dependency to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-tvrank = "0.2"
+tvrank = "0.3"
 ```
 
 Or, using `cargo add`:
@@ -114,66 +110,82 @@ Include the `Imdb` type:
 use tvrank::imdb::Imdb;
 ```
 
-Create a directory for the cache using the `tempfile` crate, and pass that to the
-`ImdbStorage` constructor then create the database service:
+Create a directory for the cache using the `tempfile` crate, create some functions that
+will work as callbacks for status updates by the storage backend, and pass all of that to
+the `ImdbStorage` constructor then create the database service:
 
 ```rust
 let cache_dir = tempfile::Builder::new().prefix("tvrank_").tempdir()?;
+
+fn download_init(name: &str, content_len: Option<u64>) {
+  println!("Starting download of {} (size = {:?})", name, content_len);
+}
+
+fn download_progress(_userdata: &(), _delta: u64) {}
+
+fn download_finish(_userdata: &()) {
+  println!("Finished download");
+}
+
+fn extract_init(name: &str) {
+  println!("Extracting {}", name);
+}
+
+fn extract_progress(_userdata: &(), _delta: u64) {}
+
+fn extract_finish(_userdata: &()) {
+  println!("Finished extracting");
+}
+
 let storage = ImdbStorage::new(
   cache_dir.path(),
-  |db_name, content_len| {
-    println!("Starting download of {} (size = {:?})", db_name, content_len);
-  },
-  |_, _| {},
-  |_| {
-    println!("Finished download");
-  },
-  |db_name| {
-    println!("Decompressing {}", db_name);
-  },
-  |_, _| {},
-  |_| {
-    println!("Finished decompression");
-  },
+  false,
+  &(download_init, download_progress, download_finish),
+  &(extract_init, extract_progress, extract_finish),
 )?;
-let imdb = Imdb::new(&storage)?;
+let imdb = Imdb::new(8, &storage)?;
 ```
 
-Note that the storage constructor takes 6 closures: `on_download_init`,
-`on_download_progress`, `on_download_finish`, `on_extract_init`, `on_extract_progress` and
-`on_extract_finish`. These are meant to print progress, or create a progress bar object
-and pass it around for updates.
+Note that the storage constructor takes 6 closures as callbacks: `download_init`,
+`download_progress`, `download_finish`, `extract_init`, `extract_progress` and
+`extract_finish`. These are meant to print progress, or create a progress bar object and
+pass it around for updates.
 
-Afterwards, one can query the database using either `imdb.movies_by_title(...)` or
-`imdb.series_by_title(...)`, and print out some information about the results. Note that
-the return type of `Imdb::movies_by_title` is a vector of vectors of titles, this is due
-to the multi-threaded nature of the service: each vector contains the resulting titles
-from each thread.
+Afterwards, one can query the database using either `imdb.by_id(...)`,
+`imdb.by_title_and_year(...)` or `imdb.by_keywords(...)`, and print out some information
+about the results.
 
 ```rust
-for titles in imdb.movies_by_title("city of god".as_bytes(), Some(2002))? {
-  for title in titles {
-    let id = title.title_id();
-
-    println!("ID: {}", id);
-    println!("Primary name: {}", title.primary_title());
-    println!("Original name: {}", title.original_title());
-
-    if let Some((rating, votes)) = title.rating() {
-      println!("Rating: {}/100 ({} votes)", rating, votes);
-    } else {
-      println!("Rating: N/A");
-    }
-
-    if let Some(runtime) = title.runtime() {
-      println!("Runtime: {}", humantime::format_duration(runtime));
-    } else {
-      println!("Runtime: N/A");
-    }
-
-    println!("Genres: {}", title.genres());
-    println!("--");
+let title = "city of god";
+let year = 2002;
+
+println!("Matches for {} and {:?}:", title, year);
+
+for title in imdb.by_title_and_year(title, year, ImdbQueryType::Movies)? {
+  let id = title.title_id();
+
+  println!("ID: {}", id);
+  println!("Primary name: {}", title.primary_title());
+  if let Some(original_title) = title.original_title() {
+    println!("Original name: {}", original_title);
+  } else {
+    println!("Original name: N/A");
+  }
+
+  if let Some((rating, votes)) = title.rating() {
+    println!("Rating: {}/100 ({} votes)", rating, votes);
+  } else {
+    println!("Rating: N/A");
   }
+
+  if let Some(runtime) = title.runtime() {
+    println!("Runtime: {}", humantime::format_duration(runtime));
+  } else {
+    println!("Runtime: N/A");
+  }
+
+  println!("Genres: {}", title.genres());
+  println!("--");
 }
 ```
 

examples/query.rs

@@ -3,6 +3,8 @@
 use tvrank::imdb::{Imdb, ImdbQueryType, ImdbStorage};
 
 fn main() -> tvrank::Res<()> {
+  let cache_dir = tempfile::Builder::new().prefix("tvrank_").tempdir()?;
+
   fn download_init(name: &str, content_len: Option<u64>) {
     println!("Starting download of {} (size = {:?})", name, content_len);
   }
@@ -23,7 +25,6 @@ fn main() -> tvrank::Res<()> {
     println!("Finished extracting");
   }
 
-  let cache_dir = tempfile::Builder::new().prefix("tvrank_").tempdir()?;
   let storage = ImdbStorage::new(
     cache_dir.path(),
     false,