if/soup: A CLI tool for non-hierarchical file organization. - Codeberg.org

soup
----
"I'm at soup!"
 -- Kururugi Suzaku, code ment
what is soup?
-------------
`soup` is a cli tool for associating things.
why is soup?
------------
When you have a lot of files, or pieces of data in general,
it's often easier to search them if you classify them. For
example, songs can be classified by their artist, album,
or playlist; academic papers can be classified by their
discipline; and websites can be tagged and bookmarked.
It is often the case that such systems of organization can
be simplified to a list of items, where each item is associated
with a classifier; items with multiple classifiers would then
show up multiple times in the list. For example, a list of songs
could include a song with multiple classifications, e.g.:
[... ("enjoy the silence", "depeche mode"),
 ("enjoy the silence", "electronic"),
 ("enjoy the silence", "emotional playlist"), ...]
You may ask, what's so good about soup if it's essentially
just a giant database full of string tuples? Surprisingly, the
value of soup lies in the fact that it's so simple, because
you can build lots of arbitrarily complex tagging systems on
top of it (see https://idlewords.com/talks/fan_is_a_tool_using_animal.htm).
In conclusion, the purpose of soup is to provide a unified
interface for facilitating an extremely common mechanism (tagging)
while also following the unix philosophy of composability.
implementation details (if you're interested)
--------------------------------------------
soup uses a deeply embedded domain-specific language
for writing subcommand. What this basically means,
from the point of view of a Haskell programmer, is
that subcommand are written in a really concise do-block,
and all the complexity is hidden somewhere else. 
The DSL itself uses some strange GADT tricks to maintain
a degree of type safety, although this comes at the expense
of added complexity in the backend -- there are many different
intermediate types that come into play.
Once the main part of soup is finished, any refactoring
in the future would aim to trim down the type complexity
and make the backend less messy, while keeping the EDSL
frontend simple.
versioning scheme
-----------------
Each release has version dd.mm.yy, named after the day it was
initially released, as well as a nickname related to something
that was going on around that time.
status
------
v12.02.21.ox "ox" is out! It's the first release, so it's
a little messy, but it should work. I'm focusing on other
projects for now, so the next release won't be for awhile.
how to build (nixos)
--------------------
> nix-build release.nix
how to build (otherwise)
-----------------------
> cabal build
contributing
------------
If you want to contribute or have an idea, send me an email or ping
me on fedi before doing a pull request. If we talk things over more,
then your contribution is more likely to get merged. Don't be afraid
to ask questions, either.
quick documentation
-------------------
On the command-line, you can run "soup help" to view the documentation.
soup has the following commands:
"item" commands:
> soup ls items
 list all items.
> soup ls items TAGS
 list all items that have TAGS
> soup rm items ITEMS
 remove items.
"tag" commands:
> soup untag ITEM TAGS
 remove TAGS from ITEM.
> soup ls tags
 list all tags.
> soup ls tags ITEMS
 list all tags that ITEMS have.
> soup rm tags TAGS
 remove TAGS.
> soup tag ITEM TAGS
 associate ITEM with TAGS.
miscellaneous commands:
> soup vomit
 list everything in the database.