A CLI tool for non-hierarchical file organization.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
rhipsalis sulcata 63a760ab08 finish first version! 6 months ago
propaganda add propaganda 6 months ago
src finish first version! 6 months ago
CHANGELOG.md initial commit 8 months ago
LICENSE initial commit 8 months ago
Main.hs did monad instances 7 months ago
README finish first version! 6 months ago
Setup.hs initial commit 8 months ago
TODO.org change database backend 6 months ago
init.sql improve database creation 6 months ago
release.nix start big rewrite 6 months ago
result finish first version! 6 months ago
shell.nix initial commit 8 months ago
soup.cabal change database backend 6 months ago
soup.db add ls tags subcommand 6 months ago
soup.nix change database backend 6 months ago
spec remove terse flag 7 months ago

README

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.