Files
README.md

Foliat #

A simple and expressive language for tagging your data into a tree like structure, where a single .flt file is all you need.


Installation #

Coming soon


Usage #

Coming soon


Language #

Basics #

Assign tags to subjects using =

beach.jpg = vacation summer 2024

Subjects and tags are either bare identifiers or quoted strings for names containing reserved characters

"https://example.com/page" = bookmark reading tech
"/home/user/docs/cv.pdf"   = work important

Multiple subjects #

Assign the same tags to multiple subjects at once:

photo1.jpg photo2.jpg photo3.jpg = vacation 2024

Hierarchy #

Use / to create hierarchy on either side:

photo/beach.jpg     = trip/2024
photo/mountain.jpg  = trip/2025

Grouping #

Use ( ) as shorthand to expand combinations:

# Equivalent to photo/beach.jpg photo/mountain.jpg = trip/2024
photo/(beach.jpg mountain.jpg) = trip/2024

# Equivalent to a/c a/d b/c b/d = tag1
(a b)/(c d) = tag1

# Works on the right side too
photo/(beach.jpg mountain.jpg) = trip/(2024 europe)
# Equivalent to:
photo/beach.jpg = trip/2024 trip/europe
photo/mountain.jpg = trip/2024 trip/europe

Aliases #

Define reusable tag groups using :

:work = important work-related deadline

report.pdf    = :work 2024
proposal.docx = :work client

Aliases can reference other aliases:

:base     = important archived
:work     = :base work-related
:personal = :base personal

Redefining subjects #

Redefining a subject appends its tags - these two programs are equivalent:

photo.jpg = vacation
photo.jpg = 2024
photo.jpg = vacation 2024

Comments #

Single-line:

# This is a comment
photo.jpg = vacation  # inline comment

Multi-line (nestable):

(#
  This is a
  multi-line comment

  (# and this is nested #)

  still in the outer comment
#)

Directives #

Directives are prefixed with @ to change how a file is handled.

@format = json
photo/beach.jpg = trip/2024 trip/europe
photo/mountain.jpg = trip/2024 trip/europe

Calling foliat query file.flt --tag mountain.jpg returns the output as json.


Full Example #

# Aliases

:media    = personal media
:trip     = :media vacation
:work-doc = work important document

# Photos

(photos/beach.jpg photos/sunset.jpg) = :trip summer europe
photos/conference.jpg                = work 2024 conference

# Documents

"docs/Q3 Report.pdf"   = :work-doc 2024 finance
"docs/Q4 Proposal.pdf" = :work-doc 2024 finance draft

# URLs

"https://tangled.org/lettever.tngl.sh"  = bookmark programming open-source
"https://en.wikipedia.org/wiki/Parsing" = bookmark reading cs/parsing

Query #

foliat query file.flt --subject beach.png
foliat query file.flt --tag vacation
foliat query file.flt --tag "trip & vacation"
foliat query file.flt --tag trip&vacation # Quotes are optional as long as you don't use spaces
foliat query file.flt --tag vacation --subject beach.png

Matching #

  • trip - any tag containing trip as a segment
  • /trip - trip is the first segment
  • trip/ - trip is the last segment
  • /trip/ - exact match
  • trip/* - trip followed by exactly one segment
  • trip/*/vacation - trip, any single segment, then vacation
  • trip/**/vacation - trip, zero or more segments, then vacation

Operators #

  • & - AND
  • | - OR
  • ! - NOT
  • () - grouping, overrides left-to-right precedence

Output formats #

Coming soon


License #

MIT