Function: table-insert
table-insert is an autoloaded, interactive and byte-compiled function
defined in table.el.gz.
Signature
(table-insert COLUMNS ROWS &optional CELL-WIDTH CELL-HEIGHT)
Documentation
Insert an editable text table.
Insert a table of specified number of COLUMNS and ROWS. Optional parameter CELL-WIDTH and CELL-HEIGHT can specify the size of each cell. The cell size is uniform across the table if the specified size is a number. They can be a list of numbers to specify different size for each cell. When called interactively, the list of number is entered by simply listing all the numbers with space characters delimiting them.
Examples:
M-x table-insert (table-insert) inserts a table at the current point location.
Suppose we have the following situation where -!- indicates the
location of point.
-!-
Type M-x table-insert (table-insert) and hit ENTER key. As it asks table
specification, provide 3 for number of columns, 1 for number of rows,
5 for cell width and 1 for cell height. Now you shall see the next
table and the point is automatically moved to the beginning of the
first cell.
+-----+-----+-----+
|-!- | | |
+-----+-----+-----+
Inside a table cell, there are special key bindings.
M-9 M-x table-widen-cell (table-widen-cell) (or C-u (universal-argument) 9 M-x table-widen-cell (table-widen-cell)) widens the first cell by 9 character
width, which results as
+--------------+-----+-----+
|-!- | | |
+--------------+-----+-----+
Type TAB M-x table-widen-cell (table-widen-cell) then type TAB M-2 M-7 M-x table-widen-cell (table-widen-cell) (or C-u (universal-argument) 2 7 M-x table-widen-cell (table-widen-cell)). Typing
TAB moves the point forward by a cell. The result now looks like this:
+--------------+------+--------------------------------+
| | |-!- |
+--------------+------+--------------------------------+
If you knew each width of the columns prior to the table creation,
what you could have done better was to have had given the complete
width information to table-insert.
Cell width(s): 14 6 32
instead of
Cell width(s): 5
This would have eliminated the previously mentioned width adjustment work all together.
If the point is in the last cell type S-TAB S-TAB to move it to the
first cell. Now type M-x table-heighten-cell (table-heighten-cell) which heighten the row by a line.
+--------------+------+--------------------------------+
|-!- | | |
| | | |
+--------------+------+--------------------------------+
Type M-x table-insert-row-column (table-insert-row-column) and tell it to insert a row.
+--------------+------+--------------------------------+
|-!- | | |
| | | |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
Move the point under the table as shown below.
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
-!-
Type M-x table-insert-row (table-insert-row) instead of M-x table-insert-row-column (table-insert-row-column). M-x table-insert-row-column (table-insert-row-column) does not work
when the point is outside of the table. This insertion at
outside of the table effectively appends a row at the end.
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
|-!- | | |
| | | |
+--------------+------+--------------------------------+
Text editing inside the table cell produces reasonably expected results.
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
| | |Text editing inside the table |
| | |cell produces reasonably |
| | |expected results.-!- |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
Inside a table cell has a special keymap.
Keymap table-cell-map is not currently defined.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/textmodes/table.el.gz
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;
;; Commands
;;
;;;###autoload
(defun table-insert (columns rows &optional cell-width cell-height)
"Insert an editable text table.
Insert a table of specified number of COLUMNS and ROWS. Optional
parameter CELL-WIDTH and CELL-HEIGHT can specify the size of each
cell. The cell size is uniform across the table if the specified size
is a number. They can be a list of numbers to specify different size
for each cell. When called interactively, the list of number is
entered by simply listing all the numbers with space characters
delimiting them.
Examples:
\\[table-insert] inserts a table at the current point location.
Suppose we have the following situation where `-!-' indicates the
location of point.
-!-
Type \\[table-insert] and hit ENTER key. As it asks table
specification, provide 3 for number of columns, 1 for number of rows,
5 for cell width and 1 for cell height. Now you shall see the next
table and the point is automatically moved to the beginning of the
first cell.
+-----+-----+-----+
|-!- | | |
+-----+-----+-----+
Inside a table cell, there are special key bindings.
\\<table-cell-map>
M-9 \\[table-widen-cell] (or \\[universal-argument] 9 \\[table-widen-cell]) widens the first cell by 9 character
width, which results as
+--------------+-----+-----+
|-!- | | |
+--------------+-----+-----+
Type TAB \\[table-widen-cell] then type TAB M-2 M-7 \\[table-widen-cell] (or \\[universal-argument] 2 7 \\[table-widen-cell]). Typing
TAB moves the point forward by a cell. The result now looks like this:
+--------------+------+--------------------------------+
| | |-!- |
+--------------+------+--------------------------------+
If you knew each width of the columns prior to the table creation,
what you could have done better was to have had given the complete
width information to `table-insert'.
Cell width(s): 14 6 32
instead of
Cell width(s): 5
This would have eliminated the previously mentioned width adjustment
work all together.
If the point is in the last cell type S-TAB S-TAB to move it to the
first cell. Now type \\[table-heighten-cell] which heighten the row by a line.
+--------------+------+--------------------------------+
|-!- | | |
| | | |
+--------------+------+--------------------------------+
Type \\[table-insert-row-column] and tell it to insert a row.
+--------------+------+--------------------------------+
|-!- | | |
| | | |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
Move the point under the table as shown below.
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
-!-
Type \\[table-insert-row] instead of \\[table-insert-row-column]. \\[table-insert-row-column] does not work
when the point is outside of the table. This insertion at
outside of the table effectively appends a row at the end.
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
|-!- | | |
| | | |
+--------------+------+--------------------------------+
Text editing inside the table cell produces reasonably expected
results.
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
| | |Text editing inside the table |
| | |cell produces reasonably |
| | |expected results.-!- |
+--------------+------+--------------------------------+
| | | |
| | | |
+--------------+------+--------------------------------+
Inside a table cell has a special keymap.
\\{table-cell-map}"
(interactive
(progn
(barf-if-buffer-read-only)
(if (table--probe-cell)
(error "Can't insert a table inside a table"))
(mapcar (function table--read-from-minibuffer)
'(("Number of columns" . table-columns-history)
("Number of rows" . table-rows-history)
("Cell width(s)" . table-cell-width-history)
("Cell height(s)" . table-cell-height-history)))))
(table--make-cell-map)
;; Reform the arguments.
(if (null cell-width) (setq cell-width (car table-cell-width-history)))
(if (null cell-height) (setq cell-height (car table-cell-height-history)))
(if (stringp columns) (setq columns (string-to-number columns)))
(if (stringp rows) (setq rows (string-to-number rows)))
(if (stringp cell-width)
(setq cell-width (table--string-to-number-list cell-width)))
(if (stringp cell-height)
(setq cell-height (table--string-to-number-list cell-height)))
(if (numberp cell-width) (setq cell-width (cons cell-width nil)))
(if (numberp cell-height) (setq cell-height (cons cell-height nil)))
;; Test validity of the arguments.
(dolist (arg `((columns . ,columns)
(rows . ,rows)
(cell-width . ,cell-width)
(cell-height . ,cell-height)))
(let* ((value (cdr arg))
(error-handler
(lambda ()
(error "%s must be a positive integer%s" (car arg)
(if (listp value)
" or a list of positive integers" "")))))
(if (null value) (funcall error-handler))
(dolist (arg1 (if (listp value) value
(cons value nil)))
(if (or (not (integerp arg1))
(< arg1 1))
(funcall error-handler)))))
(let ((orig-coord (table--get-coordinate))
(coord (table--get-coordinate))
r i cw ch cell-str border-str)
;; Prefabricate the building blocks border-str and cell-str.
(with-temp-buffer
;; Construct border-str.
(insert table-cell-intersection-char)
(setq cw cell-width)
(setq i 0)
(while (< i columns)
(insert (make-string (car cw)
(string-to-char table-cell-horizontal-chars))
table-cell-intersection-char)
(if (cdr cw) (setq cw (cdr cw)))
(setq i (1+ i)))
(setq border-str (buffer-substring (point-min) (point-max)))
;; construct cell-str
(erase-buffer)
(insert table-cell-vertical-char)
(setq cw cell-width)
(setq i 0)
(while (< i columns)
(let ((beg (point)))
(insert (make-string (car cw) ?\s))
(insert table-cell-vertical-char)
(table--put-cell-line-property beg (1- (point))))
(if (cdr cw) (setq cw (cdr cw)))
(setq i (1+ i)))
(setq cell-str (buffer-substring (point-min) (point-max))))
;; if the construction site has an empty border push that border down.
(save-excursion
(beginning-of-line)
(if (looking-at "\\s *$")
(progn
(setq border-str (concat border-str "\n"))
(setq cell-str (concat cell-str "\n")))))
;; now build the table using the prefabricated building blocks
(setq r 0)
(setq ch cell-height)
(while (< r rows)
(if (> r 0) nil
(table--goto-coordinate coord) (setcdr coord (1+ (cdr coord)))
(table--untabify-line (point))
(insert border-str))
(setq i 0)
(while (< i (car ch))
(table--goto-coordinate coord) (setcdr coord (1+ (cdr coord)))
(table--untabify-line (point))
(insert cell-str)
(setq i (1+ i)))
(table--goto-coordinate coord) (setcdr coord (1+ (cdr coord)))
(table--untabify-line (point))
(insert border-str)
(if (cdr ch) (setq ch (cdr ch)))
(setq r (1+ r)))
;; stand by at the first cell
(table--goto-coordinate (table--offset-coordinate orig-coord '(1 . 1)))
(table-recognize-cell 'force)))