diff options
Diffstat (limited to 'doc/lispref')
| -rw-r--r-- | doc/lispref/buffers.texi | 2 | ||||
| -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/functions.texi | 25 | ||||
| -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/numbers.texi | 18 | ||||
| -rw-r--r-- | doc/lispref/os.texi | 39 | ||||
| -rw-r--r-- | doc/lispref/package.texi | 30 | ||||
| -rw-r--r-- | doc/lispref/processes.texi | 3 | ||||
| -rw-r--r-- | doc/lispref/searching.texi | 4 | ||||
| -rw-r--r-- | doc/lispref/sequences.texi | 8 | ||||
| -rw-r--r-- | doc/lispref/strings.texi | 9 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 118 |
18 files changed, 384 insertions, 67 deletions
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index f64d6f1600e..a72e1eb69fc 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/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 6b59e319172..9389aa1ba19 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 e2eaa03f68f..3a39826761c 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -2120,7 +2120,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, @@ -2128,8 +2128,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 @@ -3150,7 +3148,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}, @@ -3206,7 +3205,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/functions.texi b/doc/lispref/functions.texi index 854dd33030c..db59463235f 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1225,7 +1225,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 @@ -1252,15 +1252,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/internals.texi b/doc/lispref/internals.texi index 8bf9abfc614..76be7bf0ac6 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/numbers.texi b/doc/lispref/numbers.texi index c12ffe2cde7..e692ee1cc2f 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -1107,6 +1107,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/os.texi b/doc/lispref/os.texi index 396d7dd045c..0e30ad519a8 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-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 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..7e7a8cd9bc8 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -105,24 +105,32 @@ 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-initialize} 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. @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 +installed, and 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 -loading the packages twice. @xref{Package Installation,,, emacs, The -GNU Emacs Manual}. +evaluating package autoloads more than once. @xref{Package +Installation,,, emacs, The GNU Emacs Manual}. 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; it is for internal use only. + +In most cases, you should not need to call @code{package-initialize}, +as this is done automatically during startup. Simply make sure to put +any code that should run before @code{package-initialize} 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 deffn @node Simple Packages diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 34426f339c6..af177e053cc 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -2715,8 +2715,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 e759967aa8a..26985b5d267 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 3a599e5f535..80079bcfb00 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/strings.texi b/doc/lispref/strings.texi index f3911998799..8a9e27d00ec 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 diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 0e1c9941e95..e992c0f561d 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 @@ -4516,9 +4517,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. @@ -4536,7 +4537,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 @@ -4703,8 +4704,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 @@ -4771,9 +4779,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. @@ -4891,6 +4899,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 |