Add unique filters help docs

mps-interpreter/README.md

@@ -89,6 +89,11 @@ Matches all items
 
 Replace items matching the filter with operation1 and replace items not matching the filter with operation2. The `else operation2` part may be omitted to preserve items not matching the filter. To perform operations with the current item, use the special variable `item`. The replacement filter may not contain || -- instead, use multiple filters chained together.
 
+#### unique
+#### unique field -- e.g. `iterable.(unique title);`
+
+Keep only items which are do not duplicate another item, or keep only items whoes specified field does not duplicate another item's same field. The first non-duplicated instance of an item is always the one that is kept.
+
 ### Functions
 Similar to most other languages: `function_name(param1, param2, etc.);`.
 These always return an iterable which can be manipulated.
@@ -150,39 +155,39 @@ Combine multiple iterables such that only items that exist in iterable1 and iter
 Empty iterator. Useful for deleting items using replacement filters.
 
 ### Sorters
-Operations to sort the items in an iterable: iterable~(sorter) OR iterable.sort(sorter)
+Operations to sort the items in an iterable: `iterable~(sorter)` OR `iterable.sort(sorter)`.
 
-#### field -- e.g. iterable~(filename)
+#### field -- e.g. `iterable~(filename);`
 
 Sort by a MpsItem field. Valid field names change depending on what information is available when the MpsItem is populated, but usually title, artist, album, genre, track, filename are valid fields. Items with a missing/incomparable fields will be sorted to the end.
 
 #### shuffle
-#### random shuffle -- e.g. iterable~(shuffle)
+#### random shuffle -- e.g. `iterable~(shuffle);`
 
 Shuffle the songs in the iterator. This is random for up to 2^16 items, and then the randomness degrades (but at that point you won't notice). The more verbose syntax is allowed in preparation for future randomisation strategies.
 
-#### advanced bliss_first -- e.g. iterable~(advanced bliss_first)
+#### advanced bliss_first -- e.g. `iterable~(advanced bliss_first);`
 
 Sort by the distance (similarity) from the first song in the iterator. Songs which are more similar (lower distance) to the first song in the iterator will be placed closer to the first song, while less similar songs will be sorted to the end. This uses the [bliss music analyser](https://github.com/polochon-street/bliss-rs), which is a very slow operation and can cause music playback interruptions for large iterators. This requires the `advanced` feature to be enabled (without the feature enabled this is still valid syntax but doesn't change the order).
 
-#### advanced bliss_next -- e.g. iterable~(advanced bliss_next)
+#### advanced bliss_next -- e.g. `iterable~(advanced bliss_next);`
 
 Sort by the distance (similarity) between the last played song in the iterator. Similar to bliss_first. The song which is the most similar (lower distance) to the previous song in the iterator will be placed next to it, then the process is repeated. This uses the [bliss music analyser](https://github.com/polochon-street/bliss-rs), which is a very slow operation and can cause music playback interruptions for large iterators. This requires the `advanced` feature to be enabled (without the feature enabled this is still valid syntax but doesn't change the order).
 
 ### Procedures
-Operations to apply to each item in an iterable: iterable.{step1, step2, ...}
+Operations to apply to each item in an iterable: `iterable.{step1, step2, ...}`;
 
 Comma-separated procedure steps will be executed sequentially (like a for loop in regular programming languages). The variable item contains the current item of the iterable.
 
-#### let variable = something -- e.g. let my_var = 42
+#### let variable = something -- e.g. `let my_var = 42,`
 
 Declare the variable and (optionally) set the initial value to something. The assignment will only be performed when the variable has not yet been declared. When the initial value (and equals sign) is omitted, the variable is initialized as empty().
 
-#### variable = something -- e.g. my_var = 42
+#### variable = something -- e.g. `my_var = 42,`
 
 Assign something to the variable. The variable must have already been declared.
 
-#### empty() -- e.g. empty()
+#### empty() -- e.g. `empty(),`
 
 The empty or null constant.
 
@@ -202,11 +207,11 @@ if item.title == `Romantic Traffic` {
 #### something1 >= something2
 #### something1 > something2
 #### something1 <= something2
-#### something1 < something2 -- e.g. item.filename != item.title
+#### something1 < something2 -- e.g. `item.filename != item.title,`
 
 Compare something1 to something2. The result is a boolean which is useful for branch conditions.
 
-#### op iterable_operation -- e.g. op files().(0..=42)~(shuffle)
+#### op iterable_operation -- e.g. `op files().(0..=42)~(shuffle),`
 
 An iterable operation inside of the procedure. When assigned to item, this can be used to replace item with multiple others. Note that iterable operations are never executed inside the procedure; when item is iterable, it will be executed immediately after the end of the procedure for the current item.
 
@@ -215,14 +220,14 @@ An iterable operation inside of the procedure. When assigned to item, this can b
 #### something1 - something2
 #### something1 + something2
 #### something1 || something2
-#### something1 && something2 -- e.g. 42 + (128 - 64)
+#### something1 && something2 -- e.g. `42 + (128 - 64),`
 
 Various algebraic operations: brackets (order of operations), negation, subtraction, addition, logical OR, logical AND; respectively.
 
-#### Item(field1 = something1, field2 = something2, ...) - e.g. item = Item(title = item.title, filename = `/dev/null`)
+#### Item(field1 = something1, field2 = something2, ...) - e.g. `item = Item(title = item.title, filename = "/dev/null"),`
 
    Constructor for a new item. Each function parameter defines a new field and it's value.
-#### ~`string_format` something -- e.g. ~`{filename}` item
+#### ~"string_format" something -- e.g. `~"{filename}" item,`
 
    Format a value into a string. This behaves differently depending on the value's type: When the value is an Item, the item's corresponding field will replace all `{field}` instances in the format string. When the value is a primitive type (String, Int, Bool, etc.), the value's text equivalent will replace all `{}` instances in the format string. When the value is an iterable operation (Op), the operation's script equivalent will replace all `{}` instances in the format string.
 

mps-interpreter/src/lib.rs

@@ -87,6 +87,11 @@
 //!
 //! Replace items matching the filter with operation1 and replace items not matching the filter with operation2. The `else operation2` part may be omitted to preserve items not matching the filter. To perform operations with the current item, use the special variable `item`. The replacement filter may not contain || -- instead, use multiple filters chained together.
 //!
+//! ### unique
+//! ### unique field -- e.g. `iterable.(unique title);`
+//!
+//! Keep only items which are do not duplicate another item, or keep only items whoes specified field does not duplicate another item's same field. The first non-duplicated instance of an item is always the one that is kept.
+//!
 //! ## Functions
 //! Similar to most other languages: `function_name(param1, param2, etc.);`.
 //! These always return an iterable which can be manipulated.
@@ -148,39 +153,39 @@
 //! Empty iterator. Useful for deleting items using replacement filters.
 //!
 //! ## Sorters
-//! Operations to sort the items in an iterable: iterable~(sorter) OR iterable.sort(sorter)
+//! Operations to sort the items in an iterable: `iterable~(sorter)` OR `iterable.sort(sorter)`.
 //!
-//! ### field -- e.g. iterable~(filename)
+//! ### field -- e.g. `iterable~(filename);`
 //!
 //! Sort by a MpsItem field. Valid field names change depending on what information is available when the MpsItem is populated, but usually title, artist, album, genre, track, filename are valid fields. Items with a missing/incomparable fields will be sorted to the end.
 //!
 //! ### shuffle
-//! ### random shuffle -- e.g. iterable~(shuffle)
+//! ### random shuffle -- e.g. `iterable~(shuffle);`
 //!
 //! Shuffle the songs in the iterator. This is random for up to 2^16 items, and then the randomness degrades (but at that point you won't notice). The more verbose syntax is allowed in preparation for future randomisation strategies.
 //!
-//! ### advanced bliss_first -- e.g. iterable~(advanced bliss_first)
+//! ### advanced bliss_first -- e.g. `iterable~(advanced bliss_first);`
 //!
 //! Sort by the distance (similarity) from the first song in the iterator. Songs which are more similar (lower distance) to the first song in the iterator will be placed closer to the first song, while less similar songs will be sorted to the end. This uses the [bliss music analyser](https://github.com/polochon-street/bliss-rs), which is a very slow operation and can cause music playback interruptions for large iterators. This requires the `advanced` feature to be enabled (without the feature enabled this is still valid syntax but doesn't change the order).
 //!
-//! ### advanced bliss_next -- e.g. iterable~(advanced bliss_next)
+//! ### advanced bliss_next -- e.g. `iterable~(advanced bliss_next);`
 //!
 //! Sort by the distance (similarity) between the last played song in the iterator. Similar to bliss_first. The song which is the most similar (lower distance) to the previous song in the iterator will be placed next to it, then the process is repeated. This uses the [bliss music analyser](https://github.com/polochon-street/bliss-rs), which is a very slow operation and can cause music playback interruptions for large iterators. This requires the `advanced` feature to be enabled (without the feature enabled this is still valid syntax but doesn't change the order).
 //!
 //! ## Procedures
-//! Operations to apply to each item in an iterable: iterable.{step1, step2, ...}
+//! Operations to apply to each item in an iterable: `iterable.{step1, step2, ...}`;
 //!
 //! Comma-separated procedure steps will be executed sequentially (like a for loop in regular programming languages). The variable item contains the current item of the iterable.
 //!
-//! ### let variable = something -- e.g. let my_var = 42
+//! ### let variable = something -- e.g. `let my_var = 42,`
 //!
 //! Declare the variable and (optionally) set the initial value to something. The assignment will only be performed when the variable has not yet been declared. When the initial value (and equals sign) is omitted, the variable is initialized as empty().
 //!
-//! ### variable = something -- e.g. my_var = 42
+//! ### variable = something -- e.g. `my_var = 42,`
 //!
 //! Assign something to the variable. The variable must have already been declared.
 //!
-//! ### empty() -- e.g. empty()
+//! ### empty() -- e.g. `empty(),`
 //!
 //! The empty or null constant.
 //!
@@ -200,11 +205,11 @@
 //! ### something1 >= something2
 //! ### something1 > something2
 //! ### something1 <= something2
-//! ### something1 < something2 -- e.g. item.filename != item.title
+//! ### something1 < something2 -- e.g. `item.filename != item.title,`
 //!
 //! Compare something1 to something2. The result is a boolean which is useful for branch conditions.
 //!
-//! ### op iterable_operation -- e.g. op files().(0..=42)~(shuffle)
+//! ### op iterable_operation -- e.g. `op files().(0..=42)~(shuffle),`
 //!
 //! An iterable operation inside of the procedure. When assigned to item, this can be used to replace item with multiple others. Note that iterable operations are never executed inside the procedure; when item is iterable, it will be executed immediately after the end of the procedure for the current item.
 //!
@@ -213,15 +218,15 @@
 //! ### something1 - something2
 //! ### something1 + something2
 //! ### something1 || something2
-//! ### something1 && something2 -- e.g. 42 + (128 - 64)
+//! ### something1 && something2 -- e.g. `42 + (128 - 64),`
 //!
 //! Various algebraic operations: brackets (order of operations), negation, subtraction, addition, logical OR, logical AND; respectively.
 //!
-//! ### Item(field1 = something1, field2 = something2, ...) - e.g. item = Item(title = item.title, filename = `/dev/null`)
+//! ### Item(field1 = something1, field2 = something2, ...) - e.g. `item = Item(title = item.title, filename = "/dev/null"),`
 //!
 //!    Constructor for a new item. Each function parameter defines a new field and it's value.
 
-//! ### ~`string_format` something -- e.g. ~`{filename}` item
+//! ### ~"string_format" something -- e.g. `~"{filename}" item,`
 //!
 //!    Format a value into a string. This behaves differently depending on the value's type: When the value is an Item, the item's corresponding field will replace all `{field}` instances in the format string. When the value is a primitive type (String, Int, Bool, etc.), the value's text equivalent will replace all `{}` instances in the format string. When the value is an iterable operation (Op), the operation's script equivalent will replace all `{}` instances in the format string.
 //!

src/help.rs

@@ -78,7 +78,11 @@ Operations to reduce the items in an iterable: iterable.(filter)
     Matches all items
 
  if filter: operation1 else operation2 -- e.g. iterable.(if title == `Romantic Traffic`: repeat(item, 2) else item.())
-    Replace items matching the filter with operation1 and replace items not matching the filter with operation2. The `else operation2` part may be omitted to preserve items not matching the filter. To perform operations with the current item, use the special variable `item`. The replacement filter may not contain || -- instead, use multiple filters chained together.";
+    Replace items matching the filter with operation1 and replace items not matching the filter with operation2. The `else operation2` part may be omitted to preserve items not matching the filter. To perform operations with the current item, use the special variable `item`. The replacement filter may not contain || -- instead, use multiple filters chained together.
+
+ unique
+ unique field -- e.g. iterable.(unique title)
+    Keep only items which are do not duplicate another item, or keep only items whoes specified field does not duplicate another item's same field. The first non-duplicated instance of an item is always the one that is kept.";
 
 pub const SORTERS: &str =
 "SORTERS (?sorters)