comparison lisp/eshell/esh-var.el @ 87089:9c568a5e8648

Require individual files if needed when compiling, rather than esh-maint. Collect any require statements. Leave provide at start. Move any commentary to start.

87088:ddc1d773fb48

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.

(provide 'esh-var)

(eval-when-compile (require 'esh-maint))

(defgroup eshell-var nil
  "Variable interpolation is introduced whenever the '$' character
appears unquoted in any argument (except when that argument is
surrounded by single quotes).  It may be used to interpolate a
variable value, a subcommand, or even the result of a Lisp form."
  :tag "Variable handling"
  :group 'eshell)

;;; Commentary:

;; These are the possible variable interpolation syntaxes.  Also keep
;; in mind that if an argument looks like a number, it will be
;; converted to a number.  This is not significant when invoking
;; external commands, but it's important when calling Lisp functions.
;;
;;   $VARIABLE
;;
;; Interval the value of an environment variable, or a Lisp variable
;;
;;   $ALSO-VAR
;;
;; "-" is a legal part of a variable name.
;;
;;   $<MYVAR>-TOO
;;
;; Only "MYVAR" is part of the variable name in this case.
;;
;;   $#VARIABLE
;;
;; Returns the length of the value of VARIABLE.  This could also be
;; done using the `length' Lisp function.
;;
;;   $(lisp)
;;
;; Returns result of lisp evaluation.  Note: Used alone like this, it
;; is identical to just saying (lisp); but with the variable expansion
;; form, the result may be interpolated a larger string, such as
;; '$(lisp)/other'.
;;
;;   ${command}
;;
;; Returns the value of an eshell subcommand.  See the note above
;; regarding Lisp evaluations.
;;
;;   $ANYVAR[10]
;;
;; Return the 10th element of ANYVAR.  If ANYVAR's value is a string,
;; it will be split in order to make it a list.  The splitting will
;; occur at whitespace.
;;
;;   $ANYVAR[: 10]
;;
;; As above, except that splitting occurs at the colon now.
;;
;;   $ANYVAR[: 10 20]
;;
;; As above, but instead of returning just a string, it now returns a
;; list of two strings.  If the result is being interpolated into a
;; larger string, this list will be flattened into one big string,
;; with each element separated by a space.
;;
;;   $ANYVAR["\\\\" 10]
;;
;; Separate on backslash characters.  Actually, the first argument --
;; if it doesn't have the form of a number, or a plain variable name
;; -- can be any regular expression.  So to split on numbers, use
;; '$ANYVAR["[0-9]+" 10 20]'.
;;
;;   $ANYVAR[hello]
;;
;; Calls `assoc' on ANYVAR with 'hello', expecting it to be an alist.
;;
;;   $#ANYVAR[hello]
;;
;; Returns the length of the cdr of the element of ANYVAR who car is
;; equal to "hello".
;;
;; There are also a few special variables defined by Eshell.  '$$' is
;; the value of the last command (t or nil, in the case of an external
;; command).  This makes it possible to chain results:
;;
;;   /tmp $ echo /var/spool/mail/johnw
;;   /var/spool/mail/johnw
;;   /tmp $ dirname $$
;;   /var/spool/mail/
;;   /tmp $ cd $$
;;   /var/spool/mail $
;;
;; '$_' refers to the last argument of the last command.  And $?
;; contains the exit code of the last command (0 or 1 for Lisp
;; functions, based on successful completion).

(require 'env)
(require 'ring)

;;; User Variables:

(defcustom eshell-var-load-hook '(eshell-var-initialize)
  "*A list of functions to call when loading `eshell-var'."

87089:9c568a5e8648

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.

;;; Commentary:

;; These are the possible variable interpolation syntaxes.  Also keep
;; in mind that if an argument looks like a number, it will be
;; converted to a number.  This is not significant when invoking
;; external commands, but it's important when calling Lisp functions.
;;
;;   $VARIABLE
;;
;; Interval the value of an environment variable, or a Lisp variable
;;
;;   $ALSO-VAR
;;
;; "-" is a legal part of a variable name.
;;
;;   $<MYVAR>-TOO
;;
;; Only "MYVAR" is part of the variable name in this case.
;;
;;   $#VARIABLE
;;
;; Returns the length of the value of VARIABLE.  This could also be
;; done using the `length' Lisp function.
;;
;;   $(lisp)
;;
;; Returns result of lisp evaluation.  Note: Used alone like this, it
;; is identical to just saying (lisp); but with the variable expansion
;; form, the result may be interpolated a larger string, such as
;; '$(lisp)/other'.
;;
;;   ${command}
;;
;; Returns the value of an eshell subcommand.  See the note above
;; regarding Lisp evaluations.
;;
;;   $ANYVAR[10]
;;
;; Return the 10th element of ANYVAR.  If ANYVAR's value is a string,
;; it will be split in order to make it a list.  The splitting will
;; occur at whitespace.
;;
;;   $ANYVAR[: 10]
;;
;; As above, except that splitting occurs at the colon now.
;;
;;   $ANYVAR[: 10 20]
;;
;; As above, but instead of returning just a string, it now returns a
;; list of two strings.  If the result is being interpolated into a
;; larger string, this list will be flattened into one big string,
;; with each element separated by a space.
;;
;;   $ANYVAR["\\\\" 10]
;;
;; Separate on backslash characters.  Actually, the first argument --
;; if it doesn't have the form of a number, or a plain variable name
;; -- can be any regular expression.  So to split on numbers, use
;; '$ANYVAR["[0-9]+" 10 20]'.
;;
;;   $ANYVAR[hello]
;;
;; Calls `assoc' on ANYVAR with 'hello', expecting it to be an alist.
;;
;;   $#ANYVAR[hello]
;;
;; Returns the length of the cdr of the element of ANYVAR who car is
;; equal to "hello".
;;
;; There are also a few special variables defined by Eshell.  '$$' is
;; the value of the last command (t or nil, in the case of an external
;; command).  This makes it possible to chain results:
;;
;;   /tmp $ echo /var/spool/mail/johnw
;;   /var/spool/mail/johnw
;;   /tmp $ dirname $$
;;   /var/spool/mail/
;;   /tmp $ cd $$
;;   /var/spool/mail $
;;
;; '$_' refers to the last argument of the last command.  And $?
;; contains the exit code of the last command (0 or 1 for Lisp
;; functions, based on successful completion).

(provide 'esh-var)

(eval-when-compile
  (require 'pcomplete)
  (require 'esh-test)
  (require 'esh-util)
  (require 'esh-opt)
  (require 'esh-mode))
(require 'env)
(require 'ring)

(defgroup eshell-var nil
  "Variable interpolation is introduced whenever the '$' character
appears unquoted in any argument (except when that argument is
surrounded by single quotes).  It may be used to interpolate a
variable value, a subcommand, or even the result of a Lisp form."
  :tag "Variable handling"
  :group 'eshell)

;;; User Variables:

(defcustom eshell-var-load-hook '(eshell-var-initialize)
  "*A list of functions to call when loading `eshell-var'."