Commit e2d8d479 authored by Fabián Ezequiel Gallina's avatar Fabián Ezequiel Gallina Committed by Fabián Ezequiel Gallina

Documentation enhancements

parent c0428ba0
;;; python.el -- Python's flying circus support for Emacs
;; Copyright (C) 2010 Free Software Foundation, Inc.
;; Copyright (C) 2010, 2011 Free Software Foundation, Inc.
;; Author: Fabián E. Gallina <fabian@anue.biz>
;; Maintainer: FSF
......@@ -34,7 +34,7 @@
;; Implements Syntax highlighting, Indentation, Movement, Shell
;; interaction, Shell completion, Pdb tracking, Symbol completion,
;; Eldoc.
;; Skeletons, FFAP, Code Check, Eldoc.
;; Syntax highlighting: Fontification of code is provided and supports
;; python's triple quoted strings properly.
......@@ -255,7 +255,8 @@
"=" "%" "**" "//" "<<" ">>" "<=" "!="
"==" ">=" "is" "not")))
`(assignment-operator . ,(rx (or "=" "+=" "-=" "*=" "/=" "//=" "%=" "**="
">>=" "<<=" "&=" "^=" "|="))))))
">>=" "<<=" "&=" "^=" "|="))))
"Additional Python specific sexps for `python-rx'"))
(defmacro python-rx (&rest regexps)
"Python mode especialized rx macro which supports common python named REGEXPS."
......@@ -498,23 +499,18 @@ These make `python-indent-calculate-indentation' subtract the value of
(when (> indent-offset 0)
(setq python-indent-offset indent-offset))))))))
(defun python-indent-context (&optional stop)
"Return information on indentation context.
Optional argument STOP serves to stop recursive calls.
Returns a cons with the form:
\(STATUS . START)
(defun python-indent-context ()
"Get information on indentation context.
Context information is returned with a cons with the form:
\(STATUS . START)
Where status can be any of the following symbols:
* inside-paren: If point in between (), {} or []
* inside-string: If point is inside a string
* after-backslash: Previous line ends in a backslash
* after-beginning-of-block: Point is after beginning of block
* after-line: Point is after normal line
* no-indent: Point is at beginning of buffer or other special case
START is the buffer position where the sexp starts."
(save-restriction
(widen)
......@@ -704,27 +700,23 @@ START is the buffer position where the sexp starts."
(defun python-indent-line (&optional force-toggle)
"Internal implementation of `python-indent-line-function'.
Uses the offset calculated in
`python-indent-calculate-indentation' and available levels
indicated by the variable `python-indent-levels'.
indicated by the variable `python-indent-levels' to set the
current indentation.
When the variable `last-command' is equal to
`indent-for-tab-command' or FORCE-TOGGLE is non-nil:
* Cycles levels indicated in the variable `python-indent-levels'
by setting the current level in the variable
`python-indent-current-level'.
`indent-for-tab-command' or FORCE-TOGGLE is non-nil it cycles
levels indicated in the variable `python-indent-levels' by
setting the current level in the variable
`python-indent-current-level'.
When the variable `last-command' is not equal to
`indent-for-tab-command' and FORCE-TOGGLE is nil:
* calculates possible indentation levels and saves it in the
variable `python-indent-levels'.
* sets the variable `python-indent-current-level' correctly so
offset is equal to (`nth' `python-indent-current-level'
`python-indent-levels')"
`indent-for-tab-command' and FORCE-TOGGLE is nil it calculates
possible indentation levels and saves it in the variable
`python-indent-levels'. Afterwards it sets the variable
`python-indent-current-level' correctly so offset is equal
to (`nth' `python-indent-current-level' `python-indent-levels')"
(if (or (and (eq this-command 'indent-for-tab-command)
(eq last-command this-command))
force-toggle)
......@@ -745,11 +737,11 @@ When the variable `last-command' is not equal to
(defun python-indent-line-function ()
"`indent-line-function' for Python mode.
Internally just calls `python-indent-line'."
See `python-indent-line' for details."
(python-indent-line))
(defun python-indent-dedent-line ()
"Dedent current line."
"De-indent current line."
(interactive "*")
(when (and (not (or (python-info-ppss-context 'string)
(python-info-ppss-context 'comment)))
......@@ -761,9 +753,9 @@ Internally just calls `python-indent-line'."
t))
(defun python-indent-dedent-line-backspace (arg)
"Dedent current line.
"De-indent current line.
Argument ARG is passed to `backward-delete-char-untabify' when
point is not in between the indentation."
point is not in between the indentation."
(interactive "*p")
(when (not (python-indent-dedent-line))
(backward-delete-char-untabify arg)))
......@@ -795,15 +787,10 @@ Called from a program, START and END specify the region to indent."
(defun python-indent-shift-left (start end &optional count)
"Shift lines contained in region START END by COUNT columns to the left.
COUNT defaults to `python-indent-offset'.
If region isn't active, the current line is shifted.
The shifted region includes the lines in which START and END lie.
An error is signaled if any lines in the region are indented less
than COUNT columns."
COUNT defaults to `python-indent-offset'. If region isn't
active, the current line is shifted. The shifted region includes
the lines in which START and END lie. An error is signaled if
any lines in the region are indented less than COUNT columns."
(interactive
(if mark-active
(list (region-beginning) (region-end) current-prefix-arg)
......@@ -826,13 +813,9 @@ than COUNT columns."
(defun python-indent-shift-right (start end &optional count)
"Shift lines contained in region START END by COUNT columns to the left.
COUNT defaults to `python-indent-offset'.
If region isn't active, the current line is shifted.
The shifted region includes the lines in which START and END
lie."
COUNT defaults to `python-indent-offset'. If region isn't
active, the current line is shifted. The shifted region includes
the lines in which START and END lie."
(interactive
(if mark-active
(list (region-beginning) (region-end) current-prefix-arg)
......@@ -844,9 +827,9 @@ lie."
(indent-rigidly start end count)))
(defun python-indent-electric-colon (arg)
"Insert a colon and maybe outdent the line if it is a statement like `else'.
With numeric ARG, just insert that many colons. With \\[universal-argument],
just insert a single colon."
"Insert a colon and maybe de-indent the current line.
With numeric ARG, just insert that many colons. With
\\[universal-argument], just insert a single colon."
(interactive "*P")
(self-insert-command (if (not (integerp arg)) 1 arg))
(when (and (not arg)
......@@ -974,29 +957,29 @@ Returns nil if point is not in a def or class."
:safe 'stringp)
(defcustom python-shell-prompt-regexp ">>> "
"Regex matching top\-level input prompt of python shell.
The regex should not contain a caret (^) at the beginning."
"Regular Expression matching top\-level input prompt of python shell.
It should not contain a caret (^) at the beginning."
:type 'string
:group 'python
:safe 'stringp)
(defcustom python-shell-prompt-block-regexp "[.][.][.] "
"Regex matching block input prompt of python shell.
The regex should not contain a caret (^) at the beginning."
"Regular Expression matching block input prompt of python shell.
It should not contain a caret (^) at the beginning."
:type 'string
:group 'python
:safe 'stringp)
(defcustom python-shell-prompt-output-regexp nil
"Regex matching output prompt of python shell.
The regex should not contain a caret (^) at the beginning."
"Regular Expression matching output prompt of python shell.
It should not contain a caret (^) at the beginning."
:type 'string
:group 'python
:safe 'stringp)
(defcustom python-shell-prompt-pdb-regexp "[(<]*[Ii]?[Pp]db[>)]+ "
"Regex matching pdb input prompt of python shell.
The regex should not contain a caret (^) at the beginning."
"Regular Expression matching pdb input prompt of python shell.
It should not contain a caret (^) at the beginning."
:type 'string
:group 'python
:safe 'stringp)
......@@ -1005,7 +988,7 @@ The regex should not contain a caret (^) at the beginning."
python-ffap-setup-code
python-eldoc-setup-code)
"List of code run by `python-shell-send-setup-codes'.
Each variable can be either a simple string with the code to
Each variable can contain either a simple string with the code to
execute or a cons with the form (CODE . DESCRIPTION), where CODE
is a string with the code to execute and DESCRIPTION is the
description of it."
......@@ -1030,14 +1013,12 @@ description of it."
(defun python-shell-get-process-name (dedicated)
"Calculate the appropiate process name for inferior Python process.
If DEDICATED is t and the variable `buffer-file-name' is non-nil
returns a string with the form
`python-shell-buffer-name'[variable `buffer-file-name'] else
returns the value of `python-shell-buffer-name'.
After calculating the process name add the buffer name for the
process in the `same-window-buffer-names' list"
returns the value of `python-shell-buffer-name'. After
calculating the process name adds the buffer name for the process
in the `same-window-buffer-names' list."
(let ((process-name
(if (and dedicated
buffer-file-name)
......@@ -1048,7 +1029,7 @@ process in the `same-window-buffer-names' list"
process-name))
(defun python-shell-parse-command ()
"Calculates the string used to execute the inferior Python process."
"Calculate the string used to execute the inferior Python process."
(format "%s %s" python-shell-interpreter python-shell-interpreter-args))
(defun python-comint-output-filter-function (output)
......@@ -1062,10 +1043,24 @@ OUTPUT is a string with the contents of the buffer."
(define-derived-mode inferior-python-mode comint-mode "Inferior Python"
"Major mode for Python inferior process.
Adds `python-shell-completion-complete-at-point' to the
`comint-dynamic-complete-functions' list. Also binds <tab> to
`python-shell-complete-or-indent' in the
`inferior-python-mode-map'."
Runs a Python interpreter as a subprocess of Emacs, with Python
I/O through an Emacs buffer. Variables
`python-shell-interpreter' and `python-shell-interpreter-args'
controls which Python interpreter is run. Variables
`python-shell-prompt-regexp',
`python-shell-prompt-output-regexp',
`python-shell-prompt-block-regexp',
`python-shell-completion-setup-code',
`python-shell-completion-string-code', `python-eldoc-setup-code',
`python-eldoc-string-code', `python-ffap-setup-code' and
`python-ffap-string-code' can customize this mode for different
Python interpreters.
You can also add additional setup code to be run at
initialization of the interpreter via `python-shell-setup-codes'
variable.
\(Type \\[describe-mode] in the process buffer for a list of commands.)"
(set-syntax-table python-mode-syntax-table)
(setq mode-line-process '(":%s"))
(setq comint-prompt-regexp (format "^\\(?:%s\\|%s\\|%s\\)"
......@@ -1091,26 +1086,17 @@ Adds `python-shell-completion-complete-at-point' to the
(defun run-python (dedicated cmd)
"Run an inferior Python process.
Input and output via buffer *\\[python-shell-buffer-name]*.
If there is a process already running in
*\\[python-shell-buffer-name]*, switch to that buffer.
With argument, allows you to:
* Define DEDICATED so a dedicated process for the current buffer
is open.
* Define CMD so you can edit the command used to call the
interpreter (default is value of `python-shell-interpreter' and
arguments defined in `python-shell-interpreter-args').
Runs the hook `inferior-python-mode-hook' (after the
`comint-mode-hook' is run).
\(Type \\[describe-mode] in the process buffer for a list of
commands.)"
Input and output via buffer named after
`python-shell-buffer-name'. If there is a process already
running in that buffer, just switch to it.
With argument, allows you to define DEDICATED, so a dedicated
process for the current buffer is open, and define CMD so you can
edit the command used to call the interpreter (default is value
of `python-shell-interpreter' and arguments defined in
`python-shell-interpreter-args'). Runs the hook
`inferior-python-mode-hook' (after the `comint-mode-hook' is
run).
\(Type \\[describe-mode] in the process buffer for a list of commands.)"
(interactive
(if current-prefix-arg
(list
......@@ -1182,8 +1168,8 @@ When MSG is non-nil messages the first line of STRING."
(defun python-shell-send-string-no-output (string &optional process msg)
"Send STRING to PROCESS and inhibit output.
When MSG is non-nil messages the first line of STRING.
Return the output."
When MSG is non-nil messages the first line of STRING. Return
the output."
(let* ((output-buffer)
(process (or process (python-shell-get-or-create-process)))
(comint-preoutput-filter-functions
......@@ -1360,8 +1346,8 @@ else:
(defun python-shell-completion-complete-or-indent ()
"Complete or indent depending on the context.
If content before pointer is all whitespace indent. If not try to
complete."
If content before pointer is all whitespace indent. If not try
to complete."
(interactive)
(if (string-match "^[[:space:]]*$"
(buffer-substring (comint-line-beginning-position)
......@@ -1374,12 +1360,11 @@ complete."
(defvar python-pdbtrack-stacktrace-info-regexp
"> %s(\\([0-9]+\\))\\([?a-zA-Z0-9_<>]+\\)()"
"Regexp matching stacktrace information.
It is used to extract the current line and module beign
inspected.
The regexp should not start with a caret (^) and can contain a
string placeholder (\%s) which is replaced with the filename
beign inspected (so other files in the debugging process are not
"Regular Expression matching stacktrace information.
Used to extract the current line and module beign inspected. The
regexp should not start with a caret (^) and can contain a string
placeholder (\%s) which is replaced with the filename beign
inspected (so other files in the debugging process are not
opened)")
(defvar python-pdbtrack-tracking-buffers '()
......@@ -1879,7 +1864,7 @@ not inside a defun."
(mapconcat (lambda (string) string) names "."))))
(defun python-info-closing-block ()
"Return the point of the block that the current line closes."
"Return the point of the block the current line closes."
(let ((closing-word (save-excursion
(back-to-indentation)
(current-word)))
......@@ -1981,7 +1966,11 @@ character address of the specified TYPE."
;;;###autoload
(define-derived-mode python-mode fundamental-mode "Python"
"A major mode for editing Python files."
"Major mode for editing Python files.
\\{python-mode-map}
Entry to this mode calls the value of `python-mode-hook'
if that value is non-nil."
(set (make-local-variable 'tab-width) 8)
(set (make-local-variable 'indent-tabs-mode) nil)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment