https://github.com/DamienCassou/hierarchy

Emacs library to create, query, navigate and display hierarchy structures
https://github.com/DamienCassou/hierarchy

Last synced: 2 months ago
JSON representation

Emacs library to create, query, navigate and display hierarchy structures

• Host: GitHub
• URL: https://github.com/DamienCassou/hierarchy
• Owner: DamienCassou
• License: gpl-3.0
• Created: 2017-03-20T18:43:37.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2022-06-29T10:05:52.000Z (over 2 years ago)
• Last Synced: 2024-10-16T01:43:22.371Z (3 months ago)
• Language: Emacs Lisp
• Size: 2.58 MB
• Stars: 156
• Watchers: 7
• Forks: 8
• Open Issues: 11
• Metadata Files:
  • Readme: README.org
  • Contributing: CONTRIBUTING.md
  • License: COPYING

Awesome Lists containing this project

README

        
* ⚠ Integration into Emas core

This project got integrated into Emacs core in release [[https://www.gnu.org/savannah-checkouts/gnu/emacs/news/NEWS.28.1][28.1]].

Please contribute patches to Emacs core directly instead of here.

* Hierarchy

  #+BEGIN_HTML

      


        

          

        

        

          

        

      

  #+END_HTML


** Summary

Library to create, query, navigate and display hierarchy structures. You might want to read the [[https://emacs.cafe/emacs/guest-post/2017/06/26/hierarchy.html][introductory blog post]].

** Installing

Use [[http://melpa.org/][melpa]].

** Using

After having created a hierarchy with ~hierarchy-new~, populate it by

calling ~hierarchy-add-tree~ or ~hierarchy-add-trees~.  You can

then optionally sort its element with ~hierarchy-sort~. For example,

you can create an animal hierarchy by passing a child-to-parent

function to ~hierarchy-add-tree~:

#+BEGIN_SRC emacs-lisp :session animals

  (require 'hierarchy)

  (setq animals (hierarchy-new))

  (let ((parentfn

         ;; Given an item, return its parent

         (lambda (item)

           (cl-case item

             (dove 'bird)

             (pigeon 'bird)

             (bird 'animal)

             (dolphin 'animal)

             (cow 'animal)))))

    (hierarchy-add-tree animals 'dove parentfn)

    (hierarchy-add-tree animals 'pigeon parentfn)

    (hierarchy-add-tree animals 'dolphin parentfn)

    (hierarchy-add-tree animals 'cow parentfn))

  (hierarchy-sort animals)

#+END_SRC

#+RESULTS:

| bird | animal |

You can learn more about your hierarchy by using functions such as

~hierarchy-roots~, ~hierarchy-length~, ~hierarchy-children~,

~hierarchy-descendant-p~. For example, ~hierarchy-roots~ returns any

item without a parent in a hierarchy:

#+BEGIN_SRC emacs-lisp :session animals :exports both

(hierarchy-roots animals)

#+END_SRC

#+RESULTS:

| animal |

~animal~ is the only item of the ~animals~ hierarchy with no

parent. To get all items with no child, use ~hierarchy-leafs~:

#+BEGIN_SRC emacs-lisp :session animals :exports both

(hierarchy-leafs animals)

#+END_SRC

#+RESULTS:

| dove | pigeon | dolphin | cow |

It is possible to get the children of an item by using

~hierarchy-children~:

#+BEGIN_SRC emacs-lisp :session animals :exports both

(hierarchy-children animals 'animal)

#+END_SRC

#+RESULTS:

| bird | cow | dolphin |

We see here that ~animal~ has three children.

You can navigate a hierarchy using ~hierarchy-map-item~,

~hierarchy-map~ and ~hierarchy-map-tree~. For example, this code

inserts a text view of a hierarchy in a buffer:

#+BEGIN_SRC emacs-lisp :session animals :exports both

  (with-temp-buffer

    (hierarchy-map

     (hierarchy-labelfn-indent

      (lambda (animal _) (insert (symbol-name animal) "\n")))

     animals)

    (buffer-substring (point-min) (point-max)))

#+END_SRC

#+RESULTS:

: animal

:   bird

:     dove

:     pigeon

:   cow

:   dolphin

The indentation between a parent and its child can be configured by

passing one more parameter to ~hierarchy-labelfn-indent~. You can also

display clickable buttons instead of just plain text using either

~hierarchy-labelfn-button~ or ~hierarchy-labelfn-button-if~.

If you want a buffer containing only a hierarchy while being able to

navigate it with standard key-bindings use either

~hierarchy-tabulated-display~ or ~hierarchy-tree-display~ as

shown in below animated pictures.

#+BEGIN_SRC emacs-lisp :session animals :exports code

  (switch-to-buffer

   (hierarchy-tabulated-display

    animals

    (hierarchy-labelfn-indent

     (hierarchy-labelfn-button

      (lambda (item _) (insert (symbol-name item)))

      (lambda (item _) (message "You clicked on: %s" item))))))

#+END_SRC

#+RESULTS:

: #>

[[file:media/animals-tabulated-anime.gif]]

#+BEGIN_SRC emacs-lisp :session animals :exports code

  (switch-to-buffer

   (hierarchy-tree-display

    animals

    (lambda (item _) (insert (symbol-name item)))))

#+END_SRC

#+RESULTS:

: t

[[file:media/animals-tree-anime.gif]]

** Examples

*** File-system example

The hierarchy library can be used to display any kind of hierarchy you

need. For example, a [[file:examples/hierarchy-examples-fs.el][file-system navigator]] is provided as an example.

#+BEGIN_SRC emacs-lisp :session animals :exports code

  (load "./examples/hierarchy-examples-fs.el")

  ;; Execute one of the following lines to show the `.emacd.d' hierarchy

  ;; in either a tabulated list or a tree widget. This takes around 3

  ;; seconds on my computer.

  (hierarchy-examples-fs-display-filesystem "~/.emacs.d")

  (hierarchy-examples-fs-display-filesystem-tree "~/.emacs.d")

#+END_SRC

#+RESULTS:

: #

[[file:media/files-tabulated-anime.gif]]

[[file:media/files-tree-anime.gif]]

*** Faces hierarchy example

Emacs and packages define quite a lot of faces. Because a face may

inherit from another one, we can get [[file:examples/hierarchy-examples-faces.el][a hierarchy of them]]:

[[file:media/faces-tree.png]]

This is based on an [[https://github.com/DamienCassou/hierarchy/issues/74][idea and code from Yuan Fu]].

*** Major modes hierarchy example

Emacs and packages define quite a lot of major modes. A major mode

usually derives from another one which means we can get a [[file:examples/hierarchy-examples-major-modes.el][hierarchy of

major modes]]:

[[file:media/major-modes-tabulated.png]]

*** Class hierarchy example

With a bit more work, the hierarchy library can also be used to

display class hierarchies (as I am currently experimenting in [[https://github.com/DamienCassou/klassified.el][this

project]]).

[[file:media/klassified-tabulated-anime.gif]]

*** JSON navigator example

A [[https://github.com/DamienCassou/json-navigator][JSON navigator]] is also implemented as yet another example.

[[file:media/json-tree-anime.gif]]

** Contributing

Yes, please do! See [[file:CONTRIBUTING.md][CONTRIBUTING]] for guidelines.

** License

See [[file:COPYING][COPYING]]. Copyright (c) 2017 Damien Cassou.