setop-0.1.0.0: README.org

* Setop: Perform set operations on files
** Rationale

[[https://en.wikipedia.org/wiki/Set_(mathematics)#Basic_operations][Set operations]] are a convenient solution to common problems:

- create a list of tasks without duplicates (set union)
- filter tasks done out of tasks to do (set difference)
- find common elements in a database (set intersection)
- and remove theses elements (set symmetric difference)

Setop helps you run these set operations on your files.

** Usage

Let's introduce two line-separated files: =A.txt= and =B.txt=.

=A.txt= contains all numbers from 0 to 5 included
#+BEGIN_EXAMPLE
0
1
2
3
4
5
#+END_EXAMPLE

=B.txt= contains all even numbers from 0 to 8 included
#+BEGIN_EXAMPLE
0
2
4
6
8
#+END_EXAMPLE

*** Set Union (U/Union):

#+BEGIN_SRC bash
$ setop A.txt U B.txt
0
1
2
3
4
5
6
8
#+END_SRC`

*** Set Difference (D/Diff):

#+BEGIN_SRC bash
$ setop A.txt D B.txt
1
3
5
#+END_SRC`

*** Set Intersection (I/Inter):

#+BEGIN_SRC bash
$ setop A.txt I B.txt
0
2
4
#+END_SRC`

*** Set Symmetric Difference (J/Disj):

#+BEGIN_SRC bash
$ setop A.txt J B.txt
1
3
5
6
8
#+END_SRC`

*** Reading A.txt from STDIN:

#+BEGIN_SRC bash
$ cat A.txt | setop STDIN Diff B.txt
0
2
4
#+END_SRC`

*** Reading B.txt from STDIN:

#+BEGIN_SRC bash
$ cat B.txt | setop A.txt Disj STDIN
1
3
5
6
8
#+END_SRC`

** Notes

- the resulting set is *sorted in ascending order*
- some set operations are *not commutative* (e.g. A Diff B /= B Diff A)
- Setop is based on [[https://github.com/pcapriotti/optparse-applicative][optparse-applicative]] and supports [[https://github.com/pcapriotti/optparse-applicative#bash-zsh-and-fish-completions][bash/fish/zsh completions]]