hier-set

A "hierarchical set" data structure for Clojure: a set of elements with a defined hierarchical relationship, where an element is a member if it is a primary member or a descendant of one. Lookup returns set membership and all primary members that are ancestors of the lookup element.

Stack

Why

The hierarchical relationship is defined by the element sort-order and a separate containment predicate, with the following constraints:

• elements must sort prior to any descendants; and
• elements must contain all elements which sort between themselves and any descendant.

This is sufficient to represent simple hierarchical systems where the hierarchy is implicit in the entities involved, such as the Java package system, hierarchical filesystems, or IP networks. It is inappropriate for modeling complex, ad hoc hierarchies, such as the relationships between classes with multiple inheritance.

Installation

Leiningen (project.clj):

[net.clojars.savya/hier-set "1.2.1"]

Clojure CLI (deps.edn):

net.clojars.savya/hier-set {:mvn/version "1.2.1"}

Usage

Primary usage is then through the hier-set and hier-set-by constructor functions in the hier-set.core namespace. In addition to set lookup as described above, the hier-set.core/ancestors and hier-set.core/descendants functions also provide access to lazy sequences of the ancestors and descendants respectively of a provided key.

Compatibility

Requires Clojure 1.10 or later and JDK 8 or later. Continuously tested against Clojure 1.10.3, 1.11.4, and 1.12.5 on JDK 8, 11, 17, and 21.

Example

A trivial example:

(ns example.hier-set
  (:require [hier-set.core :as hs :refer [hier-set]]))

(def starts-with? #(.startsWith %2 %1))

(def h (hier-set starts-with? "ack" "foo" "foo.bar" "quux"))

(get h "bar")              ;;=> nil
(get h "foo")              ;;=> ("foo")
(get h "foo.bar.baz")      ;;=> ("foo.bar" "foo")
(hs/ancestors h "bar")     ;;=> ()
(hs/ancestors h "foo.baz") ;;=> ("foo")
(hs/descendants h "foo")   ;;=> ("foo" "foo.bar")

License

Copyright © 2012, 2014 Marshall Bockrath-Vandegrift.

Maintenance fork (2026) by Savyasachi, preserving the original Eclipse Public License. Original project: https://github.com/llasram/hier-set

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.