diff options
Diffstat (limited to 'doc/lispref')
| -rw-r--r-- | doc/lispref/buffers.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/control.texi | 3 | ||||
| -rw-r--r-- | doc/lispref/debugging.texi | 4 | ||||
| -rw-r--r-- | doc/lispref/edebug.texi | 30 | ||||
| -rw-r--r-- | doc/lispref/elisp.texi | 1 | ||||
| -rw-r--r-- | doc/lispref/eval.texi | 129 | ||||
| -rw-r--r-- | doc/lispref/files.texi | 10 | ||||
| -rw-r--r-- | doc/lispref/frames.texi | 6 | ||||
| -rw-r--r-- | doc/lispref/functions.texi | 29 | ||||
| -rw-r--r-- | doc/lispref/hooks.texi | 1 | ||||
| -rw-r--r-- | doc/lispref/internals.texi | 7 | ||||
| -rw-r--r-- | doc/lispref/lists.texi | 12 | ||||
| -rw-r--r-- | doc/lispref/loading.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/minibuf.texi | 8 | ||||
| -rw-r--r-- | doc/lispref/numbers.texi | 50 | ||||
| -rw-r--r-- | doc/lispref/objects.texi | 10 | ||||
| -rw-r--r-- | doc/lispref/os.texi | 39 | ||||
| -rw-r--r-- | doc/lispref/package.texi | 36 | ||||
| -rw-r--r-- | doc/lispref/processes.texi | 7 | ||||
| -rw-r--r-- | doc/lispref/searching.texi | 4 | ||||
| -rw-r--r-- | doc/lispref/sequences.texi | 8 | ||||
| -rw-r--r-- | doc/lispref/streams.texi | 15 | ||||
| -rw-r--r-- | doc/lispref/strings.texi | 31 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 240 | ||||
| -rw-r--r-- | doc/lispref/windows.texi | 7 |
25 files changed, 604 insertions, 87 deletions
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 45e90669b7e..cfd2fb7715b 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -816,7 +816,7 @@ regardless of which frames they were displayed on. @group ;; @r{Note that the name of the minibuffer} ;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) +(mapcar #'buffer-name (buffer-list)) @result{} ("buffers.texi" " *Minibuf-1*" "buffer.c" "*Help*" "TAGS") @end group diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 9e1bd6b3ecb..34f5f570440 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1250,7 +1250,8 @@ This construct executes @var{body} once for each integer from 0 (inclusive) to @var{count} (exclusive), binding the variable @var{var} to the integer for the current iteration. Then it returns the value of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: +Use of @var{result} is deprecated. Here is an example of using +@code{dotimes} to do something 100 times: @example (dotimes (i 100) diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index c08a382ef12..2daa8a5578f 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -656,7 +656,7 @@ forms are elided. (list ...computing arguments...) @end group (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) + eval((progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) @@ -687,7 +687,7 @@ example would look as follows: (list ...computing arguments...) @end group (progn ...) - (eval (progn (1+ var) (list (quote testing) (backtrace)))) + (eval (progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 5af48fe0963..b9cc1d5afc2 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1712,3 +1712,33 @@ Whether or not to pause for @code{edebug-sit-for-seconds} on reaching a breakpoint. Set to @code{nil} to prevent the pause, non-@code{nil} to allow it. @end defopt + +@defopt edebug-behavior-alist +By default, this alist contains one entry with the key @code{edebug} +and a list of three functions, which are the default implementations +of the functions inserted in instrumented code: @code{edebug-enter}, +@code{edebug-before} and @code{edebug-after}. To change Edebug's +behavior globally, modify the default entry. + +Edebug's behavior may also be changed on a per-definition basis by +adding an entry to this alist, with a key of your choice and three +functions. Then set the @code{edebug-behavior} symbol property of an +instrumented definition to the key of the new entry, and Edebug will +call the new functions in place of its own for that definition. +@end defopt + +@defopt edebug-new-definition-function +A function run by Edebug after it wraps the body of a definition +or closure. After Edebug has initialized its own data, this function +is called with one argument, the symbol associated with the +definition, which may be the actual symbol defined or one generated by +Edebug. This function may be used to set the @code{edebug-behavior} +symbol property of each definition instrumented by Edebug. +@end defopt + +@defopt edebug-after-instrumentation-function +To inspect or modify Edebug's instrumentation before it is used, set +this variable to a function which takes one argument, an instrumented +top-level form, and returns either the same or a replacement form, +which Edebug will then use as the final result of instrumentation. +@end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 6c3182b0c70..7ac9198bf84 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -455,6 +455,7 @@ Evaluation the program). * Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. +* Deferred Eval:: Deferred and lazy evaluation of forms. Kinds of Forms diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 2590de30c79..4e8b0df7b58 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -20,11 +20,12 @@ function @code{eval}. @ifnottex @menu -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. +* Intro Eval:: Evaluation in the scheme of things. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in the program). +* Backquote:: Easier construction of list structure. +* Eval:: How to invoke the Lisp interpreter explicitly. +* Deferred Eval:: Deferred and lazy evaluation of forms. @end menu @node Intro Eval @@ -579,15 +580,15 @@ Here are some examples of expressions that use @code{quote}: @end group @group ''foo - @result{} (quote foo) + @result{} 'foo @end group @group '(quote foo) - @result{} (quote foo) + @result{} 'foo @end group @group ['foo] - @result{} [(quote foo)] + @result{} ['foo] @end group @end example @@ -877,3 +878,115 @@ particular elements, like this: @end group @end example @end defvar + +@node Deferred Eval +@section Deferred and Lazy Evaluation + +@cindex deferred evaluation +@cindex lazy evaluation + + + Sometimes it is useful to delay the evaluation of an expression, for +example if you want to avoid performing a time-consuming calculation +if it turns out that the result is not needed in the future of the +program. The @file{thunk} library provides the following functions +and macros to support such @dfn{deferred evaluation}: + +@cindex thunk +@defmac thunk-delay forms@dots{} +Return a @dfn{thunk} for evaluating the @var{forms}. A thunk is a +closure (@pxref{Closures}) that inherits the lexical environment of the +@code{thunk-delay} call. Using this macro requires +@code{lexical-binding}. +@end defmac + +@defun thunk-force thunk +Force @var{thunk} to perform the evaluation of the forms specified in +the @code{thunk-delay} that created the thunk. The result of the +evaluation of the last form is returned. The @var{thunk} also +``remembers'' that it has been forced: Any further calls of +@code{thunk-force} with the same @var{thunk} will just return the same +result without evaluating the forms again. +@end defun + +@defmac thunk-let (bindings@dots{}) forms@dots{} +This macro is analogous to @code{let} but creates ``lazy'' variable +bindings. Any binding has the form @w{@code{(@var{symbol} +@var{value-form})}}. Unlike @code{let}, the evaluation of any +@var{value-form} is deferred until the binding of the according +@var{symbol} is used for the first time when evaluating the +@var{forms}. Any @var{value-form} is evaluated at most once. Using +this macro requires @code{lexical-binding}. +@end defmac + +Example: + +@example +@group +(defun f (number) + (thunk-let ((derived-number + (progn (message "Calculating 1 plus 2 times %d" number) + (1+ (* 2 number))))) + (if (> number 10) + derived-number + number))) +@end group + +@group +(f 5) +@result{} 5 +@end group + +@group +(f 12) +@print{} Calculating 1 plus 2 times 12 +@result{} 25 +@end group + +@end example + +Because of the special nature of lazily bound variables, it is an error +to set them (e.g.@: with @code{setq}). + + +@defmac thunk-let* (bindings@dots{}) forms@dots{} +This is like @code{thunk-let} but any expression in @var{bindings} is allowed +to refer to preceding bindings in this @code{thunk-let*} form. Using +this macro requires @code{lexical-binding}. +@end defmac + +@example +@group +(thunk-let* ((x (prog2 (message "Calculating x...") + (+ 1 1) + (message "Finished calculating x"))) + (y (prog2 (message "Calculating y...") + (+ x 1) + (message "Finished calculating y"))) + (z (prog2 (message "Calculating z...") + (+ y 1) + (message "Finished calculating z"))) + (a (prog2 (message "Calculating a...") + (+ z 1) + (message "Finished calculating a")))) + (* z x)) + +@print{} Calculating z... +@print{} Calculating y... +@print{} Calculating x... +@print{} Finished calculating x +@print{} Finished calculating y +@print{} Finished calculating z +@result{} 8 + +@end group +@end example + +@code{thunk-let} and @code{thunk-let*} use thunks implicitly: their +expansion creates helper symbols and binds them to thunks wrapping the +binding expressions. All references to the original variables in the +body @var{forms} are then replaced by an expression that calls +@code{thunk-force} with the according helper variable as the argument. +So, any code using @code{thunk-let} or @code{thunk-let*} could be +rewritten to use thunks, but in many cases using these macros results +in nicer code than using thunks explicitly. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 5137f3a9ab4..e36fdbe95bf 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -2121,7 +2121,7 @@ Note that the @samp{.~3~} in the two last examples is the backup part, not an extension. @end defun -@defun file-name-base &optional filename +@defun file-name-base filename This function is the composition of @code{file-name-sans-extension} and @code{file-name-nondirectory}. For example, @@ -2129,8 +2129,6 @@ and @code{file-name-nondirectory}. For example, (file-name-base "/my/home/foo.c") @result{} "foo" @end example - -The @var{filename} argument defaults to @code{buffer-file-name}. @end defun @node Relative File Names @@ -3151,7 +3149,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-preserved-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name},@* @code{get-file-buffer}, @code{insert-directory}, @@ -3207,7 +3206,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-pre@discretionary{}{}{}served-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, @code{get-file-buffer}, @code{insert-directory}, diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 2f9bb398865..459f05cb1c9 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -181,6 +181,12 @@ the value of that parameter in the created frame to its value in the selected frame. @end defvar +@defopt server-after-make-frame-hook +A normal hook run when the Emacs server creates a client frame. When +this hook is called, the created frame is the selected one. +@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@end defopt + @node Multiple Terminals @section Multiple Terminals diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 86181f1b491..f12fb3d00d9 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -371,8 +371,8 @@ keyword @code{&rest} before one final argument. @example @group (@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) + @r{[}&optional @r{[}@var{optional-vars}@dots{}@r{]}@r{]} + @r{[}&rest @r{[}@var{rest-var}@r{]}@r{]}) @end group @end example @@ -1235,7 +1235,7 @@ This form defines a method like @code{cl-defmethod} does. @end table @end defmac -@defmac cl-defmethod name [qualifier] arguments &rest [docstring] body +@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body This macro defines a particular implementation for the generic function called @var{name}. The implementation code is given by @var{body}. If present, @var{docstring} is the documentation string @@ -1262,15 +1262,20 @@ defined with @code{cl-defstruct} (@pxref{Structures,,, cl, Common Lisp Extensions for GNU Emacs Lisp}), or of one of its child classes. @end table -Alternatively, the argument specializer can be of the form -@code{&context (@var{expr} @var{spec})}, in which case the value of -@var{expr} must be compatible with the specializer provided by -@var{spec}; @var{spec} can be any of the forms described above. In -other words, this form of specializer uses the value of @var{expr} -instead of arguments for the decision whether the method is -applicable. For example, @code{&context (overwrite-mode (eql t))} -will make the method compatible only when @code{overwrite-mode} is -turned on. +Method definitions can make use of a new argument-list keyword, +@code{&context}, which introduces extra specializers that test the +environment at the time the method is run. This keyword should appear +after the list of required arguments, but before any @code{&rest} or +@code{&optional} keywords. The @code{&context} specializers look much +like regular argument specializers---(@var{expr} @var{spec})---except +that @var{expr} is an expression to be evaluated in the current +context, and the @var{spec} is a value to compare against. For +example, @code{&context (overwrite-mode (eql t))} will make the method +applicable only when @code{overwrite-mode} is turned on. The +@code{&context} keyword can be followed by any number of context +specializers. Because the context specializers are not part of the +generic function's argument signature, they may be omitted in methods +that don't require them. The type specializer, @code{(@var{arg} @var{type})}, can specify one of the @dfn{system types} in the following list. When a parent type diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index db4e413921f..e374d02defb 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -66,6 +66,7 @@ not exactly a hook, but does a similar job. @item after-make-frame-functions @itemx before-make-frame-hook +@itemx server-after-make-frame-hook @xref{Creating Frames}. @c Not general enough? diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index e6043357a11..9cf1a4f9a32 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -758,6 +758,13 @@ names in the documentation string from the ones used in the C code. @samp{usage:} is required if the function has an unlimited number of arguments. +Some primitives have multiple definitions, one per platform (e.g., +@code{x-create-frame}). In such cases, rather than writing the +same documentation string in each definition, only one definition has +the actual documentation. The others have placeholders beginning with +@samp{SKIP}, which are ignored by the function that parses the +@file{DOC} file. + All the usual rules for documentation strings in Lisp code (@pxref{Documentation Tips}) apply to C code documentation strings too. diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 431f5fbbab2..761750eb20c 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1141,7 +1141,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) + @result{} (lambda (x) (nconc '(foo) x)) @end group @group @@ -1159,7 +1159,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) + @result{} (lambda (x) (nconc '(foo 1 2 3 4) x)) @end group @end smallexample @end defun @@ -1733,6 +1733,14 @@ alist @end example @end defun +@defun assoc-delete-all key alist &optional test +This function is like @code{assq-delete-all} except that it accepts +an optional argument @var{test}, a predicate function to compare the +keys in @var{alist}. If omitted or @code{nil}, @var{test} defaults to +@code{equal}. As @code{assq-delete-all}, this function often modifies +the original list structure of @var{alist}. +@end defun + @defun rassq-delete-all value alist This function deletes from @var{alist} all the elements whose @sc{cdr} is @code{eq} to @var{value}. It returns the shortened alist, and diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 80b75729c13..82c133de753 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -641,7 +641,7 @@ autoloading with a magic comment: Here's what that produces in @file{loaddefs.el}: @example -(autoload (quote doctor) "doctor" "\ +(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy. \(fn)" t nil) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 1d1c93dd144..889b64af8ae 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -634,6 +634,12 @@ A history list for arguments that are Lisp expressions to evaluate. A history list for arguments that are faces. @end defvar +@findex read-variable@r{, history list} +@defvar custom-variable-history +A history list for variable-name arguments read by +@code{read-variable}. +@end defvar + @c Less common: coding-system-history, input-method-history, @c command-history, grep-history, grep-find-history, @c read-envvar-name-history, setenv-history, yes-or-no-p-history. @@ -2456,7 +2462,7 @@ locally inside the minibuffer (@pxref{Help Functions}). @anchor{Definition of minibuffer-scroll-window} If the value of this variable is non-@code{nil}, it should be a window object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. +minibuffer, it scrolls this window (@pxref{Textual Scrolling}). @end defvar @defun minibuffer-selected-window diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index c12ffe2cde7..2fed2b642fd 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -53,17 +53,15 @@ but many machines provide a wider range. Many examples in this chapter assume the minimum integer width of 30 bits. @cindex overflow - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. An integer that is out of the -Emacs range is treated as a floating-point number. + The Lisp reader reads an integer as a nonempty sequence +of decimal digits with optional initial sign and optional +final period. @example 1 ; @r{The integer 1.} 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 9000000000000000000 - ; @r{The floating-point number 9e18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -74,14 +72,17 @@ Emacs range is treated as a floating-point number. @cindex hex numbers @cindex octal numbers @cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads + The syntax for integers in bases other than 10 consists of @samp{#} +followed by a radix indication followed by one or more digits. The +radix indications are @samp{b} for binary, @samp{o} for octal, +@samp{x} for hex, and @samp{@var{radix}r} for radix @var{radix}. +Thus, @samp{#b@var{integer}} reads @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads @var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: +from 2 to 36, and allowed digits are the first @var{radix} characters +taken from @samp{0}--@samp{9}, @samp{A}--@samp{Z}. +Letter case is ignored and there is no initial sign or final period. +For example: @example #b101100 @result{} 44 @@ -90,6 +91,15 @@ from 2 to 36. For example: #24r1k @result{} 44 @end example + If an integer is outside the Emacs range, the Lisp reader ordinarily +signals an overflow. However, if a too-large plain integer ends in a +period, the Lisp reader treats it as a floating-point number instead. +This lets an Emacs Lisp program specify a large integer that is +quietly approximated by a floating-point number on machines with +limited word width. For example, @samp{536870912.} is a +floating-point number if Emacs integers are only 30 bits wide and is +an integer otherwise. + To understand how various functions work on integers, especially the bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. @@ -1107,6 +1117,24 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @end example @end defun +@cindex popcount +@cindex Hamming weight +@cindex counting set bits +@defun logcount integer +This function returns the @dfn{Hamming weight} of @var{integer}: the +number of ones in the binary representation of @var{integer}. +If @var{integer} is negative, it returns the number of zero bits in +its two's complement binary representation. The result is always +nonnegative. + +@example +(logcount 43) ; 43 = #b101011 + @result{} 4 +(logcount -43) ; -43 = #b111...1010101 + @result{} 3 +@end example +@end defun + @node Math Functions @section Standard Mathematical Functions @cindex transcendental functions diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index af740625adb..78a7dccc88d 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -2083,6 +2083,10 @@ strings), two arguments with the same contents or elements are not necessarily @code{eq} to each other: they are @code{eq} only if they are the same object, meaning that a change in the contents of one will be reflected by the same change in the contents of the other. +For other types of objects whose contents cannot be changed (e.g., +floats), two arguments with the same contents might or might not be +the same object, and @code{eq} returns @code{t} or @code{nil} +depending on whether the Lisp interpreter created one object or two. @example @group @@ -2096,6 +2100,12 @@ be reflected by the same change in the contents of the other. @end group @group +(eq 3.0 3.0) + @result{} t @r{or} nil +;; @r{The result is implementation-dependent.} +@end group + +@group (eq "asdf" "asdf") @result{} nil @end group diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index ed73a1c0319..adf554e8436 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -95,6 +95,22 @@ if requested by environment variables such as @env{LANG}. @item It does some basic parsing of the command-line arguments. +@item +It loads your early init file (@pxref{Early Init File,,, emacs, The +GNU Emacs Manual}). This is not done if the options @samp{-q}, +@samp{-Q}, or @samp{--batch} were specified. If the @samp{-u} option +was specified, Emacs looks for the init file in that user's home +directory instead. + +@item +It calls the function @code{package-activate-all} to activate any +optional Emacs Lisp package that has been installed. @xref{Packaging +Basics}. However, Emacs doesn't activate the packages when +@code{package-enable-at-startup} is @code{nil} or when it's started +with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To +activate the packages in the latter case, @code{package-activate-all} +should be called explicitly (e.g., via the @samp{--funcall} option). + @vindex initial-window-system@r{, and startup} @vindex window-system-initialization-alist @item @@ -154,15 +170,6 @@ It loads your abbrevs from the file specified by (@pxref{Abbrev Files, abbrev-file-name}). This is not done if the option @samp{--batch} was specified. -@item -It calls the function @code{package-initialize} to activate any -optional Emacs Lisp package that has been installed. @xref{Packaging -Basics}. However, Emacs doesn't initialize packages when -@code{package-enable-at-startup} is @code{nil} or when it's started -with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To -initialize packages in the latter case, @code{package-initialize} -should be called explicitly (e.g., via the @samp{--funcall} option). - @vindex after-init-time @item It sets the variable @code{after-init-time} to the value of @@ -361,6 +368,7 @@ Equivalent to @samp{-q --no-site-file --no-splash}. @cindex init file @cindex @file{.emacs} @cindex @file{init.el} +@cindex @file{early-init.el} When you start Emacs, it normally attempts to load your @dfn{init file}. This is either a file named @file{.emacs} or @file{.emacs.el} @@ -384,6 +392,19 @@ file; this way, even if you have su'd, Emacs still loads your own init file. If those environment variables are absent, though, Emacs uses your user-id to find your home directory. +@cindex early init file + Emacs also attempts to load a second init file, called the +@dfn{early init file}, if it exists. This is a file named +@file{early-init.el} in your @file{~/.emacs.d} directory. The +difference between the early init file and the regular init file is +that the early init file is loaded much earlier during the startup +process, so you can use it to customize some things that are +initialized before loading the regular init file. For example, you +can customize the process of initializing the package system, by +setting variables such as @var{package-load-list} or +@var{package-enable-at-startup}. @xref{Package Installation,,, +emacs,The GNU Emacs Manual}. + @cindex default init file An Emacs installation may have a @dfn{default init file}, which is a Lisp library named @file{default.el}. Emacs finds this file through diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index c1c61a1b5c6..37c1ee6697d 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -105,24 +105,36 @@ adds the package's content directory to @code{load-path}, and evaluates the autoload definitions in @file{@var{name}-autoloads.el}. Whenever Emacs starts up, it automatically calls the function -@code{package-initialize} to load installed packages. This is done -after loading the init file and abbrev file (if any) and before -running @code{after-init-hook} (@pxref{Startup Summary}). Automatic -package loading is disabled if the user option -@code{package-enable-at-startup} is @code{nil}. +@code{package-activate-all} to make installed packages available to the +current session. This is done after loading the early init file, but +before loading the regular init file (@pxref{Startup Summary}). +Packages are not automatically made available if the user option +@code{package-enable-at-startup} is set to @code{nil} in the early +init file. + +@defun package-activate-all +This function makes the packages available to the current session. +The user option @code{package-load-list} specifies which packages to +make available; by default, all installed packages are made available. +If called during startup, this function also sets +@code{package-enable-at-startup} to @code{nil}, to avoid accidentally +evaluating package autoloads more than once. @xref{Package +Installation,,, emacs, The GNU Emacs Manual}. + +In most cases, you should not need to call @code{package-activate-all}, +as this is done automatically during startup. Simply make sure to put +any code that should run before @code{package-activate-all} in the early +init file, and any code that should run after it in the primary init +file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). +@end defun @deffn Command package-initialize &optional no-activate This function initializes Emacs' internal record of which packages are -installed, and loads them. The user option @code{package-load-list} -specifies which packages to load; by default, all installed packages -are loaded. If called during startup, this function also sets -@code{package-enable-at-startup} to @code{nil}, to avoid accidentally -loading the packages twice. @xref{Package Installation,,, emacs, The -GNU Emacs Manual}. +installed, and then calls @code{package-activate-all}. The optional argument @var{no-activate}, if non-@code{nil}, causes Emacs to update its record of installed packages without actually -loading them; it is for internal use only. +making them available. @end deffn @node Simple Packages diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 34426f339c6..3e26f577982 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -681,7 +681,9 @@ a default sentinel will be used, which can be overridden later. @item :stderr @var{stderr} Associate @var{stderr} with the standard error of the process. A non-@code{nil} value should be either a buffer or a pipe process -created with @code{make-pipe-process}, described below. +created with @code{make-pipe-process}, described below. If +@var{stderr} is @code{nil}, standard error is mixed with standard +output, and both are sent to @var{buffer} or @var{filter}. @end table The original argument list, modified with the actual connection @@ -2715,8 +2717,7 @@ Initialize the process filter to @var{filter}. @item :filter-multibyte @var{multibyte} If @var{multibyte} is non-@code{nil}, strings given to the process -filter are multibyte, otherwise they are unibyte. The default is the -default value of @code{enable-multibyte-characters}. +filter are multibyte, otherwise they are unibyte. The default is @code{t}. @item :sentinel @var{sentinel} Initialize the process sentinel to @var{sentinel}. diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 6c1ebb22b53..1b6b80d31b2 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -642,10 +642,10 @@ is omitted, the minimum is 0; if @var{n} is omitted, there is no maximum. For both forms, @var{m} and @var{n}, if specified, may be no larger than @ifnottex -2**15 @minus{} 1 +2**16 @minus{} 1 @end ifnottex @tex -@math{2^{15}-1} +@math{2^{16}-1} @end tex . diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index f347cd9e980..ffec6f37df7 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1298,9 +1298,9 @@ not evaluate or even examine the elements of the vector. @example @group (setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eval avector) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eq avector (eval avector)) @result{} t @end group @@ -1390,9 +1390,9 @@ list with the same elements: @example @group (setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (append avector nil) - @result{} (1 two (quote (three)) "four" [five]) + @result{} (1 two '(three) "four" [five]) @end group @end example diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index ebd806601ef..032669cb102 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -809,6 +809,21 @@ when the output stream is a unibyte buffer or a marker pointing into one. @end defvar +@defvar print-charset-text-property +This variable controls printing of `charset' text property on printing +a string. The value should be @code{nil}, @code{t}, or +@code{default}. + +If the value is @code{nil}, @code{charset} text properties are never +printed. If @code{t}, they are always printed. + +If the value is @code{default}, only print @code{charset} text +properties if there is an ``unexpected'' @code{charset} property. For +ascii characters, all charsets are considered ``expected''. +Otherwise, the expected @code{charset} property of a character is +given by @code{char-charset}. +@end defvar + @defvar print-length @cindex printing limits The value of this variable is the maximum number of elements to print in diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index f3911998799..70ba1aa613e 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -121,7 +121,7 @@ character (i.e., an integer), @code{nil} otherwise. The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. -@defun make-string count character +@defun make-string count character &optional multibyte This function returns a string made up of @var{count} repetitions of @var{character}. If @var{count} is negative, an error is signaled. @@ -132,6 +132,13 @@ This function returns a string made up of @var{count} repetitions of @result{} "" @end example + Normally, if @var{character} is an @acronym{ASCII} character, the +result is a unibyte string. But if the optional argument +@var{multibyte} is non-@code{nil}, the function will produce a +multibyte string instead. This is useful when you later need to +concatenate the result with non-@acronym{ASCII} strings or replace +some of its characters with non-@acronym{ASCII} characters. + Other functions to compare with this one include @code{make-vector} (@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}). @end defun @@ -666,6 +673,28 @@ of the two strings. The sign is negative if @var{string1} (or its specified portion) is less. @end defun +@cindex Levenshtein distance +@cindex distance between strings +@cindex edit distance between strings +@defun string-distance string1 string2 &optional bytecompare +This function returns the @dfn{Levenshtein distance} between the +source string @var{string1} and the target string @var{string2}. The +Levenshtein distance is the number of single-character +changes---deletions, insertions, or replacements---required to +transform the source string into the target string; it is one possible +definition of the @dfn{edit distance} between strings. + +Letter-case of the strings is significant for the computed distance, +but their text properties are ignored. If the optional argument +@var{bytecompare} is non-@code{nil}, the function calculates the +distance in terms of bytes instead of characters. The byte-wise +comparison uses the internal Emacs representation of characters, so it +will produce inaccurate results for multibyte strings that include raw +bytes (@pxref{Text Representations}); make the strings unibyte by +encoding them (@pxref{Explicit Encoding}) if you need accurate results +with raw bytes. +@end defun + @defun assoc-string key alist &optional case-fold This function works like @code{assoc}, except that @var{key} must be a string or symbol, and comparison is done using @code{compare-strings}. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 6dde4c00f85..da09b4ae1c6 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -61,6 +61,7 @@ the character after point. * Checksum/Hash:: Computing cryptographic hashes. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. * Parsing HTML/XML:: Parsing HTML and XML. +* Parsing JSON:: Parsing and generating JSON values. * Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -3183,6 +3184,95 @@ buffer to scan. Positions are relative to @var{object}. The default for @var{object} is the current buffer. @end defun +@defun text-property-search-forward prop &optional value predicate not-current +Search for the next region that has text property @var{prop} set to +@var{value} according to @var{predicate}. + +This function is modelled after @code{search-forward} and friends in +that it moves point, but it returns a structure that describes the +match instead of returning it in @code{match-beginning} and friends. + +If the text property can't be found, the function returns @code{nil}. +If it's found, point is placed at the end of the region that has this +text property match, and a @code{prop-match} structure is returned. + +@var{predicate} can either be @code{t} (which is a synonym for +@code{equal}), @code{nil} (which means ``not equal''), or a predicate +that will be called with two parameters: The first is @var{value}, and +the second is the value of the text property we're inspecting. + +If @var{not-current}, if point is in a region where we have a match, +then skip past that and find the next instance instead. + +The @code{prop-match} structure has the following accessors: +@code{prop-match-beginning} (the start of the match), +@code{prop-match-end} (the end of the match), and +@code{prop-match-value} (the value of @var{property} at the start of +the match). + +In the examples below, imagine that you're in a buffer that looks like +this: + +@example +This is a bold and here's bolditalic and this is the end. +@end example + +That is, the ``bold'' words are the @code{bold} face, and the +``italic'' word is in the @code{italic} face. + +With point at the start: + +@lisp +(while (setq match (text-property-search-forward 'face 'bold t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the words that use the @code{bold} face. + +@lisp +(while (setq match (text-property-search-forward 'face nil t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the bits that have no face properties, which +will result in the list @samp{("This is a " "and here's " "and this is +the end")} (only reversed, since we used @code{push}). + +@lisp +(while (setq match (text-property-search-forward 'face nil nil)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the regions where @code{face} is set to +something, but this is split up into where the properties change, so +the result here will be @samp{("bold" "bold" "italic")}. + +For a more realistic example where you might use this, consider that +you have a buffer where certain sections represent URLs, and these are +tagged with @code{shr-url}. + +@lisp +(while (setq match (text-property-search-forward 'shr-url nil nil)) + (push (prop-match-value match) urls)) +@end lisp + +This will give you a list of all those URLs. + +@end defun + +@defun text-property-search-backward prop &optional value predicate not-current +This is just like @code{text-property-search-backward}, but searches +backward instead. Point is placed at the beginning of the matched +region instead of the end, though. +@end defun + + @node Special Properties @subsection Properties with Special Meanings @@ -4520,9 +4610,9 @@ It should be somewhat more efficient on larger buffers than @cindex symmetric cipher @cindex cipher, symmetric -If compiled with GnuTLS, Emacs offers built-in cryptographic support. -Following the GnuTLS API terminology, the available tools are digests, -MACs, symmetric ciphers, and AEAD ciphers. + If compiled with GnuTLS, Emacs offers built-in cryptographic +support. Following the GnuTLS API terminology, the available tools +are digests, MACs, symmetric ciphers, and AEAD ciphers. The terms used herein, such as IV (Initialization Vector), require some familiarity with cryptography and will not be defined in detail. @@ -4540,7 +4630,7 @@ structure of the GnuTLS library. @cindex format of gnutls cryptography inputs @cindex gnutls cryptography inputs format -The inputs to GnuTLS cryptographic functions can be specified in + The inputs to GnuTLS cryptographic functions can be specified in several ways, both as primitive Emacs Lisp types or as lists. The list form is currently similar to how @code{md5} and @@ -4707,8 +4797,15 @@ IV used. @section Parsing HTML and XML @cindex parsing html -When Emacs is compiled with libxml2 support, the following functions -are available to parse HTML or XML text into Lisp object trees. + Emacs can be compiled with built-in libxml2 support. + +@defun libxml-available-p +This function returns non-@code{nil} if built-in libxml2 support is +available in this Emacs session. +@end defun + +When libxml2 support is available, the following functions can be used +to parse HTML or XML text into Lisp object trees. @defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as @@ -4720,7 +4817,10 @@ The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. If the optional argument @var{discard-comments} is non-@code{nil}, -then the parse tree is created without any comments. +any top-level comment is discarded. (This argument is obsolete and +will be removed in future Emacs versions. To remove comments, use the +@code{xml-remove-comments} utility function on the data before you +call the parsing function.) In the parse tree, each HTML node is represented by a list in which the first element is a symbol representing the node name, the second @@ -4775,9 +4875,9 @@ about syntax). @cindex DOM @cindex Document Object Model -The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the -other @acronym{XML} parsing functions) is a tree structure where each -node has a node name (called a @dfn{tag}), and optional key/value + The @acronym{DOM} returned by @code{libxml-parse-html-region} (and +the other @acronym{XML} parsing functions) is a tree structure where +each node has a node name (called a @dfn{tag}), and optional key/value @dfn{attribute} list, and then a list of @dfn{child nodes}. The child nodes are either strings or @acronym{DOM} objects. @@ -4895,6 +4995,98 @@ textual nodes that just contain white-space. @end table +@node Parsing JSON +@section Parsing and generating JSON values +@cindex JSON + + When Emacs is compiled with JSON support, it provides a couple of +functions to convert between Lisp objects and JSON values. Any JSON +value can be converted to a Lisp object, but not vice versa. +Specifically: + +@itemize + +@item +JSON has a couple of keywords: @code{null}, @code{false}, and +@code{true}. These are represented in Lisp using the keywords +@code{:null}, @code{:false}, and @code{t}, respectively. + +@item +JSON only has floating-point numbers. They can represent both Lisp +integers and Lisp floating-point numbers. + +@item +JSON strings are always Unicode strings. Lisp strings can contain +non-Unicode characters. + +@item +JSON has only one sequence type, the array. JSON arrays are +represented using Lisp vectors. + +@item +JSON has only one map type, the object. JSON objects are represented +using Lisp hashtables or alists. When an alist contains several +elements with the same key, Emacs uses only the first element for +serialization, in accordance with the behavior of @code{assq}. + +@end itemize + +@noindent +Note that @code{nil} is a valid alist and represents the empty JSON +object, @code{@{@}}, not @code{null}, @code{false}, or an empty array, +all of which are different JSON values. + + If some Lisp object can't be represented in JSON, the serialization +functions will signal an error of type @code{wrong-type-argument}. +The parsing functions will signal the following errors: + +@table @code + +@item json-end-of-file + Signaled when encountering a premature end of the input text. + +@item json-trailing-content + Signaled when encountering unexpected input after the first JSON + object parsed. + +@item json-parse-error + Signaled when encountering invalid JSON syntax. + +@end table + + Only top-level values (arrays and objects) can be serialized to +JSON. The subobjects within these top-level values can be of any +type. Likewise, the parsing functions will only return vectors, +hashtables, and alists. + + The parsing functions accept keyword arguments. Currently only one +keyword argument, @code{:object-type}, is recognized; its value can be +either @code{hash-table} to parse JSON objects as hashtables with +string keys (the default) or @code{alist} to parse them as alists. + +@defun json-serialize object +This function returns a new Lisp string which contains the JSON +representation of @var{object}. +@end defun + +@defun json-insert object +This function inserts the JSON representation of @var{object} into the +current buffer before point. +@end defun + +@defun json-parse-string string &key (object-type @code{hash-table}) +This function parses the JSON value in @var{string}, which must be a +Lisp string. +@end defun + +@defun json-parse-buffer &key (object-type @code{hash-table}) +This function reads the next JSON value from the current buffer, +starting at point. It moves point to the position immediately after +the value if a value could be read and converted to Lisp; otherwise it +doesn't move point. +@end defun + + @node Atomic Changes @section Atomic Change Groups @cindex atomic changes @@ -5040,8 +5232,8 @@ making. When that happens, the arguments to individual changes are made, but won't necessarily be the minimal such region, and the arguments to each successive call of @code{after-change-functions} will then delimit the part of text being -changed exactly. In general, we advise to use either before- or the -after-change hooks, but not both. +changed exactly. In general, we advise using either the before- or +the after-change hook, but not both. @defmac combine-after-change-calls body@dots{} The macro executes @var{body} normally, but arranges to call the @@ -5065,6 +5257,30 @@ because it may lead to inefficient behavior for some change hook functions. @end defmac +@defmac combine-change-calls beg end body@dots{} +This executes @var{body} normally, except any buffer changes it makes +do not trigger the calls to @code{before-change-functions} and +@code{after-change-functions}. Instead there is a single call of each +of these hooks for the region enclosed by @var{beg} and @var{end}, the +parameters supplied to @code{after-change-functions} reflecting the +changes made to the size of the region by @var{body}. + +The result of this macro is the result returned by @var{body}. + +This macro is useful when a function makes a possibly large number of +repetitive changes to the buffer, and the change hooks would otherwise +take a long time to run, were they to be run for each individual +buffer modification. Emacs itself uses this macro, for example, in +the commands @code{comment-region} and @code{uncomment-region}. + +@strong{Warning:} You must not alter the values of +@code{before-change-functions} or @code{after-change-function} within +@var{body}. + +@strong{Warning:} You must not make any buffer changes outside of the +region specified by @var{beg} and @var{end}. +@end defmac + @defvar first-change-hook This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index f5de2fc90ba..315ffd4f484 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -4028,6 +4028,13 @@ line reappears after the echo area momentarily displays the message @samp{End of buffer}. @end deffn +@deffn Command scroll-other-window-down &optional count +This function scrolls the text in another window downward @var{count} +lines. Negative values of @var{count}, or @code{nil}, are handled as +in @code{scroll-down}. In other respects, it behaves the same way as +@code{scroll-other-window} does. +@end deffn + @defvar other-window-scroll-buffer If this variable is non-@code{nil}, it tells @code{scroll-other-window} which buffer's window to scroll. |