From 0ad2c33ecbb55a58d612c901a85c8caa25fd85ec Mon Sep 17 00:00:00 2001 From: "NGnius (Graham)" Date: Fri, 31 Dec 2021 23:39:06 -0500 Subject: [PATCH] Add READMEs and top-level intro doc comments --- Cargo.toml | 3 +++ README.md | 9 +++++++++ mps-interpreter/Cargo.toml | 3 +++ mps-interpreter/README.md | 33 +++++++++++++++++++++++++++++++++ mps-interpreter/src/lib.rs | 30 ++++++++++++++++++++++++++++++ mps-player/Cargo.toml | 3 +++ mps-player/README.md | 6 ++++++ mps-player/src/lib.rs | 3 +++ src/main.rs | 5 +++++ 9 files changed, 95 insertions(+) create mode 100644 README.md create mode 100644 mps-interpreter/README.md create mode 100644 mps-player/README.md diff --git a/Cargo.toml b/Cargo.toml index 541f4a3..ad3e09e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,6 +4,9 @@ version = "0.1.0" edition = "2021" authors = ["NGnius (Graham) "] description = "Music Playlist Scripting language (MPS)" +license = "LGPL-2.1-only OR GPL-2.0-or-later" +license-file = "LICENSE" +readme = "README.md" [workspace] members = [ diff --git a/README.md b/README.md new file mode 100644 index 0000000..80d48ff --- /dev/null +++ b/README.md @@ -0,0 +1,9 @@ +# mps + +An MPS program which plays music. +This doesn't do much yet, since mps-interpreter is still under construction. + +Future home of a MPS REPL for playing music ergonomically through a CLI. + + +License: LGPL-2.1-only OR GPL-2.0-or-later diff --git a/mps-interpreter/Cargo.toml b/mps-interpreter/Cargo.toml index 28f8126..4423536 100644 --- a/mps-interpreter/Cargo.toml +++ b/mps-interpreter/Cargo.toml @@ -2,6 +2,9 @@ name = "mps-interpreter" version = "0.1.0" edition = "2021" +license = "LGPL-2.1-only OR GPL-2.0-or-later" +license-file = "LICENSE" +readme = "README.md" [dependencies] rusqlite = { version = "0.26.3" } diff --git a/mps-interpreter/README.md b/mps-interpreter/README.md new file mode 100644 index 0000000..fc95f4f --- /dev/null +++ b/mps-interpreter/README.md @@ -0,0 +1,33 @@ +# mps-interpreter + +All necessary components to interpret and run a MPS script. + +MpsInterpretor uses a non-standard Iterator implementation, +so it is recommended to use MpsRunner to execute a script. +Since MPS is centered around iterators, script execution is also done by iterating. + +MpsInterpretor is misspelt to emphasise that it behaves strangely: +after every MPS statement, a None item is returned even when the script is not complete. +MpsRunner wraps MpsInterpretor so that this behaviour is hidden when iterating. + +```rust +use std::io::Cursor; +use mps_interpreter::*; + +let cursor = Cursor::new( +"files(folder=`~/Music/`, recursive=true)" // retrieve all files from Music folder +); + +let interpreter = MpsRunner::with_stream(cursor); + +// warning: my library has ~3800 songs, so this outputs too much information to be useful. +for result in interpreter { + match result { + Ok(item) => println!("Got song `{}` (file: `{}`)", item.title, item.filename), + Err(e) => panic!("Got error while executing: {}", e), + } +} +``` + + +License: LGPL-2.1-only OR GPL-2.0-or-later diff --git a/mps-interpreter/src/lib.rs b/mps-interpreter/src/lib.rs index 66e0d79..b3e501d 100644 --- a/mps-interpreter/src/lib.rs +++ b/mps-interpreter/src/lib.rs @@ -1,3 +1,33 @@ +//! All necessary components to interpret and run a MPS script. +//! +//! MpsInterpretor uses a non-standard Iterator implementation, +//! so it is recommended to use MpsRunner to execute a script. +//! Since MPS is centered around iterators, script execution is also done by iterating. +//! +//! MpsInterpretor is misspelt to emphasise that it behaves strangely: +//! after every MPS statement, a None item is returned even when the script is not complete. +//! MpsRunner wraps MpsInterpretor so that this behaviour is hidden when iterating. +//! +//! ``` +//! use std::io::Cursor; +//! use mps_interpreter::*; +//! +//! let cursor = Cursor::new( +//! "files(folder=`~/Music/`, recursive=true)" // retrieve all files from Music folder +//! ); +//! +//! let interpreter = MpsRunner::with_stream(cursor); +//! +//! // warning: my library has ~3800 songs, so this outputs too much information to be useful. +//! for result in interpreter { +//! match result { +//! Ok(item) => println!("Got song `{}` (file: `{}`)", item.title, item.filename), +//! Err(e) => panic!("Got error while executing: {}", e), +//! } +//! } +//! ``` +//! + mod context; mod interpretor; pub mod lang; diff --git a/mps-player/Cargo.toml b/mps-player/Cargo.toml index c360dad..d938e52 100644 --- a/mps-player/Cargo.toml +++ b/mps-player/Cargo.toml @@ -2,6 +2,9 @@ name = "mps-player" version = "0.1.0" edition = "2021" +license = "LGPL-2.1-only OR GPL-2.0-or-later" +license-file = "LICENSE" +readme = "README.md" [dependencies] rodio = { version = "^0.14"} diff --git a/mps-player/README.md b/mps-player/README.md new file mode 100644 index 0000000..b06e0a2 --- /dev/null +++ b/mps-player/README.md @@ -0,0 +1,6 @@ +# mps-player + +An MPS playback library with support for Linux media controls (D-Bus). + + +License: LGPL-2.1-only OR GPL-2.0-or-later diff --git a/mps-player/src/lib.rs b/mps-player/src/lib.rs index 75c34dd..bf1add1 100644 --- a/mps-player/src/lib.rs +++ b/mps-player/src/lib.rs @@ -1,3 +1,6 @@ +//! An MPS playback library with support for Linux media controls (D-Bus). +//! + mod controller; mod errors; pub(crate) mod os_controls; diff --git a/src/main.rs b/src/main.rs index 864f43f..5d056a0 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,8 @@ +//! An MPS program which plays music. +//! This doesn't do much yet, since mps-interpreter is still under construction. +//! +//! Future home of a MPS REPL for playing music ergonomically through a CLI. +//! use std::io; use mps_interpreter::MpsRunner; use mps_player::{MpsPlayer, PlaybackError, MpsController};