[bpt/emacs.git] / lisp / env.el

;;; env.el --- functions to manipulate environment variables  -*- lexical-binding:t -*-

;; Copyright (C) 1991, 1994, 2000-2014 Free Software Foundation, Inc.

;; Maintainer: emacs-devel@gnu.org
;; Keywords: processes, unix
;; Package: emacs

;; This file is part of GNU Emacs.

;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; UNIX processes inherit a list of name-to-string associations from their
;; parents called their `environment'; these are commonly used to control
;; program options.  This package permits you to set environment variables
;; to be passed to any sub-process run under Emacs.

;; Note that the environment string `process-environment' is not
;; decoded, but the args of `setenv' and `getenv' are normally
;; multibyte text and get coding conversion.

;;; Code:

;; History list for environment variable names.
(defvar read-envvar-name-history nil)

(defun read-envvar-name (prompt &optional mustmatch)
  "Read environment variable name, prompting with PROMPT.
Optional second arg MUSTMATCH, if non-nil, means require existing envvar name.
If it is also not t, RET does not exit if it does non-null completion."
  (completing-read prompt
		   (mapcar (lambda (enventry)
                             (let ((str (substring enventry 0
                                             (string-match "=" enventry))))
                               (if (multibyte-string-p str)
                                   (decode-coding-string
                                    str locale-coding-system t)
                                 str)))
			   (append process-environment
				   ;;(frame-environment)
				   ))
		   nil mustmatch nil 'read-envvar-name-history))

;; History list for VALUE argument to setenv.
(defvar setenv-history nil)

(defconst env--substitute-vars-regexp
  "\\$\\(?:\\(?1:[[:alnum:]_]+\\)\\|{\\(?1:[^{}]+\\)}\\|\\$\\)")

(defun substitute-env-vars (string &optional when-undefined)
  "Substitute environment variables referred to in STRING.
`$FOO' where FOO is an environment variable name means to substitute
the value of that variable.  The variable name should be terminated
with a character not a letter, digit or underscore; otherwise, enclose
the entire variable name in braces.  For instance, in `ab$cd-x',
`$cd' is treated as an environment variable.

If WHEN-DEFINED is nil, references to undefined environment variables
are replaced by the empty string; if it is a function, the function is called
with the variable name as argument and should return the text with which
to replace it or nil to leave it unchanged.
If it is non-nil and not a function, references to undefined variables are
left unchanged.

Use `$$' to insert a single dollar sign."
  (let ((start 0))
    (while (string-match env--substitute-vars-regexp string start)
      (cond ((match-beginning 1)
	     (let* ((var (match-string 1 string))
                    (value (getenv var)))
               (if (and (null value)
                        (if (functionp when-undefined)
                            (null (setq value (funcall when-undefined var)))
                          when-undefined))
                   (setq start (match-end 0))
                 (setq string (replace-match (or value "") t t string)
                       start (+ (match-beginning 0) (length value))))))
	    (t
	     (setq string (replace-match "$" t t string)
		   start (+ (match-beginning 0) 1)))))
    string))

(defun substitute-env-in-file-name (filename)
  (substitute-env-vars filename
                       ;; How 'bout we lookup other tables than the env?
                       ;; E.g. we could accept bookmark names as well!
                       (if (memq system-type '(windows-nt ms-dos))
                           (lambda (var) (getenv (upcase var)))
                         t)))

(defun setenv-internal (env variable value keep-empty)
  "Set VARIABLE to VALUE in ENV, adding empty entries if KEEP-EMPTY.
Changes ENV by side-effect, and returns its new value."
  (let ((pattern (concat "\\`" (regexp-quote variable) "\\(=\\|\\'\\)"))
	(case-fold-search nil)
	(scan env)
	prev found)
    ;; Handle deletions from the beginning of the list specially.
    (if (and (null value)
	     (not keep-empty)
	     env
	     (stringp (car env))
	     (string-match pattern (car env)))
	(cdr env)
      ;; Try to find existing entry for VARIABLE in ENV.
      (while (and scan (stringp (car scan)))
	(when (string-match pattern (car scan))
	  (if value
	      (setcar scan (concat variable "=" value))
	    (if keep-empty
		(setcar scan variable)
	      (setcdr prev (cdr scan))))
	  (setq found t
		scan nil))
	(setq prev scan
	      scan (cdr scan)))
      (if (and (not found) (or value keep-empty))
	  (cons (if value
		    (concat variable "=" value)
		  variable)
		env)
	env))))

;; Fixme: Should the environment be recoded if LC_CTYPE &c is set?

(defun setenv (variable &optional value substitute-env-vars)
  "Set the value of the environment variable named VARIABLE to VALUE.
VARIABLE should be a string.  VALUE is optional; if not provided or
nil, the environment variable VARIABLE will be removed.

Interactively, a prefix argument means to unset the variable, and
otherwise the current value (if any) of the variable appears at
the front of the history list when you type in the new value.
This function always replaces environment variables in the new
value when called interactively.

SUBSTITUTE-ENV-VARS, if non-nil, means to substitute environment
variables in VALUE with `substitute-env-vars', which see.
This is normally used only for interactive calls.

The return value is the new value of VARIABLE, or nil if
it was removed from the environment.

This function works by modifying `process-environment'.

As a special case, setting variable `TZ' calls `set-time-zone-rule' as
a side-effect."
  (interactive
   (if current-prefix-arg
       (list (read-envvar-name "Clear environment variable: " 'exact) nil)
     (let* ((var (read-envvar-name "Set environment variable: " nil))
	    (value (getenv var)))
       (when value
	 (add-to-history 'setenv-history value))
       ;; Here finally we specify the args to give call setenv with.
       (list var
	     (read-from-minibuffer (format "Set %s to value: " var)
				   nil nil nil 'setenv-history
				   value)
	     t))))
  (if (and (multibyte-string-p variable) locale-coding-system)
      (let ((codings (find-coding-systems-string (concat variable value))))
	(unless (or (eq 'undecided (car codings))
		    (memq (coding-system-base locale-coding-system) codings))
	  (error "Can't encode `%s=%s' with `locale-coding-system'"
		 variable (or value "")))))
  (and value
       substitute-env-vars
       (setq value (substitute-env-vars value)))
  (if (multibyte-string-p variable)
      (setq variable (encode-coding-string variable locale-coding-system)))
  (if (and value (multibyte-string-p value))
      (setq value (encode-coding-string value locale-coding-system)))
  (if (string-match "=" variable)
      (error "Environment variable name `%s' contains `='" variable))
  (if (string-equal "TZ" variable)
      (set-time-zone-rule value))
  (setq process-environment (setenv-internal process-environment
                                             variable value t))
  value)

(defun getenv (variable &optional frame)
  "Get the value of environment variable VARIABLE.
VARIABLE should be a string.  Value is nil if VARIABLE is undefined in
the environment.  Otherwise, value is a string.

If optional parameter FRAME is non-nil, then it should be a
frame.  This function will look up VARIABLE in its `environment'
parameter.

Otherwise, this function searches `process-environment' for
VARIABLE.  If it is not found there, then it continues the search
in the environment list of the selected frame."
  (interactive (list (read-envvar-name "Get environment variable: " t)))
  (let ((value (getenv-internal (if (multibyte-string-p variable)
				    (encode-coding-string
				     variable locale-coding-system)
				  variable)
				(and frame
				     (assq 'environment
					   (frame-parameters frame))))))
    (if (and enable-multibyte-characters value)
	(setq value (decode-coding-string value locale-coding-system)))
    (when (called-interactively-p 'interactive)
      (message "%s" (if value value "Not set")))
    value))

(provide 'env)

;;; env.el ends here
Commit	Line	Data
ee041f2d	1	;;; env.el --- functions to manipulate environment variables -- lexical-binding:t --
c88ab9ce	2
ba318903	3	;; Copyright (C) 1991, 1994, 2000-2014 Free Software Foundation, Inc.
971571b9	4
34dc21db	5	;; Maintainer: emacs-devel@gnu.org
d9ecc911	6	;; Keywords: processes, unix
bd78fa1d	7	;; Package: emacs
e5167999	8
b578f267	9	;; This file is part of GNU Emacs.
6449c898	10
eb3fa2cf	11	;; GNU Emacs is free software: you can redistribute it and/or modify
b578f267	12	;; it under the terms of the GNU General Public License as published by
eb3fa2cf GM	13	;; the Free Software Foundation, either version 3 of the License, or
eb3fa2cf GM	14	;; (at your option) any later version.
6449c898	15
b578f267 EN	16	;; GNU Emacs is distributed in the hope that it will be useful,
	17	;; but WITHOUT ANY WARRANTY; without even the implied warranty of
	18	;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	19	;; GNU General Public License for more details.
6449c898	20
b578f267	21	;; You should have received a copy of the GNU General Public License
eb3fa2cf	22	;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
6449c898	23
d9ecc911 ER	24	;;; Commentary:
d9ecc911 ER	25
b578f267 EN	26	;; UNIX processes inherit a list of name-to-string associations from their
	27	;; parents called their `environment'; these are commonly used to control
	28	;; program options. This package permits you to set environment variables
	29	;; to be passed to any sub-process run under Emacs.
d9ecc911	30
1a90eae6 DL	31	;; Note that the environment string `process-environment' is not
	32	;; decoded, but the args of `setenv' and `getenv' are normally
	33	;; multibyte text and get coding conversion.
	34
e5167999 ER	35	;;; Code:
e5167999 ER	36
99ac138a RS	37	;; History list for environment variable names.
	38	(defvar read-envvar-name-history nil)
	39
	40	(defun read-envvar-name (prompt &optional mustmatch)
	41	"Read environment variable name, prompting with PROMPT.
8b740009 RS	42	Optional second arg MUSTMATCH, if non-nil, means require existing envvar name.
8b740009 RS	43	If it is also not t, RET does not exit if it does non-null completion."
99ac138a	44	(completing-read prompt
1a90eae6	45	(mapcar (lambda (enventry)
ef651d13 SM	46	(let ((str (substring enventry 0
	47	(string-match "=" enventry))))
	48	(if (multibyte-string-p str)
	49	(decode-coding-string
	50	str locale-coding-system t)
	51	str)))
5990851d	52	(append process-environment
ef651d13	53	;;(frame-environment)
de87fb59	54	))
99ac138a RS	55	nil mustmatch nil 'read-envvar-name-history))
	56
	57	;; History list for VALUE argument to setenv.
	58	(defvar setenv-history nil)
	59
3b11e6ac	60	(defconst env--substitute-vars-regexp
67dd8ad1	61	"\\$\\(?:\\(?1:[[:alnum:]_]+\\)\\\|{\\(?1:[^{}]+\\)}\\\|\\$\\)")
a4a216c5	62
ee041f2d	63	(defun substitute-env-vars (string &optional when-undefined)
a4a216c5 GM	64	"Substitute environment variables referred to in STRING.
	65	`$FOO' where FOO is an environment variable name means to substitute
	66	the value of that variable. The variable name should be terminated
	67	with a character not a letter, digit or underscore; otherwise, enclose
cccc806d RS	68	the entire variable name in braces. For instance, in `ab$cd-x',
cccc806d RS	69	`$cd' is treated as an environment variable.
ee041f2d SM	70
	71	If WHEN-DEFINED is nil, references to undefined environment variables
	72	are replaced by the empty string; if it is a function, the function is called
	73	with the variable name as argument and should return the text with which
	74	to replace it or nil to leave it unchanged.
	75	If it is non-nil and not a function, references to undefined variables are
	76	left unchanged.
cccc806d RS	77
cccc806d RS	78	Use `$$' to insert a single dollar sign."
a4a216c5	79	(let ((start 0))
3b11e6ac	80	(while (string-match env--substitute-vars-regexp string start)
a4a216c5	81	(cond ((match-beginning 1)
ee041f2d SM	82	(let* ((var (match-string 1 string))
	83	(value (getenv var)))
	84	(if (and (null value)
	85	(if (functionp when-undefined)
	86	(null (setq value (funcall when-undefined var)))
	87	when-undefined))
3b11e6ac	88	(setq start (match-end 0))
ee041f2d	89	(setq string (replace-match (or value "") t t string)
3b11e6ac	90	start (+ (match-beginning 0) (length value))))))
a4a216c5 GM	91	(t
	92	(setq string (replace-match "$" t t string)
	93	start (+ (match-beginning 0) 1)))))
	94	string))
	95
ee041f2d SM	96	(defun substitute-env-in-file-name (filename)
	97	(substitute-env-vars filename
	98	;; How 'bout we lookup other tables than the env?
	99	;; E.g. we could accept bookmark names as well!
	100	(if (memq system-type '(windows-nt ms-dos))
	101	(lambda (var) (getenv (upcase var)))
	102	t)))
a13f8f50 KL	103
	104	(defun setenv-internal (env variable value keep-empty)
	105	"Set VARIABLE to VALUE in ENV, adding empty entries if KEEP-EMPTY.
	106	Changes ENV by side-effect, and returns its new value."
	107	(let ((pattern (concat "\\`" (regexp-quote variable) "\\(=\\\|\\'\\)"))
	108	(case-fold-search nil)
	109	(scan env)
	110	prev found)
	111	;; Handle deletions from the beginning of the list specially.
	112	(if (and (null value)
	113	(not keep-empty)
	114	env
	115	(stringp (car env))
	116	(string-match pattern (car env)))
	117	(cdr env)
	118	;; Try to find existing entry for VARIABLE in ENV.
	119	(while (and scan (stringp (car scan)))
	120	(when (string-match pattern (car scan))
	121	(if value
	122	(setcar scan (concat variable "=" value))
	123	(if keep-empty
	124	(setcar scan variable)
	125	(setcdr prev (cdr scan))))
	126	(setq found t
	127	scan nil))
	128	(setq prev scan
	129	scan (cdr scan)))
	130	(if (and (not found) (or value keep-empty))
	131	(cons (if value
	132	(concat variable "=" value)
	133	variable)
	134	env)
	135	env))))
	136
5990851d	137	;; Fixme: Should the environment be recoded if LC_CTYPE &c is set?
a4a216c5	138
ef651d13	139	(defun setenv (variable &optional value substitute-env-vars)
6449c898	140	"Set the value of the environment variable named VARIABLE to VALUE.
b71038b2	141	VARIABLE should be a string. VALUE is optional; if not provided or
17ccbd91	142	nil, the environment variable VARIABLE will be removed.
cbfe666b	143
17ccbd91 KL	144	Interactively, a prefix argument means to unset the variable, and
	145	otherwise the current value (if any) of the variable appears at
	146	the front of the history list when you type in the new value.
	147	This function always replaces environment variables in the new
	148	value when called interactively.
99ac138a	149
27bdc650 RS	150	SUBSTITUTE-ENV-VARS, if non-nil, means to substitute environment
	151	variables in VALUE with `substitute-env-vars', which see.
	152	This is normally used only for interactive calls.
	153
	154	The return value is the new value of VARIABLE, or nil if
	155	it was removed from the environment.
	156
ef651d13 SM	157	This function works by modifying `process-environment'.
ef651d13 SM	158
1a90eae6 DL	159	As a special case, setting variable `TZ' calls `set-time-zone-rule' as
1a90eae6 DL	160	a side-effect."
cbfe666b RS	161	(interactive
cbfe666b RS	162	(if current-prefix-arg
27bdc650	163	(list (read-envvar-name "Clear environment variable: " 'exact) nil)
2a5becfb GM	164	(let* ((var (read-envvar-name "Set environment variable: " nil))
	165	(value (getenv var)))
	166	(when value
4c5f6185	167	(add-to-history 'setenv-history value))
99ac138a	168	;; Here finally we specify the args to give call setenv with.
71296446	169	(list var
a4a216c5 GM	170	(read-from-minibuffer (format "Set %s to value: " var)
	171	nil nil nil 'setenv-history
	172	value)
a4a216c5	173	t))))
1a90eae6	174	(if (and (multibyte-string-p variable) locale-coding-system)
1ebb05c4 KH	175	(let ((codings (find-coding-systems-string (concat variable value))))
	176	(unless (or (eq 'undecided (car codings))
	177	(memq (coding-system-base locale-coding-system) codings))
	178	(error "Can't encode `%s=%s' with `locale-coding-system'"
	179	variable (or value "")))))
27bdc650 RS	180	(and value
	181	substitute-env-vars
	182	(setq value (substitute-env-vars value)))
1a90eae6 DL	183	(if (multibyte-string-p variable)
	184	(setq variable (encode-coding-string variable locale-coding-system)))
	185	(if (and value (multibyte-string-p value))
	186	(setq value (encode-coding-string value locale-coding-system)))
6449c898	187	(if (string-match "=" variable)
f105f403	188	(error "Environment variable name `%s' contains `='" variable))
a13f8f50 KL	189	(if (string-equal "TZ" variable)
a13f8f50 KL	190	(set-time-zone-rule value))
ef651d13 SM	191	(setq process-environment (setenv-internal process-environment
ef651d13 SM	192	variable value t))
a13f8f50	193	value)
49116ac0	194
da8e8fc1	195	(defun getenv (variable &optional frame)
b1e11b4f GM	196	"Get the value of environment variable VARIABLE.
	197	VARIABLE should be a string. Value is nil if VARIABLE is undefined in
	198	the environment. Otherwise, value is a string.
	199
da8e8fc1	200	If optional parameter FRAME is non-nil, then it should be a
3b11e6ac	201	frame. This function will look up VARIABLE in its `environment'
a13f8f50	202	parameter.
f105f403	203
da8e8fc1	204	Otherwise, this function searches `process-environment' for
a13f8f50 KL	205	VARIABLE. If it is not found there, then it continues the search
a13f8f50 KL	206	in the environment list of the selected frame."
b1e11b4f	207	(interactive (list (read-envvar-name "Get environment variable: " t)))
1a90eae6 DL	208	(let ((value (getenv-internal (if (multibyte-string-p variable)
	209	(encode-coding-string
	210	variable locale-coding-system)
36ab8612	211	variable)
263903f7 JB	212	(and frame
	213	(assq 'environment
	214	(frame-parameters frame))))))
1a90eae6 DL	215	(if (and enable-multibyte-characters value)
1a90eae6 DL	216	(setq value (decode-coding-string value locale-coding-system)))
32226619	217	(when (called-interactively-p 'interactive)
b1e11b4f GM	218	(message "%s" (if value value "Not set")))
	219	value))
	220
1bbda2d6 NF	221	(provide 'env)
	222
	223	;;; env.el ends here