grid.el

Contents

• Description
• API

Description

This library provides a two-dimensional layout system that you can use to arrange text into blocks, rows or columns of blocks, applying different display properties (:align, :margin, :padding, :border, etc)

Evaluate it in a buffer at the first character of some line:

(progn
  (load "test/strings.el")
  (grid-insert-row `(( :content ,test-grid-1-line :width 20 :border t)
                     ( :content ,test-grid-1-line :padding (1 . ?#)
                       :width 15 :align center :margin (0 2))
                     ( :content ,test-grid-1-line :width 20 :align right
                       :border t))))

Result:

With grid-text-selection-mode (local minor mode) enabled, it’s possible to select the text only within desired box:

(progn
  (load "test/strings.el")
  (grid-text-selection-mode)
  (grid-insert-column
   `(,(grid-make-row `(( :content ,test-grid-1-line :width 20 :border t)
                       ( :content ,test-grid-1-line :padding (1 . ?#)
                         :width 15 :align center :margin (0 2))
                       ( :content ,test-grid-1-line :width 20 :align right
                         :border t)))
     ( :content ,test-grid-1-line :padding (1 . ?·) :width 59))))

If grid-revert-on-width-change is t, buffers containing grids with :width set as percentage will be updated each time window size is changed:

(progn
  (setopt grid-revert-on-width-change t)
  (load "test/strings.el")
  (grid-insert-column
   `(,(grid-make-row `(( :content ,test-grid-1-line :width .2 :border t)
                       ( :content ,test-grid-1-line :padding (1 . ?#)
                         :width .15 :align center :margin (0 2))
                       ( :content ,test-grid-1-line :width .2 :align right
                         :border t)))
     ( :content ,test-grid-1-line :padding (1 . ?·) :width .58))))

See test/ for examples.

API

• grid-insert-box

(grid-insert-box BOX)

• grid-insert-rows

(grid-insert-rows '(ROW ROW ...))
;; ROW: '(BOX BOX ...)

• grid-insert-row

(grid-insert-row ROW)
;; ROW: '(BOX BOX ...)

• grid-insert-column

(grid-insert-column COLUMN)
;; COLUMN: '(BOX BOX ...)

• grid-make-box
• grid-make-column
• grid-make-row
• grid-make-rows

BOX formats:

• string. In that case the width of the box will be equal to the longest line in the string.
• plist. Properties:

  :content - string to be inserted in the box

  Optional:

  :align - content alignment

  • center
  • left (default)
  • right

  :width - width of the box

  • float [0.5, .3] - width as a percentage of the current window
  • integer - number of characters

  :border

  • boolean

  :padding - space between the content and the border

  Side formats (can be used as a value. in that case, all 4 sides will use it):

  • integer - number of whitespace characters
  • (integer . character) - number of specified characters

  List formats:

  • (top right bottom left) - each side can be an integer or a cons pair
  • (vertical horizontal) - shortened version, where top = bottom, left = right

  :margin - space outside of the box. Has the same format as :padding.