Add a brief README and LICENSE
- ID
852e623- date
2025-01-11 11:11:08+00:00- author
Alex Chan <alex@alexwlchan.net>- parent
1e62d75- message
Add a brief README and LICENSE- changed files
Changed files
LICENSE (0) → LICENSE (1053)
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..ddc366e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2025 Alex Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
README.md (0) → README.md (1397)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ba7f41f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+# randline
+
+This tool picks one or more random lines from a file (or anything else you pass to it).
+
+```console
+$ randline < /usr/share/dict/words
+Urania
+
+$ randline 3 < /usr/share/dict/words
+foolhardiness
+rhinoscopic
+wormhood
+```
+
+
+
+
+## How it works
+
+This tool uses [reservoir sampling](https://en.wikipedia.org/wiki/Reservoir_sampling) to select the random lines; in particular Algorithm L.
+
+I wrote it as a way to understand how reservoir sampling works, and to try using Rust generics.
+Although the final tool only deals with strings, the underlying `reservoir_sample` can sample iterators of any type.
+
+
+
+
+
+## Installation
+
+You can download compiled binaries from the [GitHub releases](https://github.com/alexwlchan/randline/releases).
+
+Alternatively, you can install from source.
+You need Rust installed; I recommend using [Rustup].
+Then clone this repository and compile the code:
+
+```console
+$ git clone "https://github.com/alexwlchan/emptydir.git"
+$ cd emptydir
+$ cargo install --path .
+```
+
+[Rustup]: https://rustup.rs/
+
+
+
+
+
+## Usage
+
+You need to pipe input to `randline`.
+If you don't pass an argument, it will print a single random line.
+
+```console
+$ randline < /usr/share/dict/words
+blithen
+```
+
+You can choose the number of random lines to print by passing a single argument `k`:
+
+```console
+$ randline 3 < /usr/share/dict/words
+unprofessed
+ragout
+Tarpeia
+```
+
+
+
+
+
+## License
+
+MIT.