Function: table-capture
table-capture is an autoloaded, interactive and byte-compiled function
defined in table.el.gz.
Signature
(table-capture BEG END &optional COL-DELIM-REGEXP ROW-DELIM-REGEXP JUSTIFY MIN-CELL-WIDTH COLUMNS)
Documentation
Convert plain text into a table by capturing the text in the region.
Create a table with the text in region as cell contents. BEG and END
specify the region. The text in the region is replaced with a table.
The removed text is inserted in the table. When optional
COL-DELIM-REGEXP and ROW-DELIM-REGEXP are provided the region contents
is parsed and separated into individual cell contents by using the
delimiter regular expressions. This parsing determines the number of
columns and rows of the table automatically. If COL-DELIM-REGEXP and
ROW-DELIM-REGEXP are omitted the result table has only one cell and
the entire region contents is placed in that cell. Optional JUSTIFY
is one of left, center or right, which specifies the cell
justification. Optional MIN-CELL-WIDTH specifies the minimum cell
width. Optional COLUMNS specify the number of columns when
ROW-DELIM-REGEXP is not specified.
Example 1:
1, 2, 3, 4
5, 6, 7, 8
, 9, 10
Running table-capture on above 3 line region with COL-DELIM-REGEXP
"," and ROW-DELIM-REGEXP "\\n" creates the following table. In
this example the cells are centered and minimum cell width is
specified as 5.
+-----+-----+-----+-----+
| 1 | 2 | 3 | 4 |
+-----+-----+-----+-----+
| 5 | 6 | 7 | 8 |
+-----+-----+-----+-----+
| | 9 | 10 | |
+-----+-----+-----+-----+
Note:
In case the function is called interactively user must use C-q (quoted-insert) quoted-insert
in order to enter "\\n" successfully. COL-DELIM-REGEXP at the end
of each row is optional.
Example 2:
This example shows how a table can be used for text layout editing.
Let table-capture capture the following region starting from
-!- and ending at -*-, that contains three paragraphs and two item
name headers. This time specify empty string for both
COL-DELIM-REGEXP and ROW-DELIM-REGEXP.
-!-table-capture is a powerful command however mastering its power
requires some practice. Here is a list of items what it can do.
Parse Cell Items By using column delimiter regular
expression and raw delimiter regular
expression, it parses the specified text
area and extracts cell items from
non-table text and then forms a table out
of them.
Capture Text Area When no delimiters are specified it
creates a single cell table. The text in
the specified region is placed in that
cell.-*-
Now the entire content is captured in a cell which is itself a table like this.
+-----------------------------------------------------------------+
|table-capture is a powerful command however mastering its power|
|requires some practice. Here is a list of items what it can do. |
| |
|Parse Cell Items By using column delimiter regular |
| expression and raw delimiter regular |
| expression, it parses the specified text |
| area and extracts cell items from |
| non-table text and then forms a table out |
| of them. |
| |
|Capture Text Area When no delimiters are specified it |
| creates a single cell table. The text in |
| the specified region is placed in that |
| cell. |
+-----------------------------------------------------------------+
By splitting the cell appropriately we now have a table consisting of paragraphs occupying its own cell. Each cell can now be edited independently.
+-----------------------------------------------------------------+
|table-capture is a powerful command however mastering its power|
|requires some practice. Here is a list of items what it can do. |
+---------------------+-------------------------------------------+
|Parse Cell Items |By using column delimiter regular |
| |expression and raw delimiter regular |
| |expression, it parses the specified text |
| |area and extracts cell items from |
| |non-table text and then forms a table out |
| |of them. |
+---------------------+-------------------------------------------+
|Capture Text Area |When no delimiters are specified it |
| |creates a single cell table. The text in |
| |the specified region is placed in that |
| |cell. |
+---------------------+-------------------------------------------+
By applying table-release, which does the opposite process, the
contents become once again plain text. table-release works as
companion command to table-capture this way.
Key Bindings
Source Code
;; Defined in /usr/src/emacs/lisp/textmodes/table.el.gz
;;;###autoload
(defun table-capture (beg end &optional col-delim-regexp row-delim-regexp justify min-cell-width columns)
"Convert plain text into a table by capturing the text in the region.
Create a table with the text in region as cell contents. BEG and END
specify the region. The text in the region is replaced with a table.
The removed text is inserted in the table. When optional
COL-DELIM-REGEXP and ROW-DELIM-REGEXP are provided the region contents
is parsed and separated into individual cell contents by using the
delimiter regular expressions. This parsing determines the number of
columns and rows of the table automatically. If COL-DELIM-REGEXP and
ROW-DELIM-REGEXP are omitted the result table has only one cell and
the entire region contents is placed in that cell. Optional JUSTIFY
is one of `left', `center' or `right', which specifies the cell
justification. Optional MIN-CELL-WIDTH specifies the minimum cell
width. Optional COLUMNS specify the number of columns when
ROW-DELIM-REGEXP is not specified.
Example 1:
1, 2, 3, 4
5, 6, 7, 8
, 9, 10
Running `table-capture' on above 3 line region with COL-DELIM-REGEXP
\",\" and ROW-DELIM-REGEXP \"\\n\" creates the following table. In
this example the cells are centered and minimum cell width is
specified as 5.
+-----+-----+-----+-----+
| 1 | 2 | 3 | 4 |
+-----+-----+-----+-----+
| 5 | 6 | 7 | 8 |
+-----+-----+-----+-----+
| | 9 | 10 | |
+-----+-----+-----+-----+
Note:
In case the function is called interactively user must use \\[quoted-insert] `quoted-insert'
in order to enter \"\\n\" successfully. COL-DELIM-REGEXP at the end
of each row is optional.
Example 2:
This example shows how a table can be used for text layout editing.
Let `table-capture' capture the following region starting from
-!- and ending at -*-, that contains three paragraphs and two item
name headers. This time specify empty string for both
COL-DELIM-REGEXP and ROW-DELIM-REGEXP.
-!-`table-capture' is a powerful command however mastering its power
requires some practice. Here is a list of items what it can do.
Parse Cell Items By using column delimiter regular
expression and raw delimiter regular
expression, it parses the specified text
area and extracts cell items from
non-table text and then forms a table out
of them.
Capture Text Area When no delimiters are specified it
creates a single cell table. The text in
the specified region is placed in that
cell.-*-
Now the entire content is captured in a cell which is itself a table
like this.
+-----------------------------------------------------------------+
|`table-capture' is a powerful command however mastering its power|
|requires some practice. Here is a list of items what it can do. |
| |
|Parse Cell Items By using column delimiter regular |
| expression and raw delimiter regular |
| expression, it parses the specified text |
| area and extracts cell items from |
| non-table text and then forms a table out |
| of them. |
| |
|Capture Text Area When no delimiters are specified it |
| creates a single cell table. The text in |
| the specified region is placed in that |
| cell. |
+-----------------------------------------------------------------+
By splitting the cell appropriately we now have a table consisting of
paragraphs occupying its own cell. Each cell can now be edited
independently.
+-----------------------------------------------------------------+
|`table-capture' is a powerful command however mastering its power|
|requires some practice. Here is a list of items what it can do. |
+---------------------+-------------------------------------------+
|Parse Cell Items |By using column delimiter regular |
| |expression and raw delimiter regular |
| |expression, it parses the specified text |
| |area and extracts cell items from |
| |non-table text and then forms a table out |
| |of them. |
+---------------------+-------------------------------------------+
|Capture Text Area |When no delimiters are specified it |
| |creates a single cell table. The text in |
| |the specified region is placed in that |
| |cell. |
+---------------------+-------------------------------------------+
By applying `table-release', which does the opposite process, the
contents become once again plain text. `table-release' works as
companion command to `table-capture' this way."
(interactive
(let ((col-delim-regexp)
(row-delim-regexp))
(barf-if-buffer-read-only)
(if (table--probe-cell)
(error "Can't insert a table inside a table"))
(list
(mark) (point)
(setq col-delim-regexp
(read-from-minibuffer "Column delimiter regexp: "
(car table-col-delim-regexp-history) nil nil 'table-col-delim-regexp-history))
(setq row-delim-regexp
(read-from-minibuffer "Row delimiter regexp: "
(car table-row-delim-regexp-history) nil nil 'table-row-delim-regexp-history))
(let* ((completion-ignore-case t)
(default (car table-capture-justify-history)))
(if (and (string= col-delim-regexp "") (string= row-delim-regexp "")) 'left
(intern
(downcase (completing-read
(format-prompt "Justify" default)
'(("left") ("center") ("right"))
nil t nil 'table-capture-justify-history default)))))
(if (and (string= col-delim-regexp "") (string= row-delim-regexp "")) "1"
(table--read-from-minibuffer '("Minimum cell width" . table-capture-min-cell-width-history)))
(if (and (not (string= col-delim-regexp "")) (string= row-delim-regexp ""))
(string-to-number
(table--read-from-minibuffer '("Number of columns" . table-capture-columns-history)))
nil)
)))
(if (> beg end) (let ((tmp beg)) (setq beg end) (setq end tmp)))
(if (string= col-delim-regexp "") (setq col-delim-regexp nil))
(if (string= row-delim-regexp "") (setq row-delim-regexp nil))
(if (and columns (< columns 1)) (setq columns nil))
(unless min-cell-width (setq min-cell-width "5"))
(let ((contents (buffer-substring beg end))
(cols 0) (rows 0) c r cell-list
(delim-pattern
(if (and col-delim-regexp row-delim-regexp)
(format "\\(\\(%s\\)?\\s *\\(%s\\)\\s *\\)\\|\\(\\(%s\\)\\s *\\)"
col-delim-regexp row-delim-regexp col-delim-regexp)
(if col-delim-regexp
(format "\\(\\)\\(\\)\\(\\)\\(\\(%s\\)\\s *\\)" col-delim-regexp))))
(contents-list))
;; when delimiters are specified extract cells and determine the cell dimension
(if delim-pattern
(with-temp-buffer
(insert contents)
;; make sure the contents ends with a newline
(goto-char (point-max))
(unless (zerop (current-column))
(insert ?\n))
;; skip the preceding white spaces
(goto-char (point-min))
(if (looking-at "\\s +")
(goto-char (match-end 0)))
;; extract cell contents
(let ((from (point)))
(setq cell-list nil)
(setq c 0)
(while (and (re-search-forward delim-pattern nil t)
(cond
;; row delimiter
((and (match-string 1) (not (string= (match-string 1) "")))
(setq rows (1+ rows))
(setq cell-list
(append cell-list (list (buffer-substring from (match-beginning 1)))))
(setq from (match-end 1))
(setq contents-list
(append contents-list (list cell-list)))
(setq cell-list nil)
(setq c (1+ c))
(if (> c cols) (setq cols c))
(setq c 0)
t)
;; column delimiter
((and (match-string 4) (not (string= (match-string 4) "")))
(setq cell-list
(append cell-list (list (buffer-substring from (match-beginning 4)))))
(setq from (match-end 4))
(setq c (1+ c))
(if (> c cols) (setq cols c))
t)
(t nil))))
;; take care of the last element without a post delimiter
(unless (null (looking-at ".+$"))
(setq cell-list
(append cell-list (list (match-string 0))))
(setq cols (1+ cols)))
;; take care of the last row without a terminating delimiter
(unless (null cell-list)
(setq rows (1+ rows))
(setq contents-list
(append contents-list (list cell-list)))))))
;; finalize the table dimension
(if (and columns contents-list)
;; when number of columns are specified and cells are parsed determine the dimension
(progn
(setq cols columns)
(setq rows (/ (+ (length (car contents-list)) columns -1) columns)))
;; when dimensions are not specified default to a single cell table
(if (zerop rows) (setq rows 1))
(if (zerop cols) (setq cols 1)))
;; delete the region and reform line breaks
(delete-region beg end)
(goto-char beg)
(unless (zerop (current-column))
(insert ?\n))
(unless (looking-at "\\s *$")
(save-excursion
(insert ?\n)))
;; insert the table
;; insert the cell contents
(if (null contents-list)
;; single cell
(let ((width) (height))
(with-temp-buffer
(insert contents)
(table--remove-eol-spaces (point-min) (point-max))
(table--untabify (point-min) (point-max))
(setq width (table--measure-max-width))
(setq height (1+ (table--current-line (point-max))))
(setq contents (buffer-substring (point-min) (point-max))))
(table-insert cols rows width height)
(table-with-cache-buffer
(insert contents)
(setq table-inhibit-auto-fill-paragraph t)))
;; multi cells
(table-insert cols rows min-cell-width 1)
(setq r 0)
(setq cell-list nil)
(while (< r rows)
(setq r (1+ r))
(setq c 0)
(unless cell-list
(setq cell-list (car contents-list))
(setq contents-list (cdr contents-list)))
(while (< c cols)
(setq c (1+ c))
(if (car cell-list)
(table-with-cache-buffer
(insert (car cell-list))
(setq cell-list (cdr cell-list))
(setq table-cell-info-justify justify)))
(table-forward-cell 1))))))